Autres pages › drivers

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

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 of devices/go/ (boards.md).
  • Rust with Embassy on a microcontroller (STM32, nRF, RP2040, ESP32): archec gen --target embassy, with the Rust drivers of devices/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
}
Diagramme : Bench
Ce qu’archec dessine depuis ce code : Bench

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
}
Diagramme : Hw
Ce qu’archec dessine depuis ce code : Hw

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, a Hardware struct with one field per device, HW (an async mutex that holds it) and the start! macro;
  • src/hw/peripherals.rs and src/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:

  1. the board's port the device is linked to: board.i2c2 -> air.i2c takes I2C2 on the pins the port says (pins { scl PB10; sda PB11 });
  2. the device's own port: part arm: HobbyServo { in pin { pins { pin PA6 } } };
  3. 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#

  1. Find a crate that implements the device on embedded-hal 1.0 (cargo tree shows which embedded-hal a crate uses; many are still on 0.2). Note its version and license.

  2. 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 why

    The struct is named as the component and is generic over the peripherals (pub struct Bme280<I: I2cBus>). new takes them in the order of new:, an I²C one followed by its address. Write a pub fn for each of the model's functions, under its name.

  3. Add the device to tools/gobot-catalog/rust.go and run go run ./tools/gobot-catalog lib/arche-hw-store: its .arche gets rust-driver and rust-license.

  4. 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 check of 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 HW and 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.