pico-de-gallo-hal

pico-de-gallo-hal lets you run real embedded-hal driver code against a Pico de Gallo board on your laptop.

That is the whole value proposition:

• write your driver against standard traits,
• swap in pico-de-gallo-hal during host-side testing,
• iterate without cross-compiling, flashing, linker scripts, or probe tools.

If your driver already speaks embedded-hal, this crate turns Pico de Gallo into a host-side transport layer instead of a custom test harness.

Runtime Model

Hal::new() works in both sync and async host code.

• Inside a Tokio runtime, the crate uses tokio::task::block_in_place() for blocking trait calls.
• Outside Tokio, it creates and owns its own runtime.

That means one Hal value can back ordinary tests, examples, and async host applications.

Construction

Accessors and Helpers

The current public API is:

Note

The source-of-truth API currently exposes gpio(pin) and uart(). There are not separate output_pin(), input_pin(), or uart_async() constructors; the returned handles implement the relevant blocking and async traits directly.

Implemented Traits

The UART row is feature-gated by embedded-io major version — see Feature Flags below.

The Uart handle uses the baud rate and framing currently configured on the device; the HAL cannot change either. If a driver requires a particular UART configuration, apply it before using hal.uart() through gallo uart set-config, pico-de-gallo-lib, the C FFI, or Python. Do not reconfigure the same device concurrently with HAL reads or writes: firmware applies the baud divisor before the framing and drains neither direction.

And two project-specific surfaces sit alongside the trait-based ones:

Feature Flags

embedded-io 0.6 and 0.7 are both supported through additive features:

# 0.6 only (default)
pico-de-gallo-hal = "0.7"

# 0.7 only
pico-de-gallo-hal = { version = "0.7", default-features = false, features = ["embedded-io-07"] }

# both majors at once
pico-de-gallo-hal = { version = "0.7", features = ["embedded-io-07"] }

Minimal Example

use embedded_hal::i2c::I2c;
use pico_de_gallo_hal::Hal;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hal = Hal::new();
    let mut i2c = hal.i2c();

    let mut buf = [0u8; 2];
    i2c.write_read(0x48, &[0x00], &mut buf)?;

    println!("raw bytes: {:02x?}", buf);
    Ok(())
}

That same pattern is why this crate is so useful in driver development: the code above looks like ordinary embedded Rust because it is ordinary embedded Rust.

Transparent Transaction Batching

Two methods matter a lot for performance:

• I2c::transaction()
• SpiDevice::transaction()

The HAL does not turn those into several USB round-trips. Instead, it encodes the operations into Pico de Gallo batch requests and sends them in one shot.

So if your driver already uses the transaction APIs from embedded-hal, you get Pico de Gallo’s batching support automatically.

For I²C, the batch is also one transaction on the bus: adjacent operations of the same type run back to back without a STOP, changing direction emits a repeated START, and only the final operation is followed by a STOP. Two adjacent writes therefore form one gather write. This requires firmware built from schema 0.7 or newer; older firmware ran each operation as a separate transaction. The crate implements only I2c::transaction() directly, so the embedded-hal defaults for read, write, and write_read all use these same semantics.

#![allow(unused)]
fn main() {
use embedded_hal::i2c::{I2c, Operation};
use pico_de_gallo_hal::Hal;

fn read_register(hal: &Hal) -> Result<[u8; 2], Box<dyn std::error::Error>> {
    let mut i2c = hal.i2c();
    let mut buf = [0u8; 2];

    i2c.transaction(
        0x48,
        &mut [
            Operation::Write(&[0x00]),
            Operation::Read(&mut buf),
        ],
    )?;

    Ok(buf)
}
}

For SPI devices, spi_device(cs_pin) wraps the same idea with automatic CS assert/deassert around the whole transaction.

Chip-select bounds

spi_device(cs_pin) validates cs_pin against the GPIO count the connected board reports before it drives the pin, so a refused chip-select leaves the pin exactly as you configured it. Read the count yourself with num_gpios(); prefer it over the compile-time pico_de_gallo_lib::NUM_GPIOS, which is only this build’s default.

The first lookup performs one implicit validated device/info round-trip, bounded at 300 seconds; the value is then cached and shared by every handle cloned from the same connection. SpiHalError keeps the outcomes disjoint:

DeviceInfo(_) is never reported as an invalid chip-select: a failure to learn the valid range is a connectivity or compatibility problem, not an argument problem.

num_gpios() returns HalInitError::Validate(_) on failure, including ValidateError::Timeout. Failures are not cached, so retrying is fine.

When to Reach for This Crate

Use pico-de-gallo-hal when you want to:

• validate a driver crate against real hardware behavior,
• keep one code path for host-side tests and MCU targets,
• avoid writing custom mocks before you know the driver is correct.

For a full walk-through, jump ahead to Testing with pico-de-gallo-hal in Part V.