[FEATURE] Common interface for LORA chips

[raiden00pl]

Is your feature request related to a problem? Please describe.

Currently NuttX supports only sx127x but more drivers for LORA are coming. All these drivers should use the same common API, so that it will be possible to create portable user applications.

This most likely will involve breaking changes for sx127x (easy to detect and fix compiler errors).

The problem is partly due to a decision that I made a long time ago when adding sx127x support with Greg approval, that the LORA chips in NuttX would be character drivers, not network devices. The reason for this is that edge devices supporting LORA are low-power devices with limited resources. For such devices, supporting the network stack is a waste of resources.
The result of this decision is that we cannot use the portable interface provided by the network stack and we have to design a portable interface as a character device.

We want to avoid the fate of legacy sensors where there was no common interface, making it impossible to create portable applications with them.

Here are two PRs that add another LORA chips:

• drivers/wireless: Add support for the RN903 and RN2483 LoRa modules #15828
• Initial standalone sx126x driver [WIP] #15795

Describe the solution you'd like

Common API for LORA chips.

Describe alternatives you've considered

No response

Verification

• I have verified before submitting the report.

[keever50]

my idea was to use the current WLIOC, but extend it with the modulation. ex: WLIOC_LORA, WLIOC_GFSK, WLIOC_OOK, WLIOC_QPSK etc. LoRa devices often can use multiple modulation techniques like that.
It would be way easier to spot mistakes of misplaced wlioc commands. (gfsk fdiv on a lora modulation mode. Not possible).

This allows you to have
WLIOC_LORA_BW
WLIOC_LORA_SF
these are common across all lora devices so far i know.

And leave the WLIOC_SET_FREQ and WLIOC_SET_PWR as is. These are common across nearly all RF chips. Except for the super cheap ones.

Then there are some more specific commands such as CRC, fixed header etc. I guess these can be left in familly specifics. Obviously with default values.

The result would be an API that all apps can work with. Including ones that allow adaptive data rate, like LoRaWAN.

[raiden00pl]

@keever50 it's a good idea to introduce 3 levels of ioctl: 1. common RF commands, 2. modulation specific commands, 3. chips specific commands. However, the last type of commands should be avoided if possible, but I understand that it may be necessary in some cases.

The ultimate goal should be an API enabling support for LoRaWAN. I haven't been following the LoRaWAN topic for a while, but the last time I saw 'loramac-node' implementation from Semtech it was awful, so I gave up on porting it to NuttX.

[linguini1]

I suppose this common interface would also still involve having read and write as rx/tx?

[raiden00pl]

yes, read and write should be used. But in addition to the data itself, metadata such as RSSI or SNR should be returned if available from the driver.

[linguini1]

yes, read and write should be used. But in addition to the data itself, metadata such as RSSI or SNR should be returned if available from the driver.

Maybe as an ioctl?

[raiden00pl]

Maybe as an ioctl?

I don't think so. This should be returned at the same time as the data from radio. Here is example how it's done for ieee802154:

nuttx/include/nuttx/wireless/ieee802154/ieee802154_device.h

Lines 52 to 64 in ff4d461

	struct mac802154dev_rxframe_s
	{
	struct ieee802154_data_ind_s meta;
	uint8_t payload[IEEE802154_MAX_PHY_PACKET_SIZE];
	uint8_t length;
	/* In promiscuous mode, the entire frame is passed to the application
	* inside the payload field. The offset field is used to specify the start
	* of the actual payload, skipping the 802.15.4 header.
	*/
	uint8_t offset;
	};

[keever50]

I used the SX127x way in my SX126x already, but i guess we also need to standardize this too.

nuttx/include/nuttx/wireless/lpwan/sx127x.h

Lines 113 to 124 in ff4d461

	#ifdef CONFIG_LPWAN_SX127X_RXSUPPORT
	/* RX FIFO data */
	struct sx127x_read_hdr_s
	{
	uint16_t datalen;
	int8_t snr;
	int16_t rssi;
	uint8_t reserved[3];
	uint8_t data[SX127X_READ_DATA_MAX];
	};
	#endif

The signal information is quite nice to have in the packet.
I also provided a crc_error variable in my own variant.
Its ofcourse 1 when there is a CRC check error. Otherwise always 0.
Useful for when the user wants to repair the packet.

Maybe nice to have in the common interface.

I am not sure what the reserved bytes are for?

[keever50]

I'm not sure what is the best way to figure out together what the best common interface is going to be and how to make one. What about the mailing list?
But maybe this is a good starting point.
How about the following

— IOCTL —
Common:

• WLIOC_COM_FREQ // Hz
• WLIOC_COM_PWR // Power ( in dBm or mW? )
• WLIOC_COM_PREAMBLES // Bytes
• WLIOC_COM_MOD // Modulation technique ( Maybe? )

LoRa:

• WLIOC_LORA_SF // Spreading factor
• WLIOC_LORA_BW // Bandwidth
• WLIOC_LORA_CR // Code rate
• WLIOC_LORA_CRC // CRC enable (enables CRC bytes)
• WLIOC_LORA_FIXED_HDR // Fixed header length (enables length byte)
• WLIOC_LORA_SYNCWORD // Syncword bytes (Include length?)

Specific implementations

• WLIOC_model_function

— Read header —

• Payload bytes
• Payload length
• RSSI // What format?
• SNR // What format?
• Error // Comes from CRC or checksums

Now, because IOCTL is a limited resource,
is it a good idea to compact some parameters into a struct?
It is done already in some implementations (including in mine).
I configure the entire lora modulation using one struct.