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_twai"
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_twai.dodo |
RECEIVE
Constant · Source
Interrupt sources for listen and take_interrupts (INT_ENA and INT_RAW bits): a frame waits (RIE), the transmit buffer became free (TIE), the error warning or bus-off status changed (EIE), a data overrun (DOIE), the controller became error passive or active again (EPIE), it lost arbitration (ALIE), and it saw a bus error (BEIE).
pub const RECEIVE: u32 = 1 << 0
TRANSMIT
Constant · Source
pub const TRANSMIT: u32 = 1 << 1
ERROR_WARNING
Constant · Source
pub const ERROR_WARNING: u32 = 1 << 2
OVERRUN
Constant · Source
pub const OVERRUN: u32 = 1 << 3
ERROR_PASSIVE
Constant · Source
pub const ERROR_PASSIVE: u32 = 1 << 5
ARBITRATION_LOST
Constant · Source
pub const ARBITRATION_LOST: u32 = 1 << 6
BUS_ERROR
Constant · Source
pub const BUS_ERROR: u32 = 1 << 7
MAX_FILTERS
Constant · Source
The most filters a controller takes.
pub const MAX_FILTERS: usize = 8
ABORT_POLLS
Constant · Source
Status reads before abort_pending gives up with Timeout. Aborting takes effect at once unless a frame is on the bus, which ends within 160 bit times.
pub const ABORT_POLLS: u32 = 100_000
WARNING_LIMIT
Constant · Source
The error warning limit (ERR_WARNING_LIMIT), the counter level that sets STATUS.ERR_ST: the SJA1000’s default.
pub const WARNING_LIMIT: u32 = 96
Mode
Enum · Source
Operating modes after configuration.
pub enum Mode {
// Take part in the bus: send, receive, and acknowledge frames.
Normal,
// Send without needing an acknowledge and receive one's own frames,
// through the filters; for checking a controller with its TX looped to
// its RX and no other node.
SelfTest,
// Receive every valid frame but never send, acknowledge, or signal
// errors; for monitoring a bus or detecting its bit rate.
ListenOnly
}
Config
Struct · Source
How
Controller.newandconfigureset the controller up.
pub struct Config {
pub bitrate: u32
// Where to sample each bit, in thousandths of the bit; see "Bit
// timing".
pub sample_point_permille: u32
pub mode: Mode
// Send each frame once, without retrying after an error or a lost
// arbitration. The transmit buffer is free afterwards either way.
pub one_shot: bool
// Sample each bit three times and take the majority, for slow, noisy
// buses; CiA recommends a single sample above 125 kbit/s.
pub triple_sampling: bool
// Start recovering from bus-off as soon as the controller is seen
// bus-off, instead of when `recover` is called.
pub automatic_recovery: bool
}
Config.new
Function · Source
Normal mode at
bitrate, sampling once at 87.5%, retrying frames, recovering from bus-off automatically.
pub fn new(bitrate: u32) -> Config
Timing
Struct · Source
The TWAI bit timing registers for one bit rate.
pub struct Timing {
// BUS_TIMING_0: the synchronization jump width less one (bits 15-14)
// and the baud rate prescaler BRP (bits 13-0).
pub bus_timing_0: u32
// BUS_TIMING_1: segment 2 less one (bits 6-4) and segment 1 less one
// (bits 3-0); `configure` adds triple sampling (bit 7).
pub bus_timing_1: u32
// The bit rate the registers give, rounded, and the sample point.
pub bitrate: u32
pub sample_point_permille: u32
}
limits
Function · Source
The ranges hal.can_timing may choose from for TWAI: prescalers of 2 to 32768 clock cycles in steps of 2, segment 1 of 2 to 16 quanta, segment 2 of 2 to 8, and a jump width up to 4.
pub fn limits() -> hal.CanTimingLimits
timing
Function · Source
The timing registers for
bitratefrom a function clock ofclock_hz, sampling nearsample_point_permille; see “Bit timing” above. InvalidInput if no timing reaches the bit rate within 0.5%.
pub fn timing(clock_hz: u32, bitrate: u32, sample_point_permille: u32) -> Timing!hal.Error
FilterPlan
Struct · Source
The hardware acceptance filter: single or dual mode, and the acceptance code and mask as one 32-bit value each, ACR0 and AMR0 in the top byte. Mask bits set are bits the filter ignores (the hardware’s sense).
pub struct FilterPlan {
pub single: bool
pub code: u32
pub mask: u32
}
plan_filters
Function · Source
The hardware filter for
filters; see “Filters” above. InvalidInput for more than MAX_FILTERS filters or an identifier too large for its kind.
pub fn plan_filters(filters: &[hal.CanFilter]) -> FilterPlan!hal.Error
encode_frame
Function · Source
A frame’s 13 bytes as the data registers hold it: the frame information, the identifier (2 bytes standard, 4 extended, left-aligned), and the data. Returns how many bytes the frame uses.
pub fn encode_frame(frame: &hal.CanFrame, bytes: &mut[13]u8) -> usize
decode_frame
Function · Source
Make
framethe frame inbytes, as the data registers hold it. A data length code above 8 means 8 bytes, as classic CAN defines it.
pub fn decode_frame(bytes: &[13]u8, frame: &mut hal.CanFrame) -> void!hal.Error
Controller
Struct · Source
A TWAI controller over registers R, from
newuntilrelease.
pub struct Controller<R: hal.Registers>: hal.Can {
// Private implementation fields omitted.
}
Controller.attach
Function · Source
Take registers R of a controller that is already running, keeping its configuration, with no filters for the software check and automatic bus-off recovery;
configuresets it up. Most programs callnewinstead.
pub fn attach(registers: R) -> Controller<R>
Controller.new
Function · Source
Configure the controller with registers R, clocked at
clock_hz(the 40 MHz crystal on the ESP32-C6), fromconfigandfilters; seeconfigure. InvalidInput as forconfigure, before the controller is touched.
pub fn new(registers: R, clock_hz: u32, config: &Config, filters: &[hal.CanFilter]) -> Controller<R>!hal.Error
Controller.configure
Function · Source
Set the controller up from
configandfilters: enter reset mode, which drops a pending frame and the received ones, clear the error counters, program the bit timing and the acceptance filter, and start in the configured mode. InvalidInput for a bit rate the controller cannot reach or filters it does not take (see “Filters”), before the controller is touched.
pub fn configure(&mut self, clock_hz: u32, config: &Config, filters: &[hal.CanFilter]) -> void!hal.Error
Controller.set_mode
Function · Source
Switch to
mode, keeping the bit timing and filters. The controller passes through reset mode, which drops a pending frame and the frames in the FIFO; the error counters stay.
pub fn set_mode(&mut self, mode: Mode)
Controller.poll_send
Function · Source
Queue
framein the transmit buffer and request it; see hal.Can and “Sending” above. False while the previous frame is pending. Unsupported for an FD frame, as TWAI sends classic CAN only, and in ListenOnly mode; Bus while the controller is bus-off.
pub fn poll_send(&mut self, frame: &hal.CanFrame) -> bool!hal.Error
Controller.poll_receive
Function · Source
Take the oldest received frame the filters pass into
frame; see hal.Can and “Receiving” above. False while none waits, and while the controller is bus-off. Overrun once where frames were lost.
pub fn poll_receive(&mut self, frame: &mut hal.CanFrame) -> bool!hal.Error
Controller.error_state
Function · Source
The fault confinement state: BusOff while STATUS.BUS_OFF_ST is set (starting recovery if automatic), Passive while either error counter is 128 or more, else Active.
pub fn error_state(&mut self) -> hal.CanErrorState!hal.Error
Controller.tec
Function · Source
The transmit error counter (TEC): error-passive from 128, bus-off after 255. During bus-off recovery it counts the runs of 11 recessive bits still to come down from 127.
pub fn tec(&mut self) -> u32
Controller.rec
Function · Source
The receive error counter (REC): error-passive from 128.
pub fn rec(&mut self) -> u32
Controller.status
Function · Source
The status register (STATUS), for the bits error_state does not report, such as ERR_ST (bit 6: a counter reached WARNING_LIMIT).
pub fn status(&mut self) -> u32
Controller.waiting
Function · Source
The frames waiting in the FIFO, including the places of lost ones (RX_MESSAGE_CNT).
pub fn waiting(&mut self) -> u32
Controller.is_pending
Function · Source
Whether a frame waits in the transmit buffer.
pub fn is_pending(&mut self) -> bool
Controller.error_code
Function · Source
The last bus error the controller saw (ERR_CODE_CAP): its segment (bits 4-0), whether it was receiving (bit 5), and its kind (bits 7-6: bit, form, stuff, or other error). Reading it lets the controller capture the next error.
pub fn error_code(&mut self) -> u32
Controller.abort_pending
Function · Source
Cancel the frame waiting to be sent (ABORT_TX) and wait until the transmit buffer is free; a frame already on the bus finishes first. Timeout after ABORT_POLLS status reads.
pub fn abort_pending(&mut self) -> void!hal.Error
Controller.recover
Function · Source
Start recovering from bus-off: leave the reset mode the controller entered, so it counts 128 runs of 11 recessive bits and becomes error active. Does nothing unless the controller is bus-off.
pub fn recover(&mut self)
Controller.listen
Function · Source
Raise the controller’s interrupt while any of
sources(RECEIVE, TRANSMIT, …, ORed together) is pending; replaces the set listened to.
pub fn listen(&mut self, sources: u32)
Controller.take_interrupts
Function · Source
The interrupt sources pending among those listened to, which reading clears, except RECEIVE, which stays while a frame waits.
pub fn take_interrupts(&mut self) -> u32
Controller.release
Function · Source
Enter reset mode, which stops the controller, and return its registers.
pub fn release(self) -> R