Consolidate all LORA physical layer implementations behind one API

[ceekdee]

This issue arises out of the discussion regarding the recent addition of an implementation to support the Semtech sx126x LORA chips:

#985 (comment)

I hope to start working on this project in December, or to contribute to other initiatives that start before then. In the meantime, this issue serves as a launchpad for a discussion on expectations developers have for a LORA physical layer implementation and API that supports Semtech LORA chips and MCU variants. It would be most helpful if envisioned use cases can be added here to shape the discussion.

My personal focus at this time is on a point-to-point (P2P) implementation that requires only the LORA physical layer. However, I see great value in interfacing the physical layer implementation with - for example - the Drogue IoT project.

[lulf]

Commenting here instead of #1041

A brief synopsis of architectural thoughts to this point for the implementation in issue 1023. A bit premature, but I will be unavailable to work on an implementation until the end of November and want to encourage other thoughts.

• produce a trait that describes LoRa API functions that are prevalent across Semtech chips (the base API, largely present in the sx126x implementation - https://github.com/embassy-rs/embassy/blob/master/embassy-lora/src/sx126x/sx126x_lora/mod.rs - which closely followed the Semtech C implementation);
• produce additional traits for LoRa API functions unique to different flavors of Semtech chips;
  *implement enums and structs which support the various concerns represented across the full API, making each as generic as possible to support present and future LoRa chips (this will build on the separation of concerns in the stm32wl driver);
• implement an orchestrator for each MCU/LoRa chip combination. For example, the rak4631 will have an orchestrator, as will a STM32 nucleo board;
• each orchestrator is a lightweight implementation which grabs the device-specific pins and SPI bus and assembles the necessary enums and structures to support the MCU/LoRa chip combination;
• the LoRa generic and board-specific API for an MCU/LoRa chip combination will be accessed through the orchestrator.

I agree on the approach. However, in terms of where this happens, I think we should leave board-specifics out of embassy-lora itself, and perhaps surface the orchestrator concept, at least initially, in a separate create (some kind of BSP?). Most likely outside the embassy main repo? I think what you're describing is not only a solution for lora specifically, but a pattern that applies to other types of networking.

With all these traits its also a potential downside of making the APIs a bit harder to use, so keeping embassy-lora somewhat focused on the drivers + integrating with rust-lorawan I think is the appropriate scope for that, because some might want to use it at that level rather than binding to some orchestrator for their board.

[ceekdee]

Adding additional comment moved from #1041:

Perhaps a better way to envision the "orchestrator" is as a builder which returns a LoRa structure supporting the API for an MCU/LoRa chip combination.

Since the only current interfaces to Semtech chips of which I am aware are SPI and pin setting/checking, the hope is to hide any dependencies on STM32WL or nRF52 for this behind the LoRa API.

[ceekdee]

@jbeaurivage, @lulf: I am back after a 3 week hiatus.

I am making a note here regarding the fix in #1064. We will need to consider the setting of the polarity bit for both the LoRa P2P case and the LoRaWAN case. I assume that for the P2P case inverted polarity should not be set. Perhaps the P2P case should not use PhyTxRx.

[jbeaurivage]

Agreed; considering that PhyTxRx is a construct specific to lorawan-device it probably shouldn't be used for non-LoRaWAN operations.

[ceekdee]

It appears that to this point the Embassy emphasis within lora has been on the LoRaWAN use case, so I'm not sure whether PhyTxRx should be solely a LoRaWAN construct when P2P is considered. In any case, I will need to adjust the Embassy repository's P2P examples sooner rather than later to support our decision.

LoRa P2P is quite useful. I believe it supports Meshtastic's off grid communication project, and I have used it in order to hand my neighbor a device that receives and reports - as an example - my home's temperature while I am away. Our homes are separated by a significant distance, so it helps that they can be alerted to a malfunctioning furnace remotely.

[jbeaurivage]

LoRa P2P is quite useful.

Oh no doubt, all I'm saying is that PhyTxRx is a trait provided by lorawan-device. Maybe we'd be better off making that dep optional behind a lorawan Cargo feature? We can certainly also provide P2P impls with sane defaults for the modulation/packet parameters.

[lulf]

So, the original intent for embassy-lora was to be an integration point between lorawan-device and embassy HALs.

As I think you correctly point out, there is a useful use case for LoRa P2P as well. An alternative to adding a lorawan feature flag to enable that integration would be to move the existing stuff into a new crate embassy-lorawan and then use the existing embassy-lora for the basic lora functionality/parameters.

However, is also some work ongoing in rust-iot/radio-hal#24 - and I'm wondering if time would be better spent making that work with async/embassy, as it would probably cover most of the functionality for LoRa p2p. The additional work would then to make the lorawan-device work with the 'radio-hal' drivers.

At the time when embassy-lora was created, there was no embedded-hal-async, so keeping it inside embassy was the easiest. Now I think maybe more of the drivers could live in radio-hal (which would need to use embedded-hal-async), and only the bits that depend on embassy HALs need to live in the embassy repo.

Thoughts?

[ceekdee]

It should be easy enough for me to open a separate issue to fix the LoRa P2P examples to use Sx1262xRadio's lora implementation directly.

Hopefully the automatic GitHub reference placed in the pertinent radio-hal pull request will gauge interest within that team.

The decision comes down to what functionality Embassy itself should encompass. There was a decision to place the BLE implementation represented by nrf-softdevice outside Embassy. LoRa also provides device-device communication, so maybe it should also move out of Embassy. And then what does that mean for embassy-net?

However, given the trouble I've had getting both LoRa and BLE functionality to cargo up together to use the full functionality of the RAK4631 module, I'd currently vote to keep LoRa in Embassy and move BLE in there :). To be fair, I haven't put much effort into hammering LoRa/BLE together and realize prospects will improve as these features head toward release.

[lulf]

First of all, let me say I'm very grateful for your contributions to embassy-lora and embassy, and I hope you will continue to feel motivated for that. So please take my disagreement with your stance only as a disagreement. And in any case, it's just my personal opinion, I'm happy for things to go in a different direction if that's what other maintainers want.

It should be easy enough for me to open a separate issue to fix the LoRa P2P examples to use Sx1262xRadio's lora implementation directly.

Hopefully the automatic GitHub reference placed in the pertinent radio-hal pull request will gauge interest within that team.

The decision comes down to what functionality Embassy itself should encompass. There was a decision to place the BLE implementation represented by nrf-softdevice outside Embassy. LoRa also provides device-device communication, so maybe it should also move out of Embassy. And then what does that mean for embassy-net?

My take is that Rust/Cargo already has a mechanism for writing independent libraries that compose with traits + crates.io. IMO the reason for keeping a module in the embassy repo itself is that it

a. is not releasable (yet) and depended on by the HALs or the executor
c. significantly simplifies the issue tracking, CI and release process

The downside of having a module in embassy repo is that it increases the review, CI and release bottleneck of the module itself.

The reason why embassy-net and embassy-lora is in the tree is a bit historical: there was no public embedded-nal-async, embedded-io, embassy-time or embassy-sync crates. However, embassy-stm32 depends on embassy-net, which is something you don't have for embassy-lora.

The reason why nrf-softdevice is not in embassy I don't know, but I think it makes sense to keep it separate, especially now that it doesn't directly depend on embassy other than utlities like embassy-sync, and softdevice also being deprecated by Nordic, so it doesn't really make sense to add that now.

Now that embedded-hal-async exists, drivers like sx127x or sx126x only really needs to rely on those gpio and SPI traits. The added benefit is that those drivers can be used in frameworks like RTIC or on an ESP32 easily without depending on embassy, which is a win-win for everyone. Keeping them in embassy will make it perceived to be embassy-specific, and it makes changes and releasing those drivers a slower process. Keeping them in a separate repo will be easier because there will be a smaller set of maintainers that are focused on those drivers instead.

stm32wl is a bit of a special case where there is a dependency on embassy-stm32, but I don't think it should drive the direction. I'm sure we can figure something out for that.

However, given the trouble I've had getting both LoRa and BLE functionality to cargo up together to use the full functionality of the RAK4631 module, I'd currently vote to keep LoRa in Embassy and move BLE in there :). To be fair, I haven't put much effort into hammering LoRa/BLE together and realize prospects will improve as these features head toward release.

To summarize my stance: I think that would be moving in the wrong direction, and you loose the benefits you get when there is a dependency manager like cargo, an ecosystem like crates.io, and the standardized traits where you can mix and match. I'm not against having examples in embassy that tie everything together.

In any case I think @Dirbaio should have the final say in where we're heading.

[ceekdee]

Excellent response! I do not have the big picture here, and this response helps. While I'll start implementing the LoRa consolidation feature (the root subject of this issue) in Embassy itself, it should be easy to move it to a better crate as this shakes out. I will also review the embedded-hal-async crate in detail to ensure the LoRa consolidation feature relies on it for SPI and GPIO.