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/can/mcp2515"
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 |
mcp2515.dodo |
MODE_POLLS
Constant · Source
Reads of CANSTAT, or of the transmit requests, before a wait for the chip gives up with Timeout. A mode change takes effect at once unless a frame is being sent or received, which ends within 160 bit times, far fewer than this many reads.
pub const MODE_POLLS: u32 = 1024
RECEIVE
Constant · Source
Interrupt sources for listen, ignore, and acknowledge (CANINTE bits): a frame waits in a receive buffer (RX0IE, RX1IE), a transmit buffer sent its frame (TX0IE-TX2IE), and the error flags changed, which includes an overflow (ERRIE).
pub const RECEIVE: u8 = 0x03
TRANSMIT
Constant · Source
pub const TRANSMIT: u8 = 0x1C
ERROR
Constant · Source
pub const ERROR: u8 = 0x20
Mode
Enum · Source
Operating modes after configuration.
pub enum Mode {
// Take part in the bus: send, receive, and acknowledge frames.
Normal,
// Frames sent come straight back to the receive buffers, through the
// filters, without reaching the bus; for self-tests.
Loopback,
// 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 chip up.
pub struct Config {
// The crystal or oscillator on the chip's OSC1 pin, such as 8, 16, or
// 20 MHz.
pub oscillator_hz: u32
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 (OSM). The transmit buffer is free afterwards either way.
pub one_shot: bool
}
Config.new
Function · Source
Normal mode at
bitratefromoscillator_hz, sampling at 87.5%, retrying frames.
pub fn new(oscillator_hz: u32, bitrate: u32) -> Config
Timing
Struct · Source
The MCP2515’s bit timing registers for one bit rate.
pub struct Timing {
// Synchronization jump width less one (bits 7-6) and the baud rate
// prescaler BRP (bits 5-0).
pub cnf1: u8
// BTLMODE, then phase segment 1 less one (bits 5-3) and the
// propagation segment less one (bits 2-0).
pub cnf2: u8
// Phase segment 2 less one (bits 2-0).
pub cnf3: u8
}
limits
Function · Source
The ranges hal.can_timing may choose from for the MCP2515: prescalers of 2 to 128 oscillator 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 an oscillator ofoscillator_hz, sampling nearsample_point_permille; see “Bit timing” above. InvalidInput if no timing reaches the bit rate within 0.5%.
pub fn timing(oscillator_hz: u32, bitrate: u32, sample_point_permille: u32) -> Timing!hal.Error
Controller
Struct · Source
An MCP2515 on SPI bus B, selected by pin P. Owns both, as the hal.Can methods take no bus, and gives them back with
release.
pub struct Controller<B: hal.Spi, P: hal.OutputPin>: hal.Can {
// Private implementation fields omitted.
}
Controller.attach
Function · Source
Take the bus and the chip-select pin, and deselect the chip, without talking to it;
configuresets it up. Most programs callnewinstead.
pub fn attach(bus: B, select: P) -> Controller<B, P> from(bus, select)
Controller.new
Function · Source
Attach to the chip and configure it; see
configure. The bus and pin are dropped with an error; use attach and configure to keep them.
pub fn new(bus: B, select: P, config: &Config, filters: &[hal.CanFilter]) -> Controller<B, P>!hal.Error from(bus, select)
Controller.configure
Function · Source
Reset the chip and set it up from
configandfilters: wait for configuration mode, program the bit timing, filters, and rollover, and switch to the configured mode. Frames in the chip are lost. InvalidInput for a bit rate it cannot reach or filters it cannot hold (see “Filters”), before the chip is touched; Timeout if the chip does not reach configuration mode or then the configured mode.
pub fn configure(&mut self, config: &Config, filters: &[hal.CanFilter]) -> void!hal.Error
Controller.set_mode
Function · Source
Switch to
mode, keeping the configuration. The chip changes mode only between frames, and Timeout if it has not after MODE_POLLS reads.
pub fn set_mode(&mut self, mode: Mode) -> void!hal.Error
Controller.poll_send
Function · Source
Queue
framein a free transmit buffer and request it; see hal.Can and “Sending” above. False while no buffer can take it in order. Unsupported for an FD frame, as the chip sends classic CAN only; Bus while the chip is bus-off (EFLG.TXBO).
pub fn poll_send(&mut self, frame: &hal.CanFrame) -> bool!hal.Error
Controller.poll_receive
Function · Source
Take the oldest received frame into
frame; see hal.Can and “Receiving” above. False while none waits. Overrun once after frames were lost, clearing EFLG.RX0OVR and RX1OVR.
pub fn poll_receive(&mut self, frame: &mut hal.CanFrame) -> bool!hal.Error
Controller.error_state
Function · Source
The fault confinement state from EFLG: BusOff with TXBO, Passive with TXEP or RXEP, else Active. SPI errors pass through.
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.
pub fn tec(&mut self) -> u8!hal.Error
Controller.rec
Function · Source
The receive error counter (REC): error-passive from 128.
pub fn rec(&mut self) -> u8!hal.Error
Controller.error_flags
Function · Source
The error flags (EFLG), for the warning bits error_state does not report.
pub fn error_flags(&mut self) -> u8!hal.Error
Controller.listen
Function · Source
Pull INT low while any of
sources(RECEIVE, TRANSMIT, ERROR, or several ORed together) has its flag set.
pub fn listen(&mut self, sources: u8) -> void!hal.Error
Controller.ignore
Function · Source
Stop pulling INT low for
sources.
pub fn ignore(&mut self, sources: u8) -> void!hal.Error
Controller.interrupt_pending
Function · Source
Whether INT is low now: a source listened to has its flag set.
pub fn interrupt_pending(&mut self) -> bool!hal.Error
Controller.acknowledge
Function · Source
Clear the TRANSMIT and ERROR flags among
sources, which hold INT low until cleared. The RECEIVE flags are left alone: they clear as poll_receive takes the frames, and clearing one by hand would drop a frame.
pub fn acknowledge(&mut self, sources: u8) -> void!hal.Error
Controller.abort_pending
Function · Source
Cancel every frame waiting to be sent (ABAT) and wait until the chip has dropped them; a frame already on the bus finishes first. Timeout after MODE_POLLS reads.
pub fn abort_pending(&mut self) -> void!hal.Error
Controller.bus
Function · Source
The SPI bus, for other devices on it between CAN calls, each with its own chip select.
pub fn bus(&mut self) -> &mut B from(self)
Controller.release
Function · Source
Give back the bus and the chip-select pin. The chip keeps running.
pub fn release(self) -> (B, P)