diff --git a/API.md b/API.md index 22afc67..739ade2 100644 --- a/API.md +++ b/API.md @@ -19,16 +19,18 @@ LoRa.begin(frequency); Returns `1` on success, `0` on failure. -## Set pins +### Set pins -Override the default `NSS` and `NRESET` pins used by the library. **Must** be called before `LoRa.begin()`. +Override the default `NSS`, `NRESET`, and `DIO0` pins used by the library. **Must** be called before `LoRa.begin()`. ```arduino LoRa.setPins(ss, reset, dio0); ``` - * `ss` new slave select pin to use, defaults to `10` - * `reset` new reset pin to use, defaults to `9` - * `dio0` new DIO0 pin to use, defaults to `2` + * `ss` - new slave select pin to use, defaults to `10` + * `reset` - new reset pin to use, defaults to `9` + * `dio0` - new DIO0 pin to use, defaults to `2` + +This call is optional and only needs to be used if you need to change the default pins used. ### End @@ -46,8 +48,12 @@ Start the sequence of sending a packet. ```arduino LoRa.beginPacket(); + +LoRa.beginPacket(implicitHeader); ``` + * `implicitHeader` - (optional) `true` enables implicit header mode, `false` enables explicit header mode (default) + Returns `1` on success, `0` on failure. ### Writing @@ -59,12 +65,12 @@ LoRa.write(byte); LoRa.write(buffer, length); ``` -* `byte` single byte to write to packet +* `byte` - single byte to write to packet or -* `buffer` data to write to packet -* `length` size of data to write +* `buffer` - data to write to packet +* `length` - size of data to write Returns the number of bytes written. @@ -88,9 +94,44 @@ Check if a packet has been received. ```arduino int packetSize = LoRa.parsePacket(); + +int packetSize = LoRa.parsePacket(size); ``` -Returns the packet size or `0` if no packet was received. + * `size` - (optional) if `> 0` implicit header mode is enabled with the expected a packet of `size` bytes, default mode is explicit header mode + + +Returns the packet size in bytes or `0` if no packet was received. + +### Continuous receive mode + +#### Register callback + +Register a callback function for when a packet is received. + +```arduino +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. + +```arduino +LoRa.receive(); + +LoRa.receive(int size); +``` + + * `size` - (optional) if `> 0` implicit header mode is enabled with the expected a packet of `size` bytes, default mode is explicit header mode + +The `onReceive` callback will be called when a packet is received. ### Packet RSSI @@ -100,6 +141,14 @@ int rssi = LoRa.packetRssi(); Returns the RSSI of the received packet. +### Packet SNR + +```arduino +float snr = LoRa.packetSnr(); +``` + +Returns the estimated SNR of the received packet in dB. + ### Available ```arduino @@ -116,7 +165,7 @@ Peek at the next byte in the packet. byte b = LoRa.peek(); ``` -Returns the next byte in the packet or `-1` if no bytes available. +Returns the next byte in the packet or `-1` if no bytes are available. ### Reading @@ -126,7 +175,125 @@ Read the next byte from the packet. byte b = LoRa.read(); ``` -Returns the next byte in the packet or `-1` if no bytes available. +Returns the next byte in the packet or `-1` if no bytes are available. **Note:** Other Arduino [`Stream` API's](https://www.arduino.cc/en/Reference/Stream) can also be used to read data from the packet +## Other radio modes + +### Idle mode + +Put the radio in idle (standby) mode. + +```arduino +LoRa.idle(); +``` + +### Sleep mode + +Put the radio in sleep mode. + +```arduino +LoRa.sleep(); +``` + +## Radio parameters + +### TX Power + +Change the TX power of the radio. + +```arduino +LoRa.setTxPower(txPower); +``` + * `txPower` - TX power in dB, defaults to `17` + + Supported values are between `2` and `17`. + +### Frequency + +Change the frequency of the radio. + +```arduino +LoRa.setFrequency(frequency); +``` + * `frequency` - frequency in Hz (`433E6`, `866E6`, `915E6`) + +### Spreading Factor + +Change the spreading factor of the radio. + +```arduino +LoRa.setSpreadingFactor(spreadingFactor); +``` + * `spreadingFactor` - spreading factor, defaults to `7` + +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. + +```arduino +LoRa.setSignalBandwidth(signalBandwidth); +``` + + * `signalBandwidth` - signal bandwidth in Hz, defaults to `125E3`. + +Supported values are `7.8E3`, `10.4E3`, `15.6E3`, `20.8E3`, `31.25E3`, `41.7E3`, `62.5E3`, `125E3`, and `250E3`. + +### Coding Rate + +Change the coding rate of the radio. + +```arduino +LoRa.setCodingRate4(codingRateDenominator); +``` + + * `codingRateDenominator` - denominator of the coding rate, defaults to `5` + +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. + +```arduino +LoRa.setPreambleLength(preambleLength); +``` + + * `preambleLength` - preamble length in symbols, defaults to `8` + +Supported values are between `6` and `65535`. + +### Sync Word + +Change the sync word of the radio. + +```arduino +LoRa.setSyncWord(syncWord); +``` + + * `syncWord` - byte value to use as the sync word, defaults to `0x34` + +### CRC + +Enable or disable CRC usage, by default a CRC is not used. + +```arduino +LoRa.crc(); + +LoRa.noCrc(); +``` + +## Other functions + +### Random + +Generate a random byte, based on the Wideband RSSI measurement. + +``` +byte b = LoRa.random(); +``` + +Returns random byte. diff --git a/keywords.txt b/keywords.txt index 5b6df85..93c5562 100644 --- a/keywords.txt +++ b/keywords.txt @@ -34,10 +34,8 @@ receive KEYWORD2 idle KEYWORD2 sleep KEYWORD2 -random KEYWORD2 - -setFrequency KEYWORD2 setTxPower KEYWORD2 +setFrequency KEYWORD2 setSpreadingFactor KEYWORD2 setSignalBandwidth KEYWORD2 setCodingRate4 KEYWORD2 @@ -46,6 +44,7 @@ setSyncWord KEYWORD2 crc KEYWORD2 noCrc KEYWORD2 +random KEYWORD2 setPins KEYWORD2 dumpRegisters KEYWORD2 diff --git a/src/LoRa.cpp b/src/LoRa.cpp index 84a8b82..e792917 100644 --- a/src/LoRa.cpp +++ b/src/LoRa.cpp @@ -297,9 +297,15 @@ void LoRaClass::sleep() writeRegister(REG_OP_MODE, MODE_LONG_RANGE_MODE | MODE_SLEEP); } -byte LoRaClass::random() +void LoRaClass::setTxPower(int level) { - return readRegister(REG_RSSI_WIDEBAND); + if (level < 2) { + level = 2; + } else if (level > 17) { + level = 17; + } + + writeRegister(REG_PA_CONFIG, PA_BOOST | (level - 2)); } void LoRaClass::setFrequency(long frequency) @@ -313,17 +319,6 @@ void LoRaClass::setFrequency(long frequency) writeRegister(REG_FRF_LSB, (uint8_t)(frf >> 0)); } -void LoRaClass::setTxPower(int level) -{ - if (level < 2) { - level = 2; - } else if (level > 17) { - level = 17; - } - - writeRegister(REG_PA_CONFIG, PA_BOOST | (level - 2)); -} - void LoRaClass::setSpreadingFactor(int sf) { if (sf < 6) { @@ -385,7 +380,7 @@ void LoRaClass::setCodingRate4(int denominator) writeRegister(REG_MODEM_CONFIG_1, (readRegister(REG_MODEM_CONFIG_1) & 0xf1) | (cr << 1)); } -void LoRaClass::setPreambleLength(unsigned long length) +void LoRaClass::setPreambleLength(long length) { writeRegister(REG_PREAMBLE_MSB, (uint8_t)(length >> 8)); writeRegister(REG_PREAMBLE_LSB, (uint8_t)(length >> 0)); @@ -406,6 +401,11 @@ void LoRaClass::noCrc() writeRegister(REG_MODEM_CONFIG_2, readRegister(REG_MODEM_CONFIG_2) & 0xfb); } +byte LoRaClass::random() +{ + return readRegister(REG_RSSI_WIDEBAND); +} + void LoRaClass::setPins(int ss, int reset, int dio0) { _ss = ss; diff --git a/src/LoRa.h b/src/LoRa.h index f5df68a..849cf0f 100644 --- a/src/LoRa.h +++ b/src/LoRa.h @@ -38,18 +38,18 @@ public: void idle(); void sleep(); - byte random(); - - void setFrequency(long frequency); void setTxPower(int level); + void setFrequency(long frequency); void setSpreadingFactor(int sf); void setSignalBandwidth(long sbw); void setCodingRate4(int denominator); - void setPreambleLength(unsigned long length); + void setPreambleLength(long length); void setSyncWord(int sw); void crc(); void noCrc(); + byte random(); + void setPins(int ss = LORA_DEFAULT_SS_PIN, int reset = LORA_DEFAULT_RESET_PIN, int dio0 = LORA_DEFAULT_DIO0_PIN); void dumpRegisters(Stream& out);