Proposal: Common IOCTL API for RF Modulation Technologies

[Kevin Witteveen]

Hi Nuttx,

This is a follow-up to GitHub issue #15856
 initiated by raiden00pl. The
discussion there provides useful context for this proposal.

*--- Summary ---*
Currently, the IOCTL API for character-driven RF devices lacks a common
interface across different modulation technologies, such as LoRa, FSK, and
OOK. As a result, driver-specific IOCTL commands are created even when they
could be shared across multiple radios. This fragmentation makes
application portability more difficult to maintain.

*--- Impact ---*
This does require some changes to be made to 4 RF drivers.

   - My SX126x (New, experimental)
   - Raiden SX127x,
   - Linguini RN2xx3 (New, experimental)
   - nRF

The three of us—Raiden, Linguini, and I—support this idea and are already
involved in the development. Once implemented, this common API would make
it easier for IoT applications to run on NuttX with minimal driver-specific
modifications, reducing maintenance overhead and eliminating redundant
implementations.

*--- Breaking ---*
This is considered a breaking change if the following IOCTL command may be
changed:

WLIOC_SETTXPOWER takes an integer value for dB. This can be changed to
steps of 1/100 dB instead. Because the RN2xx3 and some radios can take
smaller values. (*Open for discussion)*

However, the RN2xx3 and SX126x drivers are marked experimental, so any
modifications to these are *not* considered breaking.

*--- Strategy ---*

   1. Introduce new IOCTL commands without modifying legacy implementations.
   2. Gradually migrate existing drivers to the new API while testing and
   documenting.
   3. Remove legacy implementations

To avoid breaking changes, we could retain the legacy APIs if desired and
only remove the *experimental* ones.

*--- Proposal API header ---*
https://github.com/keever50/nuttx/blob/common_wireless_character_driver_API/include/nuttx/wireless/ioctl.h
I collaborated with Raiden and Linguini on defining these IOCTL commands.
Feedback and suggestions from the community would be greatly appreciated.

*--- Note about "Experimental" ---*
The SX126x and RN2xx3 drivers are marked as experimental, meaning users are
explicitly warned that changes may occur in the near future. They were
labeled as such before being merged.

Looking forward to your thoughts!

Best regards,

Kevin (Keever50 on github)

Re: Proposal: Common IOCTL API for RF Modulation Technologies

[Nathan Hartman]

Hi all,

I like the fact that there has been a high level analysis here and an
effort to make things consistent across multiple types of communications.

Since the drivers mentioned are experimental, I agree that breaking changes
aren't breaking stabilized interfaces.

We should just be careful to mention this in the release notes because this
could create a long debugging session for someone.

Here's an idea: there could be a Kconfig that must be defined if using any
of these drivers. Some kind of
CONFIG_I_KNOW_ABOUT_THE_BREAKING_CHANGES_IN_THE_RF_DRIVERS. (That should
*not* be its name; I'm only writing it to illustrate my idea.) If this
Kconfig isn't present, #ifdef logic in the source code will deliberately
break the build with #error directive, and adjacent documentation in the
comments. This will ensure that nobody using the ioctl as it currently is
will have any head scratching and long debugging session. Thoughts?

Nathan

On Thu, Mar 13, 2025 at 4:50 PM Kevin Witteveen 
wrote:

> Hi Nuttx,
>
> This is a follow-up to GitHub issue #15856
>  initiated by raiden00pl.
> The
> discussion there provides useful context for this proposal.
>
> *--- Summary ---*
> Currently, the IOCTL API for character-driven RF devices lacks a common
> interface across different modulation technologies, such as LoRa, FSK, and
> OOK. As a result, driver-specific IOCTL commands are created even when they
> could be shared across multiple radios. This fragmentation makes
> application portability more difficult to maintain.
>
> *--- Impact ---*
> This does require some changes to be made to 4 RF drivers.
>
>- My SX126x (New, experimental)
>- Raiden SX127x,
>- Linguini RN2xx3 (New, experimental)
>- nRF
>
> The three of us—Raiden, Linguini, and I—support this idea and are already
> involved in the development. Once implemented, this common API would make
> it easier for IoT applications to run on NuttX with minimal driver-specific
> modifications, reducing maintenance overhead and eliminating redundant
> implementations.
>
> *--- Breaking ---*
> This is considered a breaking change if the following IOCTL command may be
> changed:
>
> WLIOC_SETTXPOWER takes an integer value for dB. This can be changed to
> steps of 1/100 dB instead. Because the RN2xx3 and some radios can take
> smaller values. (*Open for discussion)*
>
> However, the RN2xx3 and SX126x drivers are marked experimental, so any
> modifications to these are *not* considered breaking.
>
> *--- Strategy ---*
>
>1. Introduce new IOCTL commands without modifying legacy
> implementations.
>2. Gradually migrate existing drivers to the new API while testing and
>documenting.
>3. Remove legacy implementations
>
> To avoid breaking changes, we could retain the legacy APIs if desired and
> only remove the *experimental* ones.
>
> *--- Proposal API header ---*
>
> https://github.com/keever50/nuttx/blob/common_wireless_character_driver_API/include/nuttx/wireless/ioctl.h
> I collaborated with Raiden and Linguini on defining these IOCTL commands.
> Feedback and suggestions from the community would be greatly appreciated.
>
> *--- Note about "Experimental" ---*
> The SX126x and RN2xx3 drivers are marked as experimental, meaning users are
> explicitly warned that changes may occur in the near future. They were
> labeled as such before being merged.
>
> Looking forward to your thoughts!
>
> Best regards,
>
> Kevin (Keever50 on github)
>

Re: [BREAKING] boot/nxboot: enhance bootloader capabilities and decision logic

[Sebastien Lorquet]

Thanks for this message.

I have reviewed the pull request and I approve these changes given the 
described context.


The tests coverage looks good.

I suggest a short notice in the release notes *summary* (that will be 
read by more people), as historical information for future users that 
could wonder about functionality changes.


Sebastien


On 13/03/2025 05:11, Tomek CEDRO wrote:

Hello world :-)

Michal Lenc is proposing new interesting features in nxboot but that
will break current nxboot compatibility, please review the PR and join
the discussion :-)

https://github.com/apache/nuttx-apps/pull/3024


### Summary

This commit enhances the bootloader capabilities. The image's header
is extended with header version, size, platform identifier and pointer
to optional next header. CRC32 now includes part of the header in its
calculation as well.

The change also avoids having two different magics for image uploaded
over programmer and update image. Both these images have the same
magic and this magic is changed internally by the bootloader's logic.
The change is needed because image with standard magic is
automatically considered as a confirmed image (uploaded with
programmer).

The current implementation avoids tails at all, therefore the user
application uploading the image does not have to erase the tail before
new upload. The image is considered as confirmed if it has standard
magic or its recovery is present. This means the bootloader has to
erase the header of the update image after the update is done (to
avoid update loop and to mark the image as unstable). This page is
written back during the confirmation.

This is a breaking change, but necessary for the future development of
the bootloader. The added header version field will allow to add
minor/major updates while keeping the backwards compatibility.

### Impact

Breaking change for nxboot bootloader. I think no one is using it so
far (except for us at Elektroline), so it should not be a big issue.
This also adds version field in the header so future breaking changes
could be tracked easily. It is also a better and more user friendly
design, so I think these advantages are big enough to break the old
images that are not used by anyone so far.

Documentation updated at apache/nuttx#15981

### Testing

Tested on SAMv7 custom board with various scenarios:

 revert after update
 confirm after update
 multiple updates in a row
 board power restarts during recovery creation, update and revert processes

All these scenarios lead to the valid image in primary slot.

@michallenc