SubGHz API

[QuantumEF]

Looking at the documentation, it looks like there currently is no SubGHz Rust API. I wanted to confirm that is the case, and also ask if anyone has started on this. If not, how can I help get started on this? My assumption is to start by reviewing the flipperzero-sys crate and the bindings to the SubGHz items in there? Any suggestions on how I should start laying this out any making this API would be appreciated.

[dcoles]

Hi @QuantumEF,

That's correct. No one has taken a look at wrapping the SubGHZ API yet, so it's up for grabs!

Typically the approach I've been using has been:

1. Write a program that uses the low-level Flipper API in question to understand how it works
   • The best source of reference for this is a similar app from flipperzero-firmware (e.g. subghz_cli.c)
   • The flipperzero-sys crate contains automatically generated bindings to all the public symbols (the ones that begin with Function,+,) and use the same names as the C APIs
   • At this stage, you'll need to make heavy use of unsafe blocks (the FFI section of the Rustonomicon is very useful here)
2. Start cleaning up this program so that it's more idiomatic Rust
   • A lot of this is working out "safe" ways to make use of the "unsafe" flipperzero_sys APIs
   • Usually this involves some sort of wrapper class (the i2c module is a good example)
   • Try to use the same concepts as the C API, rather than making a totally new interface
3. Add these high-level wrapper classes to the flipperzero crate
   • Generally the module layout should match the import path of the equivalent C header
   • FuriString should generally be used rather than depending on alloc::String

Straight function calls aren't too bad. Usually the most tricky parts are dealing with callbacks as they need to be extern "C". We don't really have a great general-purpose way of bridging these without having to perform extra allocations.

[QuantumEF]

Thank you for the advice on how you have approached this problem and some pointers on specific items to look at! I already have a project in mind, so I will start slowly looking into how I am going to get it to work.

[QuantumEF]

So, having done some looking into this, it would be best for work on the SPI to be included first so that I can work with that API.
I see there is an open draft pull request #113, @str4d mentions in issue #117 that they are still working on including the embedded-hal traits.

@str4d, are you still working on #113 or have you abandoned it for now? I am willing to help with this, but I am going to need to first familiarize myself better with the embeded-hal traits.

[QuantumEF]

Another Update based on my research:
It looks like most of the furi_hal_subghz functions are making calls to the furi_hal_spi and furi_hal_gpio apis, so I am probably going to focus my effort on contributing to those sections and have the SubGhz api provided by this project utilize the safe abstractions that will eventually be implemented with the Spi and Gpio abstractions. Then I can use a crate like https://docs.rs/cc1101/latest/cc1101/ to interface with the SubGhz module itself.

That being said there are some functions like LL_TIM_EnableCounter that do not seem to be provided by the flipperzero-sys crate, so I will probably have to use those functions as is. This mainly seems to be the case for the async functions.

[QuantumEF]

Another Update:

So my original plan was flawed for a few reasons.
Like in the above post, I was planning on using the cc1101 create to interface simple because of code reuse, but there are two problems with this:

1. Usage of the cc1101 create would not properly set the RF switch to operate on the correct path.
2. The FuriHalBus Docs say

Below is the list of peripherals that are enabled and disabled by the system. The user code must avoid using them directly, preferring the respective APIs instead.

I imagine this is for good reason as (like mentioned in 1.) the RF switch, this api also provides the guards for accidentally transmitting out of the permitted frequency range.

Part of the original reason I wanted to use the cc1101 crate was because the furi api felt a bit clunking when it came to working with custom configurations. Further, I was hoping to utilize more safe abstractions around lower level code that cannot really have safe abstractions written around it. This also means I have some new comments to add for #113.

My new plan is to create some sort of nice "preset builder" to create a "nice" interface.

It would still be nice to work with lower level items to fully utilize rusts type system, but oh well, maybe another day.

[str4d]

@str4d, are you still working on #113 or have you abandoned it for now? I am willing to help with this, but I am going to need to first familiarize myself better with the embeded-hal traits.

I haven't had much time in the past year, but am back around now and will figure out what the current state of GPIO is (which is what I said in #117 I was waiting on in order to unblock #113).