Traits for CAN (Controller Area Network)

Author: timokroeger

src/can/blocking.rs

@@ -0,0 +1,17 @@
+//! Blocking CAN API
+
+/// A blocking CAN interface that is able to transmit and receive frames.
+pub trait Can {
+    /// Associated frame type.
+    type Frame: crate::can::Frame;
+
+    /// Associated error type.
+    type Error;
+
+    /// Puts a frame in the transmit buffer. Blocks until space is available in
+    /// the transmit buffer.
+    fn write(&mut self, frame: &Self::Frame) -> Result<(), Self::Error>;
+
+    /// Blocks until a frame was received or an error occured.
+    fn read(&mut self) -> Result<Self::Frame, Self::Error>;
+}

src/can/id.rs

@@ -0,0 +1,103 @@
+//! CAN Identifiers.
+
+/// Standard 11-bit CAN Identifier (`0..=0x7FF`).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub struct StandardId(u16);
+
+impl StandardId {
+    /// CAN ID `0`, the highest priority.
+    pub const ZERO: Self = Self(0);
+
+    /// CAN ID `0x7FF`, the lowest priority.
+    pub const MAX: Self = Self(0x7FF);
+
+    /// Tries to create a `StandardId` from a raw 16-bit integer.
+    ///
+    /// This will return `None` if `raw` is out of range of an 11-bit integer (`> 0x7FF`).
+    #[inline]
+    pub const fn new(raw: u16) -> Option<Self> {
+        if raw <= 0x7FF {
+            Some(Self(raw))
+        } else {
+            None
+        }
+    }
+
+    /// Creates a new `StandardId` without checking if it is inside the valid range.
+    #[inline]
+    pub const unsafe fn new_unchecked(raw: u16) -> Self {
+        Self(raw)
+    }
+
+    /// Returns this CAN Identifier as a raw 16-bit integer.
+    #[inline]
+    pub fn as_raw(&self) -> u16 {
+        self.0
+    }
+}
+
+/// Extended 29-bit CAN Identifier (`0..=1FFF_FFFF`).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub struct ExtendedId(u32);
+
+impl ExtendedId {
+    /// CAN ID `0`, the highest priority.
+    pub const ZERO: Self = Self(0);
+
+    /// CAN ID `0x1FFFFFFF`, the lowest priority.
+    pub const MAX: Self = Self(0x1FFF_FFFF);
+
+    /// Tries to create a `ExtendedId` from a raw 32-bit integer.
+    ///
+    /// This will return `None` if `raw` is out of range of an 29-bit integer (`> 0x1FFF_FFFF`).
+    #[inline]
+    pub const fn new(raw: u32) -> Option<Self> {
+        if raw <= 0x1FFF_FFFF {
+            Some(Self(raw))
+        } else {
+            None
+        }
+    }
+
+    /// Creates a new `ExtendedId` without checking if it is inside the valid range.
+    #[inline]
+    pub const unsafe fn new_unchecked(raw: u32) -> Self {
+        Self(raw)
+    }
+
+    /// Returns this CAN Identifier as a raw 32-bit integer.
+    #[inline]
+    pub fn as_raw(&self) -> u32 {
+        self.0
+    }
+
+    /// Returns the Base ID part of this extended identifier.
+    pub fn standard_id(&self) -> StandardId {
+        // ID-28 to ID-18
+        StandardId((self.0 >> 18) as u16)
+    }
+}
+
+/// A CAN Identifier (standard or extended).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub enum Id {
+    /// Standard 11-bit Identifier (`0..=0x7FF`).
+    Standard(StandardId),
+
+    /// Extended 29-bit Identifier (`0..=0x1FFF_FFFF`).
+    Extended(ExtendedId),
+}
+
+impl From<StandardId> for Id {
+    #[inline]
+    fn from(id: StandardId) -> Self {
+        Id::Standard(id)
+    }
+}
+
+impl From<ExtendedId> for Id {
+    #[inline]
+    fn from(id: ExtendedId) -> Self {
+        Id::Extended(id)
+    }
+}

src/can/mod.rs

@@ -0,0 +1,47 @@
+//! Controller Area Network
+
+pub mod blocking;
+pub mod nb;
+
+mod id;
+
+pub use id::*;
+
+/// A CAN2.0 Frame
+pub trait Frame: Sized {
+    /// Creates a new frame.
+    /// Returns an error when the data slice is too long.
+    fn new(id: impl Into<Id>, data: &[u8]) -> Result<Self, ()>;
+
+    /// Creates a new remote frame (RTR bit set).
+    /// Returns an error when the data length code (DLC) is not valid.
+    fn new_remote(id: impl Into<Id>, dlc: usize) -> Result<Self, ()>;
+
+    /// Returns true if this frame is a extended frame.
+    fn is_extended(&self) -> bool;
+
+    /// Returns true if this frame is a standard frame.
+    fn is_standard(&self) -> bool {
+        !self.is_extended()
+    }
+
+    /// Returns true if this frame is a remote frame.
+    fn is_remote_frame(&self) -> bool;
+
+    /// Returns true if this frame is a data frame.
+    fn is_data_frame(&self) -> bool {
+        !self.is_remote_frame()
+    }
+
+    /// Returns the frame identifier.
+    fn id(&self) -> Id;
+
+    /// Returns the data length code (DLC) which is in the range 0..8.
+    ///
+    /// For data frames the DLC value always matches the length of the data.
+    /// Remote frames do not carry any data, yet the DLC can be greater than 0.
+    fn dlc(&self) -> usize;
+
+    /// Returns the frame data (0..8 bytes in length).
+    fn data(&self) -> &[u8];
+}

src/can/nb.rs

@@ -0,0 +1,28 @@
+//! Non-blocking CAN API
+
+/// A CAN interface that is able to transmit and receive frames.
+pub trait Can {
+    /// Associated frame type.
+    type Frame: crate::can::Frame;
+
+    /// Associated error type.
+    type Error;
+
+    /// Puts a frame in the transmit buffer to be sent on the bus.
+    ///
+    /// If the transmit buffer is full, this function will try to replace a pending
+    /// lower priority frame and return the frame that was replaced.
+    /// Returns `Err(WouldBlock)` if the transmit buffer is full and no frame can be
+    /// replaced.
+    ///
+    /// # Notes for implementers
+    ///
+    /// * Frames of equal identifier shall be transmited in FIFO fashion when more
+    ///   than one transmit buffer is available.
+    /// * When replacing pending frames make sure the frame is not in the process of
+    ///   being send to the bus.
+    fn transmit(&mut self, frame: &Self::Frame) -> nb::Result<Option<Self::Frame>, Self::Error>;
+
+    /// Returns a received frame if available.
+    fn receive(&mut self) -> nb::Result<Self::Frame, Self::Error>;
+}

src/lib.rs

@@ -409,6 +409,7 @@
 pub mod fmt;
 pub use nb;
 pub mod adc;
+pub mod can;
 pub mod capture;
 pub mod delay;
 pub mod digital;