API referencestd/embedded

std/embedded/peripheral/esp_twai

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

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_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.new and configure set 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 bitrate from a function clock of clock_hz, sampling near sample_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 frame the frame in bytes, 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 new until release.

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; configure sets it up. Most programs call new instead.

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), from config and filters; see configure. InvalidInput as for configure, 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 config and filters: 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 frame in 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

Search every guide, reference page, and API declaration.