zencan-node

Crate for implementing a zencan device. Usually used in an embedded no_std context, but also can be used elsewhere.

Usage

Create a device config

First create a TOML file to define the properties of your node. This includes information like the device name and identity information, as well as a list of application specific objects to be created. All nodes get a set of standard objects, in addition to the custom ones defined in the device config.

Sample device config

device_name = "can-io"

# The device identity includes the vendor, product, revision and a serial
# number. The serial number should be unique among all device instances, so it
# is provided by the application at run-time -- e.g. from a value stored in
# flash, or a MCU UID register.
[identity]
vendor_id = 0xCAFE
product_code = 32
revision_number = 1

# PDOs are used for sending "process data". Values which are transferred
# frequency on the bus, such as control commands or sensor readings, are
# typically sent and recieved using Transmit PDOs (TPDOs) and Receive PDOs
# (RPDOS). These are configured at run-time by writing to the appropriate PDO
# configuration objects, but the number of PDOs which can be configured must be
# defined here, at compile time.
[[pdos]]
num_tpdos = 4
num_rpdos = 4

# Create an array object to store the four u16 raw analog readings
# It is read-only, so it can only be updated by the application
# It can be mapped to transmit PDOs for sending data to the bus
[[objects]]
index = 0x2000
parameter_name = "Raw Analog Input"
object_type = "array"
data_type = "uint16"
access_type = "ro"
array_size = 4
default_value = [0, 0, 0, 0]
pdo_mapping = "tpdo"

# An object for storing the scaled analog values
[[objects]]
index = 0x2001
parameter_name = "Scaled Analog Input"
object_type = "array"
data_type = "uint16"
access_type = "ro"
array_size = 4
default_value = [0, 0, 0, 0]
pdo_mapping = "tpdo"

# A configuration object for controlling the frequency of analog readings
[[objects]]
index = 0x2100
parameter_name = "Analog Read Period (ms)"
object_type = "var"
data_type = "uint32"
access_type = "rw"
default_value = 10

# A configuration object which can be used to adjust the linear offset and scale transform used to
# calculate the value in 0x2001
[[objects]]
index = 0x2101
parameter_name = "Analog Scale Config"
object_type = "record"
[[objects.subs]]
sub_index = 1
parameter_name = "Scale Numerator"
data_type = "uint16"
access_type = "rw"
default_value = 1
[[objects.subs]]
sub_index = 2
parameter_name = "Scale Denominator"
data_type = "uint16"
access_type = "rw"
default_value = 1
[[objects.subs]]
sub_index = 3
parameter_name = "Offset"
data_type = "uint16"
access_type = "rw"
default_value = 0

Add zencan-build and zencan-node as a dev-dependency

zencan-build contains functions for generating the object dictionary code, and can be used as a build dependency.

cargo add --build zencan-build

zencan-node is compiled in as a normal dependency.

cargo add zencan-node

Build the generated code in build.rs

In your build.rs script, add code like this:

fn main() {
    if let Err(e) = zencan_build::build_node_from_device_config("ZENCAN_CONFIG", "zencan_config.toml") {
        eprintln!("Failed to parse zencan_config.toml: {}", e.to_string());
        std::process::exit(-1);
    }
}

Include the generated code in your application

When including the code, it is included using the name specified in build -- ZENCAN_CONFIG in this case. This allows creating multiple object dictionaries in a single applicaation.

Typically, an application would add a snippet like this into main.rs:

mod zencan {
    zencan_node::include_modules!(ZENCAN_CONFIG);
}

Instantiate a node

    // Use the UID register or some other method to set a unique 32-bit serial number
    let serial_number: u32 = get_serial();
    zencan::OBJECT1018.set_serial(serial_number);

    let node = Node::new(
        NodeId::Unconfigured,
        &zencan::NODE_MBOX,
        &zencan::NODE_STATE,
        &zencan::OD_TABLE,
    );

Feed it incoming messages, and poll process

Since Zencan doesn't know what your CAN interface looks like, you have to do some plumbing to wire it up.

Received messages can be passed in using the NODE_MBOX struct, which serves as a Sync buffer between the receive and process contexts. For example:

zencan::NODE_MBOX.store_message(msg)?;

The node process() method must be called from time to time. It isn't critical how fast, but your node's response time depends on it. The NODE_MBOX also provides the set_process_notify_callback method. This can optionally be used to register a callback for whenever there is new information to be processed, so that the process() call can be accelerated by the application.

Here's an example snippet which uses lilos and a Notify object -- which is set by a register process notify callback function to trigger the process task to run immediately on process, or after a 10ms timeout when no callback is received.

/// A task for running the CAN node processing periodically, or when triggered by the CAN receive
/// interrupt to run immediately
async fn can_task(
    mut node: Node<'static>,
    mut can_tx: fdcan::Tx<FdCan1, NormalOperationMode>,
) -> Infallible {
    let epoch = lilos::time::TickTime::now();
    loop {
        lilos::time::with_timeout(Duration::from_millis(10), CAN_NOTIFY.until_next()).await;
        let time_us = epoch.elapsed().0 * 1000;
        // Process is called with the current time, so that it can execute periodic tasks, and a
        // callback for transmitting messages.
        node.process(time_us, &mut |msg| {
            // Convert between zencan and fdcan frame types
            let id: fdcan::id::Id = match msg.id() {
                zencan_node::common::messages::CanId::Extended(id) => {
                    fdcan::id::ExtendedId::new(id).unwrap().into()
                }
                zencan_node::common::messages::CanId::Std(id) => {
                    fdcan::id::StandardId::new(id).unwrap().into()
                }
            };
            let header = fdcan::frame::TxFrameHeader {
                len: msg.dlc,
                frame_format: fdcan::frame::FrameFormat::Standard,
                id,
                bit_rate_switching: false,
                marker: None,
            };
            can_tx.transmit(header, msg.data()).ok();
        });
    }
}

Socketcan Example

You can also run a node on linux, with socketcan. This can be useful for testing with a virtual can adapter. See this example for a full implementation.