Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

implement nRF24L01 driver #1

Draft
wants to merge 52 commits into
base: main
Choose a base branch
from
Draft

implement nRF24L01 driver #1

wants to merge 52 commits into from

Conversation

2bndy5
Copy link
Member

@2bndy5 2bndy5 commented Jul 9, 2024 •
edited
Loading

  • add source code to drive the nRF24L01
  • add a build/test/lint CI workflows; no release CI for crates.io (yet)
  • add unit tests using embedded-hal-mock (and activate codecov)
  • add (Linux only) FFI bindings (consider FFI bindings #2)
    • python binding
    • node binding
  • add examples
    • python examples
    • node.js (typescript) examples
    • rust examples

@2bndy5 2bndy5 added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 9, 2024
2bndy5 added 2 commits July 9, 2024 06:26
@2bndy5
push work in progress
281707d
@2bndy5
add .github folder
76b9d59 
includes
- CI workflow
- funding info
- dependabot config
2bndy5 added 6 commits July 9, 2024 06:44
@2bndy5
unify error type in impl EsbRadio for RF24
7c32533
@2bndy5
mark crate with ![no_std]
a397862
@2bndy5
prefer u8 over usize for memory footprint
2a571e1
@2bndy5
doc updates
541e3c2
@2bndy5
remove endian manipulation (for now)
f3d23af
@2bndy5
refactor modules
0d613e3 
- prefer to `use rf24_rs::radio::prelude::*` in user code to pull in all the required radio traits.
- support LNA_CUR bit in non-plus/clones
- prefer to `use rf24_rs::radio::{RF24 Nrf24Error}` in user code
  because namespaces will be very important in the future
@2bndy5 2bndy5 changed the title impement nRF24L01 driver implement nRF24L01 driver Jul 10, 2024
@codecov-commenter
Copy link

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

2bndy5 added 6 commits July 10, 2024 17:21
@2bndy5
update README
7051e01 
- add badges
- tick first milestone in roadmap
@2bndy5
complete unit tests 🎉
0edefdd
@2bndy5
ignore doc snippet in tests
3c62d56
@2bndy5
add package metadata
fbd92ff
@2bndy5
use macro to reduce duplicated code in unit tests
53a4137 
rust is so cool!

This new macro generates rust code at compile time and then compiles everything with the generated code in place of the macro calls.
@2bndy5
cast bool input as u8 when clearing status flags
8cf3280 
removes the need to construct a mutable byte
@2bndy5
Copy link
Member Author

2bndy5 commented Aug 1, 2024 •
edited
Loading

This is just an informative collection of my thoughts, and reasons why I paused this development.

Examples

Here's the chips I'm looking to support (initially) in the examples:

  • The implementation of embedded-hal on Linux for SoM (System on Module) boards is freakishly easy to use.
  • The implementation of embedded-hal on RP2040 is designed to be run as bare metal (no RTOS).
  • The implementation of embedded-hal on ATSAMD seems to have abstractions for various related boards (which seem to be recommended in docs).
  • The implementation of embedded-hal on AVR (supports ATmega238 and ATTiny chips) is not even published to crates.io. This is odd and a bit of a red flag for me. I could pin to a git source using a commit SHA or tag, but the process of uploading the compiled binaries recommends using a tool that wraps around the AVRdude tool used by the Arduino IDE (see ravedude).
  • The implementation for embedded-hal on Nordic chips has several abstractions based (probably generated from) on the dev kit for each supported chip (ie nRF52840-hal). It is designed to be used on bare metal (no RTOS) and does not employ a softdevice (which is supported in the embassy project -- see below).
  • The implementation for embedded-hal on esp32 seems to be a rust binding to the ESP-IDF (written in C). Like the ESP-IDF, the embedded-hal for esp32 uses a custom tool to build and upload binaries to the board.

Writing the examples is tough. The embedded-hal implementations for various chips are not conformed like the Arduino Cores for various chips families. Writing an example for the RP2040 will look significantly different from an example for the ATSAMD21.

Due to this complexity, I've decided to try and put the examples in its own "crate" (a rust term for a library) in a sub-directory named "examples". This way I can allow users to control which chip to compile for using cargo features defined in examples/cargo.toml.

Furthermore, flashing the compiled binary to a board requires a separate dependency called probe.rs. This is another reason why the examples need to use a separate crate.

Embassy Project

There is an embassy project that focuses on some SoC (System on Chip) that employ an RTOS. This seems useful for multi-processing, but it is ultimately unnecessary for simple examples. Nonetheless, I could use this embassy project for ESP32, RP2040, and nRF5x chips because they seem to have a somewhat unified API for those chips (I think).

No STD libs in embedded-hal

See the embedded-hal book about rationale. Basically, driver libraries for embedded-hal projects cannot use rust's standard libraries. This includes Vec, BTreeMap data collections because it involves allocating memory at runtime.

This will be a problem down the road when I get around to implementing the Mesh layer because we need a way to dynamically allocate memory as Logical Addresses are assigned to a mesh node's ID. There are third party libs that aim to accommodate this shortcoming, but I'll cross that bridge when I get there.

Tip

The embeded-hal implementations on Linux and ESP32 boards can use the std libs. 🎉

The embedded-hal framework (which doesn't impose embedded-hal implementations use uniformed API names for data structures) had been in beta for years. It only reached a stable release in Jan 2024. This fact has caused a side effect that can be seen in many embedded-hal implementations; they still support embedded-hal framework v0.2.x (the last beta release) as an optional cargo feature. This driver library will only support v1+ of the embedded-hal framework (unless requested otherwise).

@2bndy5 2bndy5 force-pushed the impl-rf24 branch 2 times, most recently from aec4db1 to 6031361 Compare October 8, 2024 06:07
@2bndy5
switch to monorepo
e8c4717 
introduce supplemental docs (using mkdocs) and WIP examples (incomplete at this time)

migrate to using [just](https://just.systems) as a task runner and utilize it in CI jobs.
This was linked to issues Oct 27, 2024
rename listen methods #3
Open
consider FFI bindings #2
Open
@2bndy5 2bndy5 force-pushed the impl-rf24 branch 5 times, most recently from 6b84c93 to d747b35 Compare October 29, 2024 09:33
@2bndy5
Copy link
Member Author

2bndy5 commented Oct 29, 2024 •
edited
Loading

image

Click here for information about interpreting this report.

image

2bndy5 added 2 commits October 29, 2024 22:02
@2bndy5
another refactor
06f1b25 
considering we might be distributing multiple rust crates from 1 repo.

also review rust docs
- added API layout to landing page
- filled in some missing info in functions' docs

review `print_details()` output
- show pipe information in `print_details()`
- show TX address in `print_details()`
- fix IRQ settings' output
@2bndy5
add tests
9d4b6ed 
improves some line and region coverage
@2bndy5 2bndy5 force-pushed the impl-rf24 branch 3 times, most recently from 47f9a35 to a959097 Compare October 30, 2024 07:13
@2bndy5
implicitly cast to bool in bindings
29581f2 
Only the node binding's `StatusFlags` and `WriteConfig` interfaces must use explicit boolean values.
To implicitly cast those interfaces' values to boolean would
- incur much more overhead
- lose precise typing information

See napi-rs docs about Env and Context.
@2bndy5 2bndy5 linked an issue Nov 8, 2024 that may be closed by this pull request
Consider abstracting config out of radio instance #5
Open
@2bndy5 2bndy5 force-pushed the impl-rf24 branch 4 times, most recently from aec0850 to 9a70482 Compare November 10, 2024 13:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Consider abstracting config out of radio instance rename listen methods consider FFI bindings
2 participants
@2bndy5 @codecov-commenter