Expose controls for spreading factor, coding rate, signal bandwidth.

Author: applio

README.rst

@@ -29,7 +29,26 @@ This is easily achieved by downloading
 Usage Example
 =============
 
-See examples/rfm9x_simpletest.py for a demo of the usage.
+Initialization of the RFM radio requires specifying a frequency appropriate to
+your radio hardware (i.e. 868-915 or 433 MHz) and specifying the pins used in your
+wiring from the controller board to the radio module.
+
+This example code matches the wiring used in the
+`LoRa and LoRaWAN Radio for Raspberry Pi <https://learn.adafruit.com/lora-and-lorawan-radio-for-raspberry-pi/>`_
+project:
+
+.. code-block:: python
+    import digitalio
+    import board
+    import busio
+    import adafruit_rfm9x
+
+    RADIO_FREQ_MHZ = 915.0
+    CS = digitalio.DigitalInOut(board.CE1)
+    RESET = digitalio.DigitalInOut(board.D25)
+    spi = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
+    rfm9x = adafruit_rfm9x.RFM9x(spi, CS, RESET, RADIO_FREQ_MHZ)
+
 Note: the default baudrate for the SPI is 50000000 (5MHz). The maximum setting is 10Mhz but 
 transmission errors have been observed expecially when using breakout boards.
 For breakout boards or other configurations where the boards are separated, it may be necessary to reduce
@@ -39,9 +58,21 @@ To set it to 1000000 use :
 
 .. code-block:: python
 
-    # Initialze RFM radio
+    # Initialze RFM radio with a more conservative baudrate
     rfm9x = adafruit_rfm9x.RFM9x(spi, CS, RESET, RADIO_FREQ_MHZ, baudrate=1000000)
 
+Optional controls exist to alter the signal bandwidth, coding rate, and spreading factor
+settings used by the radio to achieve better performance in different environments.
+By default, settings compatible with RadioHead Bw125Cr45Sf128 mode are used, matching
+the following example:
+
+.. code-block:: python
+
+    # Initialze RFM radio with conservative baudrate and default modem config
+    rfm9x = adafruit_rfm9x.RFM9x(spi, CS, RESET, RADIO_FREQ_MHZ, baudrate=1000000,
+                                 signal_bandwidth=125000, coding_rate=5, spreading_factor=7)
+
+See examples/rfm9x_simpletest.py for an expanded demo of the usage.
 
 
 Contributing

adafruit_rfm9x.py

@@ -192,6 +192,8 @@
 _RH_RF95_LOW_DATA_RATE_OPTIMIZE              = const(0x01)
 
 # RH_RF95_REG_1E_MODEM_CONFIG2                       0x1e
+_RH_RF95_DETECTION_OPTIMIZE                  = const(0x31)
+_RH_RF95_DETECTION_THRESHOLD                 = const(0x37)
 _RH_RF95_SPREADING_FACTOR                    = const(0xf0)
 _RH_RF95_SPREADING_FACTOR_64CPS              = const(0x60)
 _RH_RF95_SPREADING_FACTOR_128CPS             = const(0x70)
@@ -334,7 +336,8 @@ def __set__(self, obj, val):
     rx_done = _RegisterBits(_RH_RF95_REG_12_IRQ_FLAGS, offset=6, bits=1)
 
     def __init__(self, spi, cs, reset, frequency, *, preamble_length=8,
-                 high_power=True, baudrate=5000000):
+                 high_power=True, baudrate=5000000, signal_bandwidth=125000,
+                 coding_rate=5, spreading_factor=7):
         self.high_power = high_power
         # Device support SPI mode 0 (polarity & phase = 0) up to a max of 10mhz.
         # Set Default Baudrate to 5MHz to avoid problems
@@ -367,10 +370,37 @@ def __init__(self, spi, cs, reset, frequency, *, preamble_length=8,
         self._write_u8(_RH_RF95_REG_0F_FIFO_RX_BASE_ADDR, 0x00)
         # Set mode idle
         self.idle()
-        # Set modem config to RadioHead compatible Bw125Cr45Sf128 mode.
+        # Defaults set modem config to RadioHead compatible Bw125Cr45Sf128 mode.
+        # Set signal bandwidth (set to 125000 to match RadioHead Bw125).
+        bins = (7800, 10400, 15600, 20800, 31250, 41700, 62500, 125000, 250000)
+        for bw, cutoff in enumerate(bins):
+            if bandwidth <= cutoff:
+                break
+        else:
+            bw = 9
+        self._write_u8(
+            _RH_RF95_REG_1D_MODEM_CONFIG1,
+            (self._read_u8(_RH_RF95_REG_1D_MODEM_CONFIG1) & 0x0f) | (bw << 4)
+        )
+        # Set coding rate (set to 5 to match RadioHead Cr45).
+        denominator = min(max(coding_rate, 5), 8)
+        cr = denominator - 4
+        self._write_u8(
+            _RH_RF95_REG_1D_MODEM_CONFIG1,
+            (self._read_u8(_RH_RF95_REG_1D_MODEM_CONFIG1) & 0xf1) | (cr << 1)
+        )
+        # Set spreading factor (set to 7 to match RadioHead Sf128).
+        sf = min(max(spreading_factor, 6), 12)
+        self._write_u8(_RH_RF95_DETECTION_OPTIMIZE, 0xc5 if sf == 6 else 0xc3)
+        self._write_u8(_RH_RF95_DETECTION_THRESHOLD, 0x0c if sf == 6 else 0x0a)
+        self._write_u8(
+            _RH_RF95_REG_1E_MODEM_CONFIG2,
+            (
+                (self._read_u8(_RH_RF95_REG_1E_MODEM_CONFIG2) & 0x0f) | 
+                ((sf << 4) & 0xf0)
+            )
+        )
         # Note no sync word is set for LoRa mode either!
-        self._write_u8(_RH_RF95_REG_1D_MODEM_CONFIG1, 0x72)  # Fei msb?
-        self._write_u8(_RH_RF95_REG_1E_MODEM_CONFIG2, 0x74)  # Fei lsb?
         self._write_u8(_RH_RF95_REG_26_MODEM_CONFIG3, 0x00)  # Preamble lsb?
         # Set preamble length (default 8 bytes to match radiohead).
         self.preamble_length = preamble_length