9.3 KiB
LoRa API
Include Library
#include <LoRa.h>
Setup
Begin
Initialize the library with the specified frequency.
LoRa.begin(frequency);
frequency- frequency in Hz (433E6,868E6,915E6)
Returns 1 on success, 0 on failure.
Set pins
Override the default NSS, NRESET, and DIO0 pins used by the library. Must be called before LoRa.begin().
LoRa.setPins(ss, reset, dio0);
ss- new slave select pin to use, defaults to10reset- new reset pin to use, defaults to9dio0- new DIO0 pin to use, defaults to2. Must be interrupt capable via attachInterrupt(...).
This call is optional and only needs to be used if you need to change the default pins used.
No MCU controlled reset pin
To save further pins one could connect the reset pin of the MCU with reset pin of the radio thus resetting only during startup.
reset- set to-1to omit this pin
Pin dio0 interrupt callbacks
The dio0 pin can be used for channel activity detection callback, transmission finish callback and/or receiving callback, check onCadDone , onTxDone, and onReceive.
Set SPI interface
Override the default SPI interface used by the library. Must be called before LoRa.begin().
LoRa.setSPI(spi);
spi- new SPI interface to use, defaults toSPI
This call is optional and only needs to be used if you need to change the default SPI interface used, in the case your Arduino (or compatible) board has more than one SPI interface present.
Set SPI Frequency
Override the default SPI frequency of 10 MHz used by the library. Must be called before LoRa.begin().
LoRa.setSPIFrequency(frequency);
frequency- new SPI frequency to use, defaults to8E6
This call is optional and only needs to be used if you need to change the default SPI frequency used. Some logic level converters cannot support high speeds such as 8 MHz, so a lower SPI frequency can be selected with LoRa.setSPIFrequency(frequency).
End
Stop the library
LoRa.end()
Sending data
Begin packet
Start the sequence of sending a packet.
LoRa.beginPacket();
LoRa.beginPacket(implicitHeader);
implicitHeader- (optional)trueenables implicit header mode,falseenables explicit header mode (default)
Returns 1 if radio is ready to transmit, 0 if busy or on failure.
Writing
Write data to the packet. Each packet can contain up to 255 bytes.
LoRa.write(byte);
LoRa.write(buffer, length);
byte- single byte to write to packet
or
buffer- data to write to packetlength- size of data to write
Returns the number of bytes written.
Note: Other Arduino Print API's can also be used to write data into the packet
End packet
End the sequence of sending a packet.
LoRa.endPacket();
LoRa.endPacket(async);
async- (optional)trueenables non-blocking mode,falsewaits for transmission to be completed (default)
Returns 1 on success, 0 on failure.
Tx Done
WARNING: TxDone callback uses the interrupt pin on the dio0 check setPins function!
Register callback
Register a callback function for when a packet transmission finish.
LoRa.onTxDone(onTxDone);
void onTxDone() {
// ...
}
onTxDone- function to call when a packet transmission finish.
Receiving data
Parsing packet
Check if a packet has been received.
int packetSize = LoRa.parsePacket();
int packetSize = LoRa.parsePacket(size);
size- (optional) if> 0implicit header mode is enabled with the expected a packet ofsizebytes, default mode is explicit header mode
Returns the packet size in bytes or 0 if no packet was received.
Continuous receive mode
WARNING: Receive callback uses the interrupt pin on the dio0, check setPins function!
Register callback
Register a callback function for when a packet is received.
LoRa.onReceive(onReceive);
void onReceive(int packetSize) {
// ...
}
onReceive- function to call when a packet is received.
Receive mode
Puts the radio in continuous receive mode.
LoRa.receive();
LoRa.receive(int size);
size- (optional) if> 0implicit header mode is enabled with the expected a packet ofsizebytes, default mode is explicit header mode
The onReceive callback will be called when a packet is received.
Packet RSSI
int rssi = LoRa.packetRssi();
Returns the averaged RSSI of the last received packet (dBm).
Packet SNR
float snr = LoRa.packetSnr();
Returns the estimated SNR of the received packet in dB.
RSSI
int rssi = LoRa.rssi();
Returns the current RSSI of the radio (dBm). RSSI can be read at any time (during packet reception or not)
Packet Frequency Error
long freqErr = LoRa.packetFrequencyError();
Returns the frequency error of the received packet in Hz. The frequency error is the frequency offset between the receiver centre frequency and that of an incoming LoRa signal.
Available
int availableBytes = LoRa.available()
Returns number of bytes available for reading.
Peeking
Peek at the next byte in the packet.
byte b = LoRa.peek();
Returns the next byte in the packet or -1 if no bytes are available.
Reading
Read the next byte from the packet.
byte b = LoRa.read();
Returns the next byte in the packet or -1 if no bytes are available.
Note: Other Arduino Stream API's can also be used to read data from the packet
Channel Activity Detection
WARNING: Channel activity detection callback uses the interrupt pin on the dio0, check setPins function!
Register callback
Register a callback function for when channel activity detection has done.
LoRa.onCadDone(onCadDone);
void onCadDone(boolean signalDetected) {
// ...
}
onCadDone- function to call when channel activity detection has done.signalDetected- iftrue, the radio detects the presence of other LoRa signals.
Channel Activity detection mode
Puts the radio in channel activity detection mode.
LoRa.channelActivityDetection();
Other radio modes
Idle mode
Put the radio in idle (standby) mode.
LoRa.idle();
Sleep mode
Put the radio in sleep mode.
LoRa.sleep();
Radio parameters
TX Power
Change the TX power of the radio.
LoRa.setTxPower(txPower);
LoRa.setTxPower(txPower, outputPin);
txPower- TX power in dB, defaults to17outputPin- (optional) PA output pin, supported values arePA_OUTPUT_RFO_PINandPA_OUTPUT_PA_BOOST_PIN, defaults toPA_OUTPUT_PA_BOOST_PIN.
Supported values are 2 to 20 for PA_OUTPUT_PA_BOOST_PIN, and 0 to 14 for PA_OUTPUT_RFO_PIN.
Most modules have the PA output pin connected to PA BOOST,
Frequency
Change the frequency of the radio.
LoRa.setFrequency(frequency);
frequency- frequency in Hz (433E6,868E6,915E6)
Spreading Factor
Change the spreading factor of the radio.
LoRa.setSpreadingFactor(spreadingFactor);
spreadingFactor- spreading factor, defaults to7
Supported values are between 6 and 12. If a spreading factor of 6 is set, implicit header mode must be used to transmit and receive packets.
Signal Bandwidth
Change the signal bandwidth of the radio.
LoRa.setSignalBandwidth(signalBandwidth);
signalBandwidth- signal bandwidth in Hz, defaults to125E3.
Supported values are 7.8E3, 10.4E3, 15.6E3, 20.8E3, 31.25E3, 41.7E3, 62.5E3, 125E3, 250E3, and 500E3.
Coding Rate
Change the coding rate of the radio.
LoRa.setCodingRate4(codingRateDenominator);
codingRateDenominator- denominator of the coding rate, defaults to5
Supported values are between 5 and 8, these correspond to coding rates of 4/5 and 4/8. The coding rate numerator is fixed at 4.
Preamble Length
Change the preamble length of the radio.
LoRa.setPreambleLength(preambleLength);
preambleLength- preamble length in symbols, defaults to8
Supported values are between 6 and 65535.
Sync Word
Change the sync word of the radio.
LoRa.setSyncWord(syncWord);
syncWord- byte value to use as the sync word, defaults to0x12
CRC
Enable or disable CRC usage, by default a CRC is not used.
LoRa.enableCrc();
LoRa.disableCrc();
Invert IQ Signals
Enable or disable Invert the LoRa I and Q signals, by default a invertIQ is not used.
LoRa.enableInvertIQ();
LoRa.disableInvertIQ();
LNA Gain
Set LNA Gain for better RX sensitivity, by default AGC (Automatic Gain Control) is used and LNA gain is not used.
LoRa.setGain(gain);
gain- LNA gain
Supported values are between 0 and 6. If gain is 0, AGC will be enabled and LNA gain will not be used. Else if gain is from 1 to 6, AGC will be disabled and LNA gain will be used.
Other functions
Random
Generate a random byte, based on the Wideband RSSI measurement.
byte b = LoRa.random();
Returns random byte.