Inter-Integrated Circuit (I2C)

Overview

RTL8721F provides an I2C interface, a two-wire, low-speed, synchronous serial communication bus supporting master and slave roles. The Rust driver ameba_hal::i2c wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • Two-wire I2C serial interface: a serial data line (SDA) and a serial clock (SCL)

  • Master or Slave role via Role::Master / Role::Slave

  • 7-bit or 10-bit addressing mode via AddrFormat::Bit7 / AddrFormat::Bit10

  • Standard speed (≤100 kHz, SpeedMode::Ss) or Fast speed (≤400 kHz, SpeedMode::Fs), and High Speed (SpeedMode::Hs) is declared but not supported on I2C0 of RTL8721F

  • Configurable SDA hold/setup time, RX/TX FIFO threshold, and SCL/SDA glitch filter via Config

  • General Call and NULL DATA transfer support in master mode

  • Two peripheral instances, I2c0 and I2c1, both implementing the shared I2cInstance trait

  • Operation mode:

    • Blocking: poll-driven

    • Async: interrupt-driven, via embassy waker

Note

DMA-backed transfer and slave-mode async are not yet exposed by the driver’s public API. Interrupt-driven master transfers are available through I2c::into_async.

Operating Modes

I2C supports two configurable operating modes: Blocking Mode and Async Mode.

Blocking Mode

The CPU polls the I2C status registers and reads or writes the FIFO buffer as needed. This is the default mode returned by I2c::init(...).enable(), and implements embedded_hal::i2c::I2c.

Suited for simple, low-frequency transfers where blocking the current task is acceptable.

use embedded_hal::i2c::I2c as _;

use ameba_hal::i2c::{Config, I2c, I2c0};

use ameba_hal::{
    pinmux::{self, Pin, PinFunction, Pull},
    rcc,
};
...
rcc::enable(rcc::Peripheral::I2C0);
pinmux::set(Pin::PA26, PinFunction::I2C0_SDA);
pinmux::set(Pin::PA25, PinFunction::I2C0_SCL);
pinmux::set_pull(Pin::PA26, Pull::Up);
pinmux::set_pull(Pin::PA25, Pull::Up);

let mut i2c = unsafe {
    I2c::<I2c0, _>::steal()
        .init(Config::default())
        .enable()
};
...
match i2c.write(0x55u8, &[0x42u8]) {
    Err(_) => {
        println!("[PASS] I2C blocking: NACK OK");
    }
    Ok(()) => {
        println!("[FAIL] I2C blocking: unexpected ACK");
    }
}

Full example: examples/i2c/blocking/src/main.rs.

Async Mode

Interrupt-driven transfers built on the Embassy waker mechanism, obtained by calling into_async on an enabled blocking instance. Implements embedded_hal_async::i2c::I2c, so the current async task yields instead of busy-polling while a transfer is in flight.

use embassy_time::{Duration, Timer, with_timeout};
use embedded_hal_async::i2c::I2c as _;

use ameba_hal::Async;
use ameba_hal::i2c::{self, Config, I2c, I2c0};
...
ameba_hal::bind_interrupts!(struct Irqs {
    I2C0_IRQ => i2c::InterruptHandler<I2c0>;
});
...
async fn i2c_task(mut i2c: I2c<I2c0, i2c::Enabled, Async>) {
    // Phase 1: NACK error handling — write to address 0x55 (no device present).
    let result = with_timeout(Duration::from_millis(500), i2c.write(0x55u8, &[0x42u8])).await;
    match result {
        Ok(Err(_)) => println!("[PASS] I2C async: NACK OK"),
        Ok(Ok(())) => println!("[FAIL] I2C async: unexpected ACK"),
        Err(_) => println!("[FAIL] I2C async: timeout (>500ms)"),
    }
    ...
}
...
let i2c = unsafe {
    I2c::<I2c0, _>::steal().init(Config::default()).enable()
};
let i2c_async = i2c.into_async(Irqs);
...
spawner.spawn(i2c_task(i2c_async)).unwrap();

Full example: examples/i2c/async/src/main.rs.

Application Examples

The Rust SDK provides two example projects under examples/i2c/:

  • i2c/blocking

    I2C0 master, blocking mode. Writes to a non-existent slave address 0x55 and checks that the driver reports a NACK error.

    Wiring: SCL = PA25, SDA = PA26, external or internal pull-up required. No slave device is needed — the example intentionally targets an address with nothing attached.

    [I2C BLK] start
    [PASS] I2C blocking: NACK OK
    
  • i2c/async

    I2C0 master, async mode. Same NACK-detection scenario as i2c/blocking, driven through into_async instead of polling. It then issues 30 writes while a concurrent heartbeat task confirms the executor is not blocked.

    Wiring: same as i2c/blocking.

    [I2C ASYNC] start
    [PASS] I2C async: NACK OK
    [I2C] concurrent: 30 writes start
    [HB] N
    ...
    [I2C] heartbeats seen: N
    [PASS] I2C async: non-blocking OK
    [HB] N
    ...
    

    The heartbeat task keeps printing [HB] N lines after the final [PASS].

Note

Build any example with cargo xtask build example --name i2c/<demo>.

API Reference

Quick Usage

use ameba_hal::i2c::{Config, I2c, I2c0};
use embedded_hal::i2c::I2c as _;

let mut i2c = unsafe {
    I2c::<I2c0, _>::steal()
        .init(Config::default())
        .enable()
};

i2c.write(0x55u8, &[0x42u8])?;
i2c.read(0x55u8, &mut [0u8; 4])?;

I2c also implements embedded_hal_async::i2c::I2c once converted with into_async, please see the Async Mode section above.