wireless/lpwan: Add support for the RN903 and RN2483 family of LoRa

radio transceivers. This initial support includes transmit and receive
functionality and configuration and reading of radio parameters like
frequency and bandwidth.

Signed-off-by: Matteo Golin <matteo.golin@gmail.com>

Author: linguini1

Documentation/components/drivers/special/wireless.rst

@@ -1,3 +1,11 @@
 ================
 Wireless Drivers
 ================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Contents
+
+   ./wireless/*

Documentation/components/drivers/special/wireless/rn2xx3.rst

@@ -0,0 +1,355 @@
+======
+RN2XX3
+======
+
+This driver provides support for the RN2XX3 family of LoRa radio transceivers by
+Microchip. This includes both the RN2903 and RN2483 modules.
+
+.. warning::
+   This driver only contains preliminary support for a few 'radio set' commands
+   and raw radio transmit/receive. There is no support for the LoRaWAN stack
+   yet. IT IS EXPERIMENTAL.
+
+Application Programming Interface
+=================================
+
+To register the device for use, you will need to enable the standard upper half
+serial drivers (``CONFIG_STANDARD_SERIAL``), since the RN2XX3 driver requires
+the path to the UART interface the module is connected to.
+
+You will also need to ensure that the baud rate of the UART interface is set to
+57600, which is the baud rate of the RN2XX3.
+
+At registration time, the driver will automatically determine if the device is
+the RN2903 or RN2483.
+
+.. code-block:: c
+
+   #include <nuttx/wireless/lpwan/rn2xx3.h>
+
+   #ifdef CONFIG_LPWAN_RN2XX3
+
+   /* Register the RN2XX3 device driver */
+
+   ret = rn2xx3_register("/dev/rn2903", "/dev/ttyS1");
+   if (ret < 0) {
+     syslog(LOG_ERR, "Failed to register RN2XX3 device driver: %d\n", ret);
+   }
+   #endif
+
+This driver uses the standard POSIX character device interface, implementing
+``read()``, ``write()`` and ``ioctl()``.
+
+To transmit, the ``write()`` function can be used. Bytes in the provided buffer
+will be transmitted as a packet. This has the following behaviour:
+
+* If the radio is in FSK modulation mode, packets will only contain up to 64
+  bytes. A buffer of more than 64 bytes will only have 64 bytes transmitted.
+* If the radio is in LoRa modulation mode, packets will only contain up to 255
+  bytes.
+* If the buffer contains less than the current packet size limit (64 or 255
+  bytes), its contents will be transmitted as a single packet.
+
+.. code-block:: c
+
+   int radio = open("/dev/rn2903", O_RDWR);
+   if (radio < 0)
+     {
+       fprintf(stderr, "Couldn't open radio: %d\n", errno);
+       return -1;
+     }
+
+    char message[] = "Hello, world!";
+    ssize_t b_sent = write(radio, message, sizeof(message));
+    if (b_sent < 0)
+      {
+        fprintf(stderr, "Couldn't transmit: %d\n", errno);
+        return -1;
+      }
+
+To receive, the ``read()`` function can be used. As much of the received packet
+as possible will be stored in the user buffer. This has the following behaviour:
+
+* If the buffer is too small to contain the full received packet, as much of the
+  packet as possible will be stored in the buffer.
+* When the packet is fully read, ``read()`` will return ``0``.
+* If only part of the packet has been read and a call to ``write()`` or
+  ``ioctl()`` is made, the remainder of the packet is discarded.
+
+.. code-block:: c
+
+   int radio = open("/dev/rn2903", O_RDWR);
+   if (radio < 0)
+     {
+       fprintf(stderr, "Couldn't open radio: %d\n", errno);
+       return -1;
+     }
+
+    char buffer[16];
+    ssize_t b_read;
+
+    do {
+        b_read = read(radio, buffer, sizeof(buffer));
+        if (b_read < 0)
+          {
+            fprintf(stderr, "Couldn't receive: %d\n", errno);
+            return -1;
+          }
+        write(0, buffer, b_read); /* Print received bytes to stdout */
+    } while (b_read != 0);
+
+Finally, the ``ioctl()`` interface provides access to some underlying module
+commands.
+
+``WLIOC_GETSNR``
+----------------
+
+Gets the signal to noise ration of the last received packet. If no packets have
+been received, it will default to -128. Argument is a pointer to an ``int8_t``.
+
+.. code-block:: c
+
+   int8_t snr;
+   err = ioctl(radio, WLIOC_GETSNR, &snr);
+
+``WLIOC_SETRADIOFREQ``
+----------------------
+
+Sets the operating frequency of the radio module. The argument is the desired
+frequency in Hz (``uint32_t``).
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_SETRADIOFREQ, 902400000);
+
+``WLIOC_GETRADIOFREQ``
+----------------------
+
+Gets the current operating frequency of the radio module in Hz. The argument is
+a pointer to a ``uint32_t``.
+
+.. code-block:: c
+
+   uint32_t freq;
+   err = ioctl(radio, WLIOC_GETRADIOFREQ, &freq);
+
+``WLIOC_SETTXPOWERF``
+---------------------
+
+Sets the transmission power of the radio. Argument is a pointer to a ``int32_t``
+containing the desired transmission power in 0.01 dBm. After setting the
+transmission power successfully, this pointer will contain the new transmission
+power. This value may be different from the desired value, but will be the
+closest available setting that is greater than or equal to the desired value.
+
+.. code-block:: c
+
+  int32_t txpower = 1200;
+  err = ioctl(radio, WLIOC_SETTXPOWERF, &txpower);
+  printf("Actual TX power: %.2f dBm\n", txpower / 100.0f);
+
+``WLIOC_GETTXPOWERF``
+---------------------
+
+Gets the current transmission power level in 0.01 dBm. The argument is a pointer
+to a ``int32_t``.
+
+.. code-block:: c
+
+   int32_t txpwr;
+   err = ioctl(radio, WLIOC_GETTXPOWER, &txpwr);
+
+``WLIOC_SETBANDWIDTH``
+----------------------
+
+Sets the operating bandwidth of the radio module. The argument is the desired
+bandwidth in kHz (``uint32_t``). The radio only supports exact values of 125,
+250 and 500.
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_SETBANDWIDTH, 250);
+
+``WLIOC_GETBANDWIDTH``
+----------------------
+
+Gets the current operating bandwidth of the radio module in kHz. The argument is
+a pointer to a ``uint32_t``.
+
+.. code-block:: c
+
+   uint32_t bandwidth;
+   err = ioctl(radio, WLIOC_GETBANDWIDTH, &bandwidth);
+
+``WLIOC_SETSPREAD``
+----------------------
+
+Sets the operating spread factor of the radio module. The argument is a
+``uint8_t`` containing the desired spread factor between 7 and 12 (inclusive).
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_SETSPREAD, 8);
+
+``WLIOC_GETSPREAD``
+----------------------
+
+Gets the current operating spread factor of the radio module. The argument is a
+pointer to a ``uint8_t``.
+
+.. code-block:: c
+
+   uint8_t spread;
+   err = ioctl(radio, WLIOC_GETSPREAD, &spread);
+
+``WLIOC_SETPRLEN``
+----------------------
+
+Sets the operating preamble length of the radio module. The argument is a
+``uint16_t`` containing the desired preamble length.
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_SETPRLEN, 8);
+
+``WLIOC_GETPRLEN``
+----------------------
+
+Gets the current operating preamble length of the radio module. The argument is
+a pointer to a ``uint16_t``.
+
+.. code-block:: c
+
+  uint16_t prlen;
+  err = ioctl(radio, WLIOC_GETPRLEN, &prlen);
+
+``WLIOC_SETMOD``
+----------------------
+
+Sets the operating modulation of the radio module. The argument is one of the
+values in ``enum rn2xx3_mod_e``.
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_SETMOD, RN2XX3_MOD_FSK);
+
+``WLIOC_GETMOD``
+----------------------
+
+Gets the current operating modulation of the radio module. The argument is a
+pointer to an ``enum rn2xx3_mod_e``.
+
+.. code-block:: c
+
+   enum rn2xx3_mod_e modulation;
+   err = ioctl(radio, WLIOC_GETMOD, &modulation);
+   if (modulation == RN2XX3_MOD_LORA)
+     {
+       printf("LoRa modulation!\n");
+     }
+
+``WLIOC_RESET``
+---------------
+
+Resets the RN2xx3 radio module. This command takes no arguments.
+
+.. code-block:: c
+
+   err = ioctl(radio, WLIOC_RESET, 0);
+
+``WLIOC_SETSYNC``
+-----------------
+
+Sets the sync word parameter of the RN2xx3 module. The argument is a pointer to
+a ``uint64_t``. Please note that when operating using FSK modulation, the sync
+word can be a full 8 bytes (64 bits), but LoRa modulation only accepts a single
+byte sync word.
+
+.. code-block:: c
+
+   /* Radio in FSK mode prior to this call */
+
+   uint64_t syncword = 0xdeadbeefdeadbeef;
+   err = ioctl(radio, WLIOC_SETSYNC, &syncword);
+
+``WLIOC_GETSYNC``
+-----------------
+
+Gets the sync word parameter of the RN2xx3 module. The argument is a pointer to
+a ``uint64_t``.
+
+.. code-block:: c
+
+   uint64_t syncword;
+   err = ioctl(radio, WLIOC_GETSYNC, &syncword);
+
+``WLIOC_SETBITRATE``
+--------------------
+
+Sets the bit rate of the RN2xx3 module. The argument is a ``uint32_t``. The
+bit rate only applies to the module when it is in FSK modulation mode, and it
+must be between 1 - 300000.
+
+.. code-block:: c
+
+   /* Radio in FSK mode prior to this call */
+
+   err = ioctl(radio, WLIOC_SETBITRATE, 300000);
+
+``WLIOC_GETBITRATE``
+--------------------
+
+Gets the configured bit rate of the RN2xx3 module. The argument is a pointer to
+a ``uint32_t``.
+
+.. code-block:: c
+
+   uint32_t bitrate;
+   err = ioctl(radio, WLIOC_GETBITRATE, &bitrate);
+
+``WLIOC_IQIEN``
+---------------
+
+Enables the invert IQ functionality of the module. The argument is boolean of
+either true (non-zero) or false (zero).
+
+.. code-block:: c
+
+   /* Enables IQI */
+
+   err = ioctl(radio, WLIOC_IQIEN, 1);
+
+``WLIOC_CRCEN``
+---------------
+
+Enables adding a CRC header to packets. The argument is a boolean of either true
+(non-zero) or false (zero).
+
+.. code-block:: c
+
+   /* Enables CRC */
+
+   err = ioctl(radio, WLIOC_CRCEN, 1);
+
+``WLIOC_SETCODERATE``
+---------------------
+
+Sets the coding rate of the RN2xx3 module. The argument is one of the values in
+``enum rn2xx3_cr_e``.
+
+.. code-block:: c
+
+   /* Sets 4/7 coding rate */
+
+   err = ioctl(radio, WLIOC_SETCODERATE, RN2XX3_CR_4_7);
+
+``WLIOC_GETCODERATE``
+---------------------
+
+Gets the currently configured coding rate of the RN2xx3 module. The argument is
+a pointer to an ``enum rn2xx3_cr_e``.
+
+.. code-block:: c
+
+   enum rn2xx3_cr_e coderate;
+   err = ioctl(radio, WLIOC_GETCODERATE, &coderate);

drivers/wireless/lpwan/Kconfig

@@ -5,6 +5,17 @@
 
 if DRIVERS_LPWAN
 
+config LPWAN_RN2XX3
+	bool "Microchip RN2xx3 driver support"
+	default n
+	select UART # TODO what to select?
+	---help---
+        Enable driver support for the RN2xx3 LoRa radio transceiver.
+
+if LPWAN_RN2XX3
+
+endif # LPWAN_RN2XX3
+
 config LPWAN_SX127X
 	bool "SX127X Low Power Long Range transceiver support"
 	default n

drivers/wireless/lpwan/Make.defs

@@ -25,5 +25,6 @@
 ifeq ($(CONFIG_DRIVERS_LPWAN),y)
 
 include wireless/lpwan/sx127x/Make.defs
+include wireless/lpwan/rn2xx3/Make.defs
 
 endif # CONFIG_DRIVERS_LPWAN