Flipped Bits

Stop Worrying and Learn to Loop-Select

2025-02-21T00:00:00+00:00

I can't seem to break from employing the loop-select! pattern. But what should merely be an intra-task concurrency primitive combining pattern matching and futures has sparked heated discussions. While I begrudgingly acknowledge there are some footguns, here I'll advocate that actor-style programming likes the loop-select! (and so should you).

Note: In my previous post, I have looked at actor-style programming from the outside. I have described my view of the preferrable public API of an actor, the influence of channels on the system architecture, and how to structure actors and full applications for "natural actor shutdown". These relate to this article, wherein I peek into the inner workings of what an actor can look like in tokio/rust.

Hang on - what's `select!`, again?🔗

The tokio::select! macro facilitates running several processes concurrently within one task. These processes can have completely different objectives, but because they run concurrently, they may share or even mutate the local variables among each other without any locks.

While the docs on the tokio::select! macro have improved massively in the last few releases, here is another attempt at a simplified description:

Start several processes, and
oversee their progress.
Whenever one finishes, determine if its output matches our expectations for it, then
- 3a: if it did not, ignore the process, and go back to 2;
- 3b: else, stop.

These processes, as you might imagine, are futures (1). Not tasks! Futures.

The select macro will (informedly) poll each future under its supervision (2). When a future is signalled to be woken, the macro will poll it (2). This is not special, it is simply how futures are run.

Finally, when a future returns Poll::Ready(T), the resulting value is matched on a user-supplied pattern (3). If the pattern does not match (3a), the macro disregards that process but continues monitoring the remaining ones. Else, all other processes (futures) are canceled (3b) and the macro evaluates to the value yielded by the future.

Example 1: Explicit shutdown requires `loop-select!`🔗

Imagine an actor which periodically sends a message into the world. This actor shall stop running only when you tell it to, via a cancellation token. No need to resort to aborting a task using JoinHandle::abort!

The core of the Beacon actor could look like this:

pub async fn event_loop<S>(mut self, token: CancellationToken, mut sink: S) -> Self
where
    S: Sink<u8> + Unpin,
    S::Error: std::fmt::Debug,
{
    let mut interval = interval(Duration::from_secs(1));
    loop {
        // First: get the next message.
        let message = select! {
            _cancellation = token.cancelled() => {
                break;
            }
            _ = interval.tick() => {
                self.0
            }
        };
        // Second: handle it.
        if let Err(error) = sink.send(message).await {
            tracing::warn!(?error, "Sink closed");
            break;
        }
        self.0 += 1;
    }
    self
}

Because the cancellation token and the interval are monitored concurrently, triggering the cancellation token will simply break the loop. If it gets cancelled while the "business logic" is running, no problem - it will simply yield immediately on the next loop iteration.

Note: This test pauses time. That's an incredibly neat feature of tests in tokio - they run in stop-time (faster than light, sometimes)!. It works by skipping over any operations which are explicitly "sleeping" (such as Interval::tick) if they are the only remaining operations right now.

Note: The trait bounds allow us to abstract over the kind of I/O resource we are actually using. It could be a TCP socket, websocket, webtransport socket, (wrapped) channel sender, or any other implementor of the futures::Sink trait. One frequent pattern is to wrap an I/O resource implementing the AsyncWrite trait by some type which then implements the Sink trait. The codec module of tokio-util simplifies this pattern.

Full example

Example 2: `loop-select!` enables Implicit Shutdown🔗

I don't think explicit shutdown is an anti-pattern, however usually I prefer implicit shutdown. Imagine an actor similar to the previous one, which collects messages from a channel and sinks them into a TCP socket. Additionally, it shall sink a specific (unchanging) message into the socket once per second.

The core of the Forwarder actor could look like this:

pub async fn event_loop<S>(self, mut rx: mpsc::Receiver<u8>, mut sink: S) -> Self
where
    S: Sink<u8> + Unpin,
    S::Error: std::fmt::Debug,
{
    let mut interval = interval(Duration::from_secs(1));
    loop {
        // First: get the next message.
        let message = select! {
            message = rx.recv() => {
                let Some(message) = message else {
                    break;
                };
                message
            }
            _ = interval.tick() => {
                PING
            }
        };
        // Second: handle it.
        if let Err(error) = sink.send(message).await {
            tracing::warn!(?error, "Sink closed");
            break;
        }
    }
    self
}

I have previously argued that "natural actor shutdown" is "best actor shutdown". Here, we exit whenever the channel is closed naturally or in the unhappy case where our socket (sink) was closed remotely, in which case we also have no more work to do. The other actors sending us messages may react to this, as they will observe the forwarders absence eventually (certainly when they try to send it something).

Full example

Footguns hiding in the dark🔗

You may have noticed I have papered over the details.

Issue #1: Cancellation Safety🔗

I stated that the futures in the competing concurrent branches of select! are simply dropped when another arm "wins". If a future already internally commits some transaction (memory, network, database, whatever) before becoming Poll::Ready, and is then dropped, the transaction will of course not be reverted. Or worse, if part of the transaction has happened, and the future is then dropped, the system may remain in an inconsistent state. Most futures in tokio are marked cancellation safe in the docs. In the ecosystem, that annotation is less pervasive. I haven't personally had problems with Cancellation Safety Violations (or am unaware), but it is something to keep in mind.

Issue #2: A hidden panic🔗

In the examples above, we used select! to produce a value of type T. And in the sequence, I have outlined how an arm will get disabled when it resolves but the pattern does not match. So what happens if all arms become disabled? A panic!.

Note: That's because a panic! is one way to create a value of type T, by creating a value of type ! (the never type). The never type is the only subtype in Rust, and it's a subtype of every other type. There is even an impl From<!> for T somewhere, among other fun shenanigans.

Here's a simple example:

    #[tokio::test]
    #[should_panic(expected = "all branches are disabled and there is no else branch")]
    async fn select_nothing() {
        let _nonono = tokio::select! {
            Some(n) = async { None } => { n },
        };
    }

To fix it in this case, you can just add a break as a select! arm:

let zero = tokio::select! {
    Some(n) = async { None } => { n },
    else => 0,
};

I like to match or let-else on the mpsc-arm of the select (there usually is one) and break there. In other cases, one may want to break from the loop-select when reading an AsyncRead returns 0 (no more bytes to be had).

Full example

Issue #3: Easy to create an infinite busy loop🔗

Imagine having an actor to collect messages from three mpsc channels (for sake of example, it's not terribly important). One could (I did) write such an event loop:

pub async fn event_loop(
    mut self,
    mut rx1: mpsc::Receiver<u8>,
    mut rx2: mpsc::Receiver<u8>,
    mut rx3: mpsc::Receiver<u8>,
) -> Self {
    loop {
        tracing::info!("waiting for message");
        // First: get the next message.
        let message = select! {
            message = rx1.recv() => {
                message
            }
            message = rx2.recv() => {
                message
            }
            message = rx3.recv() => {
                message
            }
        };
        // Second: handle it.
        tracing::info!(value = ?message, "got message");
        self.0 += 1;
    }
}

Once all channel handles have been dropped, every pattern always matches (even though it will always be None). Then, we get our useless tracing output, and finally, we start from top. I decided to include this example because busy loops like this are especially bad in an async world. The only solace offered here is that the loop is async-busy, that is, at least it does not permanently hog the CPU. It is busy in the sense that it can always run, but at least tokio won't let it suffocate the other tasks.

Full example

Issue #4: Tooling🔗

Rustfmt simply does not touch anything within a select, and Rust Analyzer also struggles with it. That's not surprising, as the syntax is obviously invalid Rust to it.

I like to take it as an incentive to create functions for all event handlers. Here's my recommended approach: in your select, only bother with message/event collection and shutdown. The select, at the start of the event loop, shall only produce a value of a type Event or similar. Then, after collecting the event, a method on_event can be called.

pub async fn event_loop(mut self, mut rx: mpsc::Receiver<Message>) -> Self {
    loop {
        // Collect some event.
        let event = select! {
            message = rx.recv() => {
                let Some(message) = message else {
                    break;
                };
                Event::Message(message)
            }
            Some((id, status)) = self.tasks.next() => {
                Event::TaskStatus(id, status)
            }
        };

        // Process the event.
        if let Err(error) = self.on_event(event) {
            warn!(?error, "Error processing event");
        }
    }

    // Await completion of remaining tasks.
    while let Some((id, status)) = self.tasks.next().await {
        if let Err(error) = self.on_task_status(id, status) {
            warn!(?error, "Error processing task status");
        }
    }

    self
}

Full example

More Actors with Tokio

2025-02-19T00:00:00+00:00

In spring 2021, when I was first submerging into tokio, a colleague and friend mentioned I should ingest this article: Actors with Tokio by Alice Ryhl. And, did I ingest it. To summarize, the article proposes an architectural style which relies on message passing (channels) and inherent parallelism (tasks) as well as concurrency (via async/.await) to neatly and safely structure applications dealing with I/O. But really, go read the article.

Alice's post shaped and will continue to shape the asynchronous designs I take part in. Unsurprisingly, I'm not the only one - everybody working with Rust in network applications and beyond seems to relate.

I have happily and successfully applied this "actor" architecture style over the last years. Over this time, I have discovered a few minor adjustments to the proposed style for improved testability and composability.

Note: It is recommended to have read the aforementioned article before reading this one. In fact, if you're gonna read one article, read Alice's article.

I believe that an actor should be its data🔗

Alice's post starts off with a recipe, briefly introducing the style by example. Although the principle remains, I suggest a few changes. In the original recipe, the actor holds its state and its receiver. What if an actor consisted solely of its plain-old-data state?

#[derive(Debug, PartialEq, Eq)]
pub struct UniqueIdService {
    next_id: u32,
}

An actor should not own channel handles or sockets or other I/O resources. It may require them as arguments for its event loop of course! But not hold them as members. Ownership is responsibility, and who is really responsible for the run-time resources of the actor? The actor's event loop (see below).

Note: Holding simple data as actor state also simplifies restarting an actor after it broke out of its event loop: all you have to do is create new runtime resources and start the event loop again.

I prefer the Event Loop as consuming method🔗

Somewhat differently to the original recipe, I prefer this particular event loop signature:

impl UniqueIdService {
    pub async fn event_loop(mut self, mut rx: mpsc::Receiver<Message>) -> Self {
        ...
    }

Notably, the event loop is a method consuming and returning Self. It can be spawned as a task, but doesn't have to.

By returning Self, we can inspect the state after the event loop finished, and even re-enter it. And, we can assert that the correct target actor state has been reached in a unit test.

I like to leave the spawning to the user🔗

The original recipe tokio::spawns the actor event loop in a helper function. But who are we to assume that particular use? One may want to:

await the end of the event loop (without spawning),
spawn, then monitor the tokio::task::JoinHandle<_>,
create the actor event loop future and put it in something like a FuturesUnordered along with its brethren, or
spawn the event loop future on a non-tokio executor.

That's not to say you should not spawn the event loop onto some kind of task. Spawning is great, and it lets an actor run free (employing parallelism) in its own little world (no foreign references, in or out).

I don't believe in actor handles🔗

The original recipe recommends to implement an actor handle type. Perhaps surprisingly, I have stopped writing actor handle types! In my opinion, actor handles paper too much over the operations on the channel handle to the actor. I feel they obscure what is actually happening and prevent us from doing cool shit. We can't

await the termination of the actor (unless we forward mpsc::Sender::closed of the underlying sender handle)
store the response futures (oneshot::Receivers) in a combinator (see unit test),
use the actor handle from a blocking context,
... much more cool shit.

In short, all the methods implemented on the mpsc::Sender are there for good reasons, but our handle is hiding them.

If you want to reduce boilerplate anyway: use associated functions on the actor (UniqueIdService) type.

/// Query for a unique id.
///
/// Returns `None` if the actor is not running.
pub async fn get_unique_id(sender: &mpsc::Sender<Message>) -> Option<oneshot::Receiver<u32>> {
    let (callback, callback_receiver) = oneshot::channel();
    let message = Message::GetUniqueId { callback };

    sender.send(message).await.ok()?;
    Some(callback_receiver)
}

Alternatively, an extension trait on mpsc::Sender<Message> achieves the same ergonomics while keeping the full sender API accessible.

I recommend to not fold in the oneshot::Receiver like in the original handle implementation!

By holding the receiver, you can collect and await it at your convenience. For an example, see the unit test.

Unit Testing the `UniqueIdService`🔗

I have found that actors which aren't easy to test hint at bad architecture. The interfaces should be clear, and all the other parties an actor talks to should not need to be mocked: the communication medium is some channel, so one only needs to create such a channel and enqueue the correct messages on it (before running the event loop, see below).

Care must be taken to not run into timing-dependent behaviour in a unit test (and please avoid at great cost situations where you put a sleep call in your test! It reeks. There is no way to ensure real-time constraints within tokio naively, so don't pretend there is by bounding the execution time of your function under test).

The actor interface as-is enables us to write a test with a deterministic order of events, because we don't need to spawn a task running your actor and then send messages to it. Instead, we enqueue the messages, then drop the sender. Only then, we await the event loop. Here we encounter "natural actor shutdown". We can assert on the resulting final state.

#[tokio::test]
async fn should_increment_unique_id() {
    let actor = UniqueIdService::new();
    let (tx, rx) = mpsc::channel(3);

    let resp1 = UniqueIdService::get_unique_id(&tx).await.unwrap();
    let resp2 = UniqueIdService::get_unique_id(&tx).await.unwrap();
    let resp3 = UniqueIdService::get_unique_id(&tx).await.unwrap();

    // Important for this test:
    drop(tx);

    let service = actor.event_loop(rx).await;

    let nums = tokio::try_join!(resp1, resp2, resp3).unwrap();
    assert_eq!(nums, (0, 1, 2));
    assert_eq!(service, UniqueIdService { next_id: 3 });
}

Note: The event loop returns Self. This means, even if you do need to spawn it, .awaiting the tokio::task::JoinHandle<UniqueIdService> yields your actor state.

Note: One should generally, but especially in tests, await the completion of tasks somehow, if only to assert they did not panic. If you can, avoid placing asserts in test-only tasks.

Full Example

Ruling out Deadlocks with Bounded Channels🔗

Attempting to send a message on a tokio bounded mpsc channel is async, because the channel might be filled to the bound. In that case, sending will "suspend" until space becomes available. This is great, because it introduces backpressure.

In normal operation, the mpsc queue compensates flow rate differences between sending and receiving. However, imagine a situation where actor A sends actor B messages, while actor B sends actor A messages:

With both channels being bounded, the queue from A to B could become filled-to-the-bound. Then, A would be blocked until B processes the next message, meaning A would process no messages. If B now sends messages to A, they would not be processed, filling the channel to the bound. Yikes! Deadlock.

This situation is bad in another way, even if the deadlock never arises. The actor cycle prevents natural actor shutdown of A and B, because there always exists a handle to each receiver. A and B are engaged in a sort of toxic nepotistic double binding.

Note: Strive for your channel topology to be a Directed Acyclic Graph (see below).

Message `enum`s are great🔗

I have not changed a thing about the message type in the original recipe, because it's timeless. Remember to make your messages own your data - don't borrow.

Note: A message is a way to transfer ownership from one actor to another, thereby transferring the responsibility to handle the data. Borrowing indicates time-coupling of components, which would defeat the purpose of autonomously running actors, so don't do it. Don't worry, if you do it, you'll end in lifetime soup and back out, anyway.

More Note: Sounds like a V-Table? Not a coincidence.

On Call-and-Response🔗

Most actors in my experience do not require and should not employ the call-response pattern demonstrated in this example. It's a sort of sync-async crossover anyway, and blocks the "calling" actor (when implemented naively). Look at the original post under the "No responses to messages" heading.Most actors I have seen simply take "Commands", i.e. messages carrying the plain-old-data to be processed. The most fun designs I have been with did not use the pattern at all, and data flowed only left-to-right. This is good for a number of reasons, notably it prevents the biggest footgun of bounded mpsc channels and facilitates automatic application shutdown.

I like "Natural Actor Shutdown"🔗

The actor scheme presented here still employs one of the most important aspects of the original design, which is "natural actor shutdown":

while let Some(message) = rx.recv().await {
    self.handle_message(message);
}

We exit when recving on the channel yields None. As per the docs, this happens when there are no more messages in the mpsc::Receiver queue, and there are no more mpsc::Senders. In this situation, all messages have been handled, and no more senders can ever be created. After exiting the event loop, but before returning from the function, an actor may run asynchronous cleanup logic (such as unsubscribing from a message broker or closing a websocket connection). After cleaning up, the event loop shall drop all runtime resources. Other actors may then realize this situation and perform their own natural shutdown.

If your entire system topology is a DAG, you can achieve graceful shutdown by dropping the "top-level handle".

Note: If the task was spawned and isn't being joined somewhere, all actor resources are dropped. This includes channel handles of other actors.

More Note: Sounds like garbage collection? Not a coincidence.

What about Explicit Shutdown?🔗

An actor should generally detect the condition where it is no longer needed and shut down by breaking out of its event loop. I prefer this over explicitly shutting down an actor. Ideally, shutdown naturally happens gracefully when each actor finishes processing and drops its actor handles. Some designs do require distributing a tokio_util::sync::CancellationToken among the components, though.

There is no Rust Actor Framework, and it's called `tokio`🔗

As a personal opinion of mine, and perhaps a spicy take: don't use an actor framework. The ones I have seen are bad abstractions over tokio::spawn and overly restrictive.

Don't make a `Heartbeat` Actor🔗

If your actor has the sole purpose of periodically announcing itself to the world, something is wrong. If all other actors in the system are stuck or bogged down slow, should that heartbeat actor still run free? No.

The only thing better than an actor: no actor🔗

If you can avoid an actor, do so. Try to delete as many actors from your design as possible. Too many times I have observed that after an initial design, by deleting stuff from it, one can arrive at a beautiful final design. If a region of your design doesn't feel right or look nice, trust your gut: try to find the root cause of the strangeness, then try to eliminate it. You may, like me, uncover corners that are incidentally complex and can be fixed. Refuse to start implementation until you understand the problem (mind the "unreasonable effectiveness of understanding the problem").

"Original OOP" (OOOP)🔗

Famously, Alan Kay "didn't have C++ in mind" when coining the term "OOP" (Object Oriented Programming). This means inheritance, overloading, and a class keyword are completely besides the point! But what did he have in mind?

OOP to me means only messaging, local retention and protection and hiding of state-process, and extreme late-binding of all things.

Alan Kay in Dr. Alan Kay on the Meaning of “Object-Oriented Programming”.

Messaging: Passing data items along channels.
local retention of state-process: in the event loop future, it's impossible to access any state. The message handler cannot be called from the outside once the event loop is running (not even if it were public).
local protection of state-process: a tokio task is a panic boundary. An actor may crash, and the crash is observable from the outside, but it is recoverable. A panic cannot poison another actors' data because a message cannot contain (non-static) references.
hiding of state-process: actor state and message handler are private (not pub).
extreme late-binding of all things: actors are bound at spawn-time to other actors via channel handles. As discussed, a sender handle with a certain message type is like a v-table. Whatever is behind it only must know the message type. This is more late-bound than even Box<dyn ...>, probably as late-bound as you can get in Rust.

Load-Bearing Oneliners in the Rust Standard Library

2022-09-14T00:00:00+00:00

The Rust language tries to be as minimal as possible. Many crucial features and design decisions aren't compiler magic, instead they live in core or other parts of the standard library. Here are some:

Shared References are `Copy` (look don't touch)🔗

The core::marker::Copy trait marks a type which can be safely copied by simply copying its bits. Think bool, f64, Duration, or SocketAddr.

A shared reference can obviously be copied. Owning a shared reference to a T, i.e., a &T, allows us to copy it.

Here's the implementation of core::marker::Copy for shared references:

/// Shared references can be copied, but mutable references *cannot*!
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Copy for &T {}

(lives at: https://doc.rust-lang.org/src/core/marker.rs.html#839)

This means, any shared reference to objects which aren't necessarily even Sized can be copied. That's why we even can call a method taking &self - copy the pointer to self, pass it to the method.

Drop-Dead Gorgeous🔗

/// --- Doc comment omitted ---
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_drop")]
pub fn drop<T>(_x: T) {}

The function drop is passed a T without any trait bounds. What can it do with a T? It cannot Clone it, cannot do Add or Neg, cannot even Display/Debug. And it isn't returning a value of T! There isn't much besides {} that would be a valid function body:

Doing unsafe things to look at T (perilous, T might not be Sized)
Looping forever
Producing a value of type Never or core::marker::Infallible (panic and friends, or std::process::exit)
Taking a shared reference to _x, converting it to a usize, and storing it in a global AtomicUsize:

static R: AtomicUsize = AtomicUsize::new(0);

pub fn drop<T>(_x: T) {
    let r = &_x;
    R.store(r as *const T as usize, Ordering::SeqCst);
}

Playground: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=5e603039ddafeac0fdd599d78a59a13e

A Platform-Agnostic Driver for EBYTE-E32 LoRa Modules

2022-05-10T00:00:00+00:00

Radio communication is not easy, right? Well, unless it's complexities are hidden from us. That's why the nice people of Ebyte have built the E32 Modules. These modules allow for easy serial-based LoRa communication. Under the hood, they use the SX1278 modules which give us lots of power. Wouldn't it be nice to have a Rust driver for those easy to use modules?

Rust Driver🔗

Pretty bog-standard implementation of a driver that uses embedded-hal. Provided with a couple GPIOs and a serial port, this driver will expose the functions read and write from embedded-hal.

For checking if you wired everything up correctly, you can get the model data as a nice rusty struct. For configuration, there are some nice data structures for all the different parameters and options the chip provides (different baud rates for UART and radio transmission, error correction, transmission power, of course channel and address, and some more). You can just inspect the settings of the chip, or store new ones temporarily or persistently.

The implementation is scrutinized with mocking, proptests, and mutation tests. Also, it includes my first load-bearing usage of declarative macros.

Ebyte E32 Rust Driver on GitHub

Demo Project (bare metal, STM32F411 Black Pill)🔗

To be found here

CLI and graphical user interfaces for testing🔗

Project here

The parameter types inside the driver optionally implement the clap::ValueEnum derive macro behind the feature gate "value_enum" (which also requires std). This means, the enums can be used as part of a CLI! And, using the super powers of klask, this CLI can be turned into a GUI. See this project for how that goes! (I should probably blog about it).

Sneak peek:

Blocking Operation🔗

All operations are blocking, of course... Should be changed when embedded-hal becomes async or somehow supports non-blocking operation better than with nb (technically, you could do non-blocking implementation now - nb::Result gives you a WouldBlock which you could work with).

Module Graph🔗

Reduced Dependency Graph🔗

Prior Work🔗

Thanks for your inspiration!

How to Communicate Failure in Rust

2022-05-05T00:00:00+00:00

Basics explained well in this blog post: Rust Error Handling.

The linked blog post shows how to manually create boxed errors and error enums.

Boxed Errors🔗

Use boxed errors if you have a very wide set of sources which could produce errors (wide as in, many crates or many modules). Why? Because boxing an error is simple, but makes it harder to handle for the layer above you.

Error Enums🔗

A custom error enum is the way to go if you want the user of the code you are working on to be able to check what exactly failed. You do have to create an enum variant for all the different error conditions. These could carry data, like source errors, backtraces, or even the input that caused the error (see e.g. SendError).

Apps vs. Libs?🔗

In many cases, applications use boxed errors and libs use error enums. But there are also counterexamples. I personally like error enums quite a bit, but this is a question of ergonomics, API design, and maybe taste.

Gee, that's lots of typing for both approaches. It doesn't have to be!🔗

The anyhow is even nicer than the "Boxed-Error" pattern and not too expensive to use.

For error enums, the thiserror crate does all the manual work for you, and you get a nice way to declare your error codes that is completely invisible from outside of your crate or module.

Example Application (with GUI!)🔗

See error-safari for some examples of both approaches.

More Realistic Examples Please!🔗

A realistic usage of anyhow: achat, a simple demo of different ways to implement network applications with tokio.

Some realistic usages of thiserror can be found here:

pils, a simple lisp implementation inspired by Build Your Own LISP
(Silly code) famous-last-words
(Silly code) Deutsche Bahn Delay Reasons

A Platform-Agnostic Driver for the CD74HC4067

2021-03-21T00:00:00+00:00

To read 16 analog values, one might use 16 pins with ADCs. But depending on the required update rates and the available pins, this might be impossible.

Instead, a simple 74HC4067 could be used. It connects 1 of 16 analog IO lines to 1 signal line, depending on the 4 select pins. The only thing to look out for is to disable the chip with the disable signal before changing the select pins to avoid activating an unwanted line during switching.

The 74HC4067 driver described in this post requires just a couple embedded-hal GPIO pins. It ensures that the multiplexer is disabled during the changing of the channel and makes no assumptions about what happens with the I/O pin.

Why make such a simple driver?🔗

It is a simple driver for very simple hardware, yes. But any repetition saved is code and bugs saved!

Additionally, this code serves as a good demonstration of testing using embedded-hal-mock and measuring test coverage using tarpaulin. And it serves as an example of type-state programming, it's advantages, and also ergonomics pitfalls.

Example usage🔗

This code will activate random inputs. Working code for this on stm32f0 target can be found here.

let mut delay = Delay::new(/* snip */);

let gpioa = dp.GPIOA.split(/* snip */);

let (pin_0, pin_1, pin_2, pin_3, pin_enable) = disable_interrupts(|cs| {
    (
        gpioa.pa0.into_push_pull_output(cs).downgrade(),
        gpioa.pa1.into_push_pull_output(cs).downgrade(),
        gpioa.pa4.into_push_pull_output(cs).downgrade(),
        gpioa.pa8.into_push_pull_output(cs).downgrade(),
        gpioa.pa7.into_push_pull_output(cs).downgrade(),
    )
});

let mut on_for = |duration: u32,
                  pin: u8,
                  mut hc: Cd74hc4067<
    Pin<Output<PushPull>>,
    Pin<Output<PushPull>>,
    DisabledState,
>| {
    hc.set_channel_active(pin as u8).debugless_unwrap();
    let enabled = hc.enable().debugless_unwrap();

    delay.delay_ms(duration);

    enabled.disable().debugless_unwrap()
};

let mut disabled =
    cd74hc4067::Cd74hc4067::new(pin_0, pin_1, pin_2, pin_3, pin_enable).debugless_unwrap();

let mut rng = RNG::<WyRand, u8>::new(0xDEADBEEF);

let delay_time_ms: u32 = 2000;
loop {
    let generated: u8 = rng.generate_range(0, 15);
    disabled = on_for(delay_time_ms, generated, disabled);
}

Advantages of Typestate Programming🔗

The chip starts out in disabled mode
The select pins can only be changed while the chip is disabled
Once the chip is enabled, it must be disabled before anything can be done to it

Cumbersome usage due to Typestate Programming🔗

The driver implementation relies on typestate programming for implementing the state transitions. There are only 2 states, and the driver toggles between them as required. In the EnabledState, the multiplexer is active, and the active output channel cannot be changed. In the DisabledState, the multiplexer is not active, and the output channel can be selected.

This makes the usage a little bit cumbersome, but it ensures that the driver can only be used safely while remaining efficient.

Line Coverage and PhantomData🔗

While writing unit tests while keeping an eye on the line coverage, I noticed that some lines would not be covered - and for a really good reason! PhantomData markers are used in the code to disambiguate disabled and enabled states. These markers are compile-time-only constructs - hence, line coverage cannot ever include them. Neat.

See here: coverage.pdf.

A Platform-Agnostic driver for the HC12 serial radio module

2021-03-21T00:00:00+00:00

If only a serial port could be used without having to deal with cables! The HC12 serial radio module enables just this super power. It connects to a normal serial port, sending and receiving data to/from another hc12 module.

The baud rate, transmission power, channel, and some other properties can be configured over the same serial interface, using simple AT commands. To disambiguate the normal mode from the configuration mode, a digital signal is used.

In this blog post, I introduce a simple embedded-hal driver for the hc12 module. It requires a serial interface, a delay implementation, and a digital pin.

Type-state is used to disambiguate the modes of operation: normal mode, configuration mode, and sleeping mode. In normal mode, the driver instance can simply be used like any other serial device (with the Read and Write methods of the embedded-hal Serial trait).

Usage example🔗

Full code here. This example makes a driver instance, queries a few parameters, then sends a basic string over the hc12 repeatedly.

let uart = Uart::new(9600, Parity::None, 8, 1).unwrap();

let set_pin = Gpio::new().unwrap().get(18).unwrap().into_output();

let hc12 = hc12_at::hc12::Hc12::new(uart, set_pin, linux_embedded_hal::Delay);

let mut hc12 = match hc12.into_configuration_mode().unwrap();

assert!(hc12.is_ok());

let mut buffer = [0u8; 64];
let result = hc12.get_version(&mut buffer);
println!("{:?}", std::str::from_utf8(&result).unwrap());

let params = hc12.get_parameters().unwrap();

println!("{:#?}", params);

println!("{:?}", params.get_air_baud_rate());

println!(
    "{:?}",
    params.get_air_baud_rate().get_wireless_sensitivity_dbm()
);

let mut hc12 = match hc12.into_normal_mode().unwrap();

loop {
    hc12.write_buffer(b"hello hc12\r\n").unwrap();
    thread::sleep(Duration::from_millis(500));
}

Configuration🔗

The baudrate, radio channel, radio mode, and transmission power can be configured using AT commands. To get the current configuration, the API function get_params can be used.

Only some combinations of settings are valid though - the API should protect from misconfiguration.

To get the air baud rate and the wireless sensitivity as specified in the datasheet, API functions get_air_baud_rate and get_wireless_sensitivity_dbm can be used.

Fourier Transform of Cosine Function

2018-08-08T00:00:00+00:00

The Fourier transform maps a signal to its frequency spectrum, denoting exactly at which amplitude a given frequency appears in the signal. The underlying assumption is that any signal out there can be decomposed in to an infinite sum of trigonometric functions with varying amplitude, phase, and frequency. But what happens if one of the most basic functions, the cosine itself, is transformed?

Prerequisites and Notation🔗

I will use

$\widehat{f}$

to refer to the Fourier Transform of

$f$

I will use the following definition of the Fourier transform:

Let

$f \in L_2(\mathbb{R})$

be a signal. Then:

$\widehat{f}(\xi) = \int_{-\infty}^{\infty}f(t)e^{-i\xi t}dt$

Transforming the Cosine Function🔗

Plugging the Cosine into the definition of the Fourier Transform🔗

$\widehat{(cos)}(\xi) = \int_{-\infty}^{\infty}cos(t)e^{-i\xi t}dt = \\ \int_{-\infty}^{\infty}\frac{e^{it}+e^{-it}}{2}e^{-i\xi t}dt = \\ \frac{1}{2}\int_{-\infty}^{\infty}e^{it}e^{-i\xi t}dt + \frac{1}{2}\int_{-\infty}^{\infty}e^{-it}e^{-i\xi t}dt = \\ \frac{1}{2}\int_{-\infty}^{\infty}e^{it(1-\xi)}dt + \frac{1}{2}\int_{-\infty}^{\infty}e^{-it(1-\xi)}dt = \\ \frac{1}{2}\int_{-\infty}^{\infty}e^{-it(\xi-1)}dt + \frac{1}{2}\int_{-\infty}^{\infty}e^{-it(1-\xi)}dt = \\ \frac{1}{2}\int_{-\infty}^{\infty}1 e^{-it(\xi-1)}dt + \frac{1}{2}\int_{-\infty}^{\infty}1 e^{-it(1-\xi)}dt = \\ \frac{1}{2}\widehat{1}(\xi-1) + \frac{1}{2}\widehat{1}(1-\xi)$

So we see that the spectrum of the cosine is comprised of two other certain spectra, which are shifted in time.

But what is the fourier transform of 1?🔗

This can be approached using intuition. Given that the value of the spectrum of a function at frequency

$\xi = 0$

is equal to the mean of the function:

$\widehat{1}(0) = \int_{-\infty}^{\infty}1dt = \infty$

We can conclude that our spectrum is infinite at 0. But what about the rest of the function?

The 1-function does not have any other spectral components - it is boring and flat, completely defined without any frequency components other than 0.

A function that is infinite at 0 and 0 everywhere else - sounds familiar? The Dirac Impulse function!

$\delta(t) = \begin{cases} 0, & t \lt 0 \\ \infty, & t = 0 \\ 0, & t \gt 0 \end{cases}$

So, now that we have the transform of the 1-function (albeit the derivation was rather hand-wavy), we can state the fourier transform of the cosine function.

Final Result🔗

$\frac{1}{2}\widehat{1}(\xi-1) + \frac{1}{2}\widehat{1}(1-\xi) = \\ \frac{1}{2}\delta(\xi-1) + \frac{1}{2}\delta(1-\xi)$

The result: Two Impulses, one at 1, one at -1, suffice to describe the spectrum of the cosine function!

What about Cosine Functions with different Frequencies?🔗

A cosine can be given for any frequency by scaling it:

$cos(a*t)$

where

$a \in \mathbb{R}$

denotes the desired frequency. We can write this using the scaling operator

$\sigma_{a} f(\cdot) = f(a\cdot)$

. If we scale a function like that, we can try to imagine what will happen to the spectrum of the function: if we increase the frequency (

$a \gt 1$

), we stretch the spectrum to accomodate the higher spectral components, and if we decrease the frequency (

$a \lt 1$

), we compress the spectrum because there are now lower spectral components. Stated mathematically:

$\sigma_{a}\widehat{f} = \frac{1}{a}\widehat{f}(\frac{\xi}{a})$

Applying this to the Cosine yields:

$\sigma_{a}\widehat{cos} = \frac{1}{a}\widehat{cos}(\frac{\xi}{a}) = \\ \frac{1}{a}\frac{1}{2}\delta(\frac{\xi-1}{a}) + \frac{1}{a}\frac{1}{2}\delta(\frac{1-\xi}{a})$

As one might expect, transforming cosines of differing frequencies shifts the impulses around to the corresponding spectral frequencies.

Impulse Response and Transfer Function

2018-07-08T00:00:00+00:00

Applying filters to signals is one of the most important applications of mathematics in signal processing. But with all the Fourier transforms, Convolutions, and various properties like causality, time-invariance, linearity... It can get confusing. In this post, I want to clarify the relationship between a filter, it's impulse response and transfer function, and why applying a filter is the same as convoluting a transformed signal with an impulse response. Don't worry, it will sound less intimidating in the end.

Prerequisites and Notation🔗

I will use

$\widehat{c}$

to refer to the Fourier Transform of

$c$

(and

$(c + d)\hat{ }$

for the transform of larger terms). Conversely, I will use the inverted hat for the inverse of the Fourier Transform:

$c(t) = (\widehat{c}(\cdot))\vee(t)$

To denote the Convolution of signals

$c$

and

$d$

, I will use

$c \ast d$

The raw definitions are (incomplete for brevity):

Let

$c \in l_2(\mathbb{Z})$

be a signal. Then:

$\widehat{c}(\xi) = \sum_{k \in \mathbb{Z}}c(k)e^{-i\xi k}$

Let

$c, d \in l_2(\mathbb{Z})$

. Then:

$(c \ast d)(\tau) = \sum_{k \in \mathbb{Z}}c(\tau - k)d(k)$

A fundamental theorem in Signal Processing is the Convolution Theorem:

Let

$c, d \in l_2(\mathbb{Z})$

. Then:

$\widehat{(c \ast d)}(\xi) = \widehat{c}(\xi)\widehat{d}(\xi)$

The proof is included here for completeness, however it is not particularly important for the rest of the post, so feel free to skip it:

$\def\colonequals{:=} \widehat{(c \ast d)}(\xi) = \\ \sum_{k \in \mathbb{Z}}(c \ast d)(k)e^{-i\xi k}= \\ \sum_{k \in \mathbb{Z}}\sum_{s\in\mathbb{Z}}c(k-s)d(s) e^{-i\xi k}=\\ \sum_{k \in \mathbb{Z}}\sum_{s\in\mathbb{Z}}c(k-s)d(s) e^{-i\xi (k-s+s)}=\\ \sum_{k \in \mathbb{Z}}\sum_{s\in\mathbb{Z}}c(k-s)d(s) e^{-i\xi (k-s)}e^{-i\xi s}=\\ \sum_{k \in \mathbb{Z}}\sum_{s\in\mathbb{Z}}c(k-s)e^{-i\xi (k-s)}d(s) e^{-i\xi s}=\\ \sum_{s \in \mathbb{Z}}\sum_{k\in\mathbb{Z}}c(k-s)e^{-i\xi (k-s)}d(s) e^{-i\xi s}=\\ \sum_{s \in \mathbb{Z}}d(s) e^{-i\xi s}\sum_{k\in\mathbb{Z}}c(k-s)e^{-i\xi (k-s)}\\ \kappa\colonequals k-s;\\ \sum_{s \in \mathbb{Z}}d(s) e^{-i\xi s}\sum_{\kappa\in\mathbb{Z}}c(\kappa)e^{-i\xi \kappa}=\\ \sum_{\kappa\in\mathbb{Z}}c(\kappa)e^{-i\xi \kappa}\sum_{s \in \mathbb{Z}}d(s) e^{-i\xi s}=\\ \widehat{c}(\xi)\widehat{d}(\xi)$

What's a Filter?🔗

A filter is just a vector of some length N (or function on some interval), where we interpret the values as coefficients of the filter. The vector of filter coefficients will be called a "filter window" from here on.

Filtering a signal can be achieved like this:

for each sample:
    place the window on the signal, such that the sample is at the window center
    for each value of the window:
        multiply the value with the corresponding signal sample
        add the result to an accumulator A
    
    set the value of the center sample to the value of A

(This explanation is probably very engineer-like and insufficient for mathematicians. What can I do.)

A simple example: set all values of the filter to

$1/N$

. Then a sample in a filtered signal is the arithmetic mean of the samples around it, removing high-frequency content.

Properties of Filters🔗

Notice the filter coefficients in the previous example where

$1/N$

. Otherwise, we might modify the energy of the signal. Obviously, you don't want a filtered signal to be amplified or diminished. This kind of filter is called "Energy-Preserving".

There are many more properties, one of which is linearity. A linear filter has the property that you can apply it to a sum of signals and get the same result as applying it to each signal individually and then summing the result. Put in another way:

Let

$c, d \in l_2(\mathbb{Z})$

and

$a, b \in \mathbb{R}$

. Then:

$F(ac+bd) = aFc + bFd$

This property will become important later.

The Unit Impulse and why it is important🔗

The Unit Impulse function (or dirac delta) is... not actually a function, but a distribution. However, we will treat it as the following function here:

$\delta(t) = \begin{cases} 0, & t \lt 0 \\ 1, & t = 0 \\ 0, & t \gt 0 \end{cases}$

The impulse contains frequencies from every wavelength with the same amplitude. Intuitively, it is a "bang", like a gunshot. It's Fourier Transform is... just

$1$

$\widehat{\delta}(\xi) = \int_{-\infty}^{\infty}\delta (t)e^{-i\xi t}dt = 1$

In other words, we can get a unit impulse by summing up cosines of ever-increasing frequency. So what happens if we apply a filter to a unit impulse? Well, by the linearity property stated above, that would be the same as applying the filter to each of the frequencies the unit impulse is comprised of - which is, all of them. You read that right - with the unit impulse, we can see what a filter does to ANY frequency. Does it diminish high frequency? Only the low frequencies from the impulse get through. Is there a band that the filter attenuates? Those frequencies will be dimmed in the result. By the way, the result of applying a filter to a unit impulse is aptly called the "Impulse Response".

Now, let's think about the Fourier Transform of an impulse response. The impulse response contains every frequency with the amplitude that the filter permits for this frequency. So it's spectral content directly displays how the filter behaves for a given frequency.

I will denote the impulse response

$F\delta$

of a filter

$F$

with

$f$

Convolution and Filter Application🔗

Now let's clarify why applying filters can be achieved by Convolution. The best explanation I found is rather mathematical, but somewhat easy to understand.

First, let's look at a signal

$c$

in a slightly contrived way:

$c(\cdot) = \sum_{k \in \mathbb{Z}}c(k)\delta(\cdot-k)$

Equivalently, where

$\tau_{s}c(\cdot) = c(\cdot + s)$

$c(\cdot) = \sum_{k \in \mathbb{Z}}c(k)\tau_{-k}\delta$

Which is to say: you can picture a signal at a point as a unit impulse shifted to exactly that point multiplied with the entire signal.

Now let's see what happens if we apply a filter

$F$

to that signal and simplify the result.

$Fc(\cdot) = F\Big[\sum_{k \in \mathbb{Z}}c(k)\tau_{-k}\delta\Big] = \\ \sum_{k \in \mathbb{Z}}c(k)F[\tau_{-k}\delta] = \\ \sum_{k \in \mathbb{Z}}c(k)\tau_{-k}F\delta = \\ \sum_{k \in \mathbb{Z}}c(k)\tau_{-k}f = \\ \sum_{k \in \mathbb{Z}}c(k)f(\cdot - k) = \\ (c \ast f)(\cdot)$

And there you have it! Applying a filter to a signal is the same as multiplying the transformed signal with the transfer function and taking the inverse Fourier Transform of the result:

$Fc(t) = (c \ast f)(t) = (\hat{c}\hat{f})\vee(t)$

Statements and Expressions in Rust

2018-06-16T00:00:00+00:00

In this post, we will explore how Rust distinguishes between expressions and statements. Even though this distinction seems very theoretical, it has wide-ranging implications on the Rust language and (in my opinion) is a beautiful detail of Rust.

Terms and Conditions🔗

What do I mean by expressions and statements?

Arithmetic terms like (a + 3) / 2, or a condition (a & !b) | (!a & b) are expressions. Evaluating them yields some (non-empty-)value like 3 or true. This is what functional programmers mean when they say their whole program is basically one large mathematical term which is evaluated. It is important to note that evaluating an expression in this mode of thinking has no effect on the outside world, or 'context'.

To interact with the world, we need statements. A statement could be motor.drive(100), where drive(int) is a void function which changes the context such that something in the real world reflects this effect (like writing to an output port).

What's in a '{}'-Block?🔗

Languages like C and Java use curly braces to denote scope. In Rust, curly braces mark a scope too, but they can also evaluate to a value. This value can be empty '()', though. Let's see some examples:

// Standard C if statement
if (some_condition) {
    some_action();
}

// Slightly different syntax for Rust
if some_condition {
    some_action();
}

The syntax appears very similar, but this is a false lookalike: we can evaluate expressions in blocks.

let a = if some_condition {
    some_action()
} else {
    3
};

This is a very structured solution to the frequent problem of conditionally assigning/binding values to variables.

It should be noted that a semicolon suppresses the value of an expression. This is why we do not have semicola after 3 or some_action(), but after the last curly brace.

Retiring the Ternary Operator🔗

This C shorthand for an if-else-block as expression:

int val = 5;
int result = val < 10 ? 10 : val;

does not require special syntax in Rust.

let val = 5;
let result = if val < 10 { 10 } else { val };

Note that in the Rust snippet, each branch of the if statement evaluates to a number.

The Point of 'No Return'🔗

Using the return keyword is discouraged sometimes in the Rust community. It makes no difference for the program, but omitting it fits better with the 'Everything is an Expression' mode of thinking. This becomes apparent when looking at the following examples, which may look scary for some C programmers.

// C function that simply returns some value
int some_function(int x) {
    return x + 3;
}

The exit point of a C function often is a 'return', reminding us that in the background, the stack is restored and control is given to the caller.

// In Rust, the 'return' is unnecessary, since the function body is an expression.
fn some_function(x: u32) -> u32 {
    x + 3
}

// A void function in Rust
// Note: function actually returns '()', which is value of expression 'x + 3;'
fn some_void_func(x: u32) {
    x + 3; // < note the semicolon
}

// Note: the 'return' keyword can still be used for early returns
fn early_return(num: u8) -> u8 {
    if num == 3 {
        return 0
    }
    ...
}

Unary incr/decrement Confusion🔗

The standard way to increment a variable in C:

int x = 10;
// Both expression (evaluates to 10) and statement (increments x).
x++;
// Same here, except expression evaluates to 12 now.
++x;

In Rust, this works differently:

let mut x = 10;
//x++ // not possible
x += 1;

This prevents such C chaos:

int c = 0;
// What does this evaluate to?
int d = ++c + c++;
// and this?
int e = ++c + c++ + c;

Switch-Case is no Match for Patterns🔗

Pattern matching in Rust takes advantage of expression blocks quite beautifully:

let choice = 17;
let is_sparta = true;

let result = match choice {
    0 => "zero for u",
    1...9 => "choice not great",
    i if i % 2 == 1 => "larger than or equal 11, and odd",
    42 => "u r n4rd",
    300 => {
        if is_sparta {
            "This is Sparta!"
        } else {
            "This is not Sparta!"
        }
    }
    _ => "larger than or equal 10, and even",
}; // < semicolon needed, because this expression binds to 'result'

Every match arm must evaluate to the same type (&str here). The match arm can be any expression in a block that eventually evaluates to a &str. The patterns must be exhaustive! This is like switch/case on steroids.

Let's if let🔗

To destructure enums using if let is useful for ergonomic error handling with algebraic error types(Option, Result):

    let number: Option<i32> = Some(8);

    if let Some(8) = number {
        println!("Option contained an eight!");
    }

    if let Some(i) = number {
        println!("Matched {:?}!", i);
    } else {
        println!("Option contained None!");
    };

This works with any pattern, on enums, structs, and tuples.

How the Rust Compiler prevents mistakes

2018-06-04T00:00:00+00:00

When learning about Rust for the first time, one is confronted with words like 'double free', 'data race', and 'dangling pointer'. Without an understanding of these problems, the safety aspects of Rust are perhaps difficult to appreciate. However, Rust aims to appeal not only to systems programmers(where these kinds of problems are well-known), but developers from any background! It is perfectly fine to write high-level Rust code without knowing what a data race is (that is the freedom Rust grants) but understanding the underlying issue makes the compiler error messages more understandable.

To explain some of the problems Rust solves, I have collected examples to show and explain specific problems and see what rustc("the Rust complainer") has to say about them.

Let's start simple: Dereferencing Null Pointers🔗

When Tony Hoare finished implementing ALGOL 60 in 1965, he couldn't know that he would be apologizing for one of its concepts 44 years later: at '09 QCon in London, he called null pointers a 'billion dollar mistake.'

Languages since have picked up variations of the concept. For example, Java has no pointers accessible to the programmer, yet it has a NullPointerException.

Let's look at a simple C example of a null pointer dereference:

#include <stdio.h>

int main() {
    // Reading and writing to a NULL pointer results in undefined behavior.
    int *ptr = NULL;
    *ptr     = 10;
    printf("%d", *ptr);
}

We create a pointer to an int with the value of NULL. When we try to write to that location, a SIGSEGV happens to happen on my machine and setup, but dereferencing a NULL pointer is undefined behavior, meaning that anything could happen.

How does this look in Rust? Simply put, safe Rust has no null references. There is no way to express this in safe Rust.

There is always unsafe:

use std::ptr;

fn main() {
    let pointer: *mut u32 = ptr::null_mut();
    unsafe {
        *pointer = 10;
    }
    unsafe {
        println!("{}", *pointer);
    }
}

With this code, I happen to get a SIGSEGV, too.

And now for something more interesting: Free of 'use-after-free'🔗

Unlike many other languages, we have to explicitly request and release our memory from/to the operating system when working with C. Those actions still happen when using Java, Python, or Haskell, but they happen automatically in the background. This is safe (because it is automatic), and it is very comfortable for the programmer. However, such garbage collection has a cost, which is out of scope for this article but frequently discussed.

Managing memory manually (like it is done in most systems programming languages) is a difficult problem because we have to ensure that:

all allocated memory is free()'d (no memory leaks)
memory that was free()'d before is never reused (no use-after-free)
memory is free()'d exactly once in all code paths of the program (no double free)

If we fail to do this, our program might crash, or worse, it might corrupt data anywhere or present opportunities to attackers.

The free function in C deallocates previously allocated blocks of memory, but it does not invalidate our pointer to that memory - we can still use it:

#include <stdio.h>
#include <stdlib.h>

#define BUF_SIZE 16

int main() {
    puts("Enter your name!");
    char *buffer = malloc(BUF_SIZE);

    fgets(buffer, BUF_SIZE, stdin);
    printf("buffer: %s\n", buffer);
    free(buffer);

    // reusing dangling pointer into heap
    fgets(buffer, BUF_SIZE, stdin);
    printf("buffer after free: %s\n", buffer);
}

We allocate a 16-byte block, which we then pass to the fgets function to read user input. After printing that input, we free the buffer. Nothing in the C language stops us from using that pointer again!

Let's see what this would look like in Rust:

use std::io::BufRead;

fn main() {
    println!("Enter your name!");
    let stdin = std::io::stdin();
    let buffer = stdin.lock().lines().next().unwrap().unwrap();

    drop(buffer);

    println!("buffer: {}", buffer);
}

All the Rust compiler has to say is:

error[E0382]: use of moved value: `buffer`
  --> use_after_free.rs:10:28
   |
8  |     drop(buffer);
   |                    ------ value moved here
9  |
10 |     println!("buffer: {}", buffer);
   |                            ^^^^^^ value used here after move
   |
   = note: move occurs because `buffer` has type `std::string::String`, which does not implement the `Copy` trait

The error message uses some Rust-specific language (move? Copy trait?), but it is pretty clear: ownership of the buffer is moved into drop(), after which the buffer is not usable.

It is important to note that the drop function is used rarely in Rust. That is because every object is destructed automatically at the point where its owner's scope ends (which is known at compile time).

Regardless, the function exists, and it is one of the most beautiful functions in the standard library:

pub fn drop<T>(_x: T) { }

That's all they wrote: take ownership of an _x of an unconstrained type T, and go out of scope, resulting in the deterministic deconstruction of _x.

But what about `std::move`?🔗

Modern C++ introduced moving ownership. The move constructor invalidates the old owner in some agreed-upon way, even if the object is const. After the move, the old pointer may still be used (but that is not a good idea!).

#include <iostream>
#include <string>
#include <vector>

using namespace std;

int main() {
    string origin = "This is a string.";

    vector<std::string> vec;

    // Copy origin and append to vec
    vec.push_back(origin);

    cout << "After pushing origin copy onto vec, origin is unchanged: \"" << origin << "\"\n";

    // Move origin into vec, invalidating origin variable (at runtime)
    vec.push_back(std::move(origin));

    cout << "After move into vec, origin is invalidated: \"" << origin << "\"\n";

    cout << "Contents of vec: \"" << vec[0] << "\", \"" << vec[1] << "\"\n";
}

Note that a moved-from object (that is not trivially destructible) still has to be destroyed: http://www.drdobbs.com/cpp/why-moving-an-object-does-not-destroy-th/231601451

Rust has moves and ownership baked deep into the language:

fn main() {
    let mut origin: String = "This is a string".into();

    let moved = origin;

    println!("origin after move: {}", origin);
    println!("moved  after move: {}", moved);

    // Binding that was moved out from can be reassigned
    origin = "Hello, I'm back!".into();
    println!("origin after reassignment: {}", origin);
}

The Rust compiler comments:

error[E0382]: use of moved value: `origin`
 --> use_after_move_var.rs:6:39
  |
4 |     let moved = origin;
  |         ----- value moved here
5 |
6 |     println!("origin after move: {}", origin);
  |                                       ^^^^^^ value used here after move
  |
  = note: move occurs because `origin` has type `std::string::String`, which does not implement the `Copy` trait

Types implementing the Copy-trait are similar to 'primitive datatypes' in java. They are passed by value (or 'by copy'). But copying is a quick operation only for a few basic types! For any other type, the explicit clone method can be used, if the type implements the Clone trait. This is unlike C++, where an implicit copy of an object often occurs, without any special syntax.

The Many Kinds Of Dangling Pointers🔗

Dangling Pointer Into Heap🔗

In C-like languages, we can use the addresses of objects on the heap or stack directly. This is powerful, but it means we have to be cautious about the memory at the other end of a pointer:

#include "stdlib.h"
#include "stdio.h"

#define BUFFER_SIZE 16

int main() {
    int *array = malloc(BUFFER_SIZE * sizeof(int));
    for (size_t index = 0; index < BUFFER_SIZE; index++) {
        array[index] = index;
    }
    // Take a pointer into the heap-allocated array
    int *ptr = &array[6];

    // at this point, ptr becomes a dangling pointer
    free(array);

    printf("%d's array has been set free!\n", *ptr);
    *ptr = 3;
    printf("array[6] was modified to %d after being free'd!\n", *ptr);
}

This program allocates a buffer on the heap, creates a pointer into that buffer, then frees the buffer. However, the pointer still exists! That is a dangling pointer into the heap. Let's reconstruct this in Rust:

fn main() {
    let mut array = Vec::new();
    for index in 0..10 {
        array.push(index as u32);
    }

    // Take a pointer into the heap-allocated array
    let reference = &mut array[6];

    // at this point, reference would become a dangling pointer
    drop(array);

    println!("{}'s array has been set free!", *reference);
    *reference = 3;
    println!("array[6] was modified to {} after being free'd!", *reference);
}

The compiler interjects! Error message:

error[E0505]: cannot move out of `array` because it is borrowed
  --> dangling_pointer_heap.rs:11:20
   |
8  |     let reference = &mut array[6];
   |                          ----- borrow of `array` occurs here
...
11 |     drop(array);
   |                    ^^^^^ move out of `array` occurs here

The message is clear. How dare we move the ownership of the variable array to drop if we still have borrowed it to reference?

Capturing Closures🔗

Closures are anonymous functions which can capture variables from their originating scope. Therefore, if we create a string variable some_string and a closure some_closure in one scope, we can use some_string from some_closure. Closures would be pointless if we could not pass them around different scopes! That is dangerous, though:

#include <iostream>
#include <functional>

using namespace std;

function<int(int)> get_lambda_with_local_reference(int index) {
    int local_arr[] = { 1, 2, 3, 4, 5 };
    return [&](int value) { return value + local_arr[index]; };
}

int main() {
    // This function returns a lambda which internally keeps a pointer to a local array.
    // Of course, when using the returned lambda, the array does not exist anymore.
    function<int(int)> function = get_lambda_with_local_reference(2);
    cout << "lambda uses stack-local reference:" << function(6) << endl;
}

The function get_lambda_with_local_reference will return a function<int(int)>, which is a lambda that takes and returns an int. That function is defined in the last line of get_lambda_with_local_reference as returning the sum of its argument and the element at index index of an array defined in the same (stack frame) scope. When we return the lambda, this array goes out of scope. When we call it, the lambda dereferences some random value from the stack (at best).

Same story in Rust:

// This function returns a closure with a pointer to a stack-local array.
fn get_lambda_with_local_reference(index: usize) -> impl Fn(i32) -> i32 {
    let local_arr = [1, 2, 3];
    |value| value + local_arr[index]
}

// Moving the stack-local array into the returned closure is fine.
fn get_lambda_with_moved_reference(index: usize) -> impl Fn(i32) -> i32 {
    let local_arr = [1, 2, 3];
    move |value| value + local_arr[index]
}

fn main() {
    let function = get_lambda_with_local_reference(2);
    println!("lambda uses stack-local reference: {}", function(6));
}

The Rust Complainer says NO:

error[E0373]: closure may outlive the current function, but it borrows `local_arr`, which is owned by the current function
 --> dangling_pointer_closure.rs:5:5
  |
5 |     |value| value + local_arr[index]
  |     ^^^^^^^         --------- `local_arr` is borrowed here
  |     |
  |     may outlive borrowed value `local_arr`
help: to force the closure to take ownership of `local_arr` (and any other referenced variables), use the `move` keyword
  |
5 |     move |value| value + local_arr[index]
  |     ^^^^^^^^^^^^

rustc also suggests how to fix the problem, as seen in the function get_lambda_with_moved_reference.

More dangling pointers🔗

You can find more examples of less interesting dangling pointers here.

Crossing Boundaries or: yet another 'Billion Dollar Mistake'🔗

For performance reasons, the creators of the C language used raw pointers to memory blocks as array types. After creating an array, it's size has to be tracked manually, often by something like #define BUF_SIZE 256. Array access by index, like arr[115], happens without checking bounds. One could check manually. Similarly, strings (which are just char pointers) always end with a \0-byte. The performance benefits come with a price - it is incredibly easy to make a mistake:

#define BUFFER_SIZE 15

/* Compile with -fno-stack-protector for real fun */
int main() {
    int buffer[BUFFER_SIZE];
    for (int index = 0; index <= BUFFER_SIZE; index++) {
        buffer[index] = index;
        // or equivalently, but more explicit:
        *(buffer + index) = index;
    }
}

Just one character too much - the '=' in the for loop exit condition causes our index to reach one element past the buffer boundaries. This is easy to catch. But there are other possible buffer overruns which are even in the C library:

#include <stdio.h>
#include <string.h>

#define BUFFER_SIZE 16

/* Compile with -fno-stack-protector for full effect */
int main() {
    // gets is a hazardous function, and gcc even warns when using it.
    // Here, gets overwrites a part of the stack when a long text is entered on stdin,
    // possibly corrupting a variable that comes after the input buffer on the stack.
    char buffer[BUFFER_SIZE];
    int password = 0;

    printf("Enter password:\n");
    gets(buffer);

    if (strcmp(buffer, "pass123") == 0) {
        printf("Correct password\n");
        password = 1;
    } else {
        printf("Wrong password\n");
    }
    if (password) {
        printf("Privileged access granted!!!\n");
    }
}

Writing a string into the buffer that is larger than the buffer can corrupt the password flag and grant us privileged access! And yes, you should not use gets, as the compiler may tell us here. So, let's use fgets, but hide a mistake in our code:

#include <stdio.h>
#include <string.h>

#define BUFFER_SIZE 16

/* Compile with -fno-stack-protector */
int main() {
    // fgets is somewhat better than gets. But one can still use it wrong.
    char buffer[BUFFER_SIZE - 5];
    int password = 0;

    printf("Enter password:\n");
    fgets(buffer, BUFFER_SIZE, stdin);

    if (strcmp(buffer, "pass123") == 0) {
        printf("Correct password\n");
        password = 1;
    } else {
        printf("Wrong password\n");
    }
    if (password) {
        printf("Privileged access granted!!!\n");
    }
}

The fundamental problem is that the array size is unknown. There may be a performance advantage to not having those runtime index bounds checks, but modern LLVM is good at optimizing those away. Either way, bounds checks should be an opt-out feature for critical loops, not an opt-in by manually coding them in my opinion.

Obligatory Rust example:

use std::io::{self, BufRead};

fn main() {
    let array = [1, 2, 3, 4, 5, 6, 7, 8, 9];
    for index in 0..10 {
        println!("{}", array[index]);
    }
}

This code panics with 'index out of bounds' at runtime. Rust cannot catch that kind of bug at compile time (it is hard to catch in the general case)!

The Real Fun Stuff: Access to Shared Data🔗

Data races can happen if these 3 conditions are met: (1) multiple parts of a program have access to the same memory (sharing), (2) at least one of them writes to the shared data (mutation), and (3) there is no mechanism in place to ensure proper order of transactions (synchronization).

To wrap everything in mutexes and semaphores is one viable option, but Rust offers a safer and faster option: ensuring the first 2 conditions are never true at the same time. This is what "Sharing XOR mutation" means: either many processes read, or at most one writes. It turns out the borrow checker that ensures memory errors never happen also prevents many issues arising from shared access to resources because there is always a clear owner and it is known if and how data is shared.

Here is what a multithreaded C++ program could look like:

#include <iostream>
#include <thread>

struct Account {
    int balance{ 100 };
};

void transferMoney(int amount, Account &from, Account &to) {
    using namespace std::chrono_literals;
    if (from.balance >= amount) {
        from.balance -= amount;
        std::this_thread::sleep_for(1ns);
        to.balance += amount;
    }
}

void printSum(Account &a1, Account &a2) {
    std::cout << (a1.balance + a2.balance) << std::endl;
}

int main() {
    Account     account1;
    Account     account2;
    std::thread thr1(transferMoney, 50, std::ref(account1), std::ref(account2));
    std::thread thr2(transferMoney, 130, std::ref(account2), std::ref(account1));

    thr1.join();
    thr2.join();

    std::cout << "account1.balance: " << account1.balance << std::endl;
    std::cout << "account2.balance: " << account2.balance << std::endl;

    std::cout << std::endl;
}

We give the data race some time to occur. What happens is not deterministic, but the second transaction is sometimes just swallowed by the void. We have met all 3 of the above conditions!

To fix the problem, we might use an atomic type for balance, however, not even cppcheck or clang-tidy warn us here.

Translating the same to Rust:

#[derive(Debug)]
struct Account {
    balance: u32,
}

impl Account {
    fn transfer_money_to(&mut self, amount: u32, mut to: Account) {
        if self.balance >= amount {
            self.balance -= amount;
            std::thread::sleep(std::time::Duration::from_millis(1));
            to.balance += amount;
        }
    }

    fn new(initial: u32) -> Self {
        Account {
            balance: initial,
        }
    }
}

fn main() {
    let mut account1 = Account::new(100);
    let mut account2 = Account::new(100);

    let child1 = std::thread::spawn(|| {
        account1.transfer_money_to(50, account2)
    });

    let child2 = std::thread::spawn(|| {
        account2.transfer_money_to(130, account1)
    });

    child1.join();
    child2.join();

    println!("{:?}\n{:?}", account1, account2);
}

The error message here is quite long because there are so many mistakes from the Rust compiler's point of view.

More examples🔗

A few more examples can be found here.

A solution for C and C++: great linters🔗

The cppcheck and clang-tidy have heuristics for many of the problems listed here. Often, their explanation of the problem is excellent, as well.

Object-Oriented Arduino interrupts: using C++ Friend Functions

2018-01-07T00:00:00+00:00

Most Arduino users won't ever need interrupts or even C++/OOP for that matter. But for writing a nice object-oriented library or advancing your programming skills, both are very interesting subjects. But they clash somewhat: an interrupt is basically a global function that takes no arguments (not even C++-this) and returns no value, either. It is not called by the main program like regular functions, but instead runs when it is triggered by an external signal, like a pin logic voltage level change. This idea has no place in an OOP (let alone functional!) world - what object does the function belong to? It is global and cannot see or modify anything but static data, and the fact that it does not take arguments makes it impossible to call this function with method syntax. If this is confusing, don't worry: in C++, a function knows which object it belongs to by the implicit, invisible argument this. If it is still confusing, don't worry - it doesn't really matter. It just means that interrupts and OOP do not mix well.

Unless...

C++ Friend Functions🔗

A Friend Function is a function that can be at global scope (i.e. not belonging to a class) but still retain private access to all members of a specified class as if it was a member of that class. This class has to declare the function as a friend. Now, this function can be registered as interrupt!

There is one tiny ugly thing that remains: to access private members of a class instance, this instance has to be known by the interrupt. This can be done by having a global pointer to a class instance which is valid for the lifetime of the instance. If you attach your interrupts and set this pointer in your constructor you should be fine. Remember to detach the interrupts and set the pointer to NULL or nullptr in the destructor, if this applies to your program.

Example Code: Simple library to interface an Arduino or Teensy device to an RC Receiver🔗

Here is the code:

For a possibly more up-to-date version: github repo.

Programming the Teensy 3.2 using a makefile

2017-11-21T00:00:00+00:00

The Arduino toolchain is a good starting point. So many libraries, most of them fine quality, and the editor allows you to write incorrect C++ so you can have a simpler life...

Wait, what? That's right, the Arduino IDE does a lot of stuff to compile your program that usually does not happen in the standard C++ compilation procedure. For example, the IDE generates function prototypes for you, so that you can write your functions in whichever order you like. This alone is iffy for some. But it also automatically includes header files needed for your libraries, making the entire process rather opaque. This would have been reason enough for me to look into doing it differently, but really the elephant in the room that needed changing was the poor, often belittled Arduino IDE. The IDE simply does not do the toolchain justice.

Benefits from using Make🔗

Goals:

Use any editor and just run shell commands (or press buttons)
Compile and flash the program immediately after checking out from version control, not having to set up Arduino
Do syntax highlighting and completion based on local files
Symbol lookup (go to definition, find usage) and all the vim/IDE/ctags goodness.

The Easy Part: Using Someone Else's Makefile🔗

In this repo, GitHub user apmorton has prepared a working makefile. Only tiny adjustments are needed in the provided makefile, like setting desired clock frequency, setting Teensy version and enabling more compiler warning flags :)

The Hard Part: Getting Existing Code to Compile (... and run...)🔗

I had used numerous Arduino libraries in my existing project. Here it became apparent how much the Arduino IDE actually did in the backgound - after including the libraries, there was a large wall of compiler warnings and errors. Most of them can be fixed:

If it is a missing (undeclared) function:
- Looking up the header file it should be located in using google or man pages
- Looking for that header file in ./teensy3 or ./tools using ripgrep or similar
- Including that file, and seeing if that at least removes the error
- When all errors are fixed, taking a hard look at all the included code, and whether it actually does the desired job
If the issue are duplicate function definitions:
- Difficult one. You need to find out which of the functions to use and then comment out or guard (with a preprocessor definition) the others definition.
Else:
- Tough luck, you are on your own...

The Hardest Part: Fixing Remaining Issues When The Program Compiles Fine🔗

It is likely that after compiling with only few errors, the program still has different behaviour than when running under Arduino IDE... In my case, example code from I2Cdevlib was not setting an interrupt pin's pinMode and thus the interrupts were ignored when not using the IDE. Presumably, the IDE does some special magic to fix this up, I don't know. Setting the pinMode fixed this.

Good Luck!

P.S. there is an even harder part - keeping the toolchain up to date. Using platformio can fix this and get you all the benefits, but there is something to be appreciated about just running make flash...

Remote Control vehicle balance controller

2017-11-05T00:00:00+00:00

In this article, I want to present a PID-based multi-purpose balance controller that runs on the Teensy 3.2 board using Arduino libraries. It can control PWM-based actuators like servos or LEDs and electronic speed controllers driving brushless motors. This control is based on an external signal like the output from an RC receiver, and the output of an inertial measurement unit.

That means you can use this controller to stabilise or balance small vehicles like planes, multicopters, VTOLs, hydrofoils, hovercraft, or rockets...

To get the most use out of this article, you should have a basic understanding about PID, standard RC components like ESCs (electronic speed controllers), brushless motors, RX/TX, and some C/C++ programming skills.

Why use PID for balance control?🔗

A PID controller governs a system so that the difference between a setpoint and a measured value is minimized, effectively driving our system to where we want it to be. Note that anything measurable and 'steerable' (that is at least somewhat linear) can be fed into a PID controller, like temperature, position, altitude, force... Using an IMU (Inertial Measurement Unit) to give us our measurement, we can generate an output signal that depends on the attitude and angular velocity of our system.

In quadcopters, planes, and many other vehicle types, we have to constantly monitor and manipulate the attitude, thrust, velocity and similar parameters to achieve the desired result. To influence those parameters, there are control surfaces, levers or propellers/jets which inflict forces on our craft in any necessary degree of freedom.

Those propellers and levers generally control rates too - rate of rotation, rate of climb, etc. That makes them ideal for being governed by a PID controller.

Cascaded PID🔗

It is useful to use not only one but two PID controllers because the sensor output from the gyroscope is way faster than the output from the sensor fusion algorithm that fuses gyroscope and accelerometer data and produces an accurate attitude estimation. Gyroscope data drifts only over time, whereas accelerometer data does not drift but is subject to high-frequency noise. We can cascade the controllers: the first loop receives the setpoint interpreted as attitude and the currently most accurate estimation of the attitude and produces a needed angular rate as a result. This rate is fed into another loop as setpoint, and this rate loop receives the faster angular rate readings from the gyroscope directly. If the second loop executes more often, then it will ensure that the overall loop rate is fast and not limited by the time it takes to fuse the IMU data.

The setpoint can either be interpreted as a desired absolute angle or as a desired angular rate. In the first case, the PID controller will attempt to stabilize the craft to this angle, whereas in the second case, it will try to rotate the vehicle at the given rate. This is known as 'rate mode' or 'acro mode' in some flight controllers.

To achieve 'rate mode', the attitude loop simply needs to be ignored. A constant input on the roll stick of a plane in rate mode would result in a continuous roll, or a multicopter yaw stick would control the rate of z-rotation of the copter. In 'stabilize mode', a constant stick deviation is mapped to a constant vehicle deviation.

Hardware🔗

I am using a Teensy 3.2 as the brains. It has an ARM Cortex M4 chip that can be overclocked to 120MHz which is more than sufficient for this control task. The board also has plenty of GPIO pins and can tolerate a wide range of supply voltages (such as 5V from a standard RC electronic speed controller) with its internal voltage regulator.

As IMU sensor, I previously used the widely available and familiar MPU6050. This sensor offers measurement of absolute orientation as well as angular rates from the gyroscope and provides data moderately quickly using the I2C protocol. But now I am using Kris Winers EM-SENtral-based 'Ultimate Fusion Solution' which has proven to be extremely fast and accurate, if a bit expensive. The sample rate for accelerometers and gyroscopes is set 1kHz for now. The proprietary sensor fusion in the SENtral processor reacts extremely quick to changes in angular position. I chose to let the sensors do their fusion for now because it is initially very simple, but I would like to use one of the newer Invensense sensors (ICM-20608, ICM-40602) and implement my own Kalman/Madgwick filter at some point. The ICM-40602 improves on the previous generation mostly in energy consumption, which is completely irrelevant in this case.

As basic peripheral hardware (actuators), any standard ESCs, servos and TX/RX combo using PWM should work.

Four simple steps🔗

Here are the steps that need to be done to stabilize and control:

Read input from the RC receiver
Read sensor values from IMU
Calculate PID response with those measurements as input
Write the result to the connected actuators, using predefined weights

Reading input from the receiver🔗

The receiver sends pulses of varying on-time corresponding to the stick positions to our board. Using interrupts, we can measure the time passing between a rising edge and a falling edge of one signal, which should always be roughly within 1000us and 2000us (RC standard). We can simply hook an interrupt to each input pin, log the system time on a rising flank, and calculate the duration in microseconds since rising flank when the signal is falling again. The code for this is in src/PWMReceiver.cpp. PPM, which is conceptually similar but needs only one wire, is also implemented in src/PPMReceiver.cpp. All receiver interfaces should implement virtual functions in include/Receiver.h.

Race Copters, Not Conditions🔗

The duration measurement from our interrupt routines is written each time the interrupt routine executes on a falling edge. That means, we have to be careful when reading those values! I used shared volatile variables which are written to by the interrupts to store the measurements. The main loop copies the data to variables which it can use undisturbed. This way, it is always clear that the interrupt writes while the main loop reads the shared variables. When the variables are read, no interrupts are allowed since they might overwrite the values while reading them, violating the 'sharing XOR mutability' principle and thus inviting race conditions.

For a really good description on how to read RC receiver PPM output, have look at this excellent article by Ryan Boland. He explains it better than I will ever be able to - and with oscilloscope screenshots!

Read sensor values from IMU🔗

Reading the measurements and computation results from the 'Ultimate IMU Solution' is done in a similar way like in Kris Winers example program, however I adapted large parts to skip software sensor fusion and provide an object-oriented interface to the sensor.

Calculate PID response🔗

This is where the magic happens, but it is actually very simple. The PID algorithm in this discrete form (really the one everyone uses) is short and sweet, using the "poor man's derivative (-)" and the "poor man's integral (+)". Some smoothing is applied to the D term (if enabled), but I am unsure if this is actually beneficial.

I adapted some ideas presented in Brett Beauregard's series "Improving the beginners PID"

Eventually, PID coefficients will depend on the currently chosen mode (if I get to the implementation).

Write result to connected actuators🔗

The output is basically finished. It only needs to be scaled a bit and then written out using the various output methods defined in src/ESCOutput.cpp, src/ServoOutput.cpp and src/FastPWMOutput.cpp. Eventually, this will need more work: depending on the current flight mode, output mixer volumes will have to be chosen for each output channel. Possible parameters for the output channel mixers are throttle, roll/pitch/yaw attitude PID output, roll/pitch/yaw rate output, rate/stabilize mode, and even motor type (servo/ESC).

This is basically a Matrix-vector multiplication. Each output is the weighted sum of the RC inputs and the PID controlling values in each axis. Since we have 8 outputs and 8+3 (currently) values that influence them, there are 8 rows and 11 columns in our matrix. The input vector consists of 8 receiver inputs + 3 PID control values. The i-th row of the matrix consists of the weights for each output for the j-th control value.

This is a bit complex, but essentially it allows us to say: "This output reacts to the throttle stick with a factor of 0.8, and to the yaw pid value with a factor of 0.1." Additionally, we can store a matrix for each flight mode, and transition from one matrix to the next smoothly while transitioning flight modes.

Where is the catch? Well, none of this is implemented... The matrix multiplication part can be done in under a microsecond(!) on the teensy 3.5 using the capabilities of the Cortex M4. That is an interesting challenge and I hope I will get to it.

All of this depends on getting the PID and IMU and Output implementations to work with 16 bit fixed-point numbers, and never floats.

Give me the Code!🔗

The code can be found at https://github.com/barafael/raPID

Further Ideas/Inspiration🔗

I am thinking about allowing for several different flight/operation modes which consist mostly of a set of PID-coefficients and settings for mixers on each actuator output. A mixer would control how much impact each PID output should have on each actuator output.

Transitioning between flight modes could interpolate the values of the two mixers so that modes transition smoothly into each other.

If this transitional flight mode interpolation sounds familiar to you, it might be because of OpenAeroVTOL. It runs (really well) on the Hobbyking KK2.1.5 Multi-Rotor LCD Flight Control Board.

There is active and friendly support on the RCgroups forums, and it is often stated that this board is able to stabilize almost anything small-scale. However, development is confined by the hardware used (who knows for how long HK will be making the kk-board), the development style (code drops on release by the single author every couple months), and the word 'VTOL' in the name. It would be nice to really have a general controller not for just one niche, sacrificing some features (Tailsitter option, Heli-style rotor control) for a more general approach (also with more than the 3 flight modes which OAV has). Additionally, OAV does not support a derivative gain (the D in PID), arguing that this form of feedback is unnecessary for vehicles that naturally have a high damping factor due to having a higher mass or large wings. The accuracy of this statement is debatable, and to provide a more general approach a D gain is nice to have (if only for meta-stable systems or niche cases like multicopters).

Another feature of OAV is that it can entirely be configured via the onboard LCD screen (that is a miracle, really). Since version 1.5, you may also use (exclusively) Microsoft Excel to configure it, using a macro-based GUI in .xlsx format (yes, really). I am not at the point to even think about this by a long shot, but it would be nice to have a graphical configuration interface on a computer that can set options on the board over a serial or even wireless connection.

Nice error handling with Arduino blinking LED patterns

2017-10-31T00:00:00+00:00

Errors (not human errors, but literally error conditions) can happen very quickly even in simple Arduino projects. For example, an external library might sometimes fail to load data from memory due to unreliable hardware (like with the MPU6050). In this case, if you have a serial connection, you might see the error description printed there. But what if you have no serial connection because you are using your board without having a computer connected?

Using the LED and blinking in different patterns is not a great solution, because you have to know or find out what the patterns mean, but it is often the best solution available (and real hardware manufacturers often choose the same method!). In this blog post, I want to show a simple and somewhat elegant way to do this.

Here is the code:

Pretty self-explanatory! If you haven't worked with header files (like error_handling.h) before: they are really simple. Before your code gets turned into binary for the Arduino, the content of the header file is placed at it's corresponding #include. Simple as that. This way, we can define our error handling functions without cluttering our main program. The header file must be in the same directory as the main sketch. You can rename the main sketch, but if you rename the header file, you must also remember to change it's #include for the new header name.

Exploring the precision of floating-point numbers

2017-10-10T00:00:00+00:00

In this blogpost, Fabien Sanglard explains how floating point numbers are generally displayed in modern computers (using the IEEE754 Norm). His alternative perspective using buckets and offsets is brilliant and explains a fact that may be overlooked when using the standard explanation: the accuracy of floating point numbers declines with a factor of 2 by each bucket! That is because the same 'amount' of numbers is dispersed in any bucket, but the size of the bucket doubles every time.

I wanted to empirically show this and wrote this short C program:

One reason Unions are useful🔗

This program uses a C union. Unions allow you to use the same memory for multiple members, and every time you write one member, it also changes the others. This may seem useless, but it is not. In this case, it allows you to write to memory using the memory representation of float, while reading the same content of memory as individual bits. The union has 2 members, one allowing to write and read a float, the other resembling the bit pattern of a float as defined in the IEEE754 Norm. After writing to the float, you can read and manipulate the exponent and mantissa from the embedded struct.

Printing any memory content as binary [print_any(content pointer, size)]🔗

Casting the pointer to the memory content to a byte pointer (uint8_t *) allows us to index individual bytes. To access individual bits, we need to generate a bit mask for each of them. We simply start at 0b1000 0000 and keep shifting left while using the index to access a single bit and print it. Since the bit at position n will still be interpreted as being of value 2^n we need to check if it is set and print a 1 if this is the case, hence the ternary operator.

We need this function to inspect a floating point number.

Floating point numbers are discrete, too... [increase_float(content)]🔗

We imagine floats as being very fine-grained. That is exactly what they are - they do not allow for arbitrary accuracy, they are not what mathematicians would call dense.

That means, we can take a float and increase it by exactly one tiny amount, yielding the next-larger float in that bucket! That is what the function increase_float does.

We construct a float_parts union using the float as content. Then, we look at the mantissa: if it is filled to the brim, we reset it to 0 and increase the exponent by one. Otherwise, we simply increase the mantissa.

Putting it together: How accuracy declines with growing exponent [print_accuracy(low, high)]🔗

Here we keep increasing a float, and when the 'step size' changes, we log it. We also print the factor between the last and the current step size.

This function runs way faster than I expected for some reason - it visits every float there is between low and high.

There you have it! Empirical demonstration of how inaccurate floats (and doubles, just later) really are.

VIM has no keyboard shortcuts

2017-10-08T00:00:00+00:00

In this StackOverflow post, a question about the 'Most productive Vim keyboard shortcut' sparks a long discussion about Vim and productivity. In this answer, titled 'Your problem with Vim is that you don't grok vi.' which is easily one of the most influential pieces of Vim documentation and intro material on the internet, user Jim Dennis takes the question apart and shows how Vim is not about shortcuts but about a language for manipulating text. If you read and understood this answer, you probably don't need to read this post here, since it is just my personal take on the Vim philosophy.

'Shortcuts' and Vim🔗

A shortcut in any other program is like a certain event that causes the program to do a certain action. Like F5 in a browser or CTRL+D in most terminals.

In Sublime Text, there is a shortcut to delete a line: CTRL+UP+K. This cannot be remembered easily, involves CTRL, is generally hard to do and impossible with just one hand (yes, I know there is also CTRL+X). In Vim, the same action happens on dd. This seems arbitrary too, but actually it fits well into the rest of the vim language, where 'd' means to delete something and a double tap means to apply an action on an entire line. Moreover, this command can be combined with others as in a real programming language and has the side effect of storing the line in some register. This is not a shortcut, but an action from the language that makes up the way you manipulate text in vim.

Actions and Macros🔗

The fact that actions in vim can be randomly made up on the fly indefinitely, and combined with each other, is already very powerful. But there are even more benefits: since a text edit is just a sequence of characters constituting the action, the use of a macro is simply recording and playing back such a sequence of characters. Because vim is awesome, it stores a macro in some register (bearing the name you gave to the macro) so you can easily access, save for later, or modify the actions a macro does. You can also call a macro from itself for multi-line edits - to vim it is simply a long chain of characters that it must interpret. Macros can be nested - you can call a macro b from within macro a since macro invocation is only a sequence of characters. Finally, it is easy to parameterize macros with register contents.

For example, you might have a macro 'a' that finds a word matching a certain pattern and yanks it to register 'w', and then calls a macro 'b' which finds another word and substitutes the contents of the 'w' register. This could be done with regex back references, but to do it with macros in vim feels much cleaner to me - it is like programming with functions.

Why all the ramble about Macros?🔗

Because all the other text editors which use shortcuts cannot really do this and that is precisely the benefit of not having shortcuts, duh!

Initial Commit

2017-10-02T00:00:00+00:00

This is a simple Jekyll-powered blog. I intend this blog to be a log of interesting things I come across while programming, studying math, or attempting to make hardware do things.

Negating the minimum representable number in twos complement

2017-03-10T00:00:00+00:00

Usually, we expect that negating a number yields a number which is of the same absolute value, but with a flipped sign. However, there is a curious behaviour in many programming languages where this property does not hold for one special case. You might have come across this if you (like me) tried to (mis)use a constant Integer.MIN_VALUE (or somesuch) to simulate something like negative infinity. For example, this could be useful in a min-max algorithm with alpha-beta pruning.

What's the issue?!🔗

If you negate the lowest representable int in (for example) java, you could expect it to become Integer.MAX_VALUE. This however, is literally far from the truth! Instead, you get... Integer.MIN_VALUE again. How the flip did that happen?

In order to explain this behaviour, we have to dig a bit deeper into the way signed integer numbers are represented in memory:

Two's Complement🔗

If you already know how Two's Complement works, just skip this. If not, here is a short explanation:

In order to represent both positive and negative numbers, we need to somehow account for the sign of the number we are representing. This can be done in multiple ways, but Two's Complement has emerged as the most successful approach. Basically, numbers are still just binary strings of bits, but the Most Significant Bit (MSB) (the bit representing the largest power of 2) counts negatively. For example, if we have the 8-bit binary number 0001 0011, 19 in decimal, everything is normal because the MSB is zero. The number 1001 0011 however would be interpreted as (-128) + 16 + 2 + 1, -109 in decimal.

Determining the sign of a number becomes very simple: if the MSB is set, the number is negative. Zero is represented as 0000 0000, negative one as 1111 1111 (the other 7 bits are needed to offset the large 'negative weight'), and the largest positive number is 0111 1111.

Negating a Number in Two's Complement and Ranges of Representable Numbers🔗

The lowest representable number in Two's Complement is 2^(Place of MSB), while the largest number is only 2^(Place of MSB) - 1. That is because the positive numbers also need to include zero.

Negating a number in Two's Complement is easy using this 'hand rule': start at the right (Least Significant Bit LSB) and copy all zeroes and the first one. Then, invert the rest.

Bringing it together🔗

Now we have everything that is needed to understand the behaviour shown above where -a = a (with 'a' being some negative number). There are actually at least two ways to understand it, the first one involving the display range and the other involving the 'hand rule'.

If you invert the lowest representable number with the hand rule, you don't find a '1' until the very end. That means, you copy it and don't invert anything! Or, using number ranges: the positive range is one less than the negative range, which means that the lowest number simply cannot be inverted without exactly one overflow! Which means, we end up at the place we started.

Flipped Bits

Stop Worrying and Learn to Loop-Select

Hang on - what's select!, again?🔗

Example 1: Explicit shutdown requires loop-select!🔗

Example 2: loop-select! enables Implicit Shutdown🔗

Footguns hiding in the dark🔗

Issue #1: Cancellation Safety🔗

Issue #2: A hidden panic🔗

Issue #3: Easy to create an infinite busy loop🔗

Issue #4: Tooling🔗

More Actors with Tokio

I believe that an actor should be its data🔗

I prefer the Event Loop as consuming method🔗

I like to leave the spawning to the user🔗

I don't believe in actor handles🔗

Unit Testing the UniqueIdService🔗

Ruling out Deadlocks with Bounded Channels🔗

Message enums are great🔗

On Call-and-Response🔗

I like "Natural Actor Shutdown"🔗

What about Explicit Shutdown?🔗

There is no Rust Actor Framework, and it's called tokio🔗

Don't make a Heartbeat Actor🔗

The only thing better than an actor: no actor🔗

"Original OOP" (OOOP)🔗

Load-Bearing Oneliners in the Rust Standard Library

Shared References are Copy (look don't touch)🔗

Drop-Dead Gorgeous🔗

A Platform-Agnostic Driver for EBYTE-E32 LoRa Modules

Rust Driver🔗

Demo Project (bare metal, STM32F411 Black Pill)🔗

CLI and graphical user interfaces for testing🔗

Blocking Operation🔗

Module Graph🔗

Reduced Dependency Graph🔗

Prior Work🔗

How to Communicate Failure in Rust

Boxed Errors🔗

Error Enums🔗

Apps vs. Libs?🔗

Gee, that's lots of typing for both approaches. It doesn't have to be!🔗

Example Application (with GUI!)🔗

More Realistic Examples Please!🔗

A Platform-Agnostic Driver for the CD74HC4067

Why make such a simple driver?🔗

Example usage🔗

Advantages of Typestate Programming🔗

Cumbersome usage due to Typestate Programming🔗

Line Coverage and PhantomData🔗

A Platform-Agnostic driver for the HC12 serial radio module

Usage example🔗

Configuration🔗

Fourier Transform of Cosine Function

Prerequisites and Notation🔗

Transforming the Cosine Function🔗

Plugging the Cosine into the definition of the Fourier Transform🔗

But what is the fourier transform of 1?🔗

Final Result🔗

What about Cosine Functions with different Frequencies?🔗

Impulse Response and Transfer Function

Prerequisites and Notation🔗

What's a Filter?🔗

Properties of Filters🔗

The Unit Impulse and why it is important🔗

Convolution and Filter Application🔗

Statements and Expressions in Rust

Terms and Conditions🔗

What's in a '{}'-Block?🔗

Retiring the Ternary Operator🔗

The Point of 'No Return'🔗

Unary incr/decrement Confusion🔗

Switch-Case is no Match for Patterns🔗

Let's if let🔗

How the Rust Compiler prevents mistakes

Let's start simple: Dereferencing Null Pointers🔗

And now for something more interesting: Free of 'use-after-free'🔗

But what about std::move?🔗

The Many Kinds Of Dangling Pointers🔗

Dangling Pointer Into Heap🔗

Capturing Closures🔗

Hang on - what's `select!`, again?🔗

Example 1: Explicit shutdown requires `loop-select!`🔗

Example 2: `loop-select!` enables Implicit Shutdown🔗

Unit Testing the `UniqueIdService`🔗

Message `enum`s are great🔗

There is no Rust Actor Framework, and it's called `tokio`🔗

Don't make a `Heartbeat` Actor🔗

Shared References are `Copy` (look don't touch)🔗

But what about `std::move`?🔗