A Rust no-std no-alloc LED control library for spatial layouts

What’s in this post?§

• Backstory
• Announcing: Blinksy
  • Examples
    • Desktop Simulation: 2D Grid with Noise Pattern
    • Embedded: 2D APA102 Grid with Noise Pattern
    • Embedded: 1D WS2812 Strip with Rainbow Pattern
• How Blinksy works
  • Define your LED layout
    • 1D layouts
    • 2D layouts
  • Create your visual pattern
  • Setup your LED driver
    • What colors do an LED understand?
    • What protocols do an LED understand?
    • What LEDs can we talk to?
• Get started
  • Put everything together
  • Get running on a microcontroller
  • Add some LEDs
  • Hello LEDs
  • Simulate on your desktop
  • Quickstart a project
• Thanks

Backstory§

I wanted to make a LED control library that could do the following:

• Like FastLED, support all the most common LED pixel chipsets such as WS2812, APA102, and more.
• Like WLED, have a library of beautiful visual patterns.
• Unlike anything before, support not just strips and grids, but any 1D, 2D, or even 3D spatial layout.
• By using Rust, have an modern and delightful developer experience.

I had some previous learnings with LED pixels:

• PIXELS FOR THE PIXEL GOD
• A Burn Dance
• Polyledra V1: LED Tetrahedron
• Polyledra V2: LED Tensegrity

And learnings with advanced generics for no-std no-alloc embedded Rust.

Announcing: Blinksy§

Blinksy is a new LED control library for 1D, 2D, and soon 3D spatial layouts*.

* 3D layouts are coming soon, because I want an LED cube like this with native 3D animations!

Examples§

Desktop Simulation: 2D Grid with Noise Pattern§

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

use blinksy::{
    layout::{Shape2d, Vec2},
    layout2d,
    patterns::noise::{noise_fns, Noise2d, NoiseParams},
    ControlBuilder,
};
use blinksy_desktop::{
    driver::{Desktop, DesktopError},
    time::elapsed_in_ms,
};
use std::{thread::sleep, time::Duration};

fn main() {
    layout2d!(
        Layout,
        [Shape2d::Grid {
            start: Vec2::new(-1., -1.),
            horizontal_end: Vec2::new(1., -1.),
            vertical_end: Vec2::new(-1., 1.),
            horizontal_pixel_count: 16,
            vertical_pixel_count: 16,
            serpentine: true,
        }]
    );
    let mut control = ControlBuilder::new_2d()
        .with_layout::<Layout>()
        .with_pattern::<Noise2d<noise_fns::Perlin>>(NoiseParams {
            ..Default::default()
        })
        .with_driver(Desktop::new_2d::<Layout>())
        .build();

    loop {
        if let Err(DesktopError::WindowClosed) = control.tick(elapsed_in_ms()) {
            break;
        }

        sleep(Duration::from_millis(16));
    }
}

Embedded: 2D APA102 Grid with Noise Pattern§

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

#![no_std]
#![no_main]

use blinksy::{
    layout::{Shape2d, Vec2},
    layout2d,
    patterns::noise::{noise_fns, Noise2d, NoiseParams},
    ControlBuilder,
};
use gledopto::{apa102, board, elapsed, main};

#[main]
fn main() -> ! {
    let p = board!();

    layout2d!(
        Layout,
        [Shape2d::Grid {
            start: Vec2::new(-1., -1.),
            horizontal_end: Vec2::new(1., -1.),
            vertical_end: Vec2::new(-1., 1.),
            horizontal_pixel_count: 16,
            vertical_pixel_count: 16,
            serpentine: true,
        }]
    );
    let mut control = ControlBuilder::new_2d()
        .with_layout::<Layout>()
        .with_pattern::<Noise2d<noise_fns::Perlin>>(NoiseParams {
            ..Default::default()
        })
        .with_driver(apa102!(p))
        .build();

    control.set_brightness(0.1);

    loop {
        let elapsed_in_ms = elapsed().as_millis();
        control.tick(elapsed_in_ms).unwrap();
    }
}

Embedded: 1D WS2812 Strip with Rainbow Pattern§

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#![no_std]
#![no_main]

use blinksy::{
    layout::Layout1d,
    layout1d,
    patterns::rainbow::{Rainbow, RainbowParams},
    ControlBuilder,
};
use gledopto::{board, elapsed, main, ws2812};

#[main]
fn main() -> ! {
    let p = board!();

    layout1d!(Layout, 60 * 5);

    let mut control = ControlBuilder::new_1d()
        .with_layout::<Layout>()
        .with_pattern::<Rainbow>(RainbowParams {
            ..Default::default()
        })
        .with_driver(ws2812!(p, Layout::PIXEL_COUNT))
        .build();

    control.set_brightness(0.2);

    loop {
        let elapsed_in_ms = elapsed().as_millis();
        control.tick(elapsed_in_ms).unwrap();
    }
}

How Blinksy works§

• Define your LED layout in 1D, 2D, or soon 3D space
• Create your visual pattern (effect), or choose from our built-in patterns library
  • The pattern will compute colors for each LED based on its position
• Setup a driver to send each frame of colors to your LEDs, using our built-in drivers library.

To best support embedded devices, this is possible without the Rust standard library (no-std) and without any memory allocations to the heap (no-alloc).

Define your LED layout§

A layout defines the physical or logical positions of the LEDs in your setup, as arrangements in 1D, 2D, and 3D space.

To define a layout, we must define a struct that implement either the Layout1d, Layout2d, or soon Layout3d traits. To make this easy, we use either the layout1d, layout2d, or soon layout3d macro, respectively. These traits provide a PIXEL_COUNT constant, which is the number of LEDs, and a .points() method, which maps each LED pixel into a 1D, 2D, or 3D space between -1.0 and 1.0.

(For any Rust beginners: A struct is a definition of a type of object, like a class in other languages. A trait is a definition of an abstract behavior that an object might implement, like an interface in other languages. A macro is code that generates code, like a function that you call during compilation to return code, rather than call during runtime to return a value.)

1D layouts§

For a 1D layout, this is very simple, as a 1D shape only has a length.

Here is a layout for an LED strip with 60 pixels.

1

layout1d!(Layout, 60);

For our 1D space, the first LED pixel will be at -1.0 and the last LED pixel will be at 1.0.

2D layouts§

For a 2D layout, you need to define your 2D shapes: points, lines, grids, arcs, etc.

For our 2D space, we can think of:

• (-1.0, -1.0) as the bottom left
• (1.0, -1.0) as the bottom right
• (-1.0, 1.0) as the top left
• (1.0, 1.0) as the top right

Here is a layout for a basic 16x16 LED grid panel to span our 2D space:

1
2
3
4
5
6
7
8
9
10
11

layout2d!(
    Layout,
    [Shape2d::Grid {
        start: Vec2::new(-1., -1.),
        horizontal_end: Vec2::new(1., -1.),
        vertical_end: Vec2::new(-1., 1.),
        horizontal_pixel_count: 16,
        vertical_pixel_count: 16,
        serpentine: true,
    }]
);

Create your visual pattern§

A pattern, most similar to a WLED effect, generates colors for LEDs based on time and position.

We define this as a struct that implements the Pattern trait.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

/// # Type Parameters
///
/// * `Dim` - The dimension marker (Dim1d or Dim2d)
/// * `Layout` - The specific layout type
pub trait Pattern<Dim, Layout>
where
    Layout: LayoutForDim<Dim>,
{
    /// The configuration parameters type for this pattern.
    type Params;

    /// The color type produced by this pattern.
    type Color;

    /// Creates a new pattern instance with the specified parameters.
    fn new(params: Self::Params) -> Self;

    /// Generates colors for all LEDs in the layout at the given time.
    ///
    /// # Arguments
    ///
    /// * `time_in_ms` - The current time in milliseconds
    ///
    /// # Returns
    ///
    /// An iterator yielding one color per LED in the layout
    fn tick(&self, time_in_ms: u64) -> impl Iterator<Item = Self::Color>;
}

While there is one Pattern trait, it may be implemented for any dimension, using a dimension marker: Dim1d, Dim2d, or soon Dim3d. The dimension marker will then constrain the Layout generic provided, to implement either Layout1d, Layout2d, or soon Layout3d, respectively.

On initialization, the pattern is given configuration parameters. On every update, the pattern is given the current time in milliseconds, and must return an iterator that provides a color for every LED in the layout.

The color types in Blinksy are inspired by the palette crate, where they implement FromColor and IntoColor. Like FastLED we have Hsv (which uses FastLED’s rainbow hues), or for a more modern color space we have Okhsv.

To use a pattern, we can either choose from the built-in library or create our own.

We have two visual patterns to start, each implementing Pattern for 1D, 2D, and soon 3D.

• Rainbow: A basic scrolling rainbow.
• Noise: A flow through random noise functions.

Or feel free to make your own. Better yet, help contribute to our library!

Setup your LED driver§

Now for the final step.

The driver is what tells the LED hardware how to be the colors you want.

To define a driver, we must implement the Driver trait:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

pub trait Driver {
    /// The error type that may be returned by the driver.
    type Error;

    /// The color type accepted by the driver.
    type Color;

    /// Writes a sequence of colors to the LED hardware.
    ///
    /// # Arguments
    ///
    /// * `pixels` - Iterator over colors
    /// * `brightness` - Global brightness scaling factor (0.0 to 1.0)
    /// * `correction` - Color correction factors
    ///
    /// # Returns
    ///
    /// Result indicating success or an error
    fn write<I, C>(
        &mut self,
        pixels: I,
        brightness: f32,
        correction: ColorCorrection,
    ) -> Result<(), Self::Error>
    where
        I: IntoIterator<Item = C>,
        Self::Color: FromColor<C>;
}

The driver says what type of error it might return and what type of color it wants to receive.

When you write to a driver, you provide an iterator of colors (in your own color type), plus a global brightness and color correction.

What colors do an LED understand?§

The LED driver will be given colors from the visual pattern, then convert them into a new color type more suitable to what the LED hardware understands.

LEDs are generally 3 smaller LEDs, red + green + blue, each controlled via pulse-width modulation (PWM). If you tell an LED to be 100% bright, it will be on for 100% of the time (a 100% duty cycle). If you tell an LED to be 50% bright, it will be on for 50% of the time (a 50% duty cycle). And so on. Our eyes don’t notice the flicker on and off.

Therefore, we use LinearSrgb when thinking about LEDs, since linear color values correspond to the luminous intensity of light, i.e. how many photons should be emitted. However, what we actually perceive in a linear change in photons is not linear. For our evolutionary survival, we are much more sensitive to changes in dim light than we are to changes in bright light. If you double the amount of photons, we don’t see double the brightness.

This mismatch between physics and perception is why the “RGB” you think you know is actually gamma-encoded sRGB. sRGB allows us to think in terms of perception, where double the red value means double the perceived brightness of red. Then for LEDs, we convert the gamma-encoded sRGB to linear, to use as a gamma-corrected duty cycle.

By the way, if you start mixing RGB’s, make sure to do so in the linear space.

So anyways, why red, green, and blue? These correspond to the 3 light receptors in our eyes. What we perceive as color is some combination of these receptors being trigged. Our brain doesn’t know the difference between seeing the yellow wavelength as seeing a combination of the green and red wavelengths at the same time. We don’t see color as we might think. There’s no such wavelength for purple (not to be confused with violet), yet our brain makes up a color that we see.

There’s more. We say RGB, but what red, what green, what blue? To solve this, the sRGB color space defines an exact red, an exact green, an exact blue. But is the color in our color system the same as the color being output by our LEDs?

I could go on about colors, there’s more to say, more future work to be done in Blinksy, but that’s enough for now.

What protocols do an LED understand?§

To make implementing Driver easier for the various LED chipsets, we have generic support for the two main types of LED protocols:

Clocked LEDs (SPI)§

A clocked protocol is based on SPI, where chipsets have a data line and a clock line.

For every bit we want to send from the controller to the LEDs:

• First the controller sets the data line (MOSI) to HIGH for a 1 or LOW for a 0.
• Then the controller “ticks” the clock line (SCLK), by going from LOW to HIGH.
• On the rising edge of the clock line, the LED will read the data line.
• Halfway through the clock cycle, the controller will reset the clock line to LOW.

To define a clocked LED chipset, you define the ClockedLed trait.

Clockless LEDs§

A clockless protocol is based on specific timing periods, where chipsets have only a single data line.

Without a clock, the protocol depends on specific timings to represent each bit.

For example with WS2812B LEDs, to represent a 0 bit the data line must be HIGH for 0.4 microseconds, then LOW for 0.85 microseconds. These timings must be accurate to within 150 nanoseconds. That’s tiny!

With these timings in mind, we can send some bits without a clock.

To define a clockless LED chipset, you define the ClocklessLed trait.

Protocol drivers§

For each generic LED protocol type, we have specific protocol drivers for those types of LEDs:

• By bit-banging over GPIO pins, using a delay timer.
• Or by using an SPI peripheral.

For clockless protocols on ESP devices, we can also use the RMT peripheral.

(Note: I have yet to drive clockless LEDs using an SPI peripheral. For now I’m happy with my ESP32’s RMT peripheral. If you want this, maybe you can help?)

What LEDs can we talk to?§

At the moment, Blinksy supports:

• APA102 LEDs, aka DotStar
  • Apa102Delay
  • Apa102Spi
• WS2812 LEDs, aka NeoPixel
  • Ws2812Delay
  • Ws2812Rmt

With the above protocol abstractions, adding a new LED chipset is as easy as implementing ClockedLed or ClocklessLed.

By the way, props to smart-leds for paving the way on addressable LED drivers in Rust.

Get started§

Put everything together§

Okay, now that we’ve learned about layout, a pattern, and driver – let’s put them together.

We use a ControlBuilder to build a Control.

For 1D:

1
2
3
4
5

let mut control = ControlBuilder::new_1d()
    .with_layout::< /* layout type */ >()
    .with_pattern::< /* pattern type */ >(/* pattern params */)
    .with_driver(/* driver */)
    .build();

For 2D:

1
2
3
4
5

let mut control = ControlBuilder::new_2d()
    .with_layout::< /* layout type */ >()
    .with_pattern::< /* pattern type */ >(/* pattern params */)
    .with_driver(/* driver */)
    .build();

ControlBuilder means we don’t have to think about all generic types involved in a Control, we can add each part one at a time.

From here we can set a global brightness or color correction.

Then we run our main loop, calling .tick() with the current time in milliseconds.

1
2
3

loop {
    control.tick(/* current time in milliseconds */).unwrap();
}

Get running on a microcontroller§

While you can plug LEDs directly into microcontroller pins, I do recommend using an LED controller that does things properly.

I found a decent LED controller available on AliExpress: Gledopto GL-C-016WL-D.

For this, I made a board support crate: gledopto.

The board support crate provides a few macros to make your life easy, such as a board! macro to setup your board, or a ws2812! macro that sets up a WS2812 driver using the specific pins for that controller.

To make even easier, I made a quickstart project template: blinksy-quickstart-gledopto

Add some LEDs§

Now you just need to add LEDs, and away you go.

If you need an LED supplier recommendation, I’ve only had success with “BTF-Lighting”. You can find them on AliExpress, Amazon, or on their own website.

If you need more help, look at QuinLED’s helpful guides.

(Note: I will later add support for QuinLED boards, since they are the best and want to support them. Unfortunately, shipping to New Zealand was too expensive, so I will receive once a friend travels over the Pacific.)

Hello LEDs§

Now, here is our hello world of LEDs:

A strip of WS2812 LEDs with a scrolling rainbow.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#![no_std]
#![no_main]

use blinksy::{
    layout::Layout1d,
    layout1d,
    patterns::rainbow::{Rainbow, RainbowParams},
    ControlBuilder,
};
use gledopto::{board, elapsed, main, ws2812};

#[main]
fn main() -> ! {
    let p = board!();

    layout1d!(Layout, 60 * 5);

    let mut control = ControlBuilder::new_1d()
        .with_layout::<Layout>()
        .with_pattern::<Rainbow>(RainbowParams {
            ..Default::default()
        })
        .with_driver(ws2812!(p, Layout::PIXEL_COUNT))
        .build();

    control.set_brightness(0.2);

    loop {
        let elapsed_in_ms = elapsed().as_millis();
        control.tick(elapsed_in_ms).unwrap();
    }
}

Or, to show some more:

A grid of APA102 LEDs with a noise function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

#![no_std]
#![no_main]

use blinksy::{
    layout::{Shape2d, Vec2},
    layout2d,
    patterns::noise::{noise_fns, Noise2d, NoiseParams},
    ControlBuilder,
};
use gledopto::{apa102, board, elapsed, main};

#[main]
fn main() -> ! {
    let p = board!();

    layout2d!(
        Layout,
        [Shape2d::Grid {
            start: Vec2::new(-1., -1.),
            horizontal_end: Vec2::new(1., -1.),
            vertical_end: Vec2::new(-1., 1.),
            horizontal_pixel_count: 16,
            vertical_pixel_count: 16,
            serpentine: true,
        }]
    );
    let mut control = ControlBuilder::new_2d()
        .with_layout::<Layout>()
        .with_pattern::<Noise2d<noise_fns::Perlin>>(NoiseParams {
            ..Default::default()
        })
        .with_driver(apa102!(p))
        .build();

    control.set_brightness(0.1);

    loop {
        let elapsed_in_ms = elapsed().as_millis();
        control.tick(elapsed_in_ms).unwrap();
    }
}

Simulate on your desktop§

Okay, but let’s say you just want to start now, without a microcontroller, without any LEDs.

Blinksy also has a way to simulate on your desktop: blinksy-desktop.

This provides a driver (using miniquad) and an elapsed time function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

use blinksy::{
    layout::{Shape2d, Vec2},
    layout2d,
    patterns::noise::{noise_fns, Noise2d, NoiseParams},
    ControlBuilder,
};
use blinksy_desktop::{
    driver::{Desktop, DesktopError},
    time::elapsed_in_ms,
};
use std::{thread::sleep, time::Duration};

fn main() {
    layout2d!(
        Layout,
        [Shape2d::Grid {
            start: Vec2::new(-1., -1.),
            horizontal_end: Vec2::new(1., -1.),
            vertical_end: Vec2::new(-1., 1.),
            horizontal_pixel_count: 16,
            vertical_pixel_count: 16,
            serpentine: true,
        }]
    );
    let mut control = ControlBuilder::new_2d()
        .with_layout::<Layout>()
        .with_pattern::<Noise2d<noise_fns::Perlin>>(NoiseParams {
            ..Default::default()
        })
        .with_driver(Desktop::new_2d::<Layout>())
        .build();

    loop {
        if let Err(DesktopError::WindowClosed) = control.tick(elapsed_in_ms()) {
            break;
        }

        sleep(Duration::from_millis(16));
    }
}

Quickstart a project§

So wanna jump in now and start your own project?

I made a quickstart project template: blinksy-quickstart-gledopto

You can even simulate on the desktop while your controller and LEDs arrive.

Thanks§

If you want to help, the best thing to do is use Blinksy for your own LED project, and share about your adventures.

If you want to say something about this post, discuss this on GitHub.

If you want to contribute code, please:

• Help port a visual pattern from FastLED or WLED to Blinksy
• Write your own visual pattern
• Help support a new LED chipset
• Help support a new LED controller

If you want to otherwise support the project, please:

• Star the project on GitHub: ahdinosaur/blinksy
• Sponsor me on GitHub: @ahdinosaur
• Subscribe to me on YouTube, to encourage me to live-code Blinksy: @Make_with_Mikey

Thanks for sharing your attention with me. Have a good one. 💜

I want to share some inspiring science fiction that paints a picture of a future to believe in. A future with realistic challenges and realistic solutions. Fiction to help ground solarpunk into a vision of action.

Cory Doctorow, in “Science fiction and the unforeseeable future: In the 2020s, let’s imagine better things”, says:

The stories we tell about our future affect what we do when the future arrives, so science-fictional tales of weathering the crisis have the makings of a movement that allows us to do so.

In this editorial, he goes on to imagine the foundations for a possible future, one where a “Canadian Miracle” occurs:

As the vast majority of Canadians come to realize the scale of the [climate] crisis, they are finally successful in their demand that their government address it unilaterally, without waiting for other countries to agree.

…

Canada goes on a war footing: Full employment is guaranteed to anyone who will work on the energy transition – building wind, tide and solar facilities; power storage systems; electrified transit systems; high-speed rail; and retrofits to existing housing stock for an order-of-magnitude increase in energy and thermal efficiency. All of these are entirely precedented – retrofitting the housing stock is not so different from the job we undertook to purge our homes of lead paint and asbestos, and the cause every bit as urgent.

How will we pay for it? The same way we paid for the Second World War: spending the money into existence (much easier now that we can do so with a keyboard rather than a printing press), then running a massive campaign to sequester all that money in war bonds so it doesn’t cause inflation.

The justification for taking such extreme measures is obvious: a 1000 Year Reich is a horror too ghastly to countenance, but rendering our planet incapable of sustaining human life is even worse.

This premise then became a short-story, “The Canadian Miracle”, published in 2023, which you can read in full.

This continues as a book, “The Lost Cause”, also published in 2023, about near-future Burbank, California.

I highly recommend reading this editorial, short-story, and book in full. They are without a doubt my favorite contemporary author’s take on science fiction.

I want to share excerpts from this future that are specific to the Village Kit vision: a modular system for building the practical infrastructure we need to live, amidst a climate crisis.

In this future, Blue Helmet peacekeeping operations have become climate crisis responders. When cities flood, sea levels rise, forests burn, and so on, the Blue Helmets are those who respond to support new waves of climate refugees. Except, rather than the temporary refugee camps of today, they developed systems to build new permanent refugee cities.

I want to share these Blue Helmet modular systems, as an inspiring view into a practical future.

“The Lost Cause”§

The world of “The Lost Cause” is set in the 2050’s. The main character, Brooks Palazzo, is in the same generation as those who are born today.

Page 146-149:§

Let’s start with quotes from page 146 to 149.

Brooks pulls a job from the Jobs Guarantee: a federally funded, locally administered government program that provides good jobs at inclusive wages that serve community needs proposed by community groups and approved by local governments.

Here we see what a future construction process might look like, accessible even to those who aren’t professionally trained.

Preparing the lot for the new low-rise took three days: working under a master surveyor, we staked it out, got it leveled, and installed the foundation slab.

…

The original dwelling was a two bed / one bath on a one-acre lot. The new low-rise would be three stories tall, with six two-bedroom apartments and one four-bedroom apartment on the top story, and no garage.

…

The real excitement started when the panels rolled up. They came from a factory in Mojave, the same one that was providing the materials for the relocation of San Juan Capistrano. The sinterers only fused the concrete and polystyrene balls when the grid was saturated, scavenging solar energy that would otherwise go to waste.

…

I know it’s weird to nerd out about blocks, but I was a total block nerd and I knew that the Mojave plant had its own on-site research team that was always tweaking the formula, making them lighter and stronger and more resilient to temperature extremes and quake stresses. I was addicted to their
videos of test buildings being subjected to the most awesome tests, watching wrecking balls bounce off them and shake platforms making them shimmy without cracking.

…

I scanned the QR code on the tie-down with my screen to look at the manifest again. The panels—8′ × 4′ concrete sheets—weighed less than fifty kilos each.

…

A couple of the work-crew-mates had spent a Blue Helmet year in San Juan Capistrano and knew the panel construction technique backward and forward. Our foremen were a couple of the refus from the
caravan who’d been general contractors back in the San Joaquin Valley. The rest of us had watched the training videos and done the online certification and in theory we knew what we were doing—the panel system was designed to be dead-stupid simple in any event.

…

Naturally, there was a lot of last-minute delay between the time we thought we’d start standing up panels and the first panel going in: triple-checking everything was level, comparing the panels with the plans to make sure the ones with built-in conduit for plumbing, HVAC, and power services were lined up in the right spot, and so on. But finally, around eight thirty, we were ready to go.

…

The first panel went in like butter, slotting perfectly into the groove and pin system in the foundation slab. It was now structurally sound, and as the tightening crew gave each of its lock bolts a half turn, it became rigidly fixed in place. This was the keystone, and we cheered as it went up but then quickly broke into the subteams that the apps sorted us into, each with its own piece in the logical path. With twenty-five people, we could finish the main work on the first floor by sunset, and while the upper stories would take longer, that would let interior crews work on the first floor, adding fixatives to the panel intersections, connecting and testing the plumbing,gas, HVAC, and power. Give us ten days, we’d be ready for paint and furniture. It was going to be so amazing, like a magic trick.

And then…

Something unexpectedly bad happens, outside the scope of the modular system. I invite you to read the book to follow the actual storyline. 😀

Page 207-210§

Next up, Brooks imagines if his grandfather’s house was given away to the city for infill: a process of using land for high-density development.

Here we see what a future housing design process, turned city planning, might look like.

The brainstorming session made me think they were just dreamers, but Phuong and her housemates were all ex–Blue Helmets. They were used to getting up in the morning, meeting with a community group about the destiny of some brownfield site, and building a new residence there in three days flat.

Don and Arina got onto some next-generation modular slab designs and then Arina realized she’d been in the field with the woman who’d led the project to create them, so they bridged her in.

Miguel had a contact in Simi Valley who coordinated GND Housing Guarantee builds for the whole region, and he took all of ten minutes to find us a flock of cranes, bulldozers, forklifts, and other heavy machines.

Meanwhile, Phuong was crawling these databases of parameterized build plans, dragging buildings of various sizes onto Gramps’s lot to check out the shadows, seismics, and whether they needed more water infrastructure than the city could provide from the nearby mains and sewer.

I had said “high-rise” but honestly, I’d never really thought about anything more than five or six stories. The tallest building in the neighborhood was only three stories tall. Plus, even with all my GND trufan energy, I couldn’t imagine a ragtag group of guerrilla builders erecting an honest-to-goodness skyscraper. Phuong had other ideas, and she clicked and dragged a bunch of legit high-rises onto her rendering of the lot before settling on a building that could be scaled up as high as thirty floors, though she’d settled for twenty, earmarking both the top and bottom floors for community spaces.

“How’re you going to sink the pilings?” Don asked, looking over at her screen. She tapped and showed him a picture of a machine with an auger bit on it that was insane, like something you’d use to drill to the center of the Earth.

Don laughed. I laughed too. It was absurd.

“That’s two, three days of drilling,” Miguel said. He tapped at Phuong’s screen to bring up a time-critical path chart. He dragged the top story of the building down to eight floors and we watched as the time ticked down.

“Ninth story is always the killer,” he said.

Phuong stuck her lower lip out. “I want a skyscraper!”

“I know baby, I know,” Don said, distractedly, tweaking the floor plans to create more flexible configurations, either a three-bedroom and a bachelor on each floor, or two two-bedrooms. I mirrored his work on my screen and started tapping around, finding a mode that let me tap into the city street plan and start dragging that around, and before long, I was transforming the whole Verdugo corridor into high-rises with a light-rail line down the middle of it, anchored to a subway station where the old strip mall was currently languishing, part-occupied, mostly used as a skate park and a weekend craft market.

I zoomed out and saw that my own crude high-density corridor was being polished by Phuong’s housemates, who abandoned their work on the hypothetical high-rise we were going to build on Gramps’s lot in order to create green roofs, vertical farms, parkettes, a community center added to the main branch library at Buena Vista. I watched with my mouth open as they worked together, like musicians improvising a jam session, except they were improvising a whole neighborhood, and I could tab over to the spreadsheets where there were build plans, bills of materials, critical path and building-code variances we’d have to file for.

Jacob shoulder-surfed me. “It’s cool, isn’t it? It’s just Blue Helmet stuff, though; kind of thing we used to do in-country, helping people think through what their neighborhoods could be. We’d do a couple training sessions, turn ’em loose for a week to come up with designs, get into revert-wars, and then we workshop ’em and do it again. A month later, you’ve got some incredible designs, and all that stuff gets trained back into the model so it hints the next group who try it. That’s why it’s going so fast—it’s hella trained.”

“Don’t say ‘hella,’” Arina said. “It makes you sound stupid.”

“I am stupid,” he said, and crossed his eyes and stuck out his tongue.

Then Arina took away his screen and wiped out and reshaped a granny flat he’d been sticking on top of a garage off California, tapping the seismic rating box when she was done.

“There, not a death trap anymore.”

I grabbed a screen and dug in, snuggling up to Phuong, who’d sometimes look over at my screen and show me a faster or more elegant way to do what I was trying to do, and the neighborhood took on a polish and veneer that made it seem like a real architect’s rendering. I was flying around when I realized I was looking at the building we’d started with. Gramps’s house. My house.

It was beautiful, eight stories tall, roofed over with photovoltaics and a couple of eggbeaters, a courtyard with vegetable beds and ornamentals. The apartments were neat, thoughtful, weatherized for cross breezes, with charming, self-adjusting shades that kept them cool.

I flew through it, one apartment after another, the utility spaces and infrastructure, and … Phuong … guided … as we flew through the house, through the neighborhood, through the city, flying off the edge of the map into the undefined places of Cartesian grid lines.

Page 243-247§

At this point in the story, the characters take the city plan that was started in the above scene, and present it to the city as a pop-up festival.

Here again, we see the possibility of future city planning, how we could re-imagine civic engagement and community consultation. We also see the importance of future social media moderation strategies.

We hustled. By the time the first cops showed up we were curtain-raiser ready, with all our booths up and the big screens shook out and powered up, showing displays of the new Burbank, first cooked up in Phuong’s living room and then wikified and edited by a couple thousand Burbankers, mostly affinity group members and their friends, whose designs got polished up by infill urbanists all around the world.

…

Every booth displayed a different aspect of the New Burbank. One group had done transit, another had done libraries, another had done schools. The big action was in the neighborhoods, displayed as big-screen flythroughs that you could view or modify, either from your own screen or by just dragging stuff around on the big screens. The kids did a lot of the latter, while their grown-ups were more interested in the former. I eavesdropped on a lot of conversations, hopping from booth to booth, and I started to see a pattern:

Rando: “Come on, you’ve gotta be kidding me. This is crazy, it’s not what the city is about.”
Guerrilla planner: “Did you see this park?” (or stadium, or rink, or subway station, or library, or business strip)

Rando: “Sure, sure, but come on. Be serious.”
Guerrilla planner: “Did you see the lake? The lake’s super cool, it’s part of the runoff system. All the road grades run toward it; if there’s a flood it’ll absorb all the water and then most of that will end up back in the water table.”

Rando: “Yeah, that’s cool, but come on. Be serious.”
Guerrilla planner: “Did you see the solar capacity? Total energy independence, and we’ve got this concrete factory over here, it’ll just sinter prefab any time there’s more power in the grid than we can use. Then any time someone goes on the job guarantee, one of the gigs’ll be building one of these buildings, using that prefab. It’s carbon-neutral mass-scale construction—”

Rando: “That is cool. How the hell does that work?”
And then they were off. The excitement was infectious

… The people who couldn’t get to Burbank, especially other Californians who’d been in a fury about the injunctions and the bombings and the seizures, started building out our map, overlaying huge swaths of LA and the San Fernando Valley with their own dreams.

Even better: the Magas fucking hated it. This was culture-war clickbait times a billion, and it seemed like half the world’s reactionaries, trolls, bots, and assholes were determined to vandalize our virtual space (we had good anti-vandal, plus a swift revert-squad that the little kids on Magnolia joined in droves, cackling as their tiny hands smacked the screens to undo the damage faster than the irrelevant hunt-and-peck typists of the fallen past could wreak it).

Page 272§

At this point in the story, Brooks wants to follow through on his plan to tear down his grandfather’s house and building high-density housing in its place. To hell or high water.

“You want to blow up City Hall?”
“No,” I said. “I want to blow up this house.”

Not literally, of course. But knocking down a house and building an eightplex is a solved problem, as they say on the DSA socials. It takes a lot of heavy equipment and prefab slabs and a lot of people, especially if you’re in a hurry. But with every project in limbo, we had all the materials and equipment we needed standing by and most of it was in depots that were managed by friends and friends-of-friends, and there were also lots of friends and friends-of-friends standing by with nothing to do and a lot of pent-up nervous energy.

Page 275§

Here we see the participatory aspect of this future building system, anyone can contribute with the skills they have available.

We’d told Dolores and company what we were thinking of over lunch and asked them what they thought. We made sure they understood that they had a veto over this, because we weren’t about to turn them out into the smoke while we did our weird-ass shit. They were completely cool about it, though, excited once we’d conveyed what we had in mind and wanting to help out. They found friends who talked their host families into letting them double up, and pored over the floor plans for the new building, talking about how they’d furnish their places. Antonio was a finish carpenter and pulled up pictures of some of the kitchen remodels he’d done and we all noodled around with superimposing them on the renders of the interiors.

Phuong, meanwhile, had been exchanging disappearing/deniable messages with friends around the DSA, which led her to Tony Yiannopoulos, who found us a mole inside the Department of Public Works —a former shop steward who got promoted to management but never switched sides. After a couple of texts, she jumped on video and did this mind-meld thing with Phuong, ingesting her project manifest and locating available equipment at DPW lots all around the city. There was a lot of idle gear in town, thanks to the double whammy of the fires and the moratorium on emergency house construction—the city had requisitioned a lot of extra equipment from the county when the caravan first started heading our way.

Page 277§

When building an eightplex is simply a bill of materials.

I rattled the gate and shouted, “Who brought the bolt cutters?”

A figure loomed out of the smoke on the other side of the gate, bulky and shambling in a grayish, worn hazmat suit. “Don’t you cut my goddamned gate, child, or I’ll make you whittle a replacement.” The voice, muffled by the mask, was gravely and gruff, but affectionate. “You Brooks?”

“That’s me,” I said.

“You know how to drive a forklift?”

I shrugged. “Just a little I picked up on jobsites.”

“Uh-huh. How about a crane? Backhoe? Excavator? Boring machine?”

“Nope,” I said. “But they do.” I jerked my thumb over my shoulder at the gang we’d organized over the DSA socials. There were fifteen of us, and with current certifications for all those and more.

“How about a tractor cab?”

“Uh,” I said.

He snorted. “Trick question, boy. Thing drives itself. It’s got fifteen hundred prefab slabs on it and all the electric and plumbing fittings on your bill of materials.”

“Bruce,” I said, “this is just amazing.”

Page 282§

When everything fits into interlocking components.

Blue Helmet prefab buildings are fast, but word gets around faster.

We were able to recycle the foundation slab, which meant that once the pilings were in, one crew could go to work fitting and locking panels while a second crew added structural members for the next stage. Wilmar was in charge of double-checking the building against the plans, making sure that panels with inset plumbing and electrical components were seated correctly and had good interconnects with their adjacent panels.

Page 286-287§

When these interlocking components can self-validate their correctness.

Over the course of that day, progress had been amazing, then agonizing, then amazing again. The first two rows of slabs clicked into place quickly, accelerating as the work crews got into the rhythm of the job. There’d been a moment when I stepped back from sealing a slab into place and looked around and realized that there was a brand-new structure there, just like that, a magic trick in three dimensions.

Then there’d been a long period of agonizing slowness as all the services were checked and rechecked—electrics, plumbing, data. It all had interconnect and integrity sensors built in, but we had to activate them and get them initialized and chained before they could start working. Time crawled as we troubleshot persnickety problems, sometimes using Blue Helmet socials to conference in experts who could suggest fixes to thorny problems.

Then everything lit green and crews went to work snapping on the joists and locking them in, laying down the floor slabs, and putting in scaffolding for the second story and we were off to the races again, half of the next story racing around the building’s edge even as a crew added exterior and interior doors and other fittings to the first floor. We even got the plumbing working, and the jobsite got a sink and a toilet. With the door closed, the windows fitted, and the first-floor ceiling in place, we got filters running and then we had an indoor space with breathable air, just like that.

Page 293§

Imagine building the frame of a house in 48 hours.

“How did you keep this all under wraps while you built it?”

“We didn’t,” I said. “I mean, we did, a little, but it only took forty-eight hours.”

“Forty-eight hours for what?”

“For you to show up.”

I watched that land on her. “Wait … You built this over the last two days?”

“Well, the first day was mostly demolition and hauling. Most of this is day two. Phuong tells me it’ll take forever to finish the interiors, but like she said, we figure we can do all the structural work including the roof by tonight.”

Olivia opened her mouth. Closed it. Repeated the procedure. “Bullshit.”

Phuong laughed. “Girl, it’s only because you went into planning instead of going overseas with a Blue Helmet brigade. This is how we do it, when we’re working fast after a flood or a famine—the time it used to take to put up a bunch of tents and build some shithole refugee camp, now we can build a whole fucking city. We could do it here, if we had the same rules of engagement as we do in the field.”

Page 320§

In this future, building infrastructure become collaboration amongst peers, and the tooling made reflects that.

There’s a Blue Helmet truism that the last 10 percent of any project takes 90 percent of the time, and that was certainly my experience with the building that had once been Gramps’s house. The early stages had involved standard parts—slabs, infrastructure, glazing, insulation—but now that we were doing fine work, things had to be just right—exactly right modular kitchen cabinets, the right sliding doors for balconies and locks for internal doors. More than half of the work was just hitting the screens, wrangling with other crews nearby to see who had the part you needed and then figuring out how to make rendezvous and acquire it.

But over the next four days, things took shape, and a couple of the apartments got real furniture, a mix of prefabs and donated pieces, and it was wild to see the rough structure I’d left a week before with my lungs on fire and my arms so heavy I could barely lift them now looking ready for human habitation. And habitate it we did, as parts of our crew left to work on other buildings that needed more work, until there were fewer than a dozen of us on-site at any moment, many of us couples like Phuong and me, so that we ended up with our own temporary, personal apartments (though people on the third and fourth floors had to borrow facilities from their downstairs neighbors because the city hadn’t been able to upgrade our main
water service yet).

Reflections§

I want to live in this world.

If you haven’t yet read “The Lost Cause”, get yourself a copy and live in this world for a time.

There’s much more in the book than I can reasonably capture on this page, see for yourself and let me know what you see.

I want to make this future world a reality, that’s why I’m working on Village Kit. Join us?

What do you think? Discuss this further on the Village Kit forum

I made a collection of videos to showcase the magic alchemy of computation. ✨

What is computing if you take away all hardware in front of your eyes? 🌱

What does computing mean to humanity? 🌻

• PeerTube: @intertwingled@tube.arthack.nz
• GitHub: ahdinosaur/intertwingled

Not sure where to start?

• (2013) The Future of Programming : Bret Victor
• (1997) The Computer Revolution Hasn’t Happened Yet : Alan Kay

For some reason, I don’t like playing tabletop games where there’s a pre-defined set of technical rules. I feel like I end up being a computer. I enjoy playing with computers, I don’t enjoy playing as a computer simulator.

So one day, nearly a decade ago, some friends stumbled upon game we called the “Made Up Game”, and I discovered my favorite genre of game: games where you play with changing the rules of the game.

So here’s the Made Up Game: a creative card game where you make up the rules.

How to start playing the Made Up Game 🏓§

While the game is all about changing the rules, we need a set of bootstrap rules to get the game started:

Setup§

1. Shuffle a deck of cards
2. Deal 5 cards to each player
3. Place the remaining pile of cards face-down
4. Turn the top card up and place it next to the face-down pile

Step§

In clockwise direction, for each player:

1. Pick up card from the face-down pile
2. Play a card onto the face-up pile
3. Makes a change to the rules

Lose Condition§

If the next player can’t play the game within the current rules, everyone loses.

Win condition§

If all the cards are face-up on the table.

Source: ahdinosaur/made-up-game

Your first problem to solve as a team 👥§

Something you may notice is that the bootstrap rules start with a bug:

• At the beginning of every turn, the player must pickup a card from the face-down pile.
• And the lose condition is if the next player can’t play within the current rules.
• So once the face-down pile runs out, the next player can’t play, and you lose.

So if you want to survive, you must change the rules to accommodate for this.

How? Well that’s up to you!

Observations on playing the Made Up Game 🔍§

Having played the Made Up Game a few times, every game is unique, no game is ever the same.

Here are some example styles of rules I’ve seen:

(More examples)

Card games ♠️§

Since we’re using a deck of cards, why not bring in typical card game rules?

For example:

If a player plays a card of the same suit as the previous card played, then the next player must draw 2 more cards on their turn.

Story games 👑§

What if we used the cards to tell stories?

For example:

After you play a card, you tell a story about your card. Face cards are individuals and number cards are groups.

Stack games 🥪§

What if we made something from these face-up and face-down piles of cards?

For example:

• Each player can play a card anywhere to create a new face-up pile.
• Each player can draw a card from any available face-down pile.

Combat games ⚔§

Feeling too collaborative? Why not add in a combat system to the game?

Each player has 10 “health points”.

What is a “health point”? How do we lose “health points”? What happens if we run out of “health points”?

I don’t know, I don’t make the rules, that’s for you to decide in future rules.

Cursed games 👻§

Feeling too normal? Why not bring in the occult?

If you play an odd card, that pile becomes “cursed”.

What does “cursed” even mean? Shrug, that’s for you to decide as you play with more rules.

Anything is possible in the Made Up Game ✨§

There’s no limit to what rule changes are allowed, so really any game using cards as props is possible.

Think: strategy, role-playing, adventure, solitaire, shedding, trick-taking, matching, deck-building, and more.

How might you introduce a rule from another game into the Made Up Game?

More rule-changing games 📚§

Nomic ⚖️§

Since the Made Up Game, some internet friends introduced me to “Nomic”, a rule changing game created in 1982.

Nomic is a game in which changing the rules is a move. In that respect it differs from almost every other game. The primary activity of Nomic is proposing changes in the rules, debating the wisdom of changing them in that way, voting on the changes, deciding what can and cannot be done afterwards, and doing it. Even this core of the game, of course, can be changed.

• Peter Suber, The Paradox of Self-Amendment

We tried playing a game of Nomic together online, but we didn’t get too far. This was only my limited experience, but the rules felt more serious and bureaucratic. I don’t get joy from being a rule lawyer, I like to be more silly and loose with my rule playing.

I’m happy Nomic exists and maybe I should try again with a different starter culture.

If I play again, I want some fun lunacy with my rules, for example:

• Introduce celestial bodies as a foundation for “magic”, starting with the moon.
• Moonlight somehow determines how much “magical power” that players have access to.
• Create an arbitrary and artificial tension between players where some players have more “magical power” when the moon is brighter and some players have more “magical power” when the moon is darker.
• Create a cooperative challenge where every cycle of the moon causes the moon to be closer, slowly increasing the environment of “magical power” to dangerous levels.

🌕 🌖 🌗 🌘 🌑 🌒 🌓 🌔

The Counting Game 🔢§

After playing the Made Up Game for some time, I later made a more casual rule-changing game based on a drinking game, which I call the “Counting Game”.

TODO: Link to a post about the Counting Game.

Good luck! 🙏§

Thanks for reading!

If you do play the Made Up Game: good luck and have fun!

Please contribute anything you learn to ahdinosaur/made-up-game.

Disclaimer ⚠️§

As a quick disclaimer: This post is not a basic introduction to embedded Rust. For a basic introduction to embedded Rust, see the embedded Rust Bookshelf for resources.

This post is instead about solving a niche problem: how to create a re-usable library where users (developers) can setup their own hardware devices (LEDs, linear axes, spindles, relays, etc) and then use a command language (like G-Code) to control those devices, all in an Rust-y embedded-y device-agnostic type-safe heap-free way.

The embedded Rust world 🗺️§

Before we begin, here’s a quick recap of the embedded Rust world:

• Rust can compile to any target supported by LLVM, so most everything.
• You can tell Rust to be in “#[no_std]” mode and your code will not load the standard library (std) or data structures that depend on heap allocations (alloc).
  • To use data structures that depend on heap allocations (alloc), you can then BYO (bring your own) allocator, such as embedded-alloc.
• Each processor architecture usually has a Rust crate (module) for low-level access to the processor
  • For example: cortex-m for ARM processors, riscv for RISC-V processors, etc.
  • Note: most embedded chips use an ARM processor
• Each chip family has a “Peripheral Access Crate” for low level control of peripherals
  • Hardware manufacturers provide an SVD file (System View Description), which define how the hardware’s (magic) memory addresses are mapped to peripheral registers, svd2rust converts these to a type-safe Rust interface, so you can only use the registers in a safe way.
  • For example, the stm32-rs for STM32 microcontrollers, nrf-pacs for nRF microcontrollers
• Each chip family then also has a “Hardware Abstraction Layer” crate for higher level control of peripherals
  • To provide a foundation for building device-agnostic hardware drivers, embedded-hal provides Traits (abstract interfaces) for (most) hardware abstractions.
  • Each each device has their own xxx-hal which provides the specific hardware implementations for these abstract interfaces.
  • For example, I’m using a Nucleo-F767ZI, which is supported by stm32f7xx-hal.
  • Another example is the ESP32-C3 supported by es32c3-hal

(For an in-depth adventure into porting Rust to a chip, see Rust on the CH32V003)

In our quest, we will be building something device-agnostic using the generic HAL (Hardware Abstraction Layer) traits. We won’t need to worry much about the lower level details, things just work.

A device-agnostic Led interface 🟢§

So let’s say we want to create a device-agnostic (non-blocking) interface for an LED connected to your micro-controller. Here’s how we might do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

use core::{fmt::Debug, task::Poll};
use embedded_hal::digital::v2::{OutputPin, PinState};

#[derive(Copy, Clone, Debug)]
pub enum LedAction {
    Set { is_on: bool },
}

#[derive(Copy, Clone, Debug)]
pub enum LedError<PinError: Debug> {
    PinSet(PinError),
}

pub struct Led<P>
where
    P: OutputPin,
{
    pin: P,
    is_on: bool,
}

impl<P> Led<P>
where
    P: OutputPin,
    P::Error: Debug,
{
    pub fn new(pin: P) -> Self {
        Self { pin, is_on: false }
    }

    pub fn run(&mut self, action: &LedAction) {
        match action {
            LedAction::Set { is_on } => self.is_on = *is_on,
        }
    }

    pub fn poll(&mut self) -> Poll<Result<(), LedError<P::Error>>> {
        self.pin
            .set_state(PinState::from(self.is_on))
            .map_err(LedError::PinSet)?;

        Poll::Ready(Ok(()))
    }
}

For a simple example there’s a lot happening, especially if you are new to Rust!

• LedAction is an enum we will use to tell the LED how to update.
• LedError is an object we will use to represent any error.
  • This receives one generic type, PinError (which implements the Debug trait), since we don’t know the specific type of error a hardware pin might return.
  • This also uses the #[derive(...)] macro to automatically derive the traits Copy, Clone, and Debug. Note: We can only derive these traits if all the types within this object also implement the trait. This is why we must explicitly say that PinError must implement the Debug trait.
• Led is a struct we will use as our LED abstraction, like a class in other languages.
  • For the methods,
    • The new method is our constructor for creating a new LED.
    • The run method receives our action telling the LED how to update, and update our LED abstraction’s internal state (but not yet updating the external hardware).
      • This method returns nothing (which is by default the empty tuple ()).
    • The poll method will update the external hardware as needed to match the internal state.
      • This method returns a Poll (which can be either Pending or Ready(value)) of a Result (which can be either Ok(value) or Err(error)) of either a empty value () or an error P::Error (the associated type Error, attached to the OutputPin trait).
  • For the types, this receives one generic type P, which implements OutputPin (provided by the embedded-hal library). We also specify that P::Error (the associated type Error, attached to the OutputPin trait) implements Debug.

An dummy GpioA struct to impl OutputPin 👤§

Now if you’re curious, here’s what a dummy struct that implements the OutputPin trait would look like.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

use embedded_hal::digital::v2::{OutputPin, PinState};

pub struct GpioA {
    state: PinState,
}

#[derive(Copy, Clone, Debug)]
pub struct GpioAError {}

impl GpioA {
    pub fn new() -> Self {
        Self {
            state: PinState::Low,
        }
    }
}

impl OutputPin for GpioA {
    type Error = GpioAError;

    fn set_low(&mut self) -> Result<(), Self::Error> {
        self.state = PinState::Low;
        Ok(())
    }
    fn set_high(&mut self) -> Result<(), Self::Error> {
        self.state = PinState::High;
        Ok(())
    }
    fn set_state(&mut self, state: PinState) -> Result<(), Self::Error> {
        self.state = state;
        Ok(())
    }
}

Note: This won’t do anything!

In the real-world, these structs affect registers on the hardware and are provided by your device’s xxx-hal library, almost certainly generated with a macro.

An example top-level entry 🔝§

To set the stage, let’s show how we might call our Led.

An example fn main() you can run on a normal PC, using our dummy GpioA:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

fn main() {
    let led_pin = GpioA::new();
    let mut led = Led::new(led_pin);

    led.run(&LedAction::Set { is_on: true });

    loop {
        match led.poll() {
            Poll::Pending => continue,
            Poll::Ready(Ok(())) => break,
            Poll::Ready(Err(err)) => {
                println!("Error: {:?}", err);
                break;
            }
        }
    }
}

An example embedded entry for a Nucleo-F767ZI:

(Assuming knurling-rs/app-template as a starting point.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#![no_main]
#![no_std]

use my_app as _; // global logger + panicking-behavior + memory layout

use stm32f7xx_hal::{pac, prelude::*};

#[cortex_m_rt::entry]
fn main() -> ! {
    let p = pac::Peripherals::take().unwrap();
    let gpiob = p.GPIOB.split();

    let led_pin = gpiob.pb0.into_push_pull_output();
    let mut led = Led::new(led_pin);

    led.run(&LedAction::Set { is_on: true });

    loop {
        match led.poll() {
            Poll::Pending => continue,
            Poll::Ready(Ok(())) => break,
            Poll::Ready(Err(err)) => {
                defmt::println!("Error: {}", defmt::Debug2Format(&err));
                break;
            }
        }
    }
}

A more detailed Led using a timer ⏲️§

If you’re wondering why there’s a difference between run and poll, let’s change our LED abstraction so we can also tell an LED to blink for a specific amount of time. Since we can’t do a blocking sleep, you’ll see why poll is designed to be non-blocking.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

use core::fmt::Debug;
use core::task::Poll;
use embedded_hal::digital::v2::{OutputPin, PinState};
use fugit::TimerDurationU32 as TimerDuration;
use fugit_timer::Timer;
use nb;

#[derive(Clone, Copy, Debug)]
pub enum LedAction<const TIMER_HZ: u32> {
    Set { is_on: bool },
    Blink { duration: TimerDuration<TIMER_HZ> },
}

#[derive(Clone, Copy, Debug, Format)]
pub enum LedBlinkStatus {
    Start,
    Wait,
    Done,
}

#[derive(Clone, Copy, Debug)]
pub enum LedState<const TIMER_HZ: u32> {
    Set {
        is_on: bool,
    },
    Blink {
        status: LedBlinkStatus,
        duration: TimerDuration<TIMER_HZ>,
    },
}

#[derive(Clone, Copy, Debug)]
pub struct Led<P, const TIMER_HZ: u32, T>
where
    P: OutputPin,
    T: Timer<TIMER_HZ>,
{
    pin: P,
    timer: T,
    state: Option<LedState<TIMER_HZ>>,
}

#[derive(Clone, Copy, Debug)]
pub enum LedError<PinError: Debug, TimerError: Debug> {
    PinSet(PinError),
    TimerStart(TimerError),
    TimerWait(TimerError),
}

impl<P, const TIMER_HZ: u32, T> Led<P, TIMER_HZ, T>
where
    P: OutputPin,
    P::Error: Debug,
    T: Timer<TIMER_HZ>,
    T::Error: Debug,
{
    pub fn new(pin: P, timer: T) -> Self {
        Self {
            pin,
            timer,
            state: None,
        }
    }

    fn run(&mut self, action: &LedAction) {
        match action {
            LedAction::Set { is_on } => {
                self.state = Some(LedState::Set { is_on: *is_on });
            }
            LedAction::Blink { duration } => {
                self.state = Some(LedState::Blink {
                    status: LedBlinkStatus::Start,
                    duration: *duration,
                });
            }
        }
    }

    fn poll(&mut self) -> Poll<Result<(), LedError<P::Error, T::Error>> {
        match self.state {
            None => Poll::Ready(Ok(())),
            Some(LedState::Set { is_on }) => {
                // set led state
                self.pin
                    .set_state(PinState::from(is_on))
                    .map_err(LedError::PinSet)?;

                self.state = None;

                Poll::Ready(Ok(()))
            }
            Some(LedState::Blink { duration, status }) => {
                match status {
                    LedBlinkStatus::Start => {
                        // start timer
                        self.timer.start(duration).map_err(LedError::TimerStart)?;

                        // turn led on
                        self.pin.set_high().map_err(LedError::PinSet)?;

                        // update state
                        self.state = Some(LedState::Blink {
                            status: LedBlinkStatus::Wait,
                            duration,
                        });

                        Poll::Pending
                    }
                    LedBlinkStatus::Wait => match self.timer.wait() {
                        Err(nb::Error::Other(err)) => Poll::Ready(Err(LedError::TimerWait(err))),
                        Err(nb::Error::WouldBlock) => Poll::Pending,
                        Ok(()) => {
                            self.state = Some(LedState::Blink {
                                status: LedBlinkStatus::Done,
                                duration,
                            });

                            Poll::Pending
                        }
                    },
                    LedBlinkStatus::Done => {
                        self.pin.set_low().map_err(LedError::PinSet)?;

                        self.state = None;

                        Poll::Ready(Ok(()))
                    }
                }
            }
        }
    }
}

Oh gosh that’s a mouthful!

• LedState is an enum with either:
  • Set with a boolean is_on
  • Blink with a status (LedBlinkStatus) and a duration
    • LedBlinkStatus is either Start, Wait, or Done.
• In Led, we’re using a state machine:
  • The current LedState is stored in self.state.
  • For the methods:
    • On run, we receive an LedAction and update self.state, but don’t do anything to affect the LED pin or timer.
    • On poll,
      • If the current state is None, we’re done and we return (send a message to whoever polled us) that we’re done (Poll::Ready(Ok(())))
      • If the current state is Some(LedState::Set {}), we set the LED to the desired on/off state. Then, we reset the state to None and return that we’re done (Poll::Ready(Ok(()))).
      • If the current state is Some(LedState::Blink {}), the method handles the blinking action based on the current LedBlinkStatus:
        • If the status is Start, it turns the LED on, starts the timer with the given duration, updates the status to Wait, and returns Poll::Pending, indicating it’s still waiting.
        • If the status is Wait, it checks the timer:
          • If the timer returns an error, it returns Poll::Ready(Err(LedError::TimerWait(err))), propagating the error.
          • If the timer is not done and returns “would block”, it returns Poll::Pending, indicating it’s still waiting.
          • If the timer is done, it updates the status to Done and returns Poll::Pending.
        • If the status is Done, it turns the LED off, resets the state to None, and returns Poll::Ready(Ok(())), indicating it’s done.
      • In any of the steps mentioned above, if we get an erro, we send the error upwards return Poll::Ready(Err(LedError)).
  • For the types, this receives three generics:
    • A type P, which implements OutputPin (provided by the embedded-hal library). We also specify that P::Error (the associated type Error, attached to the OutputPin trait) implements Debug.
    • A constant TIMER_HZ, which describes the frequency of the timer.
    • A type T, which implements Timer<TIMER_HZ> (provided by the fugit-timer library). We also specify that T::Error implements Debug.

I hope that makes some sense.

And for completion, here’s an example embedded entry for a Nucleo-F767ZI:

(Assuming knurling-rs/app-template as a starting point.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#![no_main]
#![no_std]

use my_app as _; // global logger + panicking-behavior + memory layout

use stm32f7xx_hal::{pac, prelude::*};
use fugit::ExtU32;

#[cortex_m_rt::entry]
fn main() -> ! {
    let p = pac::Peripherals::take().unwrap();
    let rcc = p.RCC.constrain();
    let clocks = rcc.cfgr.sysclk(216.MHz()).freeze();
    let gpiob = p.GPIOB.split();

    let led_pin = gpiob.pb0.into_push_pull_output();
    let led_timer = p.TIM5.counter_us(&clocks);
    let mut led = Led::new(led_pin, led_timer);

    led.run(&LedAction::Blink { duration: 200.millis() });

    loop {
        match led.poll() {
            Poll::Pending => continue,
            Poll::Ready(Ok(())) => break,
            Poll::Ready(Err(err)) => {
                defmt::println!("Error: {}", defmt::Debug2Format(&err));
                break;
            }
        }
    }
}

For the rest of the post, I’ll be assuming the original, simpler Led struct.

A Runner to control multiple Led 🚥§

Now say we want to control multiple LEDs together.

We will create a Runner that can receive a command, delegate that command to the associated LED, and poll all active commands until completion.

To start, we know there will be three LEDs: a green LED, a blue LED, and a red LED.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

use alloc::collections::VecDeque;
use core::fmt::Debug;
use core::task::Poll;

#[derive(Copy, Clone, Debug)]
pub enum Command {
    GreenLed(LedAction),
    BlueLed(LedAction),
    RedLed(LedAction),
}

pub enum CommandError<GreenLedError: Debug, BlueLedError: Debug, RedLedError: Debug> {
    GreenLedError(GreenLedError),
    BlueLedError(BlueLedError),
    RedLedError(RedLedError),
}

pub struct Runner<GreenPin, BluePin, RedPin>
where
    GreenPin: OutputPin,
    BluePin: OutputPin,
    RedPin: OutputPin,
{
    active_commands: VecDeque<Command>,
    green_led: Led<GreenPin>,
    blue_led: Led<BluePin>,
    red_led: Led<RedPin>,
}

impl<GreenPin, BluePin, RedPin> Runner<GreenPin, BluePin, RedPin>
where
    GreenPin: OutputPin,
    GreenPin::Error: Debug,
    BluePin: OutputPin,
    BluePin::Error: Debug,
    RedPin: OutputPin,
    RedPin::Error: Debug,
{
    pub fn new(green_led: GreenLed, blue_led: BlueLed, red_led: RedLed) -> Self {
        Self {
            active_commands: VecDeque::new(),
            green_led,
            blue_led,
            red_led,
        }
    }

    pub fn run(&mut self, command: Command) {
        match command {
            Command::GreenLed(action) => self.green_led.run(&action),
            Command::BlueLed(action) => self.blue_led.run(&action),
            Command::RedLed(action) => self.red_led.run(&action),
        }
        self.active_commands.push_back(command);
    }

    pub fn poll(
        &mut self,
    ) -> Poll<Result<(), CommandError<GreenPin::Error, BluePin::Error, RedPin::Error>>> {
        let num_commands = self.active_commands.len();
        for _command_index in 0..num_commands {
            let command = self.active_commands.pop_front().unwrap();
            let result = match command {
                Command::GreenLed(_) => self
                    .green_led
                    .poll()
                    .map_err(|err| CommandError::GreenLedError(err)),
                Command::BlueLed(_) => self
                    .blue_led
                    .poll()
                    .map_err(|err| CommandError::BlueLedError(err)),
                Command::RedLed(_) => self
                    .red_led
                    .poll()
                    .map_err(|err| CommandError::RedLedError(err)),
            };

            match result {
                Poll::Ready(Ok(())) => {}
                Poll::Ready(Err(err)) => {
                    self.active_commands.push_back(command);

                    return Poll::Ready(Err(err));
                }
                Poll::Pending => {
                    self.active_commands.push_back(command);
                }
            }
        }

        if self.active_commands.len() == 0 {
            Poll::Ready(Ok(()))
        } else {
            Poll::Pending
        }
    }
}

Woah, okay!

• Command is an enum to represents any action we might want to send to any LED.
• CommandError is an enum to represent any error that might happen with any LED.
• Runner is the struct to manage our three LEDs (green, blue, and red).
  • We store a list of active commands (active_commands) and an Led object for each color.
  • For the methods:
    • new: Creates a new Runner object, taking green, blue, and red LEDs as inputs.
    • run: Takes a Command as input, performs the action for the specified LED color, and adds the command to the list of active commands.
    • poll: Checks the progress of each command in the list:
      • If a command is done, it removes the command from the list.
      • If a command is not done, it keeps the command in the list.
      • If there’s an error, it returns the error and puts the command back in the list.

Note: In this code I’m using alloc::collections::VecDeque, to make things easier. If we want collections without using alloc, I recommend the crate heapless, so here we’d use heapless::Deque.

In a nutshell, this code manages a set of LEDs, allowing you to turn them on or off by adding commands to a list, and it checks the progress of these commands. If you run into any issues, it will handle the errors for each LED color.

Problem #1: Generic type hell 😈§

Now here’s the point where I can finally start to explain why I had such a hard time to make the code for my robot re-usable as a library.

Let’s go back to Runner’s generic types: GreenPin, BluePin, and RedPin.

1
2
3
4
5
6
7
8
9
10
11

pub struct Runner<GreenPin, BluePin, RedPin>
where
  GreenPin: OutputPin,
  BluePin: OutputPin,
  RedPin: OutputPin,
{
    active_commands: VecDeque<Command>,
    green_led: Led<GreenPin>,
    blue_led: Led<BluePin>,
    red_led: Led<RedPin>,
}

Now, this looks okay (when you’ve become accustomed to generic types), but this is only considering our original Led struct that only needs a P: OutputPin. In our later Led struct, we need two more generics: const TIMER_HZ: u32 and T: Timer<TIMER_HZ>.

Imagine we needed more:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

pub struct Runner<
    GreenLedPin,
    GreenLedTimer,
    const GREEN_LED_TIMER_HZ: u32,
    BlueLedPin,
    BlueLedTimer,
    const BLUE_LED_TIMER_HZ: u32,
    RedLedPin,
    RedLedTimer,
    const RED_LED_TIMER_HZ: u32,
    XAxisStepperDriver,
    XAxisTimer,
    const X_AXIS_TIMER_HZ: u32,
    YAxisStepperDriver,
    YAxisTimer,
    const Y_AXIS_TIMER_HZ: u32,
    MainSpindleDriver,
> where
    GreenLedPin: OutputPin,
    GreenLedTimer: Timer<GREEN_LED_TIMER_HZ>,
    BlueLedPin: OutputPin,
    BlueLedTimer: Timer<BLUE_LED_TIMER_HZ>,
    RedLedPin: OutputPin,
    RedLedTimer: Timer<RED_LED_TIMER_HZ>,
    XAxisStepperDriver: SetDirection + Step,
    XAxisTimer: Timer<X_AXIS_TIMER_HZ>,
    YAxisStepperDriver: SetDirection + Step,
    YAxisTimer: Timer<Y_AXIS_TIMER_HZ>,
    MainSpindleDriver: SpindleDriver

{
    pub green_led: Led<GreenLedPin, GreenLedTimer, TICK_TIMER_HZ>,
    pub blue_led: Led<BlueLedPin, BlueLedTimer, TICK_TIMER_HZ>,
    pub red_led: Led<RedLedPin, RedLedTimer, TICK_TIMER_HZ>,
    pub x_axis: Axis<AxisMotionControl<XAxisDriver, XAxisTimer, X_AXIS_TIMER_HZ>>,
    pub y_axis: Axis<AxisMotionControl<YAxisDriver, YAxisTimer, Y_AXIS_TIMER_HZ>>,
    pub main_spindle: Spindle<MainSpindleDriver>,
}

Yuck. 🤮

The problem with these generic types is that anything that consumes a struct also need to provide their generic types. This becomes a sort of “generic hell”, where we can’t escape generic types just bubbling up to the consumer’s code and beyond.

The solution to generic type hell is traits.

So let’s go!

Solution #1: Traits to the rescue 😇§

Beyond the generic type hell problem, we want our system to support multiple types of hardware interfaces that affect the real world.

trait Actuator 💪§

We create an Actuator trait to generalize our use of hardware interfaces (while still being device agnostic).

1
2
3
4
5
6
7
8
9

use core::task::Poll;

pub trait Actuator {
    type Action;
    type Error: Debug;

    fn run(&mut self, action: &Self::Action);
    fn poll(&mut self) -> Poll<Result<(), Self::Error>>;
}

As an aside, a Rust expert might say that run should return a Future, which we can poll. I chose this design because such a future would need a mutable reference to the hardware peripherals (and Rust has strict rules about object ownership, references, and mutability) and at the time I wanted to avoid using allocations (Rc). If this is an achievable change for my current code base, I’d love to learn how, every day is a school day.

impl Actuator for Led 🟢§

Now to update Led:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

use core::{fmt::Debug, task::Poll};
use embedded_hal::digital::v2::{OutputPin, PinState};

#[derive(Copy, Clone, Debug)]
pub enum LedAction {
    Set { is_on: bool },
}

#[derive(Copy, Clone, Debug)]
pub enum LedError<PinError: Debug> {
    PinSet(PinError),
}

pub struct Led<P>
where
    P: OutputPin,
{
    pin: P,
    is_on: bool,
}

impl<P> Led<P>
where
    P: OutputPin,
{
    pub fn new(pin: P) -> Self {
        Self { pin, is_on: false }
    }
}

impl<P> Actuator for Led<P>
where
    P: OutputPin,
    P::Error: Debug,
{
    type Action = LedAction;
    type Error = LedError<P::Error>;

    fn run(&mut self, action: &Self::Action) {
        match action {
            LedAction::Set { is_on } => self.is_on = *is_on,
        }
    }

    fn poll(&mut self) -> Poll<Result<(), Self::Error>> {
        self.pin
            .set_state(PinState::from(self.is_on))
            .map_err(LedError::PinSet)?;

        Poll::Ready(Ok(()))
    }
}

The code is similar, except now we’re implementing the Actuator trait instead of implementing those methods directly on the struct.

Same Runner, different generics 🚥§

And now we can improve the Runner struct:

1
2
3
4
5
6
7
8
9
10
11

pub struct Runner<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    BlueLed: Actuator<Action = LedAction>,
    RedLed: Actuator<Action = LedAction>,
{
    active_commands: VecDeque<Command>,
    green_led: GreenLed,
    blue_led: BlueLed,
    red_led: RedLed,
}

By using a trait, we’re able to hide the generics of the implementing struct and instead focus our generics on the structs we need.

We are saying: Runner will receive three types (named GreenLed, BlueLed, and RedLed), where each type must implement the Actuator trait where the associated type Action is LedAction. Those three types correspond to a struct, and in this case correspond to the Led struct, but we didn’t specify so as to be generic.

Now the definition of Runner doesn’t “leak” the generic types of Led.

For completeness:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

use alloc::collections::VecDeque;
use core::fmt::Debug;
use core::task::Poll;

#[derive(Copy, Clone, Debug)]
pub enum Command {
    GreenLed(LedAction),
    BlueLed(LedAction),
    RedLed(LedAction),
}

#[derive(Copy, Clone, Debug)]
pub enum CommandError<GreenLedError: Debug, BlueLedError: Debug, RedLedError: Debug> {
    GreenLedError(GreenLedError),
    BlueLedError(BlueLedError),
    RedLedError(RedLedError),
}

pub struct Runner<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    BlueLed: Actuator<Action = LedAction>,
    RedLed: Actuator<Action = LedAction>,
{
    active_commands: VecDeque<Command>,
    green_led: GreenLed,
    blue_led: BlueLed,
    red_led: RedLed,
}

impl<GreenLed, BlueLed, RedLed> Runner<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    GreenLed::Error: Debug,
    BlueLed: Actuator<Action = LedAction>,
    BlueLed::Error: Debug,
    RedLed: Actuator<Action = LedAction>,
    RedLed::Error: Debug,
{
    pub fn new(green_led: GreenLed, blue_led: BlueLed, red_led: RedLed) -> Self {
        Self {
            active_commands: VecDeque::new(),
            green_led,
            blue_led,
            red_led,
        }
    }

    pub fn run(&mut self, command: Command) {
        match command {
            Command::GreenLed(action) => self.green_led.run(&action),
            Command::BlueLed(action) => self.blue_led.run(&action),
            Command::RedLed(action) => self.red_led.run(&action),
        }
        self.active_commands.push_back(command);
    }

    pub fn poll(
        &mut self,
    ) -> Poll<Result<(), CommandError<GreenLed::Error, BlueLed::Error, RedLed::Error>>> {
        let num_commands = self.active_commands.len();
        for _command_index in 0..num_commands {
            let command = self.active_commands.pop_front().unwrap();
            let result = match command {
                Command::GreenLed(_) => self
                    .green_led
                    .poll()
                    .map_err(|err| CommandError::GreenLedError(err)),
                Command::BlueLed(_) => self
                    .blue_led
                    .poll()
                    .map_err(|err| CommandError::BlueLedError(err)),
                Command::RedLed(_) => self
                    .red_led
                    .poll()
                    .map_err(|err| CommandError::RedLedError(err)),
            };

            match result {
                Poll::Ready(Ok(())) => {}
                Poll::Ready(Err(err)) => {
                    self.active_commands.push_back(command);

                    return Poll::Ready(Err(err));
                }
                Poll::Pending => {
                    self.active_commands.push_back(command);
                }
            }
        }

        if self.active_commands.len() == 0 {
            Poll::Ready(Ok(()))
        } else {
            Poll::Pending
        }
    }
}

However we still have the problem where the shape of 3 LEDs: green, blue, and red, is pre-defined.

Note: If you’re wondering why we need to be so specific with our Command enum, our run match, and our poll match: it’s because we’re avoiding heap allocations and dynamic objects. We can only use static types, so Rust knows the size of every struct at compile time, and objects are created on the stack. This approach, while extra boilerplate-y, is very efficient.

Problem #2: Pre-defined shapes 😈§

If you want to use my Runner as written above, sure the use of generic types meant you can use any device, and now the use of traits means generic types don’t leak upward. But you better have only 3 LEDs, and you better want them to be named “Green”, “Blue”, and “Red”.

Generic types were helpful to be device-agnostic, but at the same time didn’t help us be shape-agnostic.

To solve this, I discovered another trick, while still avoiding alloc.

Solution #2: User defined shapes 😇§

What if, in all the places that we hard-code GreenLed, BlueLed, and RedLed, we could allow the user to give us something which did those things?

Let’s make a new trait for this:

trait ActuatorSet ⛶⛶⛶§

1
2
3
4
5
6
7
8

pub trait ActuatorSet {
    type Action: Copy + Clone + Debug;
    type Id: Copy + Clone + Debug;
    type Error: Copy + Clone + Debug;

    fn run(&mut self, id: &Self::Id, action: &Self::Action);
    fn poll(&mut self, id: &Self::Id) -> Poll<Result<(), Self::Error>>;
}

Here we design a way to store a set of actuators for a single type (e.g. LED).

And then the user can defined their own ActuatorSet as follows:

impl LedSet for ActuatorSet 🚥§

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

#[derive(Copy, Clone, Debug)]
pub enum LedId {
    Green,
    Blue,
    Red,
}

#[derive(Copy, Clone, Debug)]
pub enum LedSetError<GreenLedError: Debug, BlueLedError: Debug, RedLedError: Debug> {
    GreenLedError(GreenLedError),
    BlueLedError(BlueLedError),
    RedLedError(RedLedError),
}

pub struct LedSet<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    BlueLed: Actuator<Action = LedAction>,
    RedLed: Actuator<Action = LedAction>,
{
    green_led: GreenLed,
    blue_led: BlueLed,
    red_led: RedLed,
}

impl<GreenLed, BlueLed, RedLed> LedSet<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    BlueLed: Actuator<Action = LedAction>,
    RedLed: Actuator<Action = LedAction>,
{
    pub fn new(green_led: GreenLed, blue_led: BlueLed, red_led: RedLed) -> Self {
        Self {
            green_led,
            blue_led,
            red_led,
        }
    }
}

impl<GreenLed, BlueLed, RedLed> ActuatorSet for LedSet<GreenLed, BlueLed, RedLed>
where
    GreenLed: Actuator<Action = LedAction>,
    GreenLed::Error: Copy + Debug,
    BlueLed: Actuator<Action = LedAction>,
    BlueLed::Error: Copy + Debug,
    RedLed: Actuator<Action = LedAction>,
    RedLed::Error: Copy + Debug,
{
    type Action = LedAction;
    type Id = LedId;
    type Error = LedSetError<GreenLed::Error, BlueLed::Error, RedLed::Error>;

    fn run(&mut self, id: &Self::Id, action: &Self::Action) {
        match id {
            LedId::Green => self.green_led.run(action),
            LedId::Blue => self.blue_led.run(action),
            LedId::Red => self.red_led.run(action),
        }
    }

    fn poll(&mut self, id: &Self::Id) -> Poll<Result<(), Self::Error>> {
        match id {
            LedId::Green => self
                .green_led
                .poll()
                .map_err(|err| LedSetError::GreenLedError(err)),
            LedId::Blue => self
                .blue_led
                .poll()
                .map_err(|err| LedSetError::BlueLedError(err)),
            LedId::Red => self
                .red_led
                .poll()
                .map_err(|err| LedSetError::RedLedError(err)),
        }
    }
}

Runner<LedSet> 🏃§

And now our runner can be re-written to receive this actuator set:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

use alloc::collections::VecDeque;
use core::fmt::Debug;
use core::task::Poll;

#[derive(Copy, Clone, Debug)]
pub enum Command<LedId> {
    Led(LedId, LedAction),
}

#[derive(Copy, Clone, Debug)]
pub enum CommandError<LedError: Debug> {
    LedError(LedError),
}

pub struct Runner<LedSet>
where
    LedSet: ActuatorSet<Action = LedAction>,
{
    active_commands: VecDeque<Command<LedSet::Id>>,
    leds: LedSet,
}

impl<LedSet> Runner<LedSet>
where
    LedSet: ActuatorSet<Action = LedAction>,
    LedSet::Error: Debug,
{
    pub fn new(leds: LedSet) -> Self {
        Self {
            active_commands: VecDeque::new(),
            leds,
        }
    }

    pub fn run(&mut self, command: Command<LedSet::Id>) {
        match command {
            Command::Led(id, action) => self.leds.run(&id, &action),
        }
        self.active_commands.push_back(command);
    }

    pub fn poll(&mut self) -> Poll<Result<(), CommandError<LedSet::Error>>> {
        let num_commands = self.active_commands.len();
        for _command_index in 0..num_commands {
            let command = self.active_commands.pop_front().unwrap();
            let result = match command {
                Command::Led(id, _) => self
                    .leds
                    .poll(&id)
                    .map_err(|err| CommandError::LedError(err)),
            };

            match result {
                Poll::Ready(Ok(())) => {}
                Poll::Ready(Err(err)) => {
                    self.active_commands.push_back(command);

                    return Poll::Ready(Err(err));
                }
                Poll::Pending => {
                    self.active_commands.push_back(command);
                }
            }
        }

        if self.active_commands.len() == 0 {
            Poll::Ready(Ok(()))
        } else {
            Poll::Pending
        }
    }
}

Now we only need to pre-define the types of actuators (e.g. LED, axis, spindle, relay, etc), not the names of the actuators. The user will give us something that defines the names. This is good!

If you’re still wondering why we still need all this boilerplate, it’s because we’re still avoiding heap allocations (alloc) and dynamic objects. Our code still only uses static objects where Rust knows the size of the objects at compile time, everything can be included on the stack, and everything is very efficient.

Depending on your situation, you could stop here. We solved the problems of generic hell and pre-defined shapes. We did all this while being maximally efficient for embedded devices.

But for my next trick, I’ll break these guarantees for the sake of a more ergonomic developer experience.

TODO 💜§

Inspiration§

A tensegrity is a structural principle based on a system of isolated components under compression inside a network of continous tension, and arranged in such a way that the compressed members (struts) do not touch each other while the prestressed tensioned members (tendons) delineate the system spatially.

The term was coined by Buckminster Fuller in the 1960s as a portmanteau of “tensional integrity”

• Tensegrity @ Wikipedia

Tensegrity prototype§

Controller§

This time I wanted to use more “off-the-shelf” LED software and hardware.

• Software: WLED
• Hardware: QuinLED-Dig-Uno

Strut design§

Bill of materials:

• aluminium extruded round tube (12.7mm outer diameter, 0.9mm thickness)
• acrylic round tube (40mm outer diameter)
• 4x 3d printed spacers
• 2x 3d printed end links
• 2x 3d printed end caps
• XT60 connectors (power)
• 2 pin electrical cable (power)
• WS2811 LED strips (White PCB, 5m 60 LEDs IP65)
• 3 pin 0.5mm^2 20AWG waterproof electrical cable (LED)
• 3 pin “small size” waterproof IP65 LED connector (LED)

Benefits of aluminium tube inner:

• Acts as heatsink for LEDs
• Can feed power cable through tube to other side

Since I couldn’t find acrylic tubes long enough, I “welded” multiple tubes together with solvent cement.

Strut assembly§

The acrylic tubes are sanded to achieve a diffuser effect.

Double doof sticks§

I also made two portable “doof sticks” based on the same strut designs, with further 3d printed sections for: batteries, bi-directional power converter, power switch, power plug, WLED controller, and button interface. All solvent welded together.

Look amazing, but fragile.

Tensegrity design§

Bill of materials:

• 6x LED struts
• 3x 6x Tendons
  • Shock cord
  • Shock cord end hooks

Each strut connects with:

• The neighbor struts at the top
• The neighbor struts at the bottom
• The neighbor struts from top to bottom

Tensegrity assembly§

Ignition§

Kiwiburn§

(An evolution from Portable Solar v1 and other learnings.)

The goal is to do a solar electric setup the “right way”:

• with a better solar charge controller
• with an inverter
• with best practice schematic for how to wire everything together
• with appropriate circuit breakers and fuses
• with appropriate thick wires
• and so on…

TODO more detail

Source: ahdinosaur/polyledra-v1

Background§

After playing with my portable rainbows, I thought about my learning objectives for the next stage of portable rainbow exploration:

• I want to go back to the BeagleBone, but this time using Rust instead of JavaScript
• I want to get back into 3d printing for enclosures and structures
• I want to upgrade from breadboards to protoboards to custom pcb circuits, out-source soldering!
• I want to play with graphics code

I was sitting on a hill listening to music at a gathering in the forest last weekend, when I saw a 20-sided shape hanging over a stage, with fairy lights strung around the edges. ✨

I thought “what if I did the same with leds”? 🌈

I then continued to spend the rest of the festival obsessing about the shape, leds, and rust interfaces, which led to here. 🐱

Shapes§

Design constraints§

To simplify production, we want:

• MUST HAVE uniform length edges (easy for buying led strip channels)
• COULD HAVE uniform angle patterns (easier for making 3d printed joints)

Icosahedron§

The original gansta shape from the festival!

An icosahedron is a 20-sided shape which regular angle patterns and uniform length edges.

It’s also a gyroelgonated pentagonal dipryamid (my original understanding of the shape): on the top and bottom is a pentagonal pyramid, in the middle is an pentagonal antiprism

Octahedron§

Tetrahedron§

Initial controller dive§

A Rust-y adventure§

Wow, Rust is legit!

Really enjoying how the compiler is so helpful.

Had my first fight with the borrow checker, still am on easy mode though. Had my first “spend hours writing a heap of rust code, finally compiles, and omg what it works!?”

I setup a basic multi-threaded message-passing architecture based on a conversation with Matt, thanks!

I wrote some code to derive pixel positions from an abstract shape, then on each clock tick it runs a function for each pixel that receives the position and returns the color, which are then all displayed in a 3d renderer.

I think the hard part of this project for me will be the graphics part, I find graphics code sooo confusing! At the moment was able to find a library that let me create shapes in 3d space without having to dive too deep. But I’m really keen to learn how to do proper graphics code, I forgot to mention that in my learning objectives above.

More Rust-y learnings§

Been making heaps of progress, yay learning Rust!

• in the simulator, render points instead of cubes for performance (until I do my own gl)
• play with simple animated rgb scene
• learn how non-blocking doesn’t make sense without an event loop
• create a scene manager to handle switching between many scenes
• hook up simulator window events so ‘left’ and ‘right’ switch previous and next scenes, respectively
• support hsl colors
• add simple rainbow scene
• support scenes to return generic iterators, to auto-convert colors without intermediate vecs

Shape walker§

Had a long battle with the Rust borrow checker, ended up on top! 😅

Then moved on to the puzzle of how to implement a shape walker. 🌈

From software to 3D modeling§

Moving from software to 3D modeling! 📐 🚥 🔆 🌈

First going to build a tetrahedron, so I bought 20 aluminum led strip channels, each 0.5m long.

Here are the dimensions of each aluminum channel (except 500mm long):

The idea is to have 3 led strip channels per edge of the tetrahedron so the edges will be lit from all angles. I had this idea before but was going to start with a single channel per edge, until I talked to my friend: she noticed that since the shapes will be regular, the best effects will come from seeing the other side of the shape through the shape!

With help from Jack, I made a 3d model of the tetrahedron connectors!

Getting ready for Winter Expo§

Mix helped me with the tetrahedron angles math, my last edge connector was so wrong 📐

Then I completely re-structured the vertex structure, so can fit wires inside and round the back

(scad, viewable stl)

Then I made a new controller scene 🎇

(rs)

Then I got my code running on the Pocket Beagle. I love Rust where I can write code on my laptop (which doesn’t have access to an spi interface necessary to control the leds), then once I had it compile on my laptop (without ever running the code) there was only a small configuration change to make it actually work on the Pocket, yay compile-time type and borrow checking!

So this weekend I got the controller rust code running on the Pocket Beagle displaying on some real led hardware, with help from Piet who introduced me to japaric/cross, OMG so great.

Now I’ve prepared 15/18 led strips in aluminium channels, made an easy deploy script from my computer to the Pocket, setup the controller binary to run automatically when the Pocket starts, and fixed the code so it outputs pixel data for 3 “arms” per tetrahedron edge (3 arms per edge * 6 edges = 18 total arms).

Next up:

• setup power injections at regular intervals across the shape (at least 3, for 180 leds per injection)
• test the current vertex structure print actually works, tune until good

Fun learning: using rust’s --release flag led to a 10x performance increase, wow! 🌟

Keen to get this ready for the Art~Hack Wellington Winter Expo. 😅

Continued§

Yesterday fixed up the edge connector model based on feedback from my friend Jack who generously did a print some time ago. then played around with a new scene using noise functions, doesn’t look good yet but is pretty fun to play with. 🌊

Today soldered up the power injectors (had these leftover from a previous project, they connect perfectly here!) and powered up all the leds, but turns out I had an off-by-one error! Notice the center point is no longer in the center. The reason was float math, 0.999996 when expecting 1, solution was to round by a decimal place.

Then based on a tip from Piet, I sprayed the strips down with circuit board lacquer so they will be less likely to short (the aluminum is anodized, but scratch under the surface and you have a conductive metal touching the copper on the strips).

Then put on the diffusers and connected everything again, organized the “arms” by edge, even though it’s not yet in the shape of a tetrahedron. Goodness, I’ve never had a project be this clean and maybe even legit!

And all powered by this cute linux computer! 🐶

(And some other things, see complete bill of materials)

More updates!§

Here’s my new scene using 4-dimensional noise to determine colors! ([x, y, z, time] where time oscillates back and forth on each “beat” (TODO), slowly steps forward), got some help from Jack at Art~Hack.

Then added a button to change modes, except since I didn’t have an actual button I just tap the wires together. 😸

Yesterday, thanks to the other Jack, got the third print of the vertex structure, third time’s a charm! (actually this design needed changes, the 4th print looks good so far.)

Mix helped me shape out the tetrahedron:

Then soldered some wires and used the 4th print to assemble a partial tetrahedron, it’s almost a thing!

In motion!

I’m still in awe that any of this is working, it’s more beautiful than I deserve. 💖

Demo§

Another splash of updates§

Another splash of updates! 🐋

I disassembled the tetrahedron and brought it with me to California. ☀ a bunch of wires soldered to the led strips broke when “unplugging” the led channels from the connector. So to make future dis-assembly and re-assembly less painful, I tried a new idea: what if the 3 led strips for a given edge connected to a edge part, and then 3 edge parts connected to a vertex part.

Here’s my first plug and socket design:

The “plug” design here was especially bad because a 3d printed part gets strength from horizontal, not vertical. So while I could connected the “plug” into the “socket”, given the lack of tolerance I pushed them tightly together and snap the “plug” broke off.

And then I realized, this is what threaded bolts 🔩 are for:

With this design, the edges are meant to be portable as units, so I discovered hot glue on both sides to prevent the wire connection from breaking and to keep out dust. 🌈

Then to bring to Burning Man, I found a bag and added 2 portable usb power packs, 🔋

Added copious amounts of tape, to robustify the setup in danger of my lack of repair tooling,

and hung the polyledra as a chandelier from rope 🐍

and later at the burn, tied to my bike. 🚲

This all landed swimmingly,

• nothing went wrong at the burn
• the batteries lasted all night, no problem
• one vertex part broke, but the tape kept everything together, as if nothing happened
• worked well
  • hanging from rope at our home camp
  • dancing with me and flowing around
  • riding on a bike

Yay! 💃

Then dis-assembled to bring back to New Zealand (during which time another two vertex parts broke), got replacements vertex parts printed at National Library Wellington, and re-assembled again for Art~Hack Spring Expo / Maker Faire Wellington.

Now to get ready for “I-Can’t-Believe-It’s-Not-Kiwiburn”:

• replace the wires with custom pcbs
  • 1 per vertex
  • 2 per edge (one on each side)
• fix the strength of the vertex part (by splitting the angle into a separate part which is printed sideways)
• make it waterproof (ready for the New Zealand outdoors)
• more frequent power injection (something goes wrong at higher power)

Rambles to share§

I figured that printing a custom PCB was highest priority, because the time between iterations could be up to a month, if I needed to have something printed overseas.

Okay, I played with KiCad before, I liked what it was doing but I didn’t like using the graphical interface, I wanted to think in terms of math (code). I was used to using OpenSCAD for my 3d modelling, I was used to writing code for physical objects, why not code for circuits?

I quickly realized KiCad used S-expressions to represent PCB components and boards. What if I wrote JavaScript which a read JavaScript config to generate a Kicad file?

So yeah: I made jseda & sexprs 😻

And made my first circuit with code:

Which later became refined to the 4 circuits I need:

Edge, side a:

Edge, side b:

Tetrahedron vertex:

Octahedron vertex:

In this time I discovered that my whole time in Wellington (~4 years), during which time I lamented the lack of a local hackerspace, there has been a publicly-available Fab Lab: Fab Lab Wgtn, complete with 3D printers, laser cutters, multiple CNC machines, a PCB mill, and more. 😋

So I was hoping to prototype my circuits on the mill, even got help from Craig to use the mill. I ended up procrastinating on that front, so while the clock was ticking and the festivals approaching I decided to place my bets on my design and get my circuits made from Seeed Studios.

Today the circuits arrived, along with 3D prints I outsourced to be printed with PETG (stronger and more weatherproof than PLA)!

So far everything looks sweet as, I’m very excited. 😊 if everything checks out, I’ll be able to make a few more tetrahedrons, maybe an octahedron, with far better structural and electrical reliability than my current prototype, yay! 💃

3D printers are happy§

Before I learned about Fab Lab Wgtn, I bought a 3D printer, which took a few months to arrive but finally did, it’s amaze. Back in the day I built a Prusa Mendel from a kit, which at the time I knew meant that my time and energy would be focused on the 3D printer itself. These days I wanted to focus on 3D printing, and Josef Prusa made a company selling their printers, so I bought a pre-assembled Prusa i3 MK3, I couldn’t be happier. 🔩

Meanwhile, I had a new idea to fix the vertex part, again keeping in the mind that the strength in a 3d printed part is printed layer by layer:

https://youtu.be/SyXvFngkf1Q

Instead of printing the angles of the vertex part as one, I made a separate part with the angle, to be printed on the side, maximizing strength. 💪

It worked, but meant I’d have another 3 sets of connectors to keep everything together. After some time exploring this new approach, I went back to the old approach and while not perfect I think it’s stronger than my last design and good enough for my purposes.

While I’ve been printing away, I ended up with PLA prototypes, wondering what to do with them. PLA is technically compostable and recyclable, but in practice you need a industrial composter (which is not available here in Wellington) and most recycling systems don’t accept PLA. Despite this reality, PLA is commonly used by your eco-friendly cafes as “compostable” coffee lids. Anyways, I’ve started re-using my PLA prototypes to make party jewelry, which has been working really well because my 3D designs are very symmetric and have appealing features (like the edge connector can look like a few faces, depending on how you angle it).

During this time, I also discovered an OpenSCAD library for polyhedra, which let me visualize the entire tetrahedron, with all the parts put together:

Oh, also I went down a side quest in the search for waterproofing, discovered the magic of o-rings and how they are used everywhere, I had no idea! I played around with making custom o-rings from making 3d models of molds to fill with rubber, Haven’t given this a hoon yet though.

Next iteration§

So far the next iteration of the tetrahedron is going well! 🌈

(Not pictured: all the time spent making a mess in the empty office while assembling and listening to drum & bass, or when I soldered things backwards and had to unsolder everything, or when twice I plugged the power plugs backwards (+5V into GND and vise versa) causing the wires to rapidly melt and burn))

Twisted§

Nowhere§

Double trouble§

“I-Can’t-Believe-It’s-Not-Kiwiburn”§

Scuttle camp§

In the classic shape of suspenders and a belt.

Continuing from PIXELS FOR THE PIXEL GOD

Source: ahdinosaur/aburndance

BOM§

Bill of materials:

• led strips: apa102
  • connector
• controller: Adafruit HUZZAH32 – ESP32 Feather Board
  • Feather proto board
  • rotary encoder
  • tactile button
• usb power source: Anker PowerCore 26800
• shoulder straps (suspenders): etsy
• waist strap (belt): etsy

User interface design§

Controller has a current mode and current param.

The current mode is being rendered with all the params for that mode.

Here are the available ways to interface with the controller:

• press 1st button for previous mode
• press 2nd button for next mode
• press 3rd button for previous param
• press 4th button for next param
• turn the rotary encoder to change the current param
• hold 1st button until white then turn rotary encoder to change brightness
• hold 2nd button until white then turn rotary encoder to change color temperature

Showcase§

Resources§

• Adafruit ESP32 learning resources
  • ESP32 pinouts
  • ESP32 guide to installing the Arduino IDE.
• arduino-esp32/…/examples/…/RepeatTimer.ino

For context, I come from the United States of America, where many of my extended family and friends may support Donald Trump and may be on the spectrum of the Alt-Right, it’s not possible for me to ignore the new waves of moderate politics.

At some point a distinction came to light, so I’d like to share what I’ve learned about moderates, good and bad.

What is a moderate?§

A moderate is a person whose opinions are not extreme, whose beliefs fall in the middle between any two sides.

Often, moderates are those who have the most privilege, who benefit most from the status quo, and who are the most tolerated.

On the flip side, being a moderate is not a applicable strategy for those who suffer from the status quo, who are part of marginalized communities, and who are actively intolerated.

However, I do believe being a moderate is a powerful strategy when used as a bridge to connect diversity. Whether I think a moderate is good or bad depends on whether they are connecting or disconnecting other sides.

Good moderates are empathetic of diverse beliefs§

If you’re able to empathize with beliefs from diverse sides, yay!

Being empathetic means listening to another person or group’s lived experience and standing in solidarity with that experience as being valid.

Bad moderates are skeptical of diverse beliefs§

If you’re skepitcal of beliefs from diverse sides, boo!

Being skeptical means you judge the experience of another person or group.

Martin Luther King, Jr. had some words to say in a “Letter from a Birmingham Jail” (16 April 1963):

First, I must confess that over the last few years I have been gravely disappointed with the white moderate. I have almost reached the regrettable conclusion that the Negro’s great stumbling block in the stride toward freedom is not the White Citizen’s Council-er or the Ku Klux Klanner, but the white moderate who is more devoted to “order” than to justice; who prefers a negative peace which is the absence of tension to a positive peace which is the presence of justice; who constantly says “I agree with you in the goal you seek, but I can’t agree with your methods of direct action;” who paternalistically feels he can set the timetable for another man’s freedom; who lives by the myth of time and who constantly advises the Negro to wait until a “more convenient season”. Shallow understanding from people of goodwill is more frustrating than absolute misunderstanding from people of ill will. Lukewarm acceptance is much more bewildering than outright rejection.

If you’re waiting for the perfect protest, please consider that everyone wants to do their best, but only those with privilege have the choice to opt-out of social justice.

Case study: NFL kneels§

Some time ago, a football player Colin Kaepernick started a movement by kneeling, instead of standing, during the national anthem.

In an interview after the game, Kaepernick gave a clear meaning to his unique expression:

I am not going to stand up to show pride in a flag for a country that oppresses black people and people of color. To me, this is bigger than football and it would be selfish on my part to look the other way. There are bodies in the street and people getting paid leave and getting away with murder.

From then on, game after game, this unique expression of kneeling was used in public events to remind the audience about the message of institutional violence against black people.

As someone seeing this happen, we’re not being asked to agree or disagree, we’re being reminded of another group’s experiences. The kneeling is a reminder, lest we forget, that the public system is unjust for some people.

Yet, in my extended network I became witness to skepticism, with articles such as “Quit grandstanding with NFL protests and get back to football”.

Sports used to be fun, but these protests are divisive and pointless. Can’t we just play ball?

Rather than being empathetic with another group’s experience, I noticed gaslighting, to the point of deflecting the message to be about the flag, the anthem, or the military.

But not all (white) moderates try to silence stories about oppression, some use their own voice to amplify the messages:

Moderate strategy: be a bridge§

As the personal is political, being a moderate with empathy is where we have an opportunity to affect positive social change, using our day-to-day interactions amongst our friends, family, co-workers, and strangers to be a bridge.

For example, here’s my friend Dominic Tarr working to bridge the gap between conflicting sides during a tense conversation on Scuttlebutt:

@marina this isn’t just some random dickwad, this dickwad is @mixmix’s dad. That is why I think it’s worth mediating, for better or worse, he’s basically family. @substack is addressing future ssb members, but I’m interesting in addressing the people who are currently here. Because one time you told me that one of the challenges facing feminism is that the default response my men is to be skeptical of whatever a woman says, but believe things that other men say. This was surprising at the time, but I soon realized you where right. So you told me that it wasn’t enough for women to argue for feminism - men like me had to as well, because other men would actually listen to me. That is what I’m trying to do here.


@bob as you can see, my friends are a bit upset by this, and now you are connected to and socialising in the same space with them. I can certainly vouch that they are highly intelligent and there are many reasons they believe what they do. Could you please take that into consideration? they are not “some segments of some societies” they are a segment of this society.


I think it’s worth bridging between these viewpoints, because I realized that my own views have changed significantly over the years. If my 18 year old self came on here and what I believed at the time, I’d have gotten blasted by current @substack too, and that would be fair enough, but that probably would have galvanized my views not changed them. So I believe that if my views can change, other’s views can change too.

To be a good moderate is to listen, to give a voice to those who aren’t being heard (or can’t be present), to be a connecting link between diverse sides, to support a diversity of tactics brought by each participant given their understanding of the local situation.

Moderate strategy: be an ally§

There are social justice movements happening around us, be an ally!

As a person with privilege, it’s easy to join a movement with good intentions, but have negative impact. notice how much attention you give or take. check if you are supporting or co-opt-ing.

Give attention to others! Try not to place yourself at the center of attention, unless as a stepping stone to pass the microphone.

Listen! A good practice is to notice how much you’re listening, versus how much you’re talking.

Ask how you can help! But don’t expect others to carry your mental load.

Caveat: The paradox of tolerance§

There’s a caveat with empathy, known as the “paradox of tolerance”

If tolerance is inclusive of the intolerant, than intolerance will ultimately dominate, eliminating the tolerant and the practice of tolerance with them.

There are small minorities of people who will use your empathy against you: fascists, racists, and other bigoted people.

Instead of trying to be seem as “reasonable”, cultivate beliefs.

Cultivate believing victims, who you have been enculturated to believe “probably deserved it”.

Believe Black men–who are not super predators, but humans who are more likely than not to be victims.

Believe Native women–who are not costumes or the past, but both most likely to be harmed by any man, and still here, working for justice for EVERYONE.

Believe Black women–actually believe them, don’t just use them as a hashtag.

Believe Native men, who are probably the most likely to be killed by police.

Believe trans people. Believe queer people. Believe ace people when they tell you they are queer.

Believe disabled people, who are whole entire humans, no matter what we have been socialized to think.

Believe children.

Believe victims.

Stop believing the police. Stop believing men over women, whites over everyone, straight people over queer people, abled people above all.

Start tearing down injustice, and do that by tearing down the injustices inside you. Your assumptions.

Stop giving power to the warlords of hatred, by believing them that only their good opinion will set the rest of us free.

• @cricketcrocker

We’re all in this together§

Be charitable to everyone you come across.

Listen and believe the stories of marginalized people.

Understand that sometimes being empathetic means stepping outside your comfort zone.

Help people (especially those with privilege) to be more empathetic of others (especially those without privilege).

Help people get past labels which are different to them and thinking about others as humans similar to them.

To help us towards this understanding, Greg shared the typical formation of a Counter Strike team:

• Openers: those who explore new opportunities
• Closers: those who exploit existing opportunities
• Supports: those who provide supplementary help to openers or closers

Roles§

Openers§

Openers love to explore. Give them an unknown territory and they can come back with a map of the explored area.

Closers§

Closers love to grind. Give them a map of an explored area and they can come up with creative solutions to problems that need solving.

Supports§

Supports grease the wheels to make sure everything moves smoothly. This may be mentorship, coaching, peer reviews, etc.

Me: For Example§

For me, I’m a great opener. I love doing proof-of-concepts! I love starting new projects. I love finding undiscovered gaps within spaces.

But I’m terrible at making things great. I only get so far as good enough and then I want to move on to the next exciting problem to solve.

As an opener, I’m often seen as a leader. Our culture usually celebrates openers as the heros: the first to discover something, the first to explore somewhere, the first to whatever.

Look, if everyone was like me, if everyone was an opener, we’d have a bad time. Openers can only achieve great work when they work alongside closers. In my mind, the world should celebrate closers more, I sure need you!

Team Work§

With this mindset, it’s unfair to expect someone who is a better closer to start a project from scratch. It’s also unfair to expect someone who is a better opener to do the long-tail work on delivering a project. And so on.

To generalize this mindset, everyone has an abundance of skills to offer. How do we match complementary skills together to advance our shared mission? How do we provide the support everyone needs to be their best?

So, when I arrive at a project, I’m most interested in asking the questions:

• Who is available for doing work here?
• What role do you want to embody?
• What support do you need to be at your best?
• How do you want to be held accountable for your work?

Also sometimes, the role someone wants to embody might not be the role they embody best.

Team work is an iterative and collaborative process.

Our so-called safe space was really a comfort zone!

caution: my perspectives on safety and comfort are privileged.

What is a comfort zone?§

A comfort zone is where you are free from any _dis_comfort.

A comfort zone is where you can avoid fear, uncertainty, doubt, stress, or situational anxiety.

From The Prophet (emphasis mine):

And tell me, people of Orphalese, what have you in these houses?
And what is it you guard with fastened doors?
Have you peace, the quiet urge that reveals your power?
Have you remembrances, the glimmering arches that span the summits of the mind?
Have you beauty, that leads the heart from things fashioned of wood and stone to the holy mountain?
Tell me, have you these in your houses?
Or have you only comfort, and the lust for comfort, that stealthy thing that enters the house a guest, and then becomes a host, and then a master?

Ay, and it becomes a tamer, and with hook and scourge makes puppets of your larger desires.
Though its hands are silken, its heart is of iron.
It lulls you to sleep only to stand by your bed and jeer at the dignity of the flesh.
It makes mock of your sound senses, and lays them in thistledown like fragile vessels.
Verily the lust for comfort murders the passion of the soul, and then walks grinning in the funeral.

What is a safe space?§

A safe space is a space where violence, harassment, or hate speech against marginalized groups is not tolerated.

A place where anyone can relax and be fully self-expressed, without fear of being made to feel uncomfortable, unwelcome or challenged on account of biological sex, race/ethnicity, sexual orientation, gender identity or expression, cultural background, age, or physical or mental ability; a place where the rules guard each person’s self-respect, dignity and feelings and strongly encourage everyone to respect others. - Advocates for Youth

A safe space is where you feel seen, where you feel heard, where you feel loved, as you are.

Safety not comfort§

A safe space is not always a comfort zone!

A safe space is where you’re safe to be vulnerable, you’re encouraged to be your authentic self, you are supported for being you.

Even in the safest of spaces, people make mistakes, situations may become tense, conflicts may arise, work may be tough, it’s okay!

A safe space does not guarantee you will be free from unintended discomfort based on real challenges, but you will be free to be yourself to face those challenges!

Safe for who?§

I notice that there is a meme floating around regarding safe spaces, with a small baby of truth amongst the dirty bathwater.

Originally, safe spaces were created as a way to protect marginalized groups. This is a great idea!

However, I notice how sometimes “safe spaces” are now used as a way to punish other groups, often for mistakes due to ignorance not malice.

Extrapolated beyond reason into an infectious narrative, this becomes “political correctness gone too far”.

But amongst the unreason, there is a small nugget of truth that people aren’t able to be themselves.

People don’t feel safe when they think they will be attacked for being themselves.

Yes, this is most important for marginalized groups, where default society is not a safe space for them to be themselves.

This is also important for everyone, we all deserve to be our best authentic selves, even when we make mistakes.

How to welcome discomfort§

Our comfort is a privilege, not an entitlement.

When we stay within our comfort zone, we enable our weaknesses at the expense of hinder personal growth.

Paradoxically, to become a better person we want to choose to be uncomfortable, to face our fears directly.

To face our fears, we should be grounded in a supportive network of strength and care.

We won’t find our best self in our comfort zone, it will be found in the (sometimes uncomfortable) safe space!

Notable mentions§

• #3 of “4 Things That Struck Me After Visiting Political Spaces in 14 US Cities”
• %KfyWqTDLSWu94KtE2buU2eoKnrBajHGqw7zbphVc0Rs=.sha256)

(Art by Victor Mosquera)

How to be charitable§

The background for this terminology is in philosophy: the Principle of Charity, which says that before you argue against someone, you should build up their argument to be as strong as possible.

Applying this to a social context: before we give someone negative feedback, we should assume the best possible intentions.

We should construct the most favorable opinion of someone until proven otherwise, to regard them as innocent until proven guilty, to give them the benefit of the doubt.

The prime directive§

In the context of agile retrospectives, we see this concept as The Prime Directive:

Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.

When we assume good faith, we are able to go beyond blaming any person involved and instead focus on the systems we are in.

Signs you are not being charitable§