Update API documentation

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.

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
 

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;

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);