API referencestd/embedded

std/embedded/peripheral/esp_i2c

Public declarations, types, methods, and source contracts for std/embedded/peripheral/esp_i2c.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/peripheral/esp_i2c"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
hal std/embedded/hal esp_i2c.dodo

FIFO_DEPTH

Constant · Source

Bytes in the FIFO, and the most one command moves.

pub const FIFO_DEPTH: usize = 32

Timing

Struct · Source

The bus timing for one SCL frequency, from timing.

pub struct Timing {
    // The function clock it counts.
    pub clock_hz: u32
    // Half an SCL period in function clock cycles.
    pub half_cycle: u32
    // The resulting SCL frequency.
    pub frequency_hz: u32
}

timing

Function · Source

The timing for an SCL frequency of frequency_hz from a function clock of clock_hz. InvalidInput above hal.I2C_FAST_PLUS_HZ, or where half a period does not fit the controller’s counters (below clock_hz / 1022, or above clock_hz / 20); a chip package divides the clock first for slower buses.

pub fn timing(clock_hz: u32, frequency_hz: u32) -> Timing!hal.Error

prescaler

Function · Source

The function clock divider a chip package sets for frequency_hz from its source clock: the smallest that keeps half a period within the counters.

pub fn prescaler(source_hz: u32, frequency_hz: u32) -> u32

Controller

Struct · Source

An I2C bus master on one controller with registers R. Implements the std/embedded/hal I2C bus protocol and its polling form.

pub struct Controller<R: hal.Registers>: hal.I2c + hal.I2cPoll {
    // Private implementation fields omitted.
}

Controller.new

Function · Source

Configure a controller fresh out of reset as a master at the SCL frequency of timing.

pub fn new(registers: R, timing: Timing) -> Controller<R>

Controller.frequency_hz

Function · Source

The SCL frequency, the closest the controller makes to the request.

pub fn frequency_hz(&self) -> u32

Controller.set_frequency

Function · Source

Change the SCL frequency, from the same function clock.

pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error

Controller.set_timing

Function · Source

Change the timing, for a chip package that changes the function clock too.

pub fn set_timing(&mut self, settings: Timing)

Controller.write

Function · Source

Write bytes to the device at address, then a STOP, polling the controller until the transaction ends. Busy while a polled transaction runs.

pub fn write(&mut self, address: u8, bytes: &[u8]) -> void!hal.Error

Controller.read

Function · Source

pub fn read(&mut self, address: u8, buffer: &mut[u8]) -> void!hal.Error

Controller.write_read

Function · Source

Write bytes, then read buffer.len bytes after a repeated start, without releasing the bus.

pub fn write_read(&mut self, address: u8, bytes: &[u8], buffer: &mut[u8]) -> void!hal.Error

Controller.write_ten_bit

Function · Source

The 10-bit address forms: InvalidInput above 0x3FF.

pub fn write_ten_bit(&mut self, address: u16, bytes: &[u8]) -> void!hal.Error

Controller.read_ten_bit

Function · Source

pub fn read_ten_bit(&mut self, address: u16, buffer: &mut[u8]) -> void!hal.Error

Controller.write_read_ten_bit

Function · Source

pub fn write_read_ten_bit(&mut self, address: u16, bytes: &[u8], buffer: &mut[u8]) -> void!hal.Error

Controller.probe

Function · Source

Whether a device answers address: its address, then a stop, with no data.

pub fn probe(&mut self, address: u8) -> bool!hal.Error

Controller.poll_write

Function · Source

Advance a write of bytes to the device at address, then a STOP, without waiting: false while it runs, true once it has ended; see hal.I2cPoll. The first call starts the transaction with up to 30 bytes (31 less the address); each later call that finds a run over starts the next 31, holding SCL low in between. Errors as for write, after which the transaction is over; InvalidInput for a call whose address or lengths differ from the running transaction’s, which keeps running. The first call waits for a busy bus to go idle, about a millisecond at most, then clocks a stuck one free, as write does; a failed transaction’s recovery waits the same. A transaction whose device holds SCL low ends with Timeout after about 100 ms, the controller’s own limit.

pub fn poll_write(&mut self, address: u8, bytes: &[u8]) -> bool!hal.Error

Controller.poll_read

Function · Source

Advance a read of buffer.len bytes, as for poll_write. Each run reads up to 31 bytes; they are all in buffer once it returns true.

pub fn poll_read(&mut self, address: u8, buffer: &mut[u8]) -> bool!hal.Error

Controller.poll_write_read

Function · Source

Advance write_read as one transaction, as for poll_write and poll_read: the bytes, a repeated START, and the read.

pub fn poll_write_read(&mut self, address: u8, bytes: &[u8], buffer: &mut[u8]) -> bool!hal.Error

Controller.poll_write_ten_bit

Function · Source

The polled transactions above for a device with a 10-bit address, as for write_ten_bit.

pub fn poll_write_ten_bit(&mut self, address: u16, bytes: &[u8]) -> bool!hal.Error

Controller.poll_read_ten_bit

Function · Source

pub fn poll_read_ten_bit(&mut self, address: u16, buffer: &mut[u8]) -> bool!hal.Error

Controller.poll_write_read_ten_bit

Function · Source

pub fn poll_write_read_ten_bit(&mut self, address: u16, bytes: &[u8], buffer: &mut[u8]) -> bool!hal.Error

Controller.is_busy

Function · Source

True while a polled transaction runs: from its first poll until a poll reports its end or it is cancelled.

pub fn is_busy(&self) -> bool

Controller.cancel

Function · Source

Abandon the running polled transaction, if any, so the next poll starts a new one. The run on the bus ends first, at its END or STOP command: up to 31 bytes’ time (2.8 ms at 100 kHz), or the controller’s own timeout. A transaction it left holding the bus then gets a STOP of its own. Resetting the state machine in the middle of a run instead can leave the controller hung, so cancel does that only when the run does not end or the bus failed.

pub fn cancel(&mut self)

Controller.release

Function · Source

Give back the registers, with the controller stopped. A polled transaction still running is cut off.

pub fn release(self) -> R

target_address

Function · Source

The SLAVE_ADDR value for a target at address, a 10-bit address with ten_bit. InvalidInput for a 7-bit address the I2C specification reserves (0x00 to 0x07 and 0x78 to 0x7F) or a 10-bit one above 0x3FF. The controller matches a 10-bit address as the two bytes a master sends, stored as the low byte from bit 7 and the header, 0b11110 and the top two bits, below it.

pub fn target_address(address: u16, ten_bit: bool) -> u32!hal.Error

Target

Struct · Source

A target (slave) on an I2C bus, answering a master at one address with one controller with registers R, any hal.Registers; it implements hal.I2cTarget. The program polls for what the master does: written bytes arrive in order, each read waits for respond, and a STOP ends the transaction.

match target.poll(&mut buffer)? { hal.I2cTargetEvent.Write(count, start) => { … } hal.I2cTargetEvent.Read => { target.respond(&reply)? } … }

The controller stretches SCL (holds it low) while its 32-byte receive FIFO is full and while a read waits for bytes, until a poll or respond lets the master go on, so a slow program delays the master but loses nothing. Masters accept such clock stretching unless they give up after a timeout of their own (SMBus allows 25 ms). The controller’s state machines give up on a stretch after 2^23 function clock cycles (210 ms from the 40 MHz crystal), so a program must poll at least that often while a master talks to it. start marks the first bytes after a STOP or a read; the receive FIFO does not mark repeated starts, so two writes joined by a repeated START arrive as one, and a program that polls more slowly than whole transactions arrive may see the bytes of two write transactions in one Write. Bytes queued by respond beyond what the master reads are dropped when it next reads. General calls (address 0) are not acknowledged.

pub struct Target<R: hal.Registers>: hal.I2cTarget {
    // Private implementation fields omitted.
}

Target.new

Function · Source

Configure a controller fresh out of reset as a target at address, a 10-bit address with ten_bit, which must pass target_address; chip packages check it before they take the controller. timing, for the bus’s SCL frequency from the controller’s function clock, sets the SDA hold and sample times; a target follows the master’s clock whatever its frequency.

pub fn new(registers: R, timing: Timing, address: u16, ten_bit: bool) -> Target<R>

Target.poll

Function · Source

What the master did since the last poll, in order: first the bytes it wrote, as many as fit buffer, then a STOP, then a read that waits for respond. Never waits. A program that polls more slowly than whole transactions arrive may see one Stop for several; start still marks where each write begins. Overrun if the receive FIFO overflowed (RXFIFO_OVF), which stretching on a full FIFO prevents; Bus if the controller lost arbitration or a state machine timed out, as when the program left a stretch waiting too long.

pub fn poll(&mut self, buffer: &mut[u8]) -> hal.I2cTargetEvent!hal.Error

Target.respond

Function · Source

Answer a Read from poll with bytes, as many as the transmit FIFO holds; returns how many, and lets the master go on. The master reads them one by one and may stop early; if it reads on, the next poll reports another Read. An empty bytes sends 0xFF, what the master would read from an idle bus, so that it is never left waiting, and returns 0. Never fails: the error is there for hal.I2cTarget.

pub fn respond(&mut self, bytes: &[u8]) -> usize!hal.Error

Target.set_address

Function · Source

Answer at address from the next transaction on, a 10-bit address with ten_bit, as for target_address. InvalidInput leaves the address unchanged.

pub fn set_address(&mut self, address: u16, ten_bit: bool) -> void!hal.Error

Target.release

Function · Source

Stop answering and give back the registers, with the state machine reset and SCL released.

pub fn release(self) -> R

Search every guide, reference page, and API declaration.