lora: Add lora modem drivers for SX127x and SX126x.

Includes:
- component oriented driver, to only install the parts that are needed
- synchronous operation
- async wrapper class for asynchronous operation
- two examples with async & synchronous versions
- documentation

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Author: projectgus

micropython/lora/README.md

@@ -0,0 +1,93 @@
+# LoRa Reliable Delivery Example
+
+This example shows a basic custom protocol for reliable one way communication
+from low-power remote devices to a central base device:
+
+- A single "receiver" device, running on mains power, listens continuously for
+  messages from one or more "sender" devices. Messages are payloads inside LoRa packets,
+  with some additional framing and address in the LoRa packet payload.
+- "Sender" devices are remote sensor nodes, possibly battery powered. These wake
+  up periodically, read some data from a sensor, and send it in a message to the receiver.
+- Messages are transmitted "reliably" with some custom header information,
+  meaning the receiver will acknowledge it received each message and the sender
+  will retry sending if it doesn't receive the acknowledgement.
+
+## Source Files
+
+* `lora_rd_settings.py` contains some common settings that are imported by
+  sender and receiver. These settings will need to be modified for the correct
+  frequency and other settings, before running the examples.
+* `receiver.py` and `receiver_async.py` contain a synchronous (low-level API)
+  and asynchronous (iterator API) implementation of the same receiver program,
+  respectively. These two programs should work the same, they are intended show
+  different ways the driver can be used.
+* `sender.py` and `sender_async.py` contain a synchronous (simple API) and
+  asynchronous (async API) implementation of the same sender program,
+  respectively. Because the standard async API resembles the Simple API, these
+  implementations are *very* similar. The two programs should work the same,
+  they are intended to show different ways the driver can be used.
+
+## Running the examples
+
+One way to run this example interactively:
+
+1. Install or "freeze in" the necessary lora modem driver package (`lora-sx127x`
+   or `lora-sx126x`) and optionally the `lora-async` package if using the async
+   examples (see main lora `README.md` in the above directory for details).
+2. Edit the `lora_rd_settings.py` file to set the frequency and other protocol
+   settings for your region and hardware (see main lora `README.md`).
+3. Edit the program you plan to run and fill in the `get_modem()` function with
+   the correct modem type, pin assignments, etc. for your board (see top-level
+   README). Note the `get_modem()` function should use the existing `lora_cfg`
+   variable, which holds the settings imported from `lora_rd_settings.py`.
+4. Change to this directory in a terminal.
+5. Run `mpremote mount . exec receiver.py` on one board and `mpremote mount
+   . exec sender.py` on another (or swap in `receiver_async.py` and/or
+   `sender_async.py` as desired).
+
+Consult the [mpremote
+documentation](https://docs.micropython.org/en/latest/reference/mpremote.html)
+for an explanation of these commands and the options needed to run two copies of
+`mpremote` on different serial ports at the same time.
+
+## Automatic Performance Tuning
+
+- When sending an ACK, the receiver includes the RSSI of the received
+  packet. Senders will automatically modify their output_power to minimize the
+  power consumption required to reach the receiver. Similarly, if no ACK is
+  received then they will increase their output power and also re-run Image
+  calibration in order to maximize RX performance.
+
+## Message payloads
+
+Messages are LoRa packets, set up as follows:
+
+LoRA implicit header mode, CRCs enabled.
+
+* Each remote device has a unique sixteen-bit ID (range 00x0000 to 0xFFFE). ID
+  0xFFFF is reserved for the single receiver device.
+* An eight-bit message counter is used to identify duplicate messages
+
+* Data message format is:
+  - Sender ID (two bytes, little endian)
+  - Counter byte (incremented on each new message, not incremented on retry).
+  - Message length (1 byte)
+  - Message (variable length)
+  - Checksum byte (sum of all proceeding bytes in message, modulo 256). The LoRa
+    packet has its own 16-bit CRC, this is included as an additional way to
+    disambiguate other LoRa packets that might appear the same.
+
+* After receiving a valid data message, the receiver device should send
+  an acknowledgement message 25ms after the modem receive completed.
+
+  Acknowledgement message format:
+  - 0xFFFF (receiver station ID as two bytes)
+  - Sender's Device ID from received message (two bytes, little endian)
+  - Counter byte from received message
+  - Checksum byte from received message
+  - RSSI value as received by radio (one signed byte)
+
+* If the remote device doesn't receive a packet with the acknowledgement
+  message, it retries up to a configurable number of times (default 4) with a
+  basic exponential backoff formula.
+

micropython/lora/examples/reliable_delivery/README.md

@@ -0,0 +1,38 @@
+# MicroPython lora reliable_delivery example - common protocol settings
+# MIT license; Copyright (c) 2023 Angus Gratton
+
+#
+######
+# To be able to be able to communicate, most of these settings need to match on both radios.
+# Consult the example README for more information about how to use the example.
+######
+
+# LoRa protocol configuration
+#
+# Currently configured for relatively slow & low bandwidth settings, which
+# gives more link budget and possible range.
+#
+# These settings should match on receiver.
+#
+# Check the README and local regulations to know what configuration settings
+# are available.
+lora_cfg = {
+    "freq_khz": 916000,
+    "sf": 10,
+    "bw": "62.5",  # kHz
+    "coding_rate": 8,
+    "preamble_len": 12,
+    "output_power": 10,  # dBm
+}
+
+# Single receiver has a fixed 16-bit ID value (senders each have a unique value).
+RECEIVER_ID = 0xFFFF
+
+# Length of an ACK message in bytes.
+ACK_LENGTH = 7
+
+# Send the ACK this many milliseconds after receiving a valid message
+#
+# This can be quite a bit lower (25ms or so) if wakeup times are short
+# and _DEBUG is turned off on the modems (logging to UART delays everything).
+ACK_DELAY_MS = 100

micropython/lora/examples/reliable_delivery/lora_rd_settings.py

@@ -0,0 +1,163 @@
+# MicroPython lora reliable_delivery example - synchronous receiver program
+# MIT license; Copyright (c) 2023 Angus Gratton
+import struct
+import time
+import machine
+from machine import SPI, Pin
+from micropython import const
+from lora import RxPacket
+
+from lora_rd_settings import RECEIVER_ID, ACK_LENGTH, ACK_DELAY_MS, lora_cfg
+
+# Change _DEBUG to const(True) to get some additional debugging output
+# about timing, RSSI, etc.
+#
+# For a lot more debugging detail, go to the modem driver and set _DEBUG there to const(True)
+_DEBUG = const(False)
+
+# Keep track of the last counter value we got from each known sender
+# this allows us to tell if packets are being lost
+last_counters = {}
+
+
+def get_modem():
+    # from lora import SX1276
+    # return SX1276(
+    #     spi=SPI(1, baudrate=2000_000, polarity=0, phase=0,
+    #             miso=Pin(19), mosi=Pin(27), sck=Pin(5)),
+    #     cs=Pin(18),
+    #     dio0=Pin(26),
+    #     dio1=Pin(35),
+    #     reset=Pin(14),
+    #     lora_cfg=lora_cfg,
+    # )
+    raise NotImplementedError("Replace this function with one that returns a lora modem instance")
+
+
+def main():
+    print("Initializing...")
+    modem = get_modem()
+
+    print("Main loop started")
+    receiver = Receiver(modem)
+
+    while True:
+        # With wait=True, this function blocks until something is received and always
+        # returns non-None
+        sender_id, data = receiver.recv(wait=True)
+
+        # Do something with the data!
+        print(f"Received {data} from {sender_id:#x}")
+
+
+class Receiver:
+    def __init__(self, modem):
+        self.modem = modem
+        self.last_counters = {}  # Track the last counter value we got from each sender ID
+        self.rx_packet = None  # Reuse RxPacket object when possible, save allocation
+        self.ack_buffer = bytearray(ACK_LENGTH)  # reuse the same buffer for ACK packets
+        self.skipped_packets = 0  # Counter of skipped packets
+
+        modem.calibrate()
+
+        # Start receiving immediately. We expect the modem to receive continuously
+        self.will_irq = modem.start_recv(continuous=True)
+        print("Modem initialized and started receive...")
+
+    def recv(self, wait=True):
+        # Receive a packet from the sender, including sending an ACK.
+        #
+        # Returns a tuple of the 16-bit sender id and the sensor data payload.
+        #
+        # This function should be called very frequently from the main loop (at
+        # least every ACK_DELAY_MS milliseconds), to avoid not sending ACKs in time.
+        #
+        # If 'wait' argument is True (default), the function blocks indefinitely
+        # until a packet is received. If False then it will return None
+        # if no packet is available.
+        #
+        # Note that because we called start_recv(continuous=True), the modem
+        # will keep receiving on its own - even if when we call send() to
+        # send an ACK.
+        while True:
+            rx = self.modem.poll_recv(rx_packet=self.rx_packet)
+
+            if isinstance(rx, RxPacket):  # value will be True or an RxPacket instance
+                decoded = self._handle_rx(rx)
+                if decoded:
+                    return decoded  # valid LoRa packet and valid for this application
+
+            if not wait:
+                return None
+
+            # Otherwise, wait for an IRQ (or have a short sleep) and then poll recv again
+            # (receiver is not a low power node, so don't bother with sleep modes.)
+            if self.will_irq:
+                while not self.modem.irq_triggered():
+                    machine.idle()
+            else:
+                time.sleep_ms(1)
+
+    def _handle_rx(self, rx):
+        # Internal function to handle a received packet and either send an ACK
+        # and return the sender and the payload, or return None if packet
+        # payload is invalid or a duplicate.
+
+        if len(rx) < 5:  # 4 byte header plus 1 byte checksum
+            print("Invalid packet length")
+            return None
+
+        sender_id, counter, data_len = struct.unpack("<HBB", rx)
+        csum = rx[-1]
+
+        if len(rx) != data_len + 5:
+            print("Invalid length in payload header")
+            return None
+
+        calc_csum = sum(b for b in rx[:-1]) & 0xFF
+        if csum != calc_csum:
+            print(f"Invalid checksum. calc={calc_csum:#x} received={csum:#x}")
+            return None
+
+        # Packet is valid!
+
+        if _DEBUG:
+            print(f"RX {data_len} byte message RSSI {rx.rssi} at timestamp {rx.ticks_ms}")
+
+        # Send the ACK
+        struct.pack_into(
+            "<HHBBb", self.ack_buffer, 0, RECEIVER_ID, sender_id, counter, csum, rx.rssi
+        )
+
+        # Time send to start as close to ACK_DELAY_MS after message was received as possible
+        tx_at_ms = time.ticks_add(rx.ticks_ms, ACK_DELAY_MS)
+        tx_done = self.modem.send(self.ack_buffer, tx_at_ms=tx_at_ms)
+
+        if _DEBUG:
+            tx_time = time.ticks_diff(tx_done, tx_at_ms)
+            expected = self.modem.get_time_on_air_us(ACK_LENGTH) / 1000
+            print(f"ACK TX {tx_at_ms}ms -> {tx_done}ms took {tx_time}ms expected {expected}")
+
+        # Check if the data we received is fresh or stale
+        if sender_id not in self.last_counters:
+            print(f"New device id {sender_id:#x}")
+        elif self.last_counters[sender_id] == counter:
+            print(f"Duplicate packet received from {sender_id:#x}")
+            return None
+        elif counter != 1:
+            # If the counter from this sender has gone up by more than 1 since
+            # last time we got a packet, we know there is some packet loss.
+            #
+            # (ignore the case where the new counter is 1, as this probably
+            # means a reset.)
+            delta = (counter - 1 - self.last_counters[sender_id]) & 0xFF
+            if delta:
+                print(f"Skipped/lost {delta} packets from {sender_id:#x}")
+                self.skipped_packets += delta
+
+        self.last_counters[sender_id] = counter
+        return sender_id, rx[4:-1]
+
+
+if __name__ == "__main__":
+    main()