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::Slave7-bit or 10-bit addressing mode via
AddrFormat::Bit7/AddrFormat::Bit10Standard 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 RTL8721FConfigurable SDA hold/setup time, RX/TX FIFO threshold, and SCL/SDA glitch filter via
ConfigGeneral Call and NULL DATA transfer support in master mode
Two peripheral instances,
I2c0andI2c1, both implementing the sharedI2cInstancetraitOperation mode:
Blocking: poll-driven
Async: interrupt-driven, via
embassywaker
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/:
-
I2C0 master, blocking mode. Writes to a non-existent slave address
0x55and 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
-
I2C0 master, async mode. Same NACK-detection scenario as
i2c/blocking, driven throughinto_asyncinstead 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] Nlines 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.