Creating Indicator Modules

Creating an indicator module is really just a matter of creating a regular Rust-based WebAssembly module that adheres to the contract we’ve defined. You’ve seen how to create wasm modules using Rust a number of times throughout this book, so it should be easy to get started.

To start, create a root directory that will hold a battery indicator, an animated indicator, and the host application. I chose to call my directory gims, but you can choose whatever you like. As a convenience, to allow you to run builds and tests on all subdirectories at once, you can create a new Cargo.toml in the gims directory with the following contents:

Use cargo new --lib to create the batteryindicator and animatedindicator projects, and cargo new --bin to create the pihost project.

Creating the Battery Indicator

The first indicator module we’re going to build is a battery indicator. Its operation is fairly simple: one of the sensor inputs represents the amount of battery remaining as a percentage. In response to that percentage, we’re going to control the color of a group of eight LEDs.

These LED indicators are each capable of lighting up with colors comprised of RGB components ranging from 0 through 255. The actual hardware used will be a Blinkt! module from Pimoroni, and I’ll include all the details later in case you want to go shopping for your own kits.

Its core logic will be to convert a number from 0-100 into an eight-element array with each element containing an RGB color value—think of it like an LED-based progress bar. For this indicator, we’ll divide the percentages among the LEDs and only light them up if the value is >= the base value for that LED. Figuring out the base value for each LED is simple—divide the eight LEDs by 100 and we get 12.5% per LED.

Update your lib.rs with the following code:

​①​

Create a tuple-struct to hold the three-color codes

​②​

Import the set_led function from our host

​③​

Expose the sensor_update and apply functions to the host

​④​

Core logic to convert a percentage into a set of eight color codes

​⑤​

Invoke the unsafe import in a loop to set all the LED colors on the host

With this code in place, we’re going to want to test our module before we plug it into real hardware.

Testing the Battery Indicator

Testing hardware and embedded systems is typically one of the hardest aspects of that kind of development. Pure hardware developers might want to just pull out an oscilloscope and take a look at how the current flows through your system, but this doesn’t help us test our business logic (though it could help integration test the host).

Fortunately for us, we don’t need to physically test the LEDs right now. We can assume that the host works and write unit tests for our business logic that determines which LEDs to light up and what colors to display.

This is where the pluggable modularity of WebAssembly modules starts to truly shine in the embedded and IoT space—finally giving us software developers a way to write unit tests for hardware-bound code without having to rig up elaborate Rube Goldberg machinery to our developer workstations.

This test code (at the bottom of lib.rs) just invokes the get_led_values function for some known percentages and ensures that we get the right color array in response:

You should be able to run cargo test from the root gims directory, and your tests should be invoked, showing output that looks like the following:

That’s it for the battery indicator, now let’s move on to an animated indicator.

Creating the Pulsing Indicator

We have plenty of options available for building an animated indicator. Given that our API is going to be calling apply at a fixed frame rate, it makes sense for us to use a key frame^[32] animation. Key frame animations are where you define (or interpolate) the values for an animation at given key points or frames.

Depending on your age, you might remember the pulsing light built into the front of the K.I.T.T. Pontiac from the old TV series Knight Rider. If not, then perhaps the pulsing animated visor in the heads of Cylons from Battlestar Galactica is more familiar. Using key frames, this is an incredibly easy animation to create.

Such a “pulser” could represent waiting for a command, an analysis in progress, a pending request to a remote system, or perhaps just to intimidate other robot operators in the competition.

The first thing we want to do is define the key frames. If we think of our eight-light LED strip as an array, then the key frames are actually just the index of the currently lit LED. With each successive frame, the “lit index” will move from left to right, take an additional pause on the far right, and then move back to the left again—reproducing the iconic “pulse” animation from Knight Rider and/or Battlestar Galactica.

You might be shocked by just how little code there is to write:

​①​

Define the “lit index” for each of the 16 frames

​②​

The exact same imports and exports as the previous module

​③​

Ensure that all eight LEDs are dark before we light up the key frame

​④​

Call set_led to turn on the light for the key frame

Since we’re guaranteed by the host contract that the frame value will monotonically increase, we just need to grab the modulo 16 of the frame counter to figure out which frame index is lit. We’ll also have to assume that the host will reset the frame counter before doing an overflow. Further, the host can change the speed of the pulser by modifying the frequency of apply calls without us having to modify the WebAssembly module at all.

With our two indicator modules in hand, let’s move on to building the Raspberry Pi host.