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_hzfrom a function clock ofclock_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_hzfrom 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
bytesto the device ataddress, 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 readbuffer.lenbytes 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
bytesto the device ataddress, 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 forwrite, 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, aswritedoes; 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.lenbytes, as forpoll_write. Each run reads up to 31 bytes; they are all inbufferonce 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_readas one transaction, as forpoll_writeandpoll_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 withten_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
respondlets 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.startmarks 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 byrespondbeyond 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 withten_bit, which must passtarget_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 forrespond. Never waits. A program that polls more slowly than whole transactions arrive may see one Stop for several;startstill 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
pollwithbytes, 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 emptybytessends 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
addressfrom the next transaction on, a 10-bit address withten_bit, as fortarget_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