Device drivers on microcontrollers
A sensor or an actuator of the hardware store (lib/arche-hw-store/devices/)
can run in two places:
- Go on a Linux board (Raspberry Pi, Jetson, BeagleBone…):
archec gen --target go, with the Gobot drivers ofdevices/go/(boards.md). - Rust with Embassy on a microcontroller (STM32, nRF, RP2040, ESP32):
archec gen --target embassy, with the Rust drivers ofdevices/rust/. This page is about this one.
Nothing on this page has been tried on a board yet. What has been checked is listed under What was tried.
One interface per peripheral#
std/peripherals (include "std/peripherals") declares one interface for each
peripheral of a microcontroller:
| Interface | Port type | What it does | Rust trait |
|---|---|---|---|
DigitalOut |
gpio |
set a pin high or low | embedded_hal::digital::OutputPin |
DigitalIn |
gpio |
read a pin | embedded_hal::digital::InputPin |
Uart |
uart |
bytes in and out | embedded_io::Read + Write |
I2cBus |
i2c |
registers of the devices on the bus | embedded_hal::i2c::I2c |
SpiBus |
spi |
bytes out and back, with a chip select | embedded_hal::spi::SpiDevice |
Adc |
analog |
a raw reading | Adc (embedded-hal 1.0 has none) |
Pwm |
pwm |
a duty cycle | embedded_hal::pwm::SetDutyCycle |
CanBus |
can |
frames by their id | embedded_can::blocking::Can |
Timer |
(every processor) | wait, read the time | embedded_hal::delay::DelayNs, embassy-time |
A port of a built-in type provides the interface of its type. So a component written against an interface links to that port on any board:
include "std/peripherals"
component Thermometer "Thermometer" {
kind device
inout bus: i2c { requires I2cBus }
}
system Bench {
part board: NucleoG474RE
part t: Thermometer
board.i2c1 -> t.bus // fine: an i2c port provides I2cBus
}A gpio port linked to a port that requires Uart is a warning
(unprovided-interface).
In Rust, the same names are in src/hw/peripherals.rs of the generated crate
(from runtime/rust/peripherals.rs of the store). A driver written against
I2cBus builds with every HAL below: they all implement embedded-hal 1.0.
The boards#
archec gen --target embassy drives the devices of a board of these families:
| Family | HAL crate | Boards of the store | Checked with cargo check |
|---|---|---|---|
| STM32 | embassy-stm32 0.2 (G4, H7), 0.1 (F4) | NUCLEO-G474RE, NUCLEO-H743ZI2, NUCLEO-F446RE | G474RE, F446RE (H743ZI2 by hand) |
| nRF | embassy-nrf 0.2 | nRF52840 DK | yes |
| RP2040 | embassy-rp 0.2 | Raspberry Pi Pico, Pico W | Pico |
| ESP32 | esp-hal 0.22, esp-hal-embassy 0.5 | ESP32-C3-DevKitM-1, ESP32-S3-DevKitC-1, ESP32-DevKitC | C3 (the S3 and the ESP32 need Espressif's Xtensa toolchain) |
What is generated for each peripheral:
| Peripheral | Generated | How |
|---|---|---|
| I²C | yes | blocking, 100 kHz; one bus shared by its devices (embedded-hal-bus's CriticalSectionDevice) |
| GPIO out, in | yes | the HAL's Output and Input (no pull: the device's circuit says it) |
| PWM | yes, in software | SoftPwm: a task toggles the pin, timed by embassy-time. Right for a servo at 50 Hz, not for a motor at 20 kHz |
| Timer | yes | embassy-time (Delay, Instant) |
| CAN | yes, for the model's buses | src/can.rs (codegen.md) |
| UART, SPI, ADC | no | the traits are there; create the peripheral in main.rs |
The devices#
These 15 devices have a Rust driver. Most are built on a crate of crates.io that uses embedded-hal 1.0; the GPIO ones are written in the store on the traits alone.
| Device | Crate | License of the crate | Plugs into |
|---|---|---|---|
| BME280 | bme280 0.5.1 | MIT OR Apache-2.0 | I²C |
| BMP280 | bme280 0.5.1 (it drives the BMP280 too) | MIT OR Apache-2.0 | I²C |
| MPU-6050 | mpu6050-dmp 0.6.1 | Apache-2.0 | I²C |
| ADXL345 | adxl345_driver2 2.0.1 | MIT | I²C |
| BH1750 | bh1750 0.1.0 | MIT OR Apache-2.0 | I²C |
| SHT3x | sht31 0.3.3 | MIT | I²C |
| INA3221 | ina3221 0.4.5 | MIT | I²C |
| ADS1115 | ads1x1x 0.3.0 | MIT OR Apache-2.0 | I²C |
| SSD1306 | ssd1306 0.10.0 | MIT OR Apache-2.0 | I²C |
| PCA9685 | pwm-pca9685 1.0.0 | MIT OR Apache-2.0 | I²C |
| HC-SR04 | none (embedded-hal 1.0) | — | two pins |
| Servo (HobbyServo) | none | — | a PWM pin |
| LED (GpioLed) | none | — | a pin |
| Button (GpioButton) | none | — | a pin |
| Relay (GpioRelay) | none | — | a pin |
The device's .arche says it, beside its Go driver:
product { vendor "Bosch Sensortec"; part-number "BME280"; driver "i2c.NewBME280Driver"; rust-driver "bme280 0.5.1"; rust-license "MIT OR Apache-2.0" }
archec device show bme280 prints runs on Go · Linux, Rust · Embassy.
The other 73 devices (the DS18B20, the HMC5883L, the displays on SPI…) run in Go only. archec says so when one is on a microcontroller's board, and leaves it out.
Using them#
Put the devices in the platform beside the board, as for Go:
include "arche-hw-store/boards/nucleo-g474re/nucleo-g474re.arche"
include "arche-hw-store/devices/bme280/bme280.arche"
include "arche-hw-store/devices/led/led.arche"
include "arche-hw-store/devices/servo/servo.arche"
system Hw {
part board: NucleoG474RE
part air: Bme280 // the board's I²C, at 0x77
part led: GpioLed // the board's user LED (PA5)
part arm: HobbyServo { in pin { pins { pin PA6 } } } // the pin it is wired to
}archec gen --target embassy then writes, in the binary's crate:
src/hw/mod.rs, generated again each time: the board's I²C bus, aHardwarestruct with one field per device,HW(an async mutex that holds it) and thestart!macro;src/hw/peripherals.rsandsrc/hw/<device>.rs, copied from the store;- in
Cargo.toml, the crates (written once: a Cargo.toml from before has not got them; compare it with a fresh one); - in
main.rs(written once), the line that starts the devices:
let _p = embassy_stm32::init(Default::default());
hw::start!(spawner, _p); // the devices on the board, and the peripherals they use (src/hw/mod.rs)
A part's ```arche body reads a device through the interface its port requires
(sensor.temperature(), fan.on()). When the port is linked to the device in
the system, the generated Out method calls the driver, so nothing is written
by hand: examples/greenhouse does this. Code written by hand reads a device
through HW:
if let Some(Ok(t)) = crate::hw::with(|h| h.air.temperature()).await {
// t is in °C
}
Each driver has the model's functions under their names (temperature,
on, move…), returning Result<_, DeviceError>. A function the driver
does not have is listed in its file's header (//! not here: …).
Where a device plugs#
archec looks, in this order:
- the board's port the device is linked to:
board.i2c2 -> air.i2ctakes I2C2 on the pins the port says (pins { scl PB10; sda PB11 }); - the device's own port:
part arm: HobbyServo { in pin { pins { pin PA6 } } }; - the board's default: its Arduino-header I²C, its user LED and button.
| Board | Default I²C (SCL, SDA) | LED | Button |
|---|---|---|---|
| NUCLEO-F446RE, NUCLEO-G474RE | I2C1 PB8, PB9 | PA5 | PC13 |
| NUCLEO-H743ZI2 | I2C1 PB8, PB9 | PB0 | PC13 |
| nRF52840 DK | TWISPI0 P0_27, P0_26 | — (active low) | P0_11 |
| Raspberry Pi Pico | I2C0 PIN_5, PIN_4 | PIN_25 | — |
| Raspberry Pi Pico W | I2C0 PIN_5, PIN_4 | — (on the radio chip) | — |
| ESP32-C3-DevKitM-1 | I2C0 GPIO5, GPIO4 | — (RGB) | GPIO9 (BOOT) |
| ESP32-S3-DevKitC-1 | I2C0 GPIO9, GPIO8 | — (RGB) | GPIO0 (BOOT) |
| ESP32-DevKitC | I2C0 GPIO22, GPIO21 | — | GPIO0 (BOOT) |
A device with no pin found is left out, and archec says which line to write.
A pin used twice is noted. The I²C address is the port's address (a part
can change it: part baro: Bmp280 { inout i2c { address 0x76 } }).
Adding a device#
Find a crate that implements the device on embedded-hal 1.0 (
cargo treeshows which embedded-hal a crate uses; many are still on 0.2). Note its version and license.Write
lib/arche-hw-store/devices/rust/<id>.rs, where<id>is the device's folder. Its header says what archec needs://! arche: Bme280 the device's component //! new: i2c(i2c) its constructor's arguments: i2c(port), output(port), input(port), pwm(port) //! cargo: bme280 = "0.5.1" a line of Cargo.toml (one per crate) //! not here: serial_number the model's functions it does not have, and whyThe struct is named as the component and is generic over the peripherals (
pub struct Bme280<I: I2cBus>).newtakes them in the order ofnew:, an I²C one followed by its address. Write apub fnfor each of the model's functions, under its name.Add the device to
tools/gobot-catalog/rust.goand rungo run ./tools/gobot-catalog lib/arche-hw-store: its.archegetsrust-driverandrust-license.Run
node --test test/embassy-drivers.test.js. It checks the header against the.arche, then, with cargo, builds the driver for one board of each family.
Adding a board#
A board of the store whose processor says hal stm32|nrf|rp|esp32 and its
chip already works: its I²C is the family's default (I2C1 on PB8/PB9 for
STM32, and so on). For other pins, give the board an I²C port with its pins,
inout i2c1: i2c { pins { scl PB8; sda PB9 } }, and link the devices to it.
For a default LED or button, add the board to BOARD_DEFAULTS in
src/gen/embassyhw.ts.
What was tried#
cargo checkof a crate with all 15 devices, for the NUCLEO-G474RE, the NUCLEO-F446RE, the nRF52840 DK, the Raspberry Pi Pico and the ESP32-C3-DevKitM-1: no error, no warning (test/embassy-drivers.test.js, when cargo and the targets are installed and the crates can be downloaded).cargo build --release(linked) of the same for those boards.- Not tried: any board on a desk, and Renode (it was not installed). Renode has no STM32G4, RP2040 or ESP32 (boards.md).
Limits#
- The drivers are blocking: a measurement holds
HWand its task until it ends (an SHT3x about 15 ms, a BH1750 about 180 ms, an HC-SR04 up to 60 ms). - PWM is in software. A hardware timer PWM, UART, SPI and ADC are not generated.
- The ESP32-S3 and the ESP32 need Espressif's Rust toolchain (
espup). - A main.rs or Cargo.toml written before devices were added keeps its old content: compare it with a fresh one.