Hosting Indicator Modules on a Raspberry Pi

To build an application that resides on a Raspberry Pi (but that we can test on our workstations) that hosts our indicator modules, we’ll need to employ a few techniques that we haven’t covered in this book yet. The requirements for our Generic Indicator Module System are as follows:

• Load a WebAssembly module at launch and immediately run, controlling LEDs

• Enforce a fixed frame rate for animated modules

• Trap the SIGINT and SIGTERM signals, gracefully turning off active LEDs before shutdown

• Hot Reloading—if a new module is copied into a monitored location, pause, then load the new module and continue

The application is designed to start and continue running forever, constantly getting new sensor inputs (though we’re only faking one sensor) and feeding that data to the indicator module. To make all of this work, you’ll get into some new Rust patterns like using multi-threaded code, channels, and conditional compilation.

Creating a Raspberry Pi Application

In the previous section, you created an empty application called pihost. At the moment there’s nothing special that you need to do to make this application suitable for a Raspberry Pi. We do need to pick some dependencies—crates that will help us monitor the file system, read and execute WebAssembly modules, respond to OS signals, and operate the Blinkt hardware module. This is a Cargo.toml that pulls in those dependencies:

This is the first time you’ve seen conditional compilation in action. The highlighted lines will only include the blinkt dependency when you’re compiling for the ARM architecture.

Watching for New Modules

There are a number of mission-critical tasks in the application and, as you’ll see, coordinating them can be really tricky. Thankfully Rust makes it pretty easy. The first task is monitoring the file system and then letting the main module runner know that it needs to reload a module. The following two functions make that possible:

​①​

Creates a multi-producer, single-consumer communication channel

​②​

Block the receive channel until a message arrives

​③​

Send a message on the channel, indicating that we should reload the WebAssembly module

In Rust, multi-producer-single-consumer (mpsc) channels are used as a safe way to communicate between threads. In the case of the watch function, the main thread sits in a loop, awaiting file system notifications from the monitored directory. When we see the NoticeWrite event, it’s time to tell another thread to reload the module from disk.

Creating the Module Runner Thread

In the last section, you saw code that sends a message on a channel to tell another thread to reload a WebAssembly module. In this section, you’ll create that main thread. This thread has a number of jobs. It obviously needs to listen for the RunnerCommand::Reload message, but it also needs to handle the RunnerCommand::Stop message (which it will get from us monitoring OS signals). It also needs to invoke methods on the module itself, setting the fake sensor input value and calling apply to take care of animations.

This is where it would be so much easier to throw up our hands and walk away. Juggling file system monitoring, two different threads, signal trapping, and ensuring a consistent frame rate in the WebAssembly module sounds as complicated as dealing with the three-body problem.^[34]

Luckily, there’s a solution that doesn’t require creating yet another coordination thread. Instead, we can use the timeout feature of channel receives. If we wait for the inverse of the frame rate in milliseconds for a message to arrive, and no messages comes, then we can invoke the apply function on the WebAssembly module. For example, if we want to enforce 20fps, then we would set our receive timeout delay to 50 milliseconds. For a frame rate of 10fps, we’d set the delay to 100 milliseconds, which actually produces a pretty good effect on the Blinkt hardware.

Let’s take a look at the code for the main function (anything from the wasm module is code that we’ll write shortly):

​①​

Enforce the frame rate with a 100ms timeout value on receive

​②​

Send channels can be cloned, hence their presence in the multi-producer module

​③​

Use the ctrlc crate to trap SIGTERM and SIGINT, sending a Stop command in response

​④​

The watch function blocks the main thread with an infinite loop

Creating the WebAssembly Module Runtime

Let’s create the wasm.rs module that was referenced by the previous set of code:

​①​

Conditionally add Blinkt to the module’s scope

​②​

Conditionally add a blinkt field to the Runtime struct

​③​

The apply function will have an index of 0.

​④​

The set_led function is the only one exported by the host/imported by the module

Most of this should look pretty familiar to you as a lot of it is just the boilerplate required to load the WebAssembly module, resolve its imports, and allow function calls.

You may have noticed one interesting thing: because of the conditional compilation, there are actually multiple functions with the same name. If we are building for ARM, then the Runtime struct gets an extra field called blinkt and the set_led function uses that field to control real hardware, whereas the “regular” version of that struct and function just emit debug text to the console.

Running the Application

To run the application on your workstation, just build the binary and execute it or type cargo run. This will launch the application and it will load the module at /home/kevin/indicators/indicator.wasm (feel free to change that location to suit your needs).

Running on a Mac, Windows, or Linux, you’ll see some console output spam as the module tells the host what LEDs to light up 10 times per second (the following is output from the animated pulse indicator):

Here I’ve tested the signal handling capabilities and the application shut down nicely in response to a Control-C. Next, we can try this out on real hardware.