Jeff McBride

Droplet Capacitance Sensing

2026-10-12T07:00:00Z

This is a throwback to something I worked on a few years ago: the PurpleDrop digital microfluidic (DMF) device and a capacitance sensing method I designed for it that turned out to work pretty well. In the process I encountered a weird dielectric hysteresis phenomenon in kapton which I’ve never really understood, and which completely disappeared when I tried to look closer at it, leaving the observation a nagging mystery to me still today.

The topic has come back to mind again lately, so I want to write about it. It was an interesting project that enabled better drop control, opened the door to feedback controlled drop splitting, and provided the measurements needed to later perform some surface lifetime experiments. I’ll give a little background about electrowetting-on-dielectric (EWOD) systems since most readers probably don’t know what that is, and then focus mainly on how the capacitance sensing worked: it used current integration to measure the charge transferred to electrodes during voltage switching.

Then, I’ll talk about the as-yet unexplained surprise – a large hysteresis in the capacitance that I interpreted to be dielectric hysteresis, but which disappeared when I came back to measure it more carefully.

DMF Background

A diagram illustrating the electrowetting behavior

Electrowetting-on-dielectric (EWOD) has been explored for decades now as a method of automated liquid handling for biological processes. Essentially, small water droplets – which likely contain other reagents or biological molecules – are trapped between two surfaces and manipulated by the selective application of a voltage on a two-dimensional array of electrodes. There’s a plethora of literature about different ways to fabricate these devices, and attempts to perform a wide array of lab processes on them. It basically works by creating electrostatic attraction between charge in the drop and the electrodes (even with low ion concentration, water molecules are sufficiently polar for this to work), making the drop seem to “wet” the normally hydrophobic surface. It’s sort of like having an electrically controllable hydrophobicity. The surface must be carefully coated with some form of fluoropolymer in order to keep it very hydrophobic by default.

I am aware of a number of attempts to commercialize products based on the technology, most failing. Illumina launched a sequencing sample prep product called ‘Neoprep’ in 2015, only to drop it later. Around 2019, Oxford Nanopore released the VolTRAX, a EWOD-based device for performing sequencing prep. The VolTRAX used a thin-film-transistor (TFT) based process, similar to that used in displays developed by a Sharp spin-off (AqDrop) to create its substrate. I thought this was a brilliant idea at the time – it allowed for many more smaller electrodes by integrating transistors – solving the problem of connector pins to the consumable substrate constraining the number of controllable electrodes – by integrating transistors right into the consumable substrate, and also taking advantage of existing high-volume manufacturing processes. This project, and AqDrop, both quietly disappeared. I have heard that the AqDrop substrates suffered from dielectric breakdown, but it’s only a rumor and I cannot substantiate it.

There have been a few companies trying to sell generic DMF devices, including Sci-bots. They sell the DropBot, and as far as I can tell are still selling some number of them. They still send me a newsletter from time to time, at least. I suspect most of those sales are one-offs to researchers looking to do an experiment and write a paper, rather than to do “real” lab work, but I would love to hear counter-examples to prove that wrong!

The problem with using DMF systems for automating real lab work seems to be reliability – and cost to a lesser extent – and this is entirely consistent with my experience working with them. They are extremely cool to watch and program, and they have an almost magic quality to the way they operate. However it is finicky to prepare and build the consumables, and their operation depends on careful control of the experiment and is prone to failure. Getting samples in and out of the device is particularly fraught. So all in all, I’m bearish about large-scale application of the technology for general lab automation. Still, it was an interesting project to work on!

Capacitance for Volume Sensing

The reason that measuring capacitance is interesting for a DMF device is that it can be used to determine drop volume. The capacitance between an electrode and the top-plate increases in proportion to the area covered by a drop between them. Knowing volume can be useful:

It allows for faster drop movement because the capacitance signal can be used to determine when the drop has moved, so that the controller can proceed as quickly as possible to the next step.
It allows detecting problems, e.g. when a drop gets stuck. Perhaps the situation can be resolved with an increase in voltage, or perhaps the protocol must be stopped early. The velocity of each movement can also be used to detect a fouling area of the surface even before it causes a failure.
When combined with feedback control, it can allow more accurate drop splitting and dispensing, supporting partial electrode coverage and arbitrary drop volumes, rather than relying on the number of active electrodes alone to control volume when dispensing.

AC Systems

DMF electrodes are driven with an AC voltage because charge build-up can cause problems when driven with DC. On many systems, such as the DropBot, a single high voltage sinusoidal source is used with an array of switches (e.g. solid state relays) to enable individual electrodes, and the AC signal lends itself well to capacitance measurement via impedance measurement – it simply requires an RC filter on the top-plate and a voltage measurement. DropBot does this, and it seems to me based on their papers and chats with one of its designers that it works quite well.

PurpleDrop “Pseudo-AC” Drive

PurpleDrop has a different electrode drive architecture, and it doesn’t really allow measuring capacitance in the same way. Instead of a sinusoidal source, PurpleDrop uses high-voltage digital outputs on two 64-channel HV507 chips. These are just shift registers with push-pull outputs – but they support 300 V! This saves space and cost by replacing 128 SSRs with two chips. In order to avoid charge trapping issues, PurpleDrop switches the polarity at 500Hz, driving the top-plate and inactive electrodes high while driving the active electrodes low for 1ms, then driving the active electrodes high while grounding the others for 1ms. The top-plate is driven by one of the HV507 pins, just like the other electrodes.

Current Sense Design

Overview

A sense resistor placed between the HV507 pin and the top-plate is used to measure the total amount of charge that is transferred to the top-plate when an electrode – or set of electrodes – is charged from 0V to V_HV, relative to the top-plate. A voltage integrator measures the total amount of charge transferred over a relevant window of time, and capacitance is the total amount of charge transferred per volt.

Because the top-plate is also charged to V_HV (which can be up to 300V) during the ‘negative’ part of the cycle, the high voltage part of the circuit must be isolated or else the current sense amplifier would be seeing some very large input voltages. To avoid that, the top-plate is tied to the main board ground, and the HV supply output as well as the HV507 chips are isolated from the rest of the board. This requires some additional opto-isolators to facilitate control between the two isolated domains, but that was well worth it for the capacitance sensing!

Block diagram of the Purpledrop system. The HV507 drivers are isolated from the main board power supplies, so that the top plate can be connected to the board ground, allowing sense measurement with no common-mode component.

Sequencing

Switching the electrode drive polarity causes a lot of transient current as various capacitances (caused by all the drops on the board, and stray capacitance) are charged/discharged. To measure only a select subset of electrodes, their charging must be isolated from the polarity switch signals or they will be swamped. It’s necessary to switch the polarity, allow sufficient time for the system to settle, and then to charge the to-be-measured electrodes in isolation.

The HV507 provides two special function pins that make this sequencing faster and require fewer shift register loads (though as I’ll get to soon, we will end up doing them anyway):

The POL pin swaps the polarity of all outputs – generating the 500Hz alternating voltage requires only toggling POL.
The BL (blank) pin (active-low) clears all outputs when asserted, which can be used to delay the charging of active electrodes after polarity switch

Measurements are taken at the start of the positive half of the cycle – i.e. when the top plate is driven low and active electrodes are driven high. The image below shows the sequence of events:

Capacitance Measurement Sequence

During the negative half of the cycle, the electrodes are driven to -V_HV relative to the top-plate. Then the polarity is switched and blanking is enabled, and a short delay allows the system to stabilize with all electrodes (including the top-plate) driven to the same voltage. In the meantime, a new configuration of “active” electrodes can be clocked into the HV507 shift registers. Then after the blanking delay, the current integrator is reset, followed by the release of the BL signal causing the active electrodes to be driven to V_HV while the top plate remains at 0 V. After a small delay to allow the electrode voltages to stabilize, the output of the current integrator – i.e. the total transferred charge – is read by an ADC.

Measurement Groups

When I say “active” electrodes, I mean the electrodes which are enabled by the droplet control algorithm for the purpose of manipulating the drops. The capacitance of these can be measured every polarity switch without interfering with system operation at all since we have to drive those electrodes anyway. It’s also possible to activate other electrodes very briefly, just to measure their capacitance, and the system supports this in two ways:

scan groups (up to 5)
bulk scan

Scan groups are measured every 500Hz cycle by activating each group just long enough to measure capacitance. The activation is not long enough to significantly affect the movement of drops. It does subtract from the on-time of the active electrodes, which slightly reduces the pressure created on drops, but for a small number of scan groups this is only a tiny effect.

Timing diagram of group sampling at the beginning of the positive polarity phase

A “bulk scan” is performed at a much lower rate (typically 2 Hz), and involves activating each of the 127 electrodes one by one to measure its capacitance. This does disrupt the pressure created by active electrodes and can sometimes be detected as a quick wobble in a drop as the active electrode(s) affecting it are disabled for a fraction of a second and then re-enabled, but is not really a functional issue.

Integration Circuit Design

Pulse Integrator Schematic

Current Gain Selection

An analog mux allows software to select between two values of sense resistor, to allow for the possibly large dynamic range of measuring large groups of electrodes and single electrodes. The selection of gain can be based on the number of electrodes being activated during the measurement, as this sets a rough upper limit on capacitance.

Amplifier Stages

Three op-amps are used in the integrator. The first provides buffering and a small amount of gain. The second is a voltage integrator, counting charge transfer. The third stage amplifies the integrator output to a good range for the ADC. A FET provides a software-controlled reset of the integrator voltage, used to start the integration¹.

Negative Supply Rail

The first iterations of this circuit lacked the negative power rail for the op-amps, and this led to some problems. For starters, despite being “rail-to-rail” amplifiers, the output can’t truly go to the 0V rail, so there was always a small amount of “masked” input signal on the integrator input, leading to integrations like this one:

Scope capture of integrator output. Left: A measurement with no drop present. Right: A measurement with a drop present.

The steady ramp is due to the offset on the first stage output. It can somewhat be calibrated for, but not with great accuracy because the shape of the current pulse varies quite a bit based on the capacitance being charged, and the amount of signal being masked depends on the shape. A bigger problem was that input noise which was nearly zero-mean is no longer zero-mean after having the negative component clipped. Adding the negative supply rail improved accuracy substantially.

“Augment” FET

An additional software controller NFET is added between HV_GND (the low side of the isolated HV supply and the ground connection for the HV507s) and GND (the ground reference for the amplifiers and ADCs, as well as the rest of the board), and is enabled when the top-plate output is driven low. I found this to improve noise performance a lot, as the HV507 drive strength is quite weak.

Results

After a few iterations, the sensing was working great. The main reason I added the high-speed “group” measurements was to do feedback control of drop splitting. I also set up PWM control for the electrodes, allowing electrode groups to be turned off early, to control the amount of pressure induced on the drop. By controlling the relative pressure on each side of a drop being split at 500Hz, using the capacitive volume measurement as feedback, a drop could be dispensed with much more accurate volume or a single drop could be divided more accurately. I made some videos at the time, and I think these give a good intuitive idea of how it worked:

Capacitance Measurement Demo Video

I made a video at the time showcasing the capacitance features:

Syringe Pump Driven Dispensing

I also used feedback control for actively pumped drop dispensing, where the feedback was crucial for knowing how much to move the syringe pump and for splitting off accurately sized drops:

The Kapton Hysteresis Mystery

Capacitance depends heavily on voltage history

Those videos were made with a Mylar film dielectric. I initially used kapton film, and it has some favorable properties like better temperature range and strong dielectric strength – one of the things we wanted to do was thermocycling, which involves heating the drop, and I thought kapton would be better suited to this. However, when I first started testing out capacitance sensing while working with the kapton film, it proved quite frustrating! It showed what appeared to me to be a strong dielectric hysteresis. Essentially, the amount of charge transferred during electrode activation depended on the recent history of the applied voltage.

I apologize in advance if the description I’m about to provide ends up confusing – it confused me a bit too at the time, and I’m writing now from memory, some messy contemporaneous notes, and whatever data I collected then well enough to understand now.

The first sign that something was going on was that the active and bulk scans did not match at all. It quickly became clear as well that the value read for a particular electrode during the bulk scan depended HEAVILY on whether that electrode was currently active.

Here’s an example. The plot below shows the bulk capacitance measurement over a long period of time. The electrode is toggled on/off every 30s as the drop is left to evaporate and shrink. The higher values are when the electrode is active, and the lower points are when it is not. The difference between active and inactive is almost a factor of 3!

Alternating Active State

I started making plots like this one for a different electrode, which is just extracting one point for each 30s period in the plot above, and also including the active measurement:

Alternating while evaporating 2

In this case, you can see that the bulk measurement while active is only slightly lower than the active measurement itself (they are measuring the same thing, so should be equal). However, for other electrodes, the difference was more stark. At first, I didn’t see the pattern because the assignment of output channel to electrode is quite randomized due to the vagaries of board layout, but then I did. The relationship between bulk measurement and active measurement for a single electrode seemed to depend strongly on the output number (i.e. the position in the HV507 shift register). To explore this relationship, I put a few drops on different electrodes with the aim of spreading them out roughly evenly across the 128 output positions:

Droplets on a board

Then, I measured the ratio of active and bulk capacitance for each droplet covered electrode:

Plot of active/bulk ratio over electrode number

Clearly there is a trend. The important thing to note here: during bulk scan, the electrodes are measured from 127 to 0, so the lower the electrode number, the more time that passes from the electrode being driven negatively to the capacitance measurement – measuring all 128 electrodes takes about 1.8ms. I did some additional experiments where I varied the scan timing, and confirmed that time delay from last activation was indeed a key factor in the decreasing bulk measurement.

Although much of the activation effect dissipates in just the 1.8ms it takes to do a scan, some residual effect could be seen to persist and slowly decay for several minutes.

The history of other electrodes matters too

It also became clear that activating other electrodes which were covered by the same drop as the measured electrode could affect the measurement in ways that were difficult to understand, but seemed to depend on whether the activated electrode came before or after the measured electrode in the scan. Here’s just one illustrative example sequence of activating different electrodes:

Three nearby electrodes

For these tests I would place a large drop on the board covering a 3x3 square of electrodes, and then pick three electrodes in this square to analyze: The center electrode, one electrode with a higher number (scanned earlier) and one with a lower number (scanned later). The three capacitances are denoted c1-c3, and a1-a3 denote whether each electrode is active (1 means it is active). In the above plot, the electrodes were c1=97, c2=95, c3=64, so they were scanned in the order c1, c2, then c3. It’s difficult to identify the pattern here, but it is clear that neighboring electrodes also matter and that the bulk capacitance measurement is no good without controlling for these effects. I won’t try to recount all of it for you here, but I did a whole series of experiments like this trying to find a clear explanatory pattern and didn’t find it.

The effect is not present with Mylar

All of this was quite frustrating, and then one day quite by accident I discovered that when I used mylar film for the dielectric instead of kapton these effects nearly vanished. If I went looking, I I could identify some ghost of the same effects, but the magnitude was so much smaller that I don’t think I would have ever taken note of it if I had started with the Mylar. This convinced me that it was some property of the Kapton causing it, and from there I switched to using the Mylar film.

Follow-up testing: No hysteresis found

The mystery still gnawed at me – and I did still want to be able to support Kapton for its heat resilience – so I set out to explore it more. I thought it would be easier to understand if I had a little more flexibility in the waveforms I applied than the PurpleDrop hardware allowed, and so I decided I would set up a more isolated experiment focused on exploring the capacitance of the kapton film. I built a high voltage amplifier so I could drive arbitrary waveforms, and a small fixture for applying voltages across the dielectric (with or without fluid). Then I set up an Analog Discovery to act as a python-controlled function generator and ADC. I even installed a TE cooler to control temperature of the film.

Dielectric Film Test Stand

After all this preparatory work, finally I set out to do the actual experiment. To my surprise and frustration, I found no sign at all of any hysteresis in the kapton! I tried adding teflon coatings, like it is on the PurpleDrop; still no effect. Suspecting something about my HV function generator setup, I wired in a PurpleDrop so I could drive it with an HV507 just like in the real system. Still nothing. I recall being at a loss for explanation at the time, and by this point my interest in the DMF project was waning. So I more or less dropped it there.

Every now and then though I wonder about it and feel bad that I never got to the bottom of it. Based on the confusing effects of neighboring electrodes, my best theory today is that there is some form of lateral charge movement going on within the kapton film, and that to recreate the effect I need to include neighboring electrodes to drive as well in my test setup (the test fixture I built had only one electrode). This is pretty speculative, but still it feels promising to me today. Somehow though I don’t remember thinking about this theory at the time. Or maybe I did but just didn’t have time to pursue it, and now I’ve forgotten.

In any case, I don’t yet know if taking the time to write this down is a preliminary step to recreating a better experiment setup to explore this more, or if it is just idle reminiscence. I’ll have to get back to you on that. In the meantime, if you have any ideas, please email me!

Footnotes

An astute reader may notice that the reset has a voltage divider so that it will reset to a nearly-but-not-quite zero voltage. I believe this is an accidental hold-over from a previous revision which lacked a negative voltage rail for the op-amp, where some saturation recovery time was required after driving the input all the way to the rail. I don’t think it’s necessary at all in this revision – but my memory is weak so maybe I’ve forgotten something.↩︎

Rust static init with None

2026-02-27T08:00:00Z

Today I learned: initializing a rust static with None does NOT ensure a zero initialized variable!

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 initialization, 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 compression 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 surprisingly 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 output?

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.

2025 Book Reviews

2025-12-30T08:00:00Z

With 2025 coming to a close, I’m going through the annual tradition of reflecting on, and summarizing the year. One of the things I’m reviewing is my reading log, so here’s a few of the books I read this year that most standout in my memory.

The Bobiverse Series

We are Legion cover

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

Control of Nature cover

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

The essays are:

A story of the Army Corp of Engineers and it’s struggles to keep the Mississippi river on its course.
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.
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

The Nvidia Way cover

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.

Adding PDO Defaults to zencan

2025-12-28T08:00:00Z

Adding a simple feature to zencan brought up some thorny topics.

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:

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).
Adopt the special rules of CANOpenNode.
Drop support for adding node ID to PDO IDs altogether.
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.

Publishing zencan crates

2025-10-29T07:00:00Z

I’ve finally published v0.0.1 of zencan to crates.io.

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)

Footnotes

Not trying to throw any shade. I have been in that position, and will likely be again. Publishing some open source code doesn’t obligate someone to support it for randos like me forever.↩︎

Building an application for the CoreMP135 using Rust and Slint

2025-10-27T07:00:00Z

This is a followup to Creating linux images for the M5Stack CoreMP135 with Buildroot. The last post talked about using buildroot to make a linux image, and this post is about building an application in Rust and running it on the image. The demo application is a CAN logger. It will use Slint to create a simple UI on the touchscreen to start and stop the log file, and it will log data to an exFAT partition on the microSD card.

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:

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
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.

Creating linux images for the M5Stack CoreMP135 with Buildroot

2025-10-25T07:00:00Z

This post is about the M5Stack CoreMP135: why I like it, and a tutorial about how to use buildroot to create a linux image for it. A follow-up post describes how I create applications with Rust to run on it.

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.

M5Stack CoreMP135

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

Building Custom Steel and Wood Furniture

2025-09-14T07:00:00Z

I recently finished building a pair of bedside tables in a stlye I’ve used a couple times before. This post is about the project and the process I used to do it.

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.

Welding Gear

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

Descrpition	Source	Price (per table)
288” 0.75” 16ga tube	Steel Supply LP	$29 (shipped)
Select pine boards	Home Depot	~$96
Drawer Slides	Amazon	$13
Handles	Amazon	$7
Recessed Power Strip	Amazon	$34
Plastic feet	Amazon	$5

	Total:	$184

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!

Hall Table

Some more process photos

To wrap up, here’s a random assortment of build photos…

Zencan Device Demo Video

2025-06-18T07:00:00Z

Two weeks ago, I posted about a Rust CANOpen Stack I was working on. It was in a bit of a disfunctional state at the time. Since then, I’ve ported two firmware projects to use it and in the process made a lot of progress on it! There’s still a ton to do to get it where I want, but today I recorded a quick live demo of the first two boards communicating using zencan! Production quality is low, but hopefully it’s still a useful way to get a feel for what it is trying to do.

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

Introducing Zencan: Easy CANOpen with Rust

2025-06-05T07:00:00Z

I’ve been kicking around an idea for a while now to create a CAN bus communication stack for Rust, and now it is finally taking shape. It’s still a work-in-progress, but I’m getting ready to publish a rough prototype, so I want to write about what I want it to be. I’m calling it Zencan, and it’s an implementation of the CANOpen protocol, with a few planned extensions.

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.

Errors using RTT and WFI

2025-05-22T07:00:00Z

This is for future-me, and for future internet searchers.

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.

Using a Rust async function as a polled state machine

2025-05-16T07:00:00Z

Using `async` functions to auto-generate a state machine

How to poll an async function manually, and then use the rust compiler as a finite-state-machine generator

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:

You have to pin it
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.

The Gauss Speedway

2022-11-15T08:00:00Z

Summary

Here’s a fun toy project I finally finished this month. It’s a racetrack built with a printed circuit board, and small 3D printed magnetic cars. They just drive around the circuit when you apply (the right) current! That’s it! That’s the project!

History

It started from a conversation with Kevin Lynagh, who did some experiments¹ with moving magnets around a 2D grid with wires running both directions, which planted the idea of a racetrack version in my head. Thanks to my now rather extensive practice designing weird PCB geometries in Kicad with python, I was able to design a test board pretty quickly over the new years holiday and ordered it. It worked pretty well, I posted a short video and then forgot about it for a while.

Then I picked it up again in the spring, imagining it as kind of a slot car game. So this led me down a deep rabbit hole of a) building a wireless slot car controller, and b) a wireless charging station for the slot car controller.

Slot controller

I spent a fair bit of time learning about wireless charging, going so far as to do VNA measurements to get a better simulation model of the coil coupling. I learned some things, and should probably write an article about that at some point before I forget completely. I also built a second revision of the track board, with two lanes, because of course a slot track with one car is boring! I only did this because I failed to engage my brain properly. Had I engaged my brain properly I would have realized that the slot cars full of magnets would exert substantial force on each other when brought into close proximity in the narrow confines of a race track before ordering the board. Ah well; I realized eventually. I got the remote working enough to decide that actually it wasn’t that fun to drive this with a slot remote, especially if there was only one car.

Measuring the coupling between two wireless power transfer coils

So I dropped all that. A nice feature of projects done for fun is that their value is derived primarily from your enjoyment, so anything is reasonably in scope as long as you’re enjoying doing it. So arguably no waste was incurred here.

A lot of this kind of project goes as far as it takes to satisfy myself that I know how I would do it, and then there’s just not so much motiviation to go any further. It starts to feel like busy work. But, in this case I wanted a packaged up version that just worked, so I did one more board spin – what you see here – and now I’m pretty happy with it².

The Design

Physics

The physics isn’t too complicated. To think about how this works you basically need to know one thing: The force created on a wire with a current is equal to the cross product B x I, which means that the force pushes orthogonally to the direction of the current and the direction of the B field. So if the magnetic field is pointed down into the board, and it’s overtop of a horizontal trace aligned with the X axis of the PCB, the magnet will be pushed vertically along the Y axis (the direction depends on the direction of current and B field, but we don’t have to concern ourselves with that too much, we can make it go either direction just by flipping the magnet).

The arrangement of the wires on the two phases allows it two be driven as a bipolar stepper motor, alternating the current in each 90 degrees out of phase. The controller on the Gauss Speedway does a bit of microstepping, performing 16 current steps per each cycle.

Then you have the problem of keeping the cars on the track, especially around curves where there are sideways g’s being pulled. That’s what the guard rails are for. These traces run along the outside, and push back in, so if the car deviates from the center, the force from the guard rail it moves towards increases, pushing it back.

Guard rail traces keep things in the center

Current control

The electronics are quite simple. We need to measure the capacitive touch sensors, but this is handled by the Touch Sense Controller peripheral on the microcontroller. Easy! The copper touch pads just wire to the microcontroller pins via a resistor.

Then we need to be able to control three currents: two for the drive phases, and one for the guard rails, and these currents need to be reversable. In order to reliably control the current regardless of the input voltage or trace resistance (e.g. the guard rail resistance is < 1ohm, while the traces are about 5ohms), each current driver gets a relatively large inductor and a capacitor across the trace. A net-tie is used in Kicad to represent the traces of the track.

Schematic of a single current driver

As long as the voltage and trace current worked out so that the peak “on” current didn’t damage anything, I suspect you could get away with driving this without the inductance. But that’s not very flexible, and I just don’t like that current ripple! The inductor part number is SRR1260A-680M.

PCB

While I got away with two layers on the prototypes, I had to go to four layers for this. There just wasn’t any way to get signals from outside the track to inside on a two layer board, so the choice was either to keep all of the control electronics outside or add layers. Putting everything outside would have made it larger, and it already barely fits on my 3D printer bed so I didn’t want that. A side benefit of going four layers is that the second layer ends up being much closer to the top, which is good for those newtons/A. The only downside is it costs more.

Enclosure

The board is just mounted into a 3D printed frame, using M3 screws and heat-sink thread inserts. The frame just barely fits on the 220x220mm bed of my Ender 3.

3D printed frame render

The Cars

The cars I printed on an FDM printer, with a 0.2mm nozzle. I got these 2mmx1mm magnets from Apex magnets, and glued them into the car with the medium CA. It’s important that they all go in with fields oriented the same way. You can arrange for this by installing one reference magnet onto something (or just use an existing car) and putting a stack of magnets onto that, then pull them off one by one. I like to mark the “up” side with a little sharpie dot, so I can keep track of the orientation visually while installing.

View of two cars, top and bottom

Levitation

For a first order analysis, one might think of the magnetic field as simply pointing down into the board. But this is only true at the very center of the magnet. Once you move out, the B field bends upwards, which creates the tantalizing possibility of a force in the z direction. An upward force of course leads to levitation. The current phases in fact create an oscillating z force ³ up and down as the car moves along. These are relatively small relative to the forward forces, and don’t cause any big problems.

But the guard rails can be positioned fairly far outside the magnet, where the field bends substantially. Can the guard rails be used for levitation?

First of all, if you want to get the force upwards instead of downwards (no good; just increases your friction), you have to swap the current so that the tangential force from the rails is outwards. This is unstable, but lots of unstable systems can be made stable with an appropriate feedback control! I could add a middle rail, and a metal bar across the car. Then the capacitance between the inner rail and the two outer rails could provide a very fast measurement of the lateral displacement of the car. “Cool!”, I think. But then, once again, I engaged my brain, and realized that while this works great if the only thing we were worried about was controlling the lateral translation, but of course a car is free to rotate too! It can rotate in about the Z direction, AND once it’s actually levitated it can rotate around the other two directions as well. The pitch rotation (the front/back going up and down) is fine, it will be stable. But the roll is tightly coupled to the left/right translation control, and I just don’t see anyway to decouple them.

Idea for stabilizing two axes. With alternating guard rails, you could both sense the lateral displacement of the front and back independently, and control them separately. This could control translation and rotatation about the z axis (yaw), but roll is still unconstrained.

So I’ve concluded there’s just no way to get levitation out of this system, but if anyone has some ideas and wants to prove me wrong, please do!

Conclusion

Yeah that’s it. It’s kind of a fun demo, and now that it’s easy to build/run I can make a few more and pass them out to unlucky friends and family!

Since I needed to fix a few things, I ordered a rev 2 which fixes some oversights on the first design, and also flips the guard rails and phases so the guard rails are on top. Now that I’m building it as a 4-layer board, the second layer isn’t very far away, and I hope this will still work with less noise (the phase traces create bumps!). I found it runs really nicely with a thin film of PET, and I’m hoping for a similar result with the guard rails on top.

Hardware design: https://github.com/mcbridejc/GaussSpeedway
Control software: https://github.com/mcbridejc/speedway-controller

Footnotes

I have one small correction to Kevin’s analysis. He notes that “the transition energies become positive” at larger magnet to coil distances, and that he was surprised to see this. This error occurs because his formula is only considering the four nearest wires. If you consider more wires this phenomenon disappears.↩︎
I have some python simulations of this, and may dig them out at some point and share…↩︎
Mostly… actually I need one more spin for a couple things and I’m thinking I should do the next one in black soldermask?↩︎

Acoustic Beamforming Notes

2022-10-10T07:00:00Z

Building an Acoustic Phased Array

Accoustic Array Parts

Introduction

Around August of 2022 I started working on an acoustic phased array. I bought some microphones, wired them up to an STM32H7 dev board, and wrote some Rust code to process the audio. This demo was designed to detect the source of a noise within the horizontal plane – i.e. it’s azimuth angle. Along the way I got some familiarity with acoustic beamforming, and it was a good exercise in Rust development, with the same codebase being used on the microcontroller, a GUI application, and a browser application. This post describes the development of the 6 microphone array, and a simulator for larger arrays. Perhaps in the future, I’ll have more to share about a much larger array combined with a camera; we’ll see!

The Video

To start with, you can check out this quick demo video to get an idea of what it does:

What is an acoustic phased array?

If you have multiple omnidirectional detectors at different locations, you can combine them into a directional detector, more sensitive to a particular source direction. If you can adjust the relative delay of the signals, you can select the focal point of the array, creating an directional receiver which can be steered electronically. It applies to electromagnetic as well as acoustic signals. With a single delay configuration at any given time, this is useful for focusing your receiver on a source, attenuating background noise coming from other directions. But also, if you can capture a segment of the raw signals, and then adjust the delays digitally you can compute a a power level for one moment, at many different focal points, effectively creating an image of power arriving from the different directions.

Components and code

I started with an STM32H7 Nucleo development board, and set out to see how many audio channels I could capture with it and stream to the ethernet port. I built an array with six microphones, which conveintely attaches to the Nucleo board.

Then I wrote some Rust code to convert the PDM microphone input to PCM, do an FFT to get a frequency spectra, and then do the delay-and-sum calculations in the frequency domain to focus the array to an array of focal points and compute total power for each. With just the six microphones, I found that it works well for measuring the azimuth to a source, but only marginally as a “camera” imaging a full 2D focal plane. This wasn’t a huge surprise; I assumed there was a reason that commercial acoustic cameras have many more than six microphones. To aid in development, I wrote a GUI using Rust GTK bindings to process the stream of UDP packets from the STM32H7, and display live results.

Once I had a reliable azimuth measurement, I added a brushless motor to rotate an indicator, so that it could physically point at the source of a detected noise.

Finally, I got the beamforming running on the microcontroller, albeit with some compromises since the CPU wasn’t able to fully process the data in real-time.

Finally, I created a javascript application to simulate a noise source and a hypothetical acoustic camera, in order to experiment with different micro layouts. This was built in Javascript, because 1) I wanted others to be able to run it without needing a Rust compiler or native binaries and 2) the UI is more complex and I find it’s easier to build with React, and 3) it’s a great demo of compiling Rust code to WASM to run in a browser!

At some point, I may refactor this a bit, but as of writing most of the code can be found in a single repository.

The main exception is a stand-alone app which does nothing but read audio and output to UDP packets: pdmstream

The simulator runs in the browser, and if you want to try it out without having to compile anything, it can be found here.

Capturing audio from PDM microphones on STM32H753

I started with this processor because a) I had a Nucleo-144 dev board for it laying around and b) at 400MHz it’s a high-end cortex, and I wanted to get as much DSP processing into this as possible. So the first question, how many synchronized PDM inputs can we get on this thing? (TL;DR: It’s 8.)

What are PDM inputs

I’m using MEMS PDM microphones from Adafruit. PDM stands for pulse density modulation. These use delta-sigma modulators to output 1-bit samples at a high rate (3.072MHz in my case) which can then be filtered to normal higher bit depth PCM samples. Many PDM microphones support combining two mics into one wire, where one channel is read on the falling clock edge, and the other is read on the rising edge.

The SAI Peripherals

The STM32H753 has four SAI – serial audio interface – peripherals, which support a variety of audio protocols. Two of them have a PDM mode, to read two microphones on each data channel, which looks like the best option for reading these microphones. There are two SAI peripherals, and at first reading each supports 4 data inputs. With two mics per input, that’s 16 channels of capture! However, as I dug into the reference manual, this number dropped to 8. The first thing is, the fourth input is left unconnected for both peripherals, so that drops us to 12 potential channels.

Table 417 from Reference Manual

Then, when I got down to pin assignments, I found that the SAI had pretty limited options. D2 on SAI1 only has one remap: PE4. Which would be OK, except – incredibly! – SAI4 D2 also has only one remap option, and it is also PE4!. So you can’t use both of them, at least not to capture different microphones! That drops the total possible input channels to 10. Finally, the D3 input on SAI1/4 has two remaps, but they are the same for both peripherals, which means if you want to use both, you have to use both of the two pins. This would be OK, but one of them is used for ethernet on the Nucleo board. That means I’m down to 8 channels.

Getting data out

The first pass at the embedded code was just a simple capture and ship approach, so that I could experiment with the signal processing on my workstation instead of on the microcontroller. With six channels (3.072MBit/s each), we need a total of about 18.4MBit/s throughput. Sadly, the USB on this chip only supports 12Mbit with the internal PHY, and the nucleo doesnt’ provide a faster USB PHY, so the only good option is the ethernet port: at 100MBit, it can push out all six channels comfortably, and the Rust stm32h7xx_hal crate supports smoltcp on this chip so it’s pretty straightforward to get going.

To read the data, one of the DMA1 streams is setup to read the SAI1 peripheral to memory, a pool of buffers is allocated, and the DMA IRQ can then push the completed buffer into a queue for transmit, then grab a free buffer from the pool and set it up for the next DMA transfer. The DMA is used in dual-buffer mode so when the transfer completes it automatically moves on to the other pre-configured destination address, and you have an entire DMA transfer time for the IRQ to swap out the inactive buffer.

All of this happens in the pdmstream application.

Audio processing

Diagram of the high level steps to compute a power vector from incoming PDM data

Converting PDM to PCM

The biggest downside to the PDM microphones (e.g., over an I2S version) is that they have to be filtered to get to higher bit-depth, lower frequency PCM samples, and this filtering is fairly inefficient to do on a CPU. All that’s really required is a low-pass filter, but if you want good noise performance and efficient processing there are some tricks, and it helps to do it in stages. Consider that the input frequency is 3MHz, and you probably don’t want to run a filter with a large number of taps at that sample frequency. I’m not going to get into the filtering much here, but will just point out that Tom Verbeure has a great series of blog posts about it. I will simply share the setup I ended up going with:

Fitlering starts with two stages of CIC decimation, then an FIR filter is run at 96KHz, and that output is further decimated by simple moving average to 24kHz

The CIC filters operate on 32-bit integers, because the integrator stage depends on integer overflow to work properly. After the second CIC filter, the values are converted to 32-bit floats, because my benchmarking found that doing the math in floats was ever so slightly faster than ints, and I don’t have to worry about managing fixed point math.

For determing FIR filter coefficients, I can highly recommend pyfda.

Conversion performance

As it turns out, doing the PDM conversion on the STM32H7 is work for the CPU. Just doing the PDM filtering on all six channels ends up using about 80% of the CPU time, leaving little for beamforming. It became pretty clear after doing some benchmarking that I was not going to be able to process all of the data in real time. So some kind of scheme for selectively processing chunks and handling overflow gracefully was clearly called for, and I’ll talk about that later.

One thing I want to note: CMSIS-DSP proved to be much faster than my implementation. I wrote my own FIR filter in Rust, and benchmarked it against the arm_fir_f32 function provided by the CMSIS library, and it ran 4x faster.

Beamforming

The beamforming is performed as a delay-and-sum in the frequency domain. It operates on a window of 1,024 samples (although I think I may be shrinking this to 512 or 256 in the future), which yields a spectrum with 1,024 frequency bins. Only a subset of the frequency bins are used, defined by a start and end frequency. For azimuth detection, I’ve found 500-2000Hz to be an effective range. Each spectrum bin is represented by a complex number which has a magnitude (i.e. total power) and a phase. To perform a delay, it can be multiplied by another complex number with unit magnitude, and an angle determining the phase adjustment. The delay to be applied can be calculated from the distance from each focal point to each microphone.

All of these phase adjustment complex numbers can be pre-calculated, yielding a NMICS x NFOCALPOINTS x NFFT matrix of complex numbers. Then computing the power for beamforming just requires one complex multiply for each frequency bin in each channel, then a summing of the phase adjusted values across channels. Sadly, storing this steering vector matrix requires a lot of memory, and all of the memory on the STM32H7 is already being used to hold audio samples, so when running on the STM32 I only pre-compute the NMICS x NFOCALPOINTS distances, not the complex steering vector. This leads to a lot of trig functions, and makes things slow. A phase (scalar) to phasor (complex) look-up function could probably be accurate enough in a reasonable size, and shave off a lot of sin/cos calls, but I haven’t looked into it at this point.

Practical implementation issues

The core PDM-to-PCM, and beamforming code lives in the dsp crate in the repository, so that it can be shared by the embedded code (stm32), the GTK gui (gui) and the React simulator (websim) crates. Creating code that could be used in the memory-constrained, heapless, no-std environment of the stm32 project, while also be used in the others created a lot of friction for me with Rust’s strict ownership management and borrow checking. I could probably write a whole blog post about the issues that popped up, but that will require a lot more reflection than I can muster tonight and take up too much space here. But one common pattern was that I needed static versions which could have their allocation size known at runtime, and heap based versions which could have things like number of microphones adjusted at run time, so you’ll see a lot of things like in the code with an interface trait, like,

pub trait BeamFormer {
    fn compute_power(
            &self,
            spectra: & dyn Spectra,
            power_out: &mut [f32],
            start_freq: f32,
            end_freq: f32);
}

And two separate implementations, like:

/// BeamFormer implementation using heap for storing steering vectors. Parameters, such as the
/// number of mics, number of focal points, or size of NFFT can be configured at runtime
pub struct HeapBeamFormer {
    steering_vectors: Array3<Complex<f32>>,
    sample_freq: f32,
}

/// BeamFormer implementation with fixed parameters known at compile time, and no heap usage
pub struct StaticBeamFormer<const NCHAN: usize, const NFOCAL: usize, const NFFT: usize> {
    steering_vectors: [[[Complex<f32>; NFFT]; NFOCAL]; NCHAN],
    sample_freq: f32,
}

Or even a third option:

/// A Beamformer implementation that does less pre-computation to avoid storage of large 
/// steering vectors, but this means it has to do more computation, sadly. 
pub struct SmallMemBeamFormer<const NCHAN: usize, const NFOCAL: usize>
where [(); NCHAN - 1]:
{
    dist: [[f32; NFOCAL]; NCHAN - 1],
    sample_freq: f32,
}

First GUI implementation

The first processing happened on my computer, with a GUI built using the rust GTK bindings, and plotters-rs. This lives in the gui direcotry of the project repo. It receives raw PDM data sent in broadcast UDP packets, collects them into appropriately sized frames, and passes them on to the DSP processing. It computes power for two beamforming focal point arrays: The circular array for azimuth calculation, and a rectangular grid for generating an image, so that both can be displayed live.

Azimuth Finding

One of the things I wanted to do as a first demo was to use the 6-mic array to determine azimuth angle of the source (i.e. what direction in the horizontal plane), and swivel something to point at them.

I tried mounging this styrofoam head above the array, but alas, it was too big and too acoustically absorbant

To find azimuth, I created an array of focal points arranged in a circle around the microphone array, with a radius of 2m, and 0.1 meters above the plane –I started with 100 points, but decreased it to 60 when I wanted to speed up processing on the STM32. So basically you focus the array at a series of points a little above the array, at a distance larger than the array size, and even if the height/elevation is off by a bit, I still expect the focal point nearest in azimuth to the source to have the highest power. The first naive approach is to take the highest power radial in each frame and call it a target. But there’s noise so we only want to respond to signals with certain power; so one can measure the RMS amplitude of each frame and set a threshold. Anything below the RMS threshold gets ignored. This is better, but what I found was that there are often echos after a sharp signal which show up at very different azimuth angles – I believe this is reverberation off of walls and other objects. This can lead to a quick solution to the correct azimuth, followed 50ms later by a bad solution.

So I added some more filtering. First of all, I reduced the azimuth power vector (the array of power at all N radials) to a complex value representing the “moment” of the power. Basically, convert each radial to a complex number with magnitude equal to the power measured there, and angle equal to the azimuth angle of the focal point. Sum these and you get a single complex moment.

Then for temporal filtering, the filter begins an estimate whenever the RMS power of a frame exceeds the threshold. It then accumulates the power moment for all frames until either: 25 frames are accumualted (about 1 second of audio), or the RMS falls below the threshold. The angle of the accumulated moment yields the new azimuth value. After an estimate, the RMS threshold is raised to the average RMS value of all frames used in the estimate, and decays over time. This prevents frames which are louder than the initial threshold, but quieter than the frames used for the recent estimate to be ignored, preventing the echo issues, and generally leading to a more stable azimuth estimate.

If that explanation leaves you wanting, the code is here.

Physical pointing device

I wanted a visible indicator of angle detection, attached to the microphones, so that if you said something, it could point at you. An arrow on a screen or, even worse, a number printed on a console – while technically adequate to show it was working – just wouldn’t have the same effect. So I needed a servo. A cheap PWM servo would have been grand, except they don’t do continuous rotation, or cover the full 360 degree range. So I went with a BLDC servo. This isn’t so hard to do: you just need angle measurement, and a driver with 3 half-bridges you can PWM. While building this, I found this excellent chip:

The STSPIN233 3-phase driver for 1.8-10V, up to 1.3A.

The STSPIN233 I hadn’t seen yet, but it’s a really great tiny and cheap option for relatively low-power/low-voltage 3 phase driver. Three half bridges, gate drivers, and it supports (optional) current sense on all three phases individually which is great for e.g. FOC. I couldn’t find this on a breakout available anywhere, so I had to buy an STSPIN233 CLICK board, which has more on it than I wanted, but that’s fine. Since it has the MCU, I went ahead and put the servo control on it.

I got some AS5600 magnetic encoder breakout boards off amazon to use for angle measurement.

I also got one of these BLDC Gimbal Motors.

Then I 3D printed some parts to mount the magnet on the rotor, hold the encoder, and mount the whole thing to the microphone ring. It looks like this:

The servo controller code gets programmed onto the STM32F0 that comes on the CLICK board, and it lives on github here: bldc-servo.

Fitting it onto the microcontroller

On the STM32, I can’t process all the frames, so they are filtered based on RMS. First of all, we allocate most of the on-chip RAM to two buffer pools:

One has 7 100kB buffers for holding PDM frames (the PDM data is BIG! 700kB holds 300ms)
One has 12 4kB buffers for holding a single channel of a PCM frame

Then the processing is separated into two stages:

pre-processing runs the PDM to PCM conversion on one channel of data, and calculates an RMS value for the frame – basically, how loud is it?
post-processing finishes the PDM to PCM conversion on the remaining channels and then performs the beamforming and azimuth estimation.

After capture, two processing queues hold audio data in flight.

The first queue is a standard queue for fresh frames; it shouldn’t ever have more than one frame at a time. The second queue has special rules: When a buffer is pushed onto the queue, the number of frames in the queue with audio data are limited to a maximum value. If there are more than 4 frames in the queue with data after a push, the frame with the lowest RMS value has its audio data freed. The RmsBuffer object (which requires only a tiny bit of RAM) remains in the queue as a place holder, indicating to later processing when a frame was dropped, and providing the RMS value (which can be used by the azimuth estimation filter even if the audio is dropped). This way the pointing decision is based on the loudest frames, and because the pre-processing is fast enough and runs at higher priority, the DMA never runs out of buffers to store the next frame. The end result is that if we get a burst of more “loud” frames than we can store, we will end up processing (at least) the loudest four of them. This seems to work well enough.

Async vs Tasks

I started out using Rust async functions, and the embassy async executor with separate tasks for the pre- and post-processing. This sort of “cooperative” multitasking means that the post-processing task has to yield frequently enough to ensure that the pre-processing task can finish each new frame and – if necessary – return the lowest RMS frame back to the pool. You can insert this breaks in processing by inserting some strategic embassy_futures.yield_now().await statements, but I found doing this in between processing each channel wasn’t sufficient, there were not obvious places to insert yields, and no easy way to make guarantees about timing in the face of potential processing changes.

Unfortunately, there’s no way for an interrupt to cause a task switch – switching can only happen on await statements. So in this case, I think the async model wasn’t quite right. Instead, I hi-jacked an unused interrupt to get easy task-free threading on the cortex, using a great trick I learned from RTIC:

First, define an interrupt to execute your task. In this case, it just completes pre-processing for any available frames:

#[interrupt]
fn LPTIM5() {
    let audio_reader = unsafe { AUDIO_READER.as_mut().unwrap() };
    embassy_futures::block_on(audio_reader.preprocess());
}

Enable the interrupt in the NVIC (NOT in the peripheral):

// Enable an "extra" irq to serve as a higher priority task than main loop
unsafe {
    cp.NVIC.set_priority(device::Interrupt::LPTIM5, 200);
    cortex_m::peripheral::NVIC::unmask(device::Interrupt::LPTIM5);
}

Then whenever a new buffer comes in, the processing task can be triggered from the IRQ.

// IRQ goes off on completion of a DMA transfer. We then swap out the inactive buffer
// for a for a fresh one, and pass the completed one off to the queue for processing
#[interrupt]
fn DMA1_STR0() {
    // <snip>... Handle the DMA stuff, get the new buffer
    
    // Put the buffer into the queue for processing
    out_producer.enqueue(pdm_buffer).ok().expect("failed queuing pdm buffer");

    // Wake the the pre-processing task which lives at the LPTIM5 interrupt vector
    let mut nvic = unsafe { crate::device::CorePeripherals::steal().NVIC };
    nvic.request(crate::device::Interrupt::LPTIM5);
}

With the priorities set right, the processing task can be preempted by other more urgent IRQs (like the DMA or UART), but it will preempt any ongoing post-processing and execute immediately after the DMA IRQ returns.

Moving Forward

More/better processing

A good acoustic camera will need more microphones, and it’s clear that the STM32H7 is not the platform for that. This is a pretty ideal application for an FPGA, I think, especially since the initial PDM filtering can be done with very low bit width, so it can be quite small in the FPGA. If the FPGA can take over audio capture/filtering, the STM32H7 could do the beamforming, but at a less-than-ideal frame rate, especially since the processing time will grow with number of channels. Switching to I2S microphones would save a lot of the processing, but I still don’t see any path to capturing more channels on the STM32H7.

Combine with a camera

I want to see just how cheaply I could produce an acoustic camera with display and video overlay. The commercial products out there are all rather expensive, and it would be cool to have a working open source camera.

Wake-on-keyword + a real head

Part of the motivation here was to create a fun desk toy that would look at you when you talk to it. To make that really work I need a) a head arrangement that doesn’t interfere with the array and b) a keyword recognition model.

The head seems very solvable. Maybe a wireframe head will allow sound through well enough, or I can locate the microphones above it (perhaps my head gets a crown?). The keyword recognition, I’m not sure. It seems like training a good keyword model takes a lot of examples, and whether I can reduce that model to something that will fit in memory and run on the STM32 is TBD.

High Voltage Amplifier

2022-05-17T07:00:00Z

An open-source design for a high-voltage amplifier based on the Apex PA88 450V opamp.

Photo of high voltage in 3d printed enclosure

What’s it for?

It’s just an amplifier that supports a relatively high output voltage. In this case, a +/- 3.3V signal in can be amplified to a +/- 200V signal out. Sometimes you need to create a signal with a fairly high voltage. Driving piezo activators is a classic example. Another example is generating a sine wave to drive electrodes on a digital microfluidic device. In my case, I wanted to test the dielectric properties of different films at high voltage.

There are benchtop high voltage amps available, but they are pretty expensive and pretty big.

The design

The amplifier itself is a PA88 from Apex. This was straight-forward to use, as it’s just an op-amp with a few discretes as recommended in the datasheet. I set the current limit resistor to 150ohm, limiting the output to 4.5mA or so. Gain is adjustable by a trim pot.

The PA88 comes in a massive TO-3 package

The remainder of the design is a switching power supply to generate a 200V rail, and a negative 200V rail, and this was a fun challenge. In the past if I needed a negative supply for an op-amp, I’ve used the MAX1044 switched-capacitor converter to invert the positive supply. But this is certainly not going to work for 200V. I found this TI AppNote demonstrating the use of a switched capacitor inverter for a bipolar supply. On each switching cycle, power from the inductor is dumped preferentially into whichever output (positive or negative) has the lower magnitude, so by regulating the positive output you get the negative output regulation for “free”.

I used the LT1171HV for the switcher. Because it can only handle 75V on the switch output, I added a couple diode boost stages to both positive and negative outputs, so at 200V output the SW pin only sees 67V.

The total BOM cost ended up being about $70, but that’s only because I was able to find the PA88 on Ebay for $30, which is a great deal. The usual price is over $200.

High voltage amplifier with top of case removed to show circuit board

Results

I’ve brought this up, and I’ve used it a bit with my Analog Discovery 2 waveform generator as the input. So far it seems to work great. The only caveat is that I’m driving fairly small capacitive loads, so I haven’t really stressed the output power. The LTSpice simulation says it should be fine to supply 4mA continuous, but I haven’t done this yet.

The design is available on github, and includes the KiCad design + gerbers, as well as STLs for the 3D printed enclosure.

KiCad Racetrack Layout with Python Plugin

2022-03-19T07:00:00Z

KiCad Magnet Racetrack Layout with Python Plugin

Summary

In 2022, I designed a small magnet racetrack on a PCB, and to do it I had to create some python tools for programmatically adding tracks and via to the PCB design. This post talks about those tools and how they work.

Example of a generated racetrack design

This was all tested in KiCad v6.0.4. The python API does change from time to time, and this could break in some way in a future release.

Tracks vs Footprints

I experimented a bit with the best way to approach this, before settling on the method I did. The first thing I tried was creating the track as a footprint, since this is what I’ve used before for designing digital microfluidic electrodes. But, there were a couple problems with this:

The first is that footprints do not allow custom geometries with electrical connectivity. What this means is that when you put copper shapes – lines, polygons, anything other than pads – into the footprint, those shapes do not get assigned the net from a pad that they touch, and you can’t draw a track to connect to it in pcbnew. You can work around this by turning off the rule preventing DRC errors, but this is annoying, and you can’t then actually use the DRC checker to make sure you’ve connected everything correctly.

The second is that it is difficult to change the footprint, and I found it convenient to use the script to layout tracks, but still retain the ability to manually modify them a bit in pcbnew after generation.

Instead of generating footprints, I created an Action Plugin which would draw the tracks and vias right into the PCB design.

The Basics: creating a plugin to modify the board

To create an action plugin, you just have to define a class which inherits from pcbnew.ActionPlugin in a python script, call the register() method on an instance of that class, and place that script into the kicad search path.

Here’s a simple example which will create a track and via at a fixed location:

example_plugin.py

import pcbnew

def pcbpoint(p):
    return pcbnew.wxPointMM(float(p[0]), float(p[1]))

class ExamplePlugin(pcbnew.ActionPlugin):
    """Draw a track and via
    """
    def defaults( self ):
        self.name = "Example Plugin"
        self.category = "Modify PCB"
        self.description = "Draws a track and a via"
        self.show_toolbar_button = True

    def Run( self ):
        board = pcbnew.GetBoard()
        group = pcbnew.PCB_GROUP(self.board)
        board.Add(group)

        # Draw a track which goes from (100, 100) to (100, 110)
        track = pcbnew.PCB_TRACK(board)
        track.SetStart(pcbpoint((100, 100)))
        track.SetEnd(pcbpoint((100, 110)))
        # Size here is specified as integer nanometers, so multiply mm by 1e6
        track.SetWidth(int(0.3 * 1e6))
        track.SetLayer(pcbnew.F_Cu)
        board.Add(track)
        group.AddItem(track)

        # Now draw a via at one end of the track
        via = pcbnew.PCB_VIA(board)
        via.SetPosition(pcbpoint((100, 110)))
        via.SetDrill(int(0.3 * 1e6))
        via.SetWidth(int(0.6 * 1e6))
        board.Add(via)
        group.AddItem(via)

ExamplePlugin().register()

This plugin also creates a group, and adds the new elements to the group. This makes it easy to select them all together to move, or to delete. If you make changes to the layout script, you have to delete the old elements, reload plugins, and then re-run the plugin to regenerate.

If you’re wondering where to install the python file, KiCad 6 has a helpful tool menu option to open the plugin directory:

For me, on linux, I place plugins in /home/jeff/.local/share/kicad/6.0/scripting/plugins.

After adding the plugin file, or making changes to it, you need to run the Tools->External Plugins->Refresh Plugins command in pcbnew.

When the plugin is loaded, it can be run from the Tools->External Plugins menu, or by clicking the new icon in the toolbar.

Generating the whole track

The full script for laying out the prototype track can be found in this gist.

It won’t teach you much more about controlling KiCad though, as the rest of the script is basically geometry for generating tracks, and I’m not realy going to go into that much here. In fact, that was just the first take, and it was eventually superceded by CurvyCad which implements the same thing in a much more generic and re-usable way.

But, one problem which pops up is how to wire the generated tracks. The track has two guard rail traces, and two phases A/B, and both ends of these wires need to get wired to connector pins. The newly generated tracks don’t have any net information, but that’s OK because that means that as soon as you connect them to something in pcbnew, they will inherit the net. The main trick is, you have to go to the “Interactive Router Settings” dialog, and enable “Highlight collisions” mode, and check the “Allow DRC violations” option. This lets you route tracks from your connector pads to the generated tracks, and when you do, KiCad automatically assigns them the connected net.

Here’s the schematic for the racetrack. It’s pretty simple:

The net ties serve to represent the four tracks on the board: the two rails and the two alternating phases. These tracks are not really connections; they are more like two-pin components and the net ties help represent that.

The script, for simplicity, generates a fully connected loop. After running it, I decided where I wanted to insert connections and I manually cut the traces to wire them to the connector pins.

That’s pretty much it. For a lot of tasks, the ability to programmatically generate PCB features allows for a lot faster design, and iteration. This demo was the first test, but now that it’s in place, I can quickly adjust the design and iterate on different versions of it.

Demo Video

And just in case you’re curious, here’s a video of the track in action:

Part 2: CurvyCad

The first plugin was very quick and dirty, and it basically had two functions: append_straight and append_arc. As example, the code below lays out a simple oval track, which starts at coordinates (150,150) and ends up back at the same point. This works because it was a simple shape and it was fairly easy to come up with a sequence which terminates exactly where it began, but it’s not very generalizable.

TURN_RADIUS = 30
pos = (150, 150)
pos = append_straight(board, pos, 10, 0)
pos = append_arc(board, pos, TURN_RADIUS, 0, 90)
pos = append_arc(board, pos, TURN_RADIUS, 90, 90)
pos = append_straight(board, pos, 10, 180)
pos = append_arc(board, pos, TURN_RADIUS, 180, 90)
pos = append_arc(board, pos, TURN_RADIUS, 270, 90)

Instead, I wanted to be able to make more arbitrary path designs, and ideally, I’d like to sketch them in a CAD tool. So, CurvyCad was born. The idea is, you define one period of the repeating pattern for the track, along a straight line, and then import a DXF file containing a series of connected lines and arcs which define the track, and the periodic pattern is repeated along this path, being bent as necessary to follow the centerline. Additionally, the pitch of the pattern – how much distance it takes to complete one cycle – is adjusted so that the last cycle ends at the end of the curve. This way, if you make a looping track, the traces at the end of the track match up to the traces at the start perfectly.

The pattern can be defined from just three elements:

Parallel lines (these run along the track, parallel to the centerline)
Transverse lines (these run perpendicular to the track)
Vias (just points, really, which are maintained to be at the same transverse distance along the line as it curves)

This is a little bit restrictive, but it limits the output to shapes which can be represented as lines and arcs. If you try to warp an arc along another arc, for example, the path you end up with will not be an arc. You could do the transformation, but it would have to be piecewise approximated with a series of lines in Kicad. More importantly, I didn’t need this so I didn’t want to do all that extra work!.

The second iteration of magnet track, created with CurvyCad

Collecting home environmental sensor data with SDR, prometheus, and grafana

2021-03-23T07:00:00Z

Summary

Although I explored a design for a custom humidity and temperature sensor, here I describe the solution I ultimately ended up with and which I would recommend to anyone looking to implement such a system.

This article discusses the use of cheap acurite sensors which transmit their measurements on 433MHz ISM band which can be easily picked up with a cheap RTL-SDR device, and the setup of prometheus for data capture as well as the monitor_rtl433 utility I created to act as a bridge between the SDR and Prometheus.

The sensors

There are a number of options for sensors on the market. I’ve used these two with success. They have worked reliably, and they each come with a unique serial number so you can add as many as you want to your system and still differentiate between them.

The AcuRite 06044 is an indoor only model with display:

Photo of Acurite 06044 sensor

The AcuRite 06002M is an indoor/outdoor model without a display:

Photo of Acurite 06002M sensor

There are other devices supported by rtl_433. Any of those should be easy to set up too.

Other hardware

To receive the signals, I used an RTL-SDR plugged into an odroid single board computer; a raspberry PI would also work just fine here, as would any other SBC that can run linux.

Setting up Linux

We’re going to setup a few services now:

Prometheus is a time series database.
Grafana is a dashboard/plotting package that will pull data from prometheus and display it in your browser.
monitor_rtl433 is a simple daemon I created to read the sensor data from the SDR and provide the stats for prometheus

I’ll give a quick run-down of how I installed these, but I also recommend checking out the documentation for the projects or other tutorials specific to that if you run into trouble or want to adapt your methods a bit.

Setting up prometheus

Prometheus has binaries for arm7, available for download here. To install, just download the arm7 tarball and extract:

wget https://github.com/prometheus/prometheus/releases/download/v2.25.2/prometheus-2.25.2.linux-armv7.tar.gz
tar -xvzf prometheus-2.25.2.linux-armv7.tar.gz
mv prometheus-2.25.2.linux-armv7 prometheus

Then create a configuration for prometheus, to tell it where to scrape input data from. Here’s my configuration as an example:

## prometheus.yml
# my global config
global:
  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
  - static_configs:
    - targets:
      # - alertmanager:9093

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
    - targets: ['localhost:9090']

  - job_name: 'monitor433'
    scrape_interval: 10s
    static_configs:
    - targets: ['localhost:5000']

The most important bit is the ‘monitor433’ scrape config job, as this tells prometheus to scape from http://localhost:5000/metrics, which is where the python `monitor433’ process we’ll be setting up shortly will be listening.

Installing grafana

Grafana also has a stand-alone arm binaries release, which can be found here, and which can be installed much the same way into your home directory:

wget https://dl.grafana.com/oss/release/grafana-7.4.5.linux-armv6.tar.gz
tar -zxvf grafana-7.4.5.linux-armv6.tar.gz
mv grafana-7.4.5.linux-armv6 grafana

Grafana configuration is stored in grafana/conf/grafana.ini. I’ll leave any setup for grafana to the reader, because, to be honest, it has been a while since I set it up and I don’t know what I had to change. It may be that the default config is fine and you can do all of the setup in the grafana GUI. Check out the setup instructions here: https://prometheus.io/docs/visualization/grafana/.

Install rtl_433

You’ll need the rtl_433 utility installed. There are instructions for building here. I built it from source with cmake. You may be able to install from a package depending on your distribution, e.g. with ubuntu sudo apt install rtl-433.

Identifying your devices

Once rtl_433 is installed, and your SDR is plugged in, you can run rtl_433 -F json to get a live stream of events detected. It should look something like this:

# rtl_433 -F json
rtl_433 version 19.08-18-g8eecdbb branch master at 201909241811 inputs file rtl_tcp RTL-SDR
Use -h for usage help and see https://triq.org/ for documentation.
Trying conf file at "rtl_433.conf"...
Trying conf file at "/root/.config/rtl_433/rtl_433.conf"...
Trying conf file at "/usr/local/etc/rtl_433/rtl_433.conf"...
Trying conf file at "/etc/rtl_433/rtl_433.conf"...

    Consider using "-M newmodel" to transition to new model keys. This will become the default someday.
    A table of changes and discussion is at https://github.com/merbanan/rtl_433/pull/986.

Registered 108 out of 138 device decoding protocols [ 1-4 8 11-12 15-17 19-21 23 25-26 29-36 38-60 63 67-71 73-100 102-103 108-116 119 121 124-128 131-138 ]
Found Rafael Micro R820T tuner
Exact sample rate is: 250000.000414 Hz
[R82XX] PLL not locked!
Sample rate set to 250000 S/s.
Tuner gain set to Auto.
Tuned to 433.920MHz.
{"time" : "2021-03-25 03:27:05", "model" : "LaCrosse TX141TH-Bv2 sensor", "id" : 71, "channel" : 0, "battery" : "OK", "temperature_C" : 11.100, "humidity" : 75, "test" : "No"}
{"time" : "2021-03-25 03:27:06", "model" : "Acurite tower sensor", "id" : 15922, "channel" : "A", "battery_low" : 0, "temperature_C" : 20.800, "humidity" : 46}
{"time" : "2021-03-25 03:27:06", "model" : "Acurite tower sensor", "id" : 15922, "channel" : "A", "battery_low" : 0, "temperature_C" : 20.800, "humidity" : 46}
{"time" : "2021-03-25 03:27:06", "model" : "Acurite tower sensor", "id" : 15922, "channel" : "A", "battery_low" : 0, "temperature_C" : 20.800, "humidity" : 46}
{"time" : "2021-03-25 03:27:07", "model" : "Acurite 606TX Sensor", "id" : 43, "battery" : "OK", "temperature_C" : 9.300, "mic" : "CHECKSUM"}
{"time" : "2021-03-25 03:27:10", "model" : "Acurite tower sensor", "id" : 15352, "channel" : "B", "battery_low" : 0, "temperature_C" : 7.700, "humidity" : 88}
{"time" : "2021-03-25 03:27:10", "model" : "Acurite tower sensor", "id" : 15352, "channel" : "B", "battery_low" : 0, "temperature_C" : 7.700, "humidity" : 88}
{"time" : "2021-03-25 03:27:10", "model" : "Acurite tower sensor", "id" : 15352, "channel" : "B", "battery_low" : 0, "temperature_C" : 7.700, "humidity" : 88}

Now your task is to identify which sensor is which, and how difficult this is will depend on how many sensors you and your neighbors have. One trick is to switch the “channel” on a sensor of interest between A and B, and watch for one of the “id” numbers to change accordingly. Or, just power on and off a sensor and watch for it to start and stop. For some sensors, there is an LED which blinks each time it transmits an update, and it’s possible to visually correlate this with the updates on the terminal. Once I figure out the ID number of a sensor, I usually write it on the back of the sensor for next time.

Setting up monitor_rtl433

You can checkout the monitor project from https://github.com/mcbridejc/monitor_rtl433. This utility is a little python daemon I wrote to spawn an rtl_433 process, and run a webserver to make make collected data available. In order to define exactly what goes into the /metrics route scraped by prometheus, you will need to write a little custom python.

For an example, see examples/main.py. Basically, you need to create a python object, derived from MetricFilter for each sensor you want to collect data from. The process method on this class takes a dict created from the json blob returned by rtl_433, and maps it to Metric objects which are provided to prometheus. This translation is necessary because the format of the JSON data varies for different sensor types.

Here’s an example of the MetricFilter class that works for both types of acurite sensor:

class AcuriteTower(MetricFilter):
    def __init__(self, id):
        self.id = id
        # The `_match` property will be used to determine which sensor records
        # this filter will be applied to
        self._match = {"model": "Acurite tower sensor", "id" : self.id}
        
    def process(self, r):
        """Takes a single sensor record, and converts it to 0 or more metrics
        """
        sensor_id = "%s%s" % (str(self.id), r['channel']) 
        yield Metric('temperature', degc2f(r['temperature_C']), labels={'sensor_id': sensor_id})
        yield Metric('humidity', r['humidity'], labels={'sensor_id': sensor_id})
        yield Metric('battery_warning', r['battery_low'], labels={'sensor_id': sensor_id})

In the constructor, it sets the _match variable to a dict. This filter will be used to process any incoming data that matches all of the key/value pairs provided here. In this case, that means any records where “model” is “Acurite tower sensor” and “id” is the provided number.

Once you create your own script based on the example main.py, you can run that and point your web browser at port 5000.

Here, you’ll get a landing page showing some options:

If you follow the sensors link, you’ll get a table with the most recent update from all of the sensors it has seen since it was started. If you live around other people, you’ll probably see a lot of sensors here. Other’s weather sensors, tire pressure sensors, alarm system sensors, etc.

The most important thing to make sure you are setup correctly for prometheus, is to make sure that you get the expected metrics under the /metrics link. It should look something like this:

Configure services

In order to make sure your three new services are automatically started at boot, you can add them as systemd services.

Here are my service definition files, which are stored in /etc/systemd/system.

/etc/systemd/system/prometheus.service

[Unit]
Description=Prometheus time series database

[Service]
Type=simple
WorkingDirectory=/root/prometheus
ExecStart=/root/prometheus/prometheus --config.file=prometheus.yml 

[Install]
WantedBy=multi-user.target

/etc/systemd/system/grafana.service

[Unit]
Description=Grafana server

[Service]
Type=simple
WorkingDirectory=/root/grafana
ExecStart=/root/grafana/bin/grafana-server -config conf/grafana.ini

[Install]
WantedBy=multi-user.target

/etc/systemd/system/monitor_rtl433.service

[Unit]
Description=433MHz sensor monitor

[Service]
Type=simple
Environment=MONITOR_RTL433_HOST="0.0.0.0"
ExecStart=/usr/bin/python3 /root/monitor433.py

[Install]
WantedBy=multi-user.target

To make sure these services are started at boot, you may need to run these commands:

sudo systemctl enable grafana.service
sudo systemctl enable prometheus.service
sudo systemctl enable monitor_rtl433.service

Grafana Setup

Now you can setup grafana dashboards with your incoming sensor info. Create plots, or gauges, or whatever you prefer. In grafana, I label data sources according to where they are, e.g. “Garage” or “Bedroom”. Here’s a quick example of a configuration for a temperature plot:

Checkout the Grafana Docs for everything you can do.

Custom Temperature and Humidity Sensor with E-ink Display

2021-03-22T07:00:00Z

E-Paper Temperature and Humidity Sensor

Summary

In 2019 I wanted some sensors to spread around my new house, and I wanted a new project, so I designed this little sensor. It was a fun exercise controlling the e-paper display, and I like the vertical USB-C connector design that allowed it to go straight onto a charger plugged into a wall outlet. Designing a sensor like this so small without inducing any self-heating is a challenge if you are looking for good accuracy. In the end, I decided to base my system on off-the-shelf 433MHz sensors, with an RTL-SDR as a base station collecting data, as described here

Design

The sensor uses an ESP32 module as the controller and WiFi radio, an AMS ENS210 for temperature and humidity sensing, and a 1.44” Pervasive Displays e-ink display. It has a USB-C connector sticking out of the back, with the idea that it could be plugged into a USB-C charger on any outlet for easy mounting and no need for batteries.

Once I got it all working, I found that it had a significant self-heating problem. Even after enabling sleep mode on the ESP32, and only powering on to sample every minute, I still got 5F+ of rise. I did a second revision of the board, with the temperature sensor placed onto a cut-out island at the bottom, with an air intake next to it so that – hopefully – convection would constantly pull fresh air in over the sensor and I could measure the ambient temperature, not the elevated value inside the case. This helped: with the redesign I got about 2F rise above ambient. Much better but still not as good as I’d like.

Front view of assembled sensor

Back view of assembled sensor}

Back of printed circuit board

Front of printed circuit board

Plan B

I put the first one into operation. But then two things happened: first I bought some off-the-shelf 433MHz wireless sensors that are much cheaper than I could build the custom sensor for and seem to have better accuracy, and then the e-ink display suddenly stopped working. The sensor still reported fine over WiFi, but a bit of debugging seem to suggest something had gone wrong with the display. The COTS sensors have a lot to recommend them: e.g. they are cheap, they can be read easily with a RTL-SDR, no WiFi configuration necessary. So ultimately, while it was fun to bring up the e-ink display and this was a neat project, it didn’t make sense to keep using it.

Since then, I’ve been using a small single-board computer and RTL-SDR to collect data from a number of sensors into a Prometheus database, and it has been simple and reliable. When I want to add a new sensor, I don’t have to order parts or build anything.

Tapper: A flexible, packaged touch-screen kit for STM32

2021-03-01T08:00:00Z

Tapper

Tapper is a general purple STM32 + touchscreen in a box with flexible IO for quick prototyping.

The situation is this: You want a microcontroller to read and display some sensor, control some process, or provide some user interface – the details vary – and you just want to build one or two but you also want it to be somewhat permanent. I really hate the jumble of wires, and the unreliability of breadboarding, but don’t want to go off and design a custom board and enclosure for each thing. I want something that’s flexible, but more reliable. It needs to be in a case. It needs to have connectorized IO. It needs to be flexible about providing power, because I don’t want to end up with a second power supply to drive the external bits, I just want to plug it in.

On Tapper:

All the IO is connected by soldered jumpers between through holes.
Each of the three six-pin connectors provides power from one of the power rails (3.3V, 5V, or VIN) based on a solder bridge
The touch screen is constant, wired to the same pins, so it works with the same software you used the last time
The nucleo-32 dev board provides an on-board ST-link for programming and debugging, as well as a USB serial port

With tapper, and a power supply like this you can get a very portable setup with whatever supply voltage you need.

My first use-case was a spincoater RPM controller. But I’ve also used it to wire up an I2C sensor and display the reading while allowing a user to switch modes and a few other projects.

More detailed info lives on the github page. There’s an example software project, which includes a basic UI widget API for the touch screen. At some point I may expand on this and pull it out as a stand-alone library. The software uses the modm C++ peripheral library, as do most of my embedded C++ projects.

KiCad automated component layout via configuration file

2021-02-28T08:00:00Z

Kicad Component Layout

Introduction

A KiCad plugin for quick programmatic layout of components on your PCB.

I’ve done a number of board designs that involve laying out a lot of footprints in precise locations that are more easily described in code than via the KiCad UI. I wrote previously about programmatic component layout in KiCad, but since then I’ve refined the process a fair bit. The code run in Kicad is reduced to a single plugin script, which you can find here: https://github.com/mcbridejc/kicad_component_layout.

The basic premise is that you, the designer, write a script (could be python, or whatever you prefer) to generate a layout.yaml, and in KiCad you execute the plugin to sync the instructions in the layout.yaml file to your PCB design. This means that you can iterate and update your design without having to constantly reload the kicad plugin, and also if you work on multiple projects that use auto-generated placements, you don’t need to manage separate plugins for each project (I think project associated plugins would be a great feature for Kicad, but alas it is not available at the moment).

Example layout.yaml

The layout file can change the positions, rotation, flip status (top/bottom), and the footprint for a component based on designators. I think a quick example of a layout file should give the idea:

  origin: [x0, y0] # Offset applied to all component locations
  components:
      R1:
          location: [x, y] # mm
          rotation: [r] # degrees
          flipped: false
          footprint:
              path: path/to/library.pretty
              name: SomeFootprint
      J1:
          ...

Github

There are more instructions on the github project. If you find it useful, or have suggestions for how to expand it, feel free to open an issue or email with suggestions. I’m pretty open to expanding it to cover more use cases if anyone else finds it useful. I’ve found that this simple plugin handles all of the programmatic use cases I’ve needed, and it avoids the need for project specific code to be installed as a KiCad plugin.

Jeff McBride

Droplet Capacitance Sensing

DMF Background

Capacitance for Volume Sensing

AC Systems

PurpleDrop “Pseudo-AC” Drive

Current Sense Design

Overview

Sequencing

Measurement Groups

Integration Circuit Design

Current Gain Selection

Amplifier Stages

Negative Supply Rail

“Augment” FET

Results

Capacitance Measurement Demo Video

Syringe Pump Driven Dispensing

The Kapton Hysteresis Mystery

Capacitance depends heavily on voltage history

The history of other electrodes matters too

The effect is not present with Mylar

Follow-up testing: No hysteresis found

Footnotes

Rust static init with None

Static data intro

BSS vs DATA

Is None encoded with zeros?

Demo Code

The solution

2025 Book Reviews

The Bobiverse Series

The Control of Nature

The Nvidia Way

Adding PDO Defaults to zencan

The original problem

Non-const init

Duplicating memory

Defaults as a function of runtime state

Options

Publishing zencan crates

Footnotes

Building an application for the CoreMP135 using Rust and Slint

Getting code onto the device

Cross Compiling

Building a UI

Rendering

Input Events

Putting it all together

Compiling outside of buildroot vs a package

Build and Install

Expandable Data partition

Repos

Creating linux images for the M5Stack CoreMP135 with Buildroot

About the CoreMP135

Programming with Buildroot Linux

Buildroot vs Debian

Buildroot Basics

Get the buildroot tree

The BR2 External Tree

Touchscreen issues

RAUC for OTA

Checkout the repo

Next steps: Adding a custom application

Building Custom Steel and Wood Furniture

Why?

Caveats

The bedside tables

Getting the steel

Welding

Wood

Painting

BOM and Material Cost

Other Tables

Couch End Table

End of hall table

Some more process photos

Zencan Device Demo Video

Video

Notes

Is `None` encoded with zeros?

Using `async` functions to auto-generate a state machine