Static data intro​

I encourage the use of static storage for all of your embedded application data storage. The reason is that then you know pretty well at build time what your RAM usage is and if it will fit, and you have less risk of stack overflow when the stack is used only for small local stuff.

So, a common pattern is allocating large buffers of data in static variables. However, rust also has some limits on const functionality which can be used for initalization, and some strict rules about uninitialized variables, so a common pattern is to store your static variables in an Option which starts at None, and gets initialized at startup:

static DATA: Mutex<Option<MyType>>  = Mutex::new(None);

BSS vs DATA​

A key thing to know is that your static variables can end up in two categories:

BSS is a section of memory which is zero-ized during the runtime init -- before your application hits main. DATA is a section of memory that get copied into RAM during the runtime init. The key differentiator is that DATA goes into your flash -- it's part of your code size -- while BSS does not.

Variables which are initialized with ALL zeros go into BSS. Variables which are not, go into DATA. And, there's no splitting up data, or compresssion here. If a struct has a size of 1kB, and one byte in the initial value is non zero, all 1kB will be stored into your flash! This can lead to some surprising code bloat, so it's generally a good idea to try to make sure that your large data types can be zero-initialized where possible.

Is None encoded with zeros?​

If you'd asked me a couple days ago, I'd have said: "yes, I think so!" Now, I know the answer is: "Usually!"

But today, when I was investigating my code size, I found a surprising large symbol in the data section. The size made sense -- the struct contained about 5kB worth of CAN message buffering -- but it was being initialied with None so why was it going into the .data section?!

The answer appears to be that None is usually encoded with zeros, but not always. For example, there is an exception when wrapping bool types, which the compiler knows can only have the value of 0 or 1. Since it knows the bool can never be 2, it is free to use the value of 2 as the discriminant for None, and combine the discriminant into the value byte, so it does. This has the benefit that size_of::<Option<bool>>() is 1, just like the bool. Otherwise, it would have to prepend an extra discriminant in front of the bool value, making the size of the data type larger in memory.

My struct, in addition to the CAN message buffers, had an array of bools, and so it seems that the compiler re-arranged the ordering of the struct in memory so that the array of bools came first, and then used a value of 2 as the discriminant for the Option enum, and so my entire 5k struct got initialized from .data.

Demo Code​

I wrote a quick example to demonstrate the behavior:

use core::mem::{size_of, transmute};

struct Foo {
    buf: [u32; 256],
}

struct FooWithBool {
    value: bool,
    buf: [u32; 256],
}

struct FooWithBoolArray {
    value: [bool; 4],
    buf: [u32; 256],
}

static FOO: Option<Foo> = None;
static FOO_WITH_BOOL: Option<FooWithBool> = None;
static FOO_WITH_BOOL_ARRAY: Option<FooWithBoolArray> = None;
static BOOL: Option<bool> = None;

fn main() {
    const FOO_SIZE: usize = size_of::<Foo>();
    const FWB_SIZE: usize = size_of::<FooWithBool>();
    const FWBA_SIZE: usize = size_of::<FooWithBoolArray>();
    const BOOL_SIZE: usize = size_of::<Option<bool>>();
    let foo_data: &[u8; FOO_SIZE] = unsafe { transmute(&FOO) };
    let fwb_data: &[u8; FWB_SIZE] = unsafe { transmute(&FOO_WITH_BOOL) };
    let fwba_data: &[u8; FWBA_SIZE] = unsafe { transmute(&FOO_WITH_BOOL_ARRAY) };
    let bool_data: &[u8; BOOL_SIZE] = unsafe { transmute(&BOOL) };

    // Show the first 12 bytes of each
    println!("size_of Option<Foo>: {}", FOO_SIZE);
    println!("size_of Option<FooWithBool>: {}", FWB_SIZE);
    println!("size_of Option<FooWithBoolArray>: {}", FWBA_SIZE);
    println!("size_of Option<bool>: {}", BOOL_SIZE);
    println!("FOO:           {:?}", &foo_data[..12]);
    println!("FOO_WITH_BOOL: {:?}", &fwb_data[..12]);
    println!("FOO_WITH_BOOL_ARRAY: {:?}", &fwba_data[..12]);
    println!("BOOL: {:?}", bool_data);
}

You can also run this yourself on the Rust Playground

The ouput?

size_of Option<Foo>: 1024
size_of Option<FooWithBool>: 1028
size_of Option<FooWithBoolArray>: 1028
size_of Option<bool>: 1
FOO:           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
FOO_WITH_BOOL: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
FOO_WITH_BOOL_ARRAY: [2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
BOOL: [2]

As you can see, with a plain bool, you get a non-zero encoding, as with the array of bools. A single bool in the struct does NOT result in non-zero None encoding, I think because it had to pad the bool anyway, so the 3 extra padding bytes can be used to store the discriminant.

The solution​

The only reliable solution I can think of to ensure a static var initializes with 0 is to use MaybeUninit.

The static_cell crate handles this well for you when you just need a local &mut. It will not really help you share the static with an IRQ.

The Bobiverse Series​

A 5-book series by Dennis E. Taylor.

This is almost certainly the most fun read on this list. I bought the first book on a recommendation from my brother, and then went through all five books over the next couple months. It's a light, somewhat corny sci-fi story based on a formerly-human "replicant" named Bob -- his mind uploaded onto some specialized hardware, he's sort of an AI with human memories -- who is placed in command of a self-reproducing Von Neumann probe and sets off to explore the galaxy. Over the centuries, he ends up building a whole new post-organic civilization.

Apparently, book 6 is coming, and I look forward to it.

The Control of Nature​

This is a book of three journalistic essays by John McPhee, published in 1989.

The essays are:

1. A story of the Army Corp of Engineers and it's struggles to keep the Mississippi river on its course.
2. The 1973 Heimaey eruption in Iceland, and how a ragtag team worked to aquire every pump they could to move enough sea-water to redirect the lava flows and save the harbor.
3. Debri flows in the San Gabriel mountains around Los Angeles, and the cities struggle to contain them

The Icelandic eruption was my favorite. The stories of walking, driving bull dozers, and keeping hoses running across the barely solidified lava fields as things spontaneously caught on fire and lava bombs fell from the sky are great. I ended up visiting Iceland shortly after reading it, and was disappointed I didn't have time to take the ferry to the island where it took place.

The Nvidia Way​

A profile of Jensen Huang and the rise of Nvidia by Tae Kim. I found this to be a very well written book filled with interesting details and stories. I think this kind of book can easily be very boring, but this one really held my attention, and I learned some things.

The original problem​

In zencan, objects have a default value. Of course they do -- they have to start with something! Often times that's just 0, but some objects should be initialized with particular values. For "application objects" -- the custom objects created in the application-specific "device config" file -- the default value can be specified as part of the object definition. However, some objects are defined automatically for the application by the code generation system, including the PDO configuration objects. Until just recently, there wasn't any way to specify the defaults for these.

PDO config objects (there are two for each PDO, called the "comm", and "mapping" objects) control how PDO messages are sent and received, and which data objects the PDO payload bytes are mapped to. Up to now, I've configured PDOs by writing to the comm and mapping objects via the SDO server, and then saving those values to flash. That's great and this type of run-time configurability is a key motivator for the project, but for some applications it makes a lot of sense to boot up with pre-configured PDOs, and so zencan needed a mechanism to specify defaults.

So, easy enough: I'll add some attributes in the [pdos] section of the device config to set the defaults, I figured. I already have a schema used in the "node configuration" files, which are used by zencan-client to do the run-time configuration. It looks like this:

# Configure TPDO1 to send on CAN ID 0x200
[tpdo.1]
enabled = true
cob = 0x200
transmission_type = 254
# Fill the PDO data with 4 bytes from object 0x2000sub1 and 4 more from 0x2000sub2
mappings = [
    { index=0x2000, sub=1, size=32 },
    { index=0x2000, sub=2, size=32 },
]

"This will be quick and easy", I figured. It was not.

Objects in zencan are defined as static variables in generated code. Then references to all the objects are put into a list of ODEntry objects. It looks something like this:

pub static RPDO_COMM_OBJECTS: [PdoCommObject; 1usize] = [
    PdoCommObject::new(&NODE_STATE.rpdos()[0usize]),
];

pub static OBJECT1000: Object1000 = Object1000::default();
pub static OBJECT1001: Object1001 = Object1001::default();
pub static OD_TABLE: [ODEntry; 3usize] = [
    ODEntry {
        index: 0x1000,
        data: &OBJECT1000,
    },
    ODEntry {
        index: 0x1001,
        data: &OBJECT1001,
    },
    ODEntry {
        index: 0x1400,
        data: &RPDO_COMM_OBJECTS[0usize],
    },
]

Defaults are just rust initializers. And this is where the first issue popped up.

Non-const init​

The first problem you hit here is that when you write to the mapping object, you write a u32 referencing the object-to-be-mapped by index and sub-index. But what the PDO actually stores is a reference to the object, so that it doesn't have to search through the table every time it has to load/store data. The data stored for each mapping looks like this:

/// Data structure for storing a PDO object mapping
struct MappingEntry {
    /// A reference to the object which is mapped
    pub object: &'static ODEntry<'static>,
    /// The index of the sub object mapped
    pub sub: u8,
    /// The length of the mapping in bytes
    pub length: u8,
}

Strictly speaking, the code generation "knows" the name and ID of every object, so it could probably generate const MappingEntry objects with the correct static references. But this is going to really complicated the already too complicated code generation code, and also yet another datatype that should be private has to become public, because the generated code now has to know more about the internals of the PDO object implementation.

But there's a bigger reason this isn't worth pursuing: Eventually zencan needs to support restoring defaults at run-time for all objects. So objects need to store a live working value as well as the default value for re-initializing.

Duplicating memory​

This raises a new concern: to restore at default, there is a requirement that both the default value and the live value be stored somewhere. But, ideally, the default value will be stored exactly once, and only in flash, while the live value will also be stored exactly once, and in RAM.

This led down a new rabbit hole of testing what scenarios rust will place data into the data section vs bss. The data section is part of the program flash size and static RAM allocation -- it is copied to RAM to initialize the variables. The bss section is just zero'd, so it doesn't have corresponding bytes in flash, making the program size smaller. In order for an object to live in bss, it needs to be initialized with all zeros. Incidentally, if one of the attributes of your object is a reference, it cannot be initialized with zeros.

There are other concerns, like in the case of PDOs, they have to allocate RAM storage for the maximum allowed number of mappings, but in flash, it would be better if the defaults were stored as variably-sized slices, so only the number of mappings initialized in the default have to take up program space.

I suspect that in the future, this will be revisted, and I think the path is going to be to enforce that the object and the object dict are private and can only be accessed via a getter function which can ensure a one-time lazy initialization process is observed. This will allow things like MaybeUnininit<&'static Pdo> where needed, to ensure that objects can go into BSS.

But as spun in a few circles on this, I realized that I was falling into a classic scope creep trap that I am very susceptible to: instead of finishing the PDO default feature I set out to implement I was refactoring all object initialization which could better be done in a follow-on PR. So I'm leaving this for later, and accepting that the first pass at PDO defaults may use more flash bytes than strictly necessary.

Defaults as a function of runtime state​

It is standard in CANOpen devices for the default PDO COB IDs to be based on the configured node ID, e.g. $NODEID+0x180. This makes a lot of sense: you might have a device that puts out some PDOs by default, and you might put more than one of those devices on the network, so zencan should support this! This means that the default we wish to load isn't even known at compile time.

Also! The main unit of information is the object data -- i.e. the bytes stored in the objects. This is what remote clients can access via the SDO server, and this is what is stored in flash when settings are persisted. So lets say our node ID is 1 and the default initializer has set the COB ID to 0x181. Now, lets say we save all the objects to flash. Then we change the node ID to 2 and reset. Should the new COB ID be 0x182? That's what I would expect! The user never changed it from the default, which is $NODEID+0x180, and now $NODEID=2, so 0x182. But what we read from flash for the COMM object is 0x181. Did the user write this value, or was it a default calculation? We now have to somehow distinguish these cases.

We could track whether the default COMM value has been changed, and then skip storing it to flash if it has not been changed from the default. That would help. But as things are setup currently, the object can't distinguish between a default being written and a value written from e.g. an SDO client.

Speaking of SDO clients: ideally, when they read the PDO configuration they could tell the difference between a COB ID which is set to 0x181 and a COB ID which is set to $NODEID+0x180. Ideally they'd even be able to configure a COB ID to use a node ID offset at runtime. If I was designing this protocol, I'd put a flag in the PDO COMM object called add_node_id to control this behavior so that the state is encoded in the object.

As I have done before when I have found the CANOpen protocol confounding, I went and and looked at what the most popular C implementation does (relevant file).

/* if default CAN-ID is written, store to OD without Node-ID */
if (CAN_ID == PDO->preDefinedCanId) {
    (void)CO_setUint32(bufCopy, COB_ID & 0xFFFFFF80U);
}

/* If default CAN-ID is stored in OD (without Node-ID), add Node-ID */
if ((CAN_ID != 0U) && (CAN_ID == (preDefinedCanId & 0xFF80U))) {
    CAN_ID = preDefinedCanId;
}

To understand the above snippets, you should know that (sticking with $NODEID=1 and COB_ID=$NODEID + 0x180 as an example) preDefinedCanId is set to 0x181. If the value encoded in the object is 0x180, it always adds the node id. If a user writes 0x181, it assumes that what the user really meant was $NODEID + 0x180 and stores 0x180 to the object. So if I try to write 0x181, it gets converted to 0x180. And when the stored value is 0x180, that is interpreted as the default $NODEID+0x180.

I don't love this. It's a special rule, and it's a surprising behavior. It also makes it impossible to use 0x180 as a COB ID, or to set the COB ID to 0x181 irrespective of the node ID. If I write 0x181 to the COB ID, I expect that to be the new COB ID even if I change the node ID. It's not hard to come up with a use case where this actually becomes a problem:

Imagine some device expects a particular message on 0x181 because historically it was sent by node 1 using the default. I come along and decide that I'm going to manage my network by serial number, and I don't care about what node IDs are assigned, so I write a controller which enumerates the nodes via LSS, and assigns them arbitrary IDs, but loads configurations into each node based on serial number. I want a node with a particular serial number to send the 0x181 PDO, so I set it up that way, only to find that when assigned a random node ID it is suddenly sending the PDO on a different ID!.

Also I think ideally it should be possible to set default PDO IDs which do not have the node ID added. A realistic use case is: "this type of device always sends this message, regardless of the assigned node ID". But this precludes any default initialization scheme which is limited to restoring object values, because the answer to the question "should I add the node ID" is not encoded anywhere in the object values. This is the same situation I'm sure the CANOpenNode author(s) were faced with when they decided to enact the special rules above.

Options​

Once again I am tempted to throw out the CANOpen spec and go my own way, but I'm not quite there yet. Some options considered:

1. Use COB_ID=0 as a special value indicating to use the default. The default has to be stored outside of the object data, and serialization to persistent storage has to be prevented when the value is 0 (because serializing just reads the object, and reading the object returns the computed value).
2. Adopt the special rules of CANOpenNode.
3. Drop support for adding node ID to PDO IDs altogether.
4. Add a new sub object to the PDO comm object to store a flag for "add the node ID" behavior.

I think 4 is clearly the ideal. Doing anything else feels like I am compromising for the sake of an old protocol, but also, if I add a sub object then someone, someday is going to use zencan to try to do a CANOpen compliance certification and will fail and be annoyed with me.

Number 2 and 3 I think are non-starters. The NODE ID offsets are standard and useful, and the special rules of number 2 are just too weird of a corner case for my taste.

So number 1 seems like the most plausible. It allows assigning any ID to the PDO via SDO, and it allows defaults to include the node ID or not. It does not allow an SDO client to distinguish between default and non-default state in general, and it does not allow setting arbitrary $NODEID + x values for the COB ID, but this is not an immediate problem at least. Also, I think it is still relatively easy in the future to add an optional extension sub-object to the COMM object with the add_node_id flag if the need ever really does arise.

After a big push back in June to get to something that more or less worked, I published zencan on github and then proceeded to lose momentum for a while. My attention wandered to other things, and I've been traveling a lot. But in the meantime, it has been out there, and I can tell that at least a few people have been trying to use it, because some of them have reached out to me about it. The project even picked up a second contributor: Ettiene provided some examples for the esp32, as well as fixing some bugs. I can also see from the search traffic that people are out there searching for "rust canopen". All of this is good motivation to put more work into the project.

I put off publishing the crates initially because I was hoping to resolve some changes to a dependency I had forked. After radio silence from the maintainer¹, I ended up working around that easily enough. Beyond that, it has just been a nagging sense of perfectionism -- there are more features I should implement or better docs to write before it was worth publishing a crate. Somehow pushing the crate feels more symbolic than throwing some code onto a github repo. It feels like more of a statement that "this is actually good enought to use".

But I decided it will be fine, and I think the practice of releases, writing changelogs, considering breaking changes more, etc will be good for the process.

Also! The timing is good now because rust v1.90 stabilized multi package publishing! One of the authors of this feature wrote a good blog post about it. Zencan is broken up into many crates, so this made the releasing process a lot easier.

Now there are more features to work on. Top of the probable list are:

• CAN-FD support
• Refactoring the device config / object dictionary management code, and adding EDS export
• SDO Client Updates
  • blocking client support
  • no_std client support
• SYNC support (client and node)

Getting code onto the device​

If you successfully built an image using coremp135-bsp, and you added your key to the authorized_keys file on the target, you should be able to SSH to it by connecting to ETH1 and using the static IP configured on it -- 192.168.2.254, or whatever you customized it to.

Then you can copy files to it with scp, e.g. scp -O my_file root@192.168.2.254:/root/.

I like to add the following entry to ~/.ssh/config to simplify connecting:

host coremp135
    HostName 192.168.2.254
    StrictHostKeyChecking no
    UpdateHostkeys yes
    User root

From here on out, you may see me reducing transfers to scp -O my_file coremp135:/root/; this is why.

Cross Compiling​

First of all, lets just get Hello World building.

Create a new project: cargo init

Add a rust-toolchain.toml file with the following:

[toolchain]
channel = "1.90.0"
targets = [ "armv7-unknown-linux-gnueabihf" ]
profile = "default"

And, we'll go ahead and add the linuxfb dependency -- we're going to it later, and it is going to be using bindgen, and will require some header files from the buildroot system, so lets get it compiling now too.

cargo add linuxfb

Now you can build for the arm target with the following command, but it will fail!

cargo build --release --target=armv7-unknown-linux-gnueabihf

We need to use the linker from buildroot, which is setup in .cargo/config.toml:

# .cargo/config.toml
[target.armv7-unknown-linux-gnueabihf]
linker = "arm-buildroot-linux-gnueabihf-gcc"

Great. Now building will fail differently!

We're going to be setting up some environment variables, to get that linker in our path and also to setup some options for sysroots. The extra options aren't necessary if we are building pure rust, but when you link against shared libraries, or compile C code (e.g. with bindgen/clang) during the build, you likely will need them. I put these environment variables into .envrc, so they can be used with tools like direnv, but they can also be activated in your current shell by simply sourcing the file: . ./.envrc.

# .envrc

# The directory where host binaries are stored in `/bin`, and the sysroot is stored in
# `arm-buildroot-linux-gnueabihf/sysroot`. This can be `output/host` in a buildroot working
# directory, or an SDK tarball built using `make sdk`
BUILDROOT_SDK_RELATIVE="../buildroot/output/host"
# Paths have to be absolute, because crates will build with different working directories
export BUILDROOT_SDK=$(cd "$BUILDROOT_SDK_RELATIVE"; pwd -P)
export SYSROOT=$BUILDROOT_SDK/arm-buildroot-linux-gnueabihf/sysroot
export PKG_CONFIG_SYSROOT_DIR=$SYSROOT
export PKG_CONFIG_PATH=$SYSROOT/usr/lib/pkgconfig/
# We need the linker (`arm-buildroot-linux-gnueabihf-gcc`) from buildroot in the path. But buildroot
# also builds a host rustc, and this will override the cargo installed rust toolchain unless we output
# cargo into path ahead of it
export PATH=$HOME/.cargo/bin:$BUILDROOT_SDK/bin:$PATH
# Bindgen is used by some lib crates, like linuxfb, and it needs to know where sysroot is as well
export BINDGEN_EXTRA_CLANG_ARGS_armv7_unknown_linux_gnueabihf="--sysroot $SYSROOT"

You can generate a tarball with all of the required sysroot files from buildroot using the make sdk target, and I do recommend doing this and saving the tarball once your linux system is somewhat stable.

Now hopefully, your program builds. You can transfer it to the target using scp, then login and run it:

scp -O target/armv7-unknown-linux-gnueabihf/release/demo coremp135:/root  
ssh coremp135
# ./demo 
Hello, world!

Building a UI​

The touchscreen can be used by drawing to the frame buffer at /dev/fb1, and reading input events from /dev/input/event0.

Rendering​

For this, we're going to use Slint to build the UI. You can use tools like the Slint vscode plugin or SlintPad to design the slint file, and it has good support for embedded devices (although note the licensing for commercial products). Of course, any UI library capable of drawing pixels to a frame buffer will work here too!

We'll use the Slint software renderer and the linuxfb crate crate to draw to the screen in our own event loop.

The minimum test application to render a slint UI looks like this:

First, add the following dependencies to Cargo.toml:

[dependencies]
linuxfb = "0.3.1"
slint = { version = "1.13.1", default-features = false, features = ["renderer-software", "std", "compat-1-2"] }


[build-dependencies]
slint-build = "1.13.1"

Then, add a simple .slint file to define the UI in ui/touch.slint:

import { AboutSlint, Button, VerticalBox } from "std-widgets.slint";

export component Demo inherits Window {
    VerticalBox {
        alignment: start;
        Text {
            text: "Hello World!";
            font-size: 24px;
            horizontal-alignment: center;
        }
        AboutSlint {
            preferred-height: 150px;
        }
        HorizontalLayout { alignment: center; Button { text: "OK!"; } }
    }
}

Then add a build.rs to compile your UI at build-time:

// build.rs
fn main() {
    slint_build::compile_with_config(
        "ui/touch.slint",
        slint_build::CompilerConfiguration::new()
            .embed_resources(slint_build::EmbedResourcesKind::EmbedForSoftwareRenderer),
    ).unwrap();
}

Then, in the application:

// main.rs
use std::{rc::Rc, time::Instant};
use slint::platform::{software_renderer::{MinimalSoftwareWindow, Rgb565Pixel}, Platform};

struct MyPlatform {
    window: Rc<MinimalSoftwareWindow>,
    start_instant: Instant,
}
impl MyPlatform {
    pub fn new(window: Rc<MinimalSoftwareWindow>) -> Self {
        let start_instant = Instant::now();
        Self {
            window,
            start_instant,
        }
    }
}
impl Platform for MyPlatform {
    fn create_window_adapter(
        &self,
    ) -> Result<Rc<dyn slint::platform::WindowAdapter>, slint::PlatformError> {
        Ok(self.window.clone())
    }

    fn duration_since_start(&self) -> core::time::Duration {
        self.start_instant.elapsed()
    }
}

// Include the types created by slint in build.rs
slint::include_modules!();

/// Draw the UI to the framebuffer and exit
fn main() {
    
    const DISPLAY_WIDTH: u32 = 320;
    const DISPLAY_HEIGHT: u32 = 240;
    let fb = linuxfb::Framebuffer::new("/dev/fb1").unwrap();

    let window = MinimalSoftwareWindow::new(Default::default());
    slint::platform::set_platform(Box::new(MyPlatform::new(window.clone()))).unwrap();
    window.set_size(slint::PhysicalSize::new(320, 240));

    // 'Demo' is the type exported in touch.slint
    let _ui = Demo::new().unwrap();
    let mut buffer = [Rgb565Pixel(0); (DISPLAY_WIDTH * DISPLAY_HEIGHT) as usize];
    slint::platform::update_timers_and_animations();
    
    window.draw_if_needed(|renderer| {
        let mut data = fb.map().unwrap();

        renderer.render(&mut buffer, DISPLAY_WIDTH as usize);
        unsafe {
            core::ptr::copy_nonoverlapping(
                buffer.as_ptr() as *mut u8,
                data.as_mut_ptr(),
                data.len(),
            )
        }
    });
}

Run that, and if all goes well, it will draw the UI onto the screen, and quit.

Input Events​

Now we need to be able to push buttons!

The evdev crate allows reading touch events from the touchscreen. The MinimalSoftwareWindow struct provides the dispatch_event() method for receiving input events. So to build an interactive UI, we just need to create an event loop: a thread which reads events, passes them to the Window, and then redraws as necessary. The only thing is, the dispatch_event() method wants to receive a `WindowEvent', so clearly we need some code to convert the evdev events into these.

If you are trying to do this...you are in luck! I did it already and published it in the slint-evdev-input crate.

The code for the entire event loop is getting a little long, so I'm not going to include it here. Instead, check it out in the repo.

Putting it all together​

Now, you can build your linux filesystem with buildroot, and you can compile a rust application, linking against the SDK/filesystem created by buildroot which will run on your system. But ultimately, you probably want to combine those steps.

There's no clear one-right-way here, that I see. One way would be to take the coremp135-bsp project, clone it, and start modifying it. But I wanted to set it up so that I could re-use a single BSP with different applications. The method I've arrived at is to create an application repository and have it pull in the buildroot tree and the coremp135-bsp tree as submodules, then define a second external tree which ammends the BSP tree to customize the system, and add its own applications.

IMHO, Buildroot does not exactly shine at this, and this process feels a little brittle. But, it is the best I've come up with so far.

Compiling outside of buildroot vs a package​

You can create your application as a buildroot package, letting the buildroot make system compile and install it. This is a very typical thing to do. The issues that I ran into were:

1. I want to also be able to cargo build + scp during development, so I need to set that up to link against the buildroot SDK anyway
2. The version of the rust toolchain included with buildroot was too old for me, so I preferred to compile with my own rust toolchain, rather than the one buildroot installs for itself.

Build and Install​

In the end, I have a simple Makefile at the top-level of the project which builds everything.

all: buildroot

.PHONY: buildroot
buildroot:
    cd buildroot; \
    make BR2_EXTERNAL=../coremp135-bsp:../canlogger-external coremp135_defconfig; \
    make COREMP135_EXFAT_DATA=1 -j4

The rust application is built and installed via a post-build script

set -e 

# Build rust application
(cd ${BR2_EXTERNAL_CANLOGGER_PATH}/canlogger; source ./.envrc; cargo build --release --target armv7-unknown-linux-gnueabihf)
# Copy application to target output directory
cp ${BR2_EXTERNAL_CANLOGGER_PATH}/canlogger/target/armv7-unknown-linux-gnueabihf/release/canlogger $TARGET_DIR/usr/bin/canlogger

# Copy overlay files to target output directory
cp -r ${BR2_EXTERNAL_CANLOGGER_PATH}/board/canlogger/overlay/* $TARGET_DIR

# Copy public key for login
if [ -e ~/.ssh/id_rsa.pub ]; then
  mkdir -p $TARGET_DIR/root/.ssh
  cp ~/.ssh/id_rsa.pub $TARGET_DIR/root/.ssh/authorized_keys
fi

And this seems to work OK.

Expandable Data partition​

A nuisance of programming devices with SD cards is that you don't generally know the size of the flash when you create an image -- more over, you ideally don't want create a 32GB image file just so you can program a mostly empty partition on a 32GB card.

My setup has three mountable partitions:

- rootfs A
- rootfs B
- data

The two rootfs partitions contain the filesystem, and are used by RAUC for doing updates -- if you are currently booting from A, then an update will be installed on B and the next reboot will boot from B.

The data partition is meant to store data which should not be erased on update. I also like to create separate filesystems for writing data, because setting things up so that your application doesn't write to your root filesystem is good for stability.

During image creation, the data partition is created as the last partition on the card, with a fixed, relatively small size. But really, I'd like it to be expanded to fill whatever space is available on the card. This is done in canlogger via an init script. After flashing the card, the first bootup will see that the partition table is small, and it will expand the partition to the end of the drive. Since the drive is already mounted as the / drive, a reboot is required to get linux to reload the partition table, so the script reboots after modifying partitions. Then on the next boot, it sees that the partition is large, but that the filesystem is still at its original size, so it resizes the filesystem. This is all handled in the S15resize_data init script.

Repos

All the relevant code is at https://github.com/mcbridejc/coremp135-canlogger. Oh, and it's also capable of logging two CAN busses to a CSV file on the exFAT partition. Maybe that's useful to somebody too.

If you want to build a project based on the CoreMP135 and want help, you can hire me! I'd love a good reason to design a custom board around the STM32MP1 or STM32MP2 family, so especially if you are thinking about doing that let's chat.

If you want to build a project based on the CoreMP135 and want help, you can hire me! I'd love a good reason to design a custom board around the STM32MP1 or STM32MP2 family, so especially if you are thinking about doing that let's chat.

About the CoreMP135​

I really like this little $75 computer from M5Stack. It's a nicely packaged, low power, small application processor which can run Linux and has a great set of IO with good connectors. It also has a small touch screen for a UI. It's like a less powerful, better packaged Raspberry PI designed for industrial control applications.

It's based on the STM32MP135. I'm a long-time user of the STM32 line of MCUs, and this family is a great addition to it -- it's an application processor with a peripheral set that feels more like a microcontroller than e.g. the broadcomm chips you find on a raspberry pi. It's single core, and has just 512MB of RAM, so it's a lightweight for computational power, but I don't usually need that and the packaging on this is so much nicer than a raspberry PI with some kluged on extension board to get the IO you need. It also comes with a DIN rail mount as well as tabs with screw holes for mounting in your system.

I first picked it up to replace a raspberry PI I had as a house monitor / control system for a camper. The raspberry PI had the usual problems:

• Power hungry
• I had to have large USB adapters for CAN and RS485, and I don't like those hanging off the USB-A ports in a vibration-heavy environment
• Flaky USB drivers that seem to crash every couple weeks, requiring a reboot.
• Needs a 5V regulator

The M5Stack has:

• 2 CAN controllers
• 1 RS485
• 1 TTL UART
• 1 I2C
• 2 gigabit ethernets!

This was perfect for my application, because it lowered the power consumption, runs off the 12V battery, has a smaller physical footprint, and I could use the integrated RS485 + CAN. The touch screen was a happy bonus.

Some things I wish it had: An on-board eMMC so that I can store the application there while still having the uSD card for removable storage, and the ability to connect a battery backup for the RTC to keep time when 12V power is removed.

I'm happy with it in the camper, and I have already ordered a second and found a use for it on a client project. It's now one of the things that I always want to have a spare on hand for when something comes up.

Programming with Buildroot Linux​

The hardware is great, but I felt that the buildroot examples from M5Stack left a lot to be desired. So I built my own buildroot external tree to support the board, and to base my own applications off of for faster development. So I'm going to walk through what I did to get up and running using buildroot, and RAUC for OTA updates.

Buildroot vs Debian​

M5Stack does provide a debian image you can load, and start using this like a normal linux machine, SSHing in and installing packages with apt. I threw this right out. I don't want to treat this like a server, I want to treat it like a microcontroller. This means I want a build process to create a complete image, and I want that image to be as small as possible. I also want the system to be stripped down to just what I need, because that's good for stability. I also want to support over-the-air updates, so it's easier to ship new code to the controller.

There are basically two common ways to build an embedded linux image: buildroot and yocto. I don't have a strong argument for one over the other, but I have a lot more experience with buildroot, and that is what M5Stack used for their example, so that is what I used.

Buildroot Basics​

The way buildroot works is: you checkout the buildroot repository, you configure it (e.g. you can start with make menuconfig, but more likely you start with a defconfig from somewhere else, more on that later), and then you build it. It will go and download tarballs of all the components you enabled -- this is things like the linux kernel and u-boot, as well as utilities for your file system like busybox and an ssh server. It's all the packages that make up a functioning linux system. It puts all these together into an image which you can load onto your flash device through a wildly convoluted series of makefiles and bash scripts.

Get the buildroot tree​

I started with the st/2024.02.9 branch of the bootlin buildroot fork. This does not appear to have a lot of changes from the mainline buildroot, and the changes seem to be related to trusted-firmware-m, which I don't think is relevant to the STM32MP135, so I think I could have just used the mainline buildroot. But I haven't it, so I'm not 100% sure.

The BR2 External Tree​

A typical way to customize a buildroot system is to create a "br2 external tree". This can contain your own configuration, filesystem overlay, device trees, custom packages, etc.

Bootlin maintains an example BR2 external tree for the whole STM32MP1 family here. It's really close, but you can't use this as-is for the CoreMP135 because it is based on dev boards which have different hardware, different pinouts, etc. The changes require, at minimum, some modification to device trees.

M5stack published their own fork of this for the CoreMP135 here. I wish they'd cleaned it up a bit -- e.g. by removing all of the dev board defconfigs, device trees, etc, to focus on the CoreMP135. You can build a filesystem from this, but I felt it was worth the time to dig into it and identify the important changes, prune the noise, and integrate it all into my own "board support package".

I spent a fair amount of time parsing the changes and integrating into my own config, and I think it was worth it because I understand much better what's going on, and now I have support for RAUC, examples of using the touchscreen, and a nice starting point for future projects on the CoreMP135. I spun up a new application last week for a client and it only took 1.5 days of work, because I could focus on building the new touch UI and application logic, and didn't have to think much at all about the underlying system configuration.

I'm using kernel v6.1. This is still fairly old (December 2022), and maybe one day I will take on updating to a more recent kernel. The bootlin external tree is using kernel v6.6 (October 2023), so there's probably no reason I can't use at least that. But there are patches that may be affected, and often there are device tree schema changes between kernel versions, so updating is not necessarily trivial. For now v6.1 is getting the job done and there are other things to do.

Touchscreen issues​

There are a collection of patches provided in the M5Stack BR2 external examples for the ILI9342C display, and for the backlight which is controlled by an AXP2101 power management IC. M5Stack provides two board configurations:

• coremp135 with kernel v6.1
• coremp135_5_15 with kernel v5.15

A major change between these two kernels is the implementation of the Direct Rendering Manager (DRM) subsystem for displays. On the 5.15, the LCD driver creates a framebuffer at /dev/fb1 and I found drawing to the display to be as simple as writing pixel data to this framebuffer. However, on the v6.1 kernel, the LCD is implemented as a TinyDRM device. Luckily, the DRM system does support the legacy frame buffer interface as well, but I found it did not work! After a log of digging and learning, I realized that the DRM pipeline was not being enabled, and the way I ended up enabling it is by installing modetest and running that. To add the modetest executable to the system, you need the right libdrm packages installed:

BR2_PACKAGE_LIBDRM=y
BR2_PACKAGE_LIBDRM_HAS_ATOMIC=y
BR2_PACKAGE_LIBDRM_INSTALL_TESTS=y

Then, I just added modetest to rc.local so it is run at boot. This was a huge time sink for me, and one of the reasons I became frustrated with the M5Stack examples -- the examples just do not seem to work on the coremp135 defconfig from the M5Stack repo. I suspect there is a more straightforward way to enable the pipeline via libdrm, but I haven't dug into that yet.

The backlight can be controlled easily via sysfs, by writing a number to /sys/class/backlight/axp2101_m5stack_bl/brightness, e.g.:

echo "100" > /sys/class/backlight/axp2101_m5stack_bl/brightness

RAUC for OTA​

Another problem to tackle was setting up RAUC for over-the-air updates. There are a lot of different config options, and a lot of things that have to be setup just right to get everything working.

The way I set it up is that the bundle always includes the entire filesystem, including linux and the application -- an alternative is that you can also set up separate bundles for the filesystem and the application, so that application updates can be smaller when they don't require any changes to the main system. There are two rootfs partitions (A and B), so that if a programming of one fails, it can fall back to booting from the previous version. There is also a third and separate data partition, which can be used to store data that does not get erased during updates.

RAUC requires communication between u-boot and linux, because ultimately it is u-boot which has to decide which partition to boot from. The communication is done via a shared section of flash which stores the "u-boot env". In the file stm32mp13_defconfig from the STMicro version of the u-boot tree, you can find the value of CONFIG_ENV_OFFSET defined as 0x900000, or you can once you've searched enough! This is there u-boot will look for its environment. There is also a second offset, CONFIG_ENV_OFFSET_REDUND, for a redundant copy of the env. Why is the env stored 9MB into the SD card? I've certainly no idea; I guess someone decided that would allow enough space to store the FSBL images before it.

So, when creating the final image file using genimage, you must make sure to allocate the env partitions at the right flash offsets and then store the uboot env there.

The final partition config in genimage.cfg looks like this:

image sdcard.img {
    hdimage {
        partition-table-type = "gpt"
    }

    partition fsbl1 {
        image = "%ATFBIN%"
    }

    partition fsbl2 {
        image = "%ATFBIN%"
    }

    partition fip {
        image = "fip.bin"
    }
    
    partition u-boot-env {
        image = "uboot-env.bin"
        # Matches CONFIG_ENV_OFFSET in U-Boot config
        offset = 0x900000
        # Matches CONFIG_ENV_SIZE in U-Boot config
        size = 0x2000
    }

    partition u-boot-env-red {
        image = "uboot-env.bin"
        # Matches CONFIG_ENV_OFFSET_REDUND in U-Boot config
        offset = 0x940000
        # Matches CONFIG_ENV_SIZE in U-Boot config
        size = 0x2000
    }

    partition rootfs-a {
        image = "rootfs.ext4"
        bootable = "yes"
        size = 500M
    }

    partition rootfs-b {
        image = "rootfs.ext4"
        size = 500M
    }

    partition data {
        image = "data.img"
    }
}

So, when creating the image, these partitions are loaded with the environment from the uboot-env.bin file. But where does this file come from you ask?! Well, it is created by the uboot-tools package, because in coremp135_defconfig, we specify the right options:

# Need to customize u-boot env for OTA support
BR2_PACKAGE_HOST_UBOOT_TOOLS=y
BR2_PACKAGE_HOST_UBOOT_TOOLS_ENVIMAGE=y
BR2_PACKAGE_HOST_UBOOT_TOOLS_ENVIMAGE_SOURCE="$(BR2_EXTERNAL_COREMP135_PATH)/board/coremp135/uEnv.txt"
BR2_PACKAGE_HOST_UBOOT_TOOLS_ENVIMAGE_SIZE="0x2000"
BR2_PACKAGE_HOST_UBOOT_TOOLS_ENVIMAGE_REDUNDANT=y

What goes in the env? Well, again as usual there are a few ways that one can go about it. What I ended up using was the countdown method, where u-boot keeps track of two counters: BOOT_A_LEFT and BOOT_B_LEFT. Each time u-boot boots from one of the partitions, it decrements the counter. If the counter for A reaches 0, it boots from B instead. When the linux image successfully boots, it sets the counter for the partition it booted from to 3 -- this is done by running rauc status mark-good in rc.local at boot.

To access the env from userspace, you use the fw_printenv and fw_setenv commands. These are configured via /etc/fw_env.config, which must also be setup to match the partitions of the env partitions, but here we can at least access them by label instead of by offset -- although, do note that you must enable eudev in order to get the /dev/disk/by-partlabel symlinks created.

/dev/disk/by-partlabel/u-boot-env 0 0x2000
/dev/disk/by-partlabel/u-boot-env-red 0 0x2000

SquashFS must also be enabled for both u-boot and the kernel. RAUC on the target has to be configured via /etc/rauc/system.conf, and also the RAUC bundle itself has to be built as part of the post-image.sh hook defined in the BSP external tree, using a key you created (see generate_rauc_key.sh) to sign it. If this is feeling all a bit convoluted...well, I agree! That's why I'm trying to make this BSP as re-usable as I can for myself.

If you get all that working, then OTA updates can be performed by simply running a command to grab the image from an HTTP server somewhere:

rauc install https://example.com/bundle.raucb

Checkout the repo​

My CoreMP135 BSP is stored on github: https://github.com/mcbridejc/coremp135-bsp

The goal is for this to be a base layer, allowing an application repo to include it as a submodule, and then build on top of it to add application specific stuff. But of course, you can also just fork it and modify it.

To build a filesystem, you can check out buildroot, and checkout coremp135-base, and then use buildroot make, e.g.:

git clone -b st/2024.02.9 https://github.com/bootlin/buildroot
git clone https://github.com/mcbridejc/coremp135-bsp
cd buildroot
make BR2_EXTERNAL=../coremp135-bsp coremp135_defconfig
make -j4

To use RAUC, you need to generate keys (see coremp135-bsp/generate_rauc_keys.sh) and store them somewhere. Then you can pass their location in using the environment variables RAUC_CERT_PATH and RAUC_KEY_PATH. You may also want to set RAUC_COMPATIBLE with a unique compatibility string for your device.

I also recommend copying a public SSH key to buildroot/output/target/root/.ssh/authorized_keys so you can use it to log in. You can customize the ETH1 static IP address if you like by editing coremp135-bsp/board/overlay/etc/network/interfaces.

Next steps: Adding a custom application​

Next up: Building a Rust Application for the CoreMP135 using Slint

Why?​

It's certainly not to save money. One reason is that it's fun to have projects. The other reason is that I can decide exactly what dimensions and features I want, rather than shopping around and settling for something else, and I think the steel frame ends up being a lower material cost and lower effort than using more wood. And If I'm being completely honest, a big reason is simply this: Melting metal with electricity is a rush.

Caveats​

I'm going to talk about what I did here. You should not infer from this that I have any idea what I'm talking about, and I'm not going to try to make a tutorial. Especially when it comes to welding, I am a complete noob. I've done this a few times now, and it works for me, but someone who knows what they are doing may well say I'm doing it all wrong. I learned everything I know about welding from...well, basically two youtube videos. If you read this andthink, "wow I can't believe he did it like that", feel free to reach out and tell me how I should have done it better!

The bedside tables​

Let's just start with some photo of the final products, shall we? That way everyone knows what I'm talking about.

I built two of these this summer. I like the double level table top, because it allows for including power outlets in a more out-of-the-way location, and for keeping books and such on the bottom, while leaving the top relatively uncluttered for storing a phone, or grabbing a glass of water in the middle of the night.

These are built from 3/4" square steel tubes welded together and painted black, and from 1x2 or 1x3 pine boards glued into panels. The drawers are built from single boards for the face, and 0.5" plywood for the sides, with 0.25" plywood bottoms.

Getting the steel​

For these, I used 16ga red oxide square tubes from steelsupplylp.com. They will cut it to desired lengths for you for a very reasonable price, which is great because then I don't have to cut it, and it makes the size reasonable for shipping. They say they cut to a 1/8" accuracy, but every time I've ordered they've been more accurate than that (accurate enough that they seem perfect for my purposes).

Welding​

After doing some reading, and watching some youtube videos, I decided that the cheapest way to achieve what I wanted was to go to Harbor Freight and buy a cheap flux-core arc welder (FCAW). Some other gear is also critical, e.g.:

• Big gloves to insulate and protect our hands from the flying molten metal
• Thick, heavy clothes to cover your skin -- again to protect from the flying molten metal. No really. I melted many holes in the synthetic fleece I wore the first time. Liquid metal goes all over the place. You need protection. Also probably a good idea not to do it around things that catch on fire easily.
• A face mask for skin and eye protection. Also because flipping your face mask up and down as you work is part of what makes welding cool and fun. You need one of these.
• A leather apron helps cover more of your clothes -- molten metal again...
• I found these magnetic right angle jigs to be super useful for holding things in place while you tack them.
• An angle grinder. You will want to grind those horrible blobby welds you made down to something a little more smooth and presentable. "An angle grinder and paint make me the welder I ain't", they say.

The first time I did this, I did a test weld. It looked terrible, and it broke immediately under strain. I did 10 more, and they got much better. Am I good? No. But steel is strong, and I'm making simple tables, so mediocre will do here. If you're about to do this for the first time, I definitely recommend having some extra scrap tubes to practice on first. There are two adjustments on the welder: Wire feed speed and current. I found that I had to go pretty low on the current for these thin walled tubes, or else I ended up just blowing holes into the steel wall rather than welding them together.

I'm not going to try to teach anyway how to weld because I suck at it and there are better resources. All I will say is that this is, in my opinion, totally worth trying. I cannot properly explain just how satisfying it is to melt two pieces of metal together.

Wood​

I ought some 1x3 "select pine" boards from home depot. For the second table, the 1x3's were out of stock, so I went with 1x2 boards. These I glued up into panels for the table top, and for the five sides of the box. I built the two tables in series, rather than parallel, and so the process on the second evolved somewhat. Mainly, I finished the wood panels and installed drawer slides before gluing them into the box, and I built the box first and used it as a jig for doing the steel tube assembly.

Drawers are made from some 0.5" ply, 0.25" ply (bottom) and 1x8 board (face) I had lying around as scrap.

Painting​

After welding, and grinding the joints down flat with the angle grinder, I paint the metal with Rust-oleum flat black spray paint. Two coats, plus maybe a bit of touch up if I missed any spots.

For the wood, I used Minwax Polyshades, with a satin finish. It seems to be pretty good. I've tried a couple others in the past, and these is easy to apply (rather than stain + poly later) and it holds up well to water and abuse. I do really struggle with getting an even coat, and avoiding drips. I suspect this is just bad technique though.

BOM and Material Cost​

Not including a bit of 1x8 board and plywood that I used scrap for.

Other Tables​

This is actually the third project since I bought the welder. First I built these...

Couch End Table​

We have a convertible couch in our guest room, and I wanted a narrow table to go between it and the wall. It's main use is as a place to sit and read, or if we have guests, a pull out bed. So, it needed a place to put a drink, a lamp, and to charge devices. I really wanted the lenght of it to match the couch.

End of hall table​

This one is just a bit of extra storage, and to decorate the blank end of our hallway. I found a peice of this wormwood board at a reclaimed furniture store and used that for the table top. Very simple construction with just a steel frame, and a couple of boards screwed onto that. The worst part of this one was getting stain into all those holes with a q-tip -- that was a tedious job!

Some more process photos​

To wrap up, here's a random assortment of build photos...

Video​

Notes​

Code running on the boards:

• can-io: https://github.com/mcbridejc/can-io-firmware
• i4-controller: https://github.com/mcbridejc/i4-controller-firmware

The repo for zencan is at https://github.com/mcbridejc/zencan.

An example project using zencan can be found at https://github.com/mcbridejc/can-io-firmware

Background​

What's a CAN bus?​

The Controller Area Network (CAN) bus, first popularized in automotive applications, is widely used for industrial automation and motion control. If you've ever used an OBD-II reader to read engine error codes, you were using a CAN bus. I've personally used it in UAVs and on rocket engine controllers, but I feel that it does not get as much use in the open-source world as it deserves, so I want to make CAN easy with Rust in hopes that it will encourage more use.

The CAN bus operates on a single differential pair, connected to all of the nodes. This means wiring multiple devices requires only two wires! It also means a single connection point can be used to plug in a computer and monitor and control all of the MCUs on the bus. It keeps wiring easy.

Many MCUs come with CAN controllers, and they handle a lot of the communications overhead without any CPU involvement. For example, bus arbitration, errors and re-transmission, prioritized message queuing, and received message filtering are all often supported by hardware.

CAN is fairly slow, with traditional CAN 2.0 busses running at a max bitrate of 1 Mbit/s. However, these days some MCUs are shipping with CAN-FD capable controllers, and I intend for Zencan to support CAN-FD. A CAN-FD bus allows for longer messages, and higher bitrates -- usually up to 5-8 Mbit/s, although I have heard of buses as fast as 20 Mbit/s.

The CAN protocol includes framing, so everything is sent as a message. A message has an ID, and a data payload. The ID is used to identify what's in the message, and also implicitly, who it's for (e.g. here is where message filtering comes in: if a node on the bus knows which messages it is interested in, it can setup hardware filters to drop any others). I think this can be confusing sometimes, so I will restate: generally, nodes on a CAN bus do not have addresses, or IDs as a node. Instead, the messages are tagged with IDs. If one wants to assign addresses to specific nodes, this has to be built on top of the CAN protocol!

Why I like CAN​

• It is smaller and cheaper than Ethernet.
• On projects which have multiple MCUs, it is convenient to plug into a single bus and talk to all of them.
• There are standard tools for monitoring and plotting data on a CAN bus, with tools like SavvyCAN and the DBC file format one can easily plot data with no code.
• It is robust! With its low speed, smart controller hardware, and differential signalling, in my experience CAN is very tolerant of less-than-ideal wiring scenarios.

Zencan Goals​

Rust​

Zencan is built in Rust because that's what I'm into lately, and there's a lack of CANOpen stacks out there for Rust.

I've been writing C/C++ for embedded systems a long time, and although there are definitely some trade-offs, I see Rust as the path forward for me. Look, if you catch me at the wrong time -- like when I've just spent an hour appeasing the borrow checker, or am frustrated by difficulty viewing static variables in a debugger -- I might offer a different opinion. But on the whole...

Configurability​

I want configurability! I want to be able to build a set of components, put them all on a CAN bus, and make them talk to each other, without having to change their firmware to do it. One way that a CAN bus has traditionally been designed is to keep a "master spreadsheet" of all the data that has to be transferred on the bus (motor temperature, motor current, velocity command, etc), cram these all into a set of messages, assign them each a CAN ID, and then write the appropriate software for each node to send and receive the relevant messages. This is fine, but I want to grab a generic motor controller board, and a generic IO board with an analog joystick plugged into it, and then configure the joystick to command the motor controller without modifying the software.

Observability​

I want to standardize interactions one might want to have with MCUs on a bus so that I can solve them well once and re-use it. I want to plug into the bus and:

• Report all the devices on the bus
• Program any device with new firmware
• Trivially plot values being generated by that device over time, or log for plotting later
• View metadata about the device such as software versions, serial numbers, etc

Ease​

A lot of code is required to get all of that, but I shouldn't have to think about it every time I start a new project. I should just be able to instantiate a node that works with a basic configuration file and a small amount of boilerplate.

Architecture​

CANOpen​

There is an existing protocol, built on top of CAN, which supports a LOT of what I want to do. It's called CANOpen. I think that Zencan is going to actually be a Rust implementation of a CANOpen stack, with some extra features layered onto it. I have some concerns about this, like the fact that CANOpen is managed by the CiA, which restricts access to the specification documents to members only. And even if you manage to find these documents, you may not find them as helpful or clear as you would like. But, the concept of the Object Dictionary and the Electronic Data Sheet (EDS) describing the objects in it, combined with the ability to map arbitrary object data into PDO messages, solves a lot of the configurability and observability requirements. CANOpen isn't exactly what I would design from scratch, but it is pretty close and has the benefit of being an established standard with existing devices and software tools. And, as far as I can find, there isn't yet a full-featured, mature CANOpen stack available for Rust. So I'm going to start here, and see if I can get everything I want out of it while maintaining CANOpen compatibility.

Specific Goals​

Specific goals of the project are:

• Support creating nodes on embedded (no_std) or linux targets
• No heap; all data statically allocated.
• Be CANOpen compatible
• Support device discovery
• Easy node configuration and object definition via a "device config" TOML file
• Support CAN-FD
• Support bulk data transfer -- e.g. a device I am targeting is an e-ink display, which requires transferring frames of pixels
• Standardized device software updates and version reporting
• A GUI and CLI interface for device management via socketcan

Configuration Files​

I am still hashing this out, and it may change!

There is a file format called EDS, or Electronic Data Sheet, which is used to describe the objects in a CANOpen object dictionary. I initially started out using an EDS file as an input to the code generation, but found that this was not ideal. For one thing, the format is fairly denormalized/redundant, which means that it can have inconsistencies and be difficult to edit manually. For another, I want the ability to specify Zencan specific options, and had no (good) way to work that into an EDS file. So instead, I've created a TOML schema for device configuration files, and EDS files will be generated as an output to be used with tools which support them.

Static Data, shared between objects and threads, without heap​

The first challenge was sharing data between different contexts. Maybe it's just code that doesn't know each other (e.g. the zencan-node crate, and user's application code) sharing access to the object dictionary. Maybe it is really on other threads. In a situation with alloc available, one might simply use an Arc to wrap the shared objects. Without Arc, we have to pass references. This quickly can lead to lifetime hell. Instead of managing these lifetimes with lots of generics, I decided to require many of the data structures to be static. In the embedded context, this is almost always the desired case anyway, and only one instance of a node is expected to exist. In other contexts, like hosting a node on linux, or in tests, this may not be the case. These can be addressed using Box::leak, to make a heap allocated object static.

Dynamic Code Generation​

Some code will be generated in build.rs, using the zencan-build crate, based on a TOML file in the project. This is somewhat similar to the way that the CANOpenNode C stack does it, but the EDS file, and more specifically the C# application used to edit the EDS file generate a C source and header file for inclusion in your application. I think that rust tooling will provide a good mechanism to auto-generate this code as part of the build process. It is still auto-generated code, and that has its downsides -- especially readability -- but I don't see how to get around it. The generated code is saved to the compilation OUT_DIR, its name stored in an env var, so that it can be included via a macro somewhere in the application. This concept is modeled after slint, which does a similar thing for including generated code from a .slint file which defines the GUI.

In build.rs, the code is generated from the device config, with a name (e.g. 'EXAMPLE1'):

fn main() {
    if let Err(e) = zencan_build::build_node_from_device_config("EXAMPLE1", "device_configs/example1.toml") {
        eprintln!("Error building node from example1.toml: {}", e);
        std::process::exit(1);
    }
}

Then in your application, the generated code can be included wherever you like as:

zencan_node::include_modules!(EXAMPLE1);

The name allows multiple nodes to be instantiated in a single application, although I do not yet have a use in mind for this, other than tests.

Here's an example of what the generated code looks like, which might help understand what's being generated:

#[allow(dead_code)]
#[derive(Debug)]
pub struct Object1000 {
    pub value: AtomicCell<u32>,
}
#[allow(dead_code)]
impl Object1000 {
    pub fn set_value(&self, value: u32) {
        self.value.store(value);
    }
    pub fn get_value(&self) -> u32 {
        self.value.load()
    }
    const fn default() -> Self {
        Object1000 {
            value: AtomicCell::new(0i64 as u32),
        }
    }
}
impl ObjectRawAccess for Object1000 {
    fn write(&self, sub: u8, offset: usize, data: &[u8]) -> Result<(), AbortCode> {
        if sub == 0 {
            if offset != 0 {
                return Err(zencan_node::common::sdo::AbortCode::UnsupportedAccess);
            }
            let value = u32::from_le_bytes(
                data
                    .try_into()
                    .map_err(|_| {
                        if data.len() < size_of::<u32>() {
                            zencan_node::common::sdo::AbortCode::DataTypeMismatchLengthLow
                        } else {
                            zencan_node::common::sdo::AbortCode::DataTypeMismatchLengthHigh
                        }
                    })?,
            );
            self.set_value(value);
            Ok(())
        } else {
            Err(AbortCode::NoSuchSubIndex)
        }
    }
    fn read(&self, sub: u8, offset: usize, buf: &mut [u8]) -> Result<(), AbortCode> {
        if sub == 0 {
            let bytes = self.get_value().to_le_bytes();
            if offset + buf.len() > bytes.len() {
                return Err(
                    zencan_node::common::sdo::AbortCode::DataTypeMismatchLengthHigh,
                );
            }
            buf.copy_from_slice(&bytes[offset..offset + buf.len()]);
            Ok(())
        } else {
            Err(AbortCode::NoSuchSubIndex)
        }
    }
    fn sub_info(&self, sub: u8) -> Result<SubInfo, AbortCode> {
        if sub != 0 {
            return Err(AbortCode::NoSuchSubIndex);
        }
        Ok(SubInfo {
            access_type: zencan_node::common::objects::AccessType::Const,
            data_type: zencan_node::common::objects::DataType::UInt32,
            size: 4usize,
            pdo_mapping: zencan_node::common::objects::PdoMapping::None,
            persist: false,
        })
    }
    fn object_code(&self) -> zencan_node::common::objects::ObjectCode {
        zencan_node::common::objects::ObjectCode::Var
    }
}
pub static OBJECT1000: Object1000 = Object1000::default();
pub static NODE_STATE: NodeState<4usize, 4usize> = NodeState::new();
pub static NODE_MBOX: NodeMbox = NodeMbox::new(NODE_STATE.rpdos());
pub static OD_TABLE: [ODEntry; 31usize] = [
    ODEntry {
        index: 0x1000,
        data: ObjectData::Storage(&OBJECT1000),
    },
]

Each object gets a struct defined, and an implementation of the ObjectRawAccess trait. All objects are instantiated statically, and stored as a table in OD_TABLE. This is the object dictionary. NODE_STATE includes some static state information used by the instantiated Node, and NODE_MBOX provides a Sync data structure for pass received messages, so that messages can be received in an IRQ handler.

Threading​

The expectation is that a single thread will own the Node object, and that most of the node behavior will happen on this thread in the form of calls to Node::process. A separate object, the NodeMbox allows for reception of messages on another thread. The expected use for this is to push received messages into the mailbox object in an IRQ handler. The object dictionary is Sync, using the critical_section crate for protecting data access. Critical section will allow embedded applications to implement critical sections by disabling interrupts, and linux applications to do so using global locks.

I tried to use crossbeam's AtomicCell for atomic access, but it does not currently support thumbv6 (i.e. Cortex M0) targets at all, because these targets lack CAS support, and I intend to use this on M0 targets.

The object dictionary, and all of the objects are Sync, as they may need to be accessed by various application code running in various thread contexts.

Object Storage vs Callback​

Zencan supports two object types:

• Storage objects have statically allocated storage for their data and support simple read/write operations
• Callback objects rely on callback functions to implement their access, allowing for validation and dynamic data handling during read or write

Control tools​

The zencan-cli crate comes with a REPL-style shell for interacting with devices over socketcan in real-time. A GUI version of this is planned as well.

Summary​

I consider Zencan now as a prototype, and still evolving. It needs more examples, documentation, and I need to implement it in more devices to flesh things out. There are still important features missing, and I expect some churn on the architecture/API. I hope over the next few months to integrate it into a few more projects, while continuing to develop it into something that someone besides myself might want to use! There are a few loose ends to tie up before I push a first release to crates.io, but I expect to be doing that soon.

Using probe-rs to attach to an STM32G0 family MCU to read log messages via defmt over RTT, I encountered the following error:

 WARN probe_rs::util::rtt::client: RTT read pointer changed, re-attaching
 WARN probe_rs::rtt::channel: RTT channel name points to unrecognized memory. Bad target description?
 WARN probe_rs::rtt::channel: RTT channel name points to unrecognized memory. Bad target description?

This occurred the same using defmt_rtt or rtt_target.

Reading through the probe-rs logs, it seemed that at some point after correctly reading the RTT memory block, it would start reading junk where it expected to read a SEGGER RTT identifier.

I am using lilos, and in its executor it uses the WFI instruction to sleep. By trying different configurations, I found that the error only occurs when the lilos executor is run.

On many cortex processors, some options have to be enabled to keep the clocks running on the debug core during sleep, e.g., on the STM32G0, the following bits have to be set:

pac::DBGMCU.cr().modify(|w| {
    w.set_dbg_standby(true);
    w.set_dbg_stop(true);
});

What I learned today is that while this may keep the dbg core running, either the SRAM or something in the bus matrix still gets disabled unless there is at least one active master, and I guess the debug core does not count. So to keep access to SRAM via the debugger during sleep, you can enable a DMA:

pac::RCC.ahbenr().modify(|w| w.set_dma1en(true));

With all three of these bits set, I can reliably read from SRAM over SWD and thus RTT is happy.

This probe-rs issue discusses the problem.

Introduction​

An interesting thing about Rust async functions is that what that async keyword actually does is tell the compiler to automatically convert your function into a state machine so that it can pick up where it left off, and have it return a core::task::Poll result every time it's poll method is called. The future object get packed with any data it needs to keep track of it's execution state.

Normally, a one doesn't call this poll method directly, but uses an Executor like tokio or lilos to poll it. The executor may not necessarily poll it in a busy loop, it may end up blocking the OS task waiting for file handles to be ready, or waiting for an interrupt to go off to flag the task as ready to run. But, there's nothing stopping you from calling poll yourself!

I've done this a few times, in a couple basic scenarios, and I think it can be useful. At least, it's useful to know how to do it. The basic premise is that sometimes, you need to build a state machine that gets called periodically, and steps through a process. For complicated state machines, this can be keeping track of a lot of state transitions with big match variables. It's fine, but sometimes I find that the state machine written as such is hard to reason about, compared to performing the same sequence of events in a blocking manner.

The full demo code from this article can be found on github

Linear sequence vs state machine​

As a simple comparison, consider a sequence of register initializations:

/// A somewhat psuedo-codey demonstration of sending a series of commands
/// to a device and waiting for an acknowledgement
fn init_device() {
    let device = ImaginaryDeviceCommander::new();
    device.command("write REG1 10");
    while !device.is_ready() {}
    device.command("write REG2 20");
    while !device.is_ready() {}
    device.command("write REG3 30");
    while !device.is_ready() {}
}

But now imagine that our process can't block. Maybe it is part of a "super loop": an application with a single thread that cyclically calls many modules so they can update themselves. Now the device initialization process needs to be refactors so that it can be performed iteratively over a series of function calls which always return quickly, something like this:

struct DeviceInitter {
    command_sent: bool,
    step: usize,
    device: ImaginaryDeviceCommander,
}

impl DeviceInitter {
    pub fn run(&mut self) -> bool {

        if step <= 3 {
            match command_sent {
                true => {
                    if self.device.is_ready() {
                        self.step += 1;
                        self.command_sent = false;
                    }
                }
                false => {
                    match self.step {
                        0 => self.device.command("write REG1 10"),
                        1 => self.device.command("write REG2 20"),
                        2 => self.device.command("write REG3 30"),
                    }
                    self.command_sent = true;
                }
            }
        }
        if self.step == 4 {
            // Complete!
            return true;
        }
    }
}

The first version certainly seems nicer to read and understand!

How to manually poll an async function​

There are two main things to know:

1. You have to pin it
2. You have to create a dummy context to pass to poll

Both are easy to do!

Finally, you need to make sure your future will yield at appropriate times. Normally, async functions yield back to the executor when they stop to wait on some IO operation to the OS, such as reading a network socket. But you can also use the pending!() macro to yield at any point.

Here is a function to run a future once, and a simple state machine demoing it's use:

use core::pin::Pin;

/// Poll a future one time, and return its result if it completes
pub fn poll_once<T>(
    mut f: Pin<&mut dyn Future<Output = T>>
) -> Option<T> {
    let mut cx = futures::task::Context::from_waker(
        futures::task::noop_waker_ref()
    );

    match f.as_mut().poll(&mut cx) {
        core::task::Poll::Ready(result) => Some(result),
        core::task::Poll::Pending => None,
    }
}

fn main() {
    let mut future = pin!(async {
        let mut i = 0;
        loop {
            if i == 2 {
                return 42;
            } else {
                i += 1;
                // Yield back to the executor. This means that
                // the future's `poll` function will return
                // `Poll::Pending` and the subsequent call will
                // pick up here
                pending!()
            }
        }
    });

    // i = 0. Not done.
    assert_eq!(poll_once(future.as_mut()), None);
    // i = 1. Not done.
    assert_eq!(poll_once(future.as_mut()), None);
    // i = 2. Done!
    assert_eq!(poll_once(future.as_mut()), Some(42));
}

There's no async runtime like tokio, async-io, etc, here; the only dependency is the futures crate.

Use case: chunked serialization​

One reason I wrote this article is that a library I am working on needed to serialize a handful of data structures in an embedded context to persist it to flash. I want to impose minimum requirements on the application, so:

• No heap usage, which means no returning a Vec<u8>.
• Do not assume the serialized output will fit in RAM. It has to be able to be written to flash in small chunks. Only the application knows what "small" means here.

This means that the serializer has to expect a series of read(buf: &mut [u8]) calls, copy the next N bytes into the buffer, and then keep track of where it was so that it can pick up where it left off on the next call to read. This is kind of a pain in the ass! It means, e.g., that when serializing a u32, it may end up writing the first byte on one call to read, and the next 3 bytes on the next.

I started writing a state machine to do this, and then decided to try it as an async function. As an example for this article, I simplified the serialization a bit, but it is essentially the same. We are going to serialize some objects that look like this:

/// Just an example of an object to be serialized.
/// Each object has a type, and a block of bytes to describe it.
struct Object {
    pub object_type: u8,
    pub data: Vec<u8>,
}

They will get serialized into the flash as [<length:u16> <object_type:u8> <data:n>], where length is the length of the data + object type byte.

So first, I need to create an async function that serializes the data, but yields after writing out each byte:

/// Utility to write bytes to a provided function, returning a Poll::Pending between each byte
async fn write_bytes(src: &[u8], mut write_fn: impl FnMut(u8)) {
    for i in 0..src.len() {
        write_fn(src[i]);
        pending!()
    }
}

/// Implements a serializer for a list of objects.
///
/// Implementing this as an async function allows the sequence of writes to be written linearly and
/// simply, allowing rustc to compile it into a state machine so that the serialization can be
/// broken up into arbitrary chunks
async fn polling_write(objects: &[Object], mut write_fn: impl FnMut(u8)) {
    for obj in objects {
        // First serialize the size of the object, which is the length of the data + 1 byte for the
        // object type
        let len = (obj.data.len() + 1) as u16;
        write_bytes(&len.to_le_bytes(), &mut write_fn).await;
        // Serialize the object type
        write_bytes(&[obj.object_type], &mut write_fn).await;
        // Serialize the object data
        write_bytes(&obj.data, &mut write_fn).await;
    }
}

Great, that wasn't so bad.

Now, lets wrap up the future into a struct that can provide the required read function:

pub struct AsyncSerializer<'a, 'b, F: Future<Output = ()>> {
    fut: Pin<&'a mut F>,
    reg: &'b RefCell<u8>,
}

impl<'a, 'b, F> AsyncSerializer<'a, 'b, F>
where
    F: Future<Output = ()>
{
    /// Create a serializer using a future and a shared data buffer
    ///
    /// The future should write to reg, and it *must yield after writing each byte*.
    pub fn new(fut: Pin<&'a mut F>, reg: &'b RefCell<u8>) -> Self {
        Self { fut, reg }
    }

    pub fn read(&mut self, buf: &mut [u8]) -> usize {
        let mut pos = 0;
        loop {
            if pos >= buf.len() {
                return pos;
            }

            if let Some(_) = poll_once(self.fut.as_mut()) {
                // Serialization is complete
                return pos;
            } else {
                buf[pos] = *self.reg.borrow();
                pos += 1;
            }
        }
    }
}

And finally, put it together and use it:

fn main() {
    // `byte_buf` serves as a temporary register for communication between the future which implements
    // serialization and the AsyncSerializer wrapper
    let byte_buf = RefCell::new(0u8);
    // Create the future from an async function, each time it is polled, it will write one byte to
    // `byte_buf`
    let future = pin!(polling_write(&objects, |b| *byte_buf.borrow_mut() = b));
    // instantiate the wrapper which will drive the future
    let mut async_serializer = AsyncSerializer::new(future, &byte_buf);

    // A vec to store the fully written data
    let mut output = Vec::new();
    // A temporary small buffer. Data will be serialized one 3-byte chunk at a time into this buffer.
    let mut buf = [0; 3];
    loop {
        let write_size = async_serializer.read(&mut buf);
        output.extend_from_slice(&buf[0..write_size]);
        if write_size < buf.len() {
            break;
        }
    }

    assert_eq!(output, [5,0,0,1,2,3,4, 9,0,1,1,2,3,4,5,6,7,8]);
}

This is made a little more complicated by the requirement that it not use the Heap. If we could use the heap, the future could be wrapped by Box::pin, and that makes managing lifetimes easier. As it is, we need to pin the future on the stack, which means that the stack frame it is created on has to outlive the serialization process. To make this a easier on the user, we can create a function to create the future and the shared RefCell, wrap them up, and provide them to a user provided callback:

    /// Create a serializer for objects, and pass it to the provided callback
    ///
    /// This allows for pinning the required data on the stack for the duration of the serializer
    /// lifetime
    pub fn serialize_objects(objects: &[Object], mut cb: impl FnMut(&mut dyn PersistSerializer)) {
        let reg = RefCell::new(0u8);
        let fut = pin!(polling_serializer(objects, |b| *(&reg).borrow_mut() = b));
        let mut serializer = AsyncSerializer::new(fut, &reg);
        cb(&mut serializer);
    }

And then the usage becomes:

    // A vec to store the fully written data
    let mut async_output = Vec::new();

    async_serialize::serialize_objects(&objects, |serializer| {
        // A temporary small buffer. Data will be serialized one 3-byte chunk at a time into this buffer.
        let mut buf = [0; 3];
        loop {
            let write_size = serializer.read(&mut buf);
            async_output.extend_from_slice(&buf[0..write_size]);
            if write_size < buf.len() {
                break;
            }
        }
    });

Trade-offs​

To be honest, I'm not 100% convinced this is a great idea. There are for sure times when it's better to write out a sequence of linear actions. But, there are downsides! There is added complexity in creating and understanding the async function, dealing with the pinning (which is especially painful without alloc), and also, stepping through async functions in the debugger can be unpleasant.

There is another more complicated example in the repo, and splitting off the processing into the future adds a layer of communication: the "main" task cannot pass data into the future once it is created, so they have to communicate using a shared structure, which has to be Sync (at least if you want to avoid unsafe code), even though we can actually be sure that the future will never be executed on another thread.