← all posts

Teaching Rust to talk to a fingerprint sensor

RustEmbedded

The AS608 is a five-dollar fingerprint module you can find on any electronics marketplace. It ships with a Windows demo tool, a PDF datasheet full of translation artifacts, and exactly zero good libraries for embedded Rust. So I wrote one.

The module talks over UART at 57600 baud. That part is easy. The hard part is that everything above the wire is a bespoke binary protocol, and the only authoritative description of it is a datasheet that was clearly translated twice on its way to me. This is a post about reading that datasheet so you don’t have to.

Every message is a packet

The AS608 never speaks in bare bytes. Every command and every response is wrapped in the same frame: a fixed header, the module address, a packet identifier, a length, the payload, and a checksum. Once you model the frame properly, the rest of the driver is just filling in payloads.

const START: u16 = 0xEF01;

struct Packet {
    address: u32,   // default 0xFFFFFFFF
    kind: u8,       // 0x01 command, 0x02 data, 0x07 ack
    payload: Vec<u8>,
}

impl Packet {
    fn to_bytes(&self) -> Vec<u8> {
        let len = (self.payload.len() + 2) as u16; // payload + checksum
        let mut buf = Vec::new();
        buf.extend_from_slice(&START.to_be_bytes());
        buf.extend_from_slice(&self.address.to_be_bytes());
        buf.push(self.kind);
        buf.extend_from_slice(&len.to_be_bytes());
        buf.extend_from_slice(&self.payload);
        let sum: u16 = (self.kind as u16)
            + len
            + self.payload.iter().map(|b| *b as u16).sum::<u16>();
        buf.extend_from_slice(&sum.to_be_bytes());
        buf
    }
}

That checksum ate an entire evening. The datasheet says “sum of package identifier, length and all payload bytes,” and it turns out it means exactly that — but I’d assumed the header and address were included too, because that’s what a reasonable protocol would do. The AS608 is not a reasonable protocol. Read the sentence, not the intent.

Enrollment is a state machine, not a function

You don’t “enroll a fingerprint” in one call. You capture an image, convert it to a character buffer, ask the user to lift and re-press, capture a second image into a second buffer, then tell the module to merge the two buffers into a template and store it. Each of those steps can fail on its own — no finger detected, poor image, or the two captures don’t match — and each has a distinct confirmation code.

Modeling that as a flat function with a pile of ? operators felt wrong, so I gave every device response its own error variant:

#[derive(Debug)]
pub enum SensorError {
    NoFinger,
    ImageMessy,
    FeatureFail,
    EnrollMismatch,
    BadChecksum,
    Timeout,
    Io(std::io::Error),
}

The payoff is that the caller reads like the datasheet’s flowchart. A NoFinger means “loop and ask again,” an EnrollMismatch means “start the whole enrollment over,” and a BadChecksum means “your wiring is flaky.” Those are three completely different recovery paths, and a single opaque Error would have flattened them into a shrug.

Reads that don’t hang

The single most important thing in a UART driver is a read that gives up. On real hardware a dropped byte doesn’t announce itself — the module simply never finishes the frame, and a naive read blocks forever. So every response read is bounded: read the fixed header first, trust its length field to know how many more bytes to expect, and put a timeout around the whole thing.

If your embedded driver can hang, it will hang, and it will do it in front of the one person you were trying to demo to.

Once that was solid, everything got calmer. Enroll, search, delete, and template up/download all became thin wrappers over “send a packet, read an acknowledgement, check the confirmation code.”

What I’d tell past me

  • Log the raw bytes both ways before you write a single parser. Half my “protocol” bugs were actually a swapped TX/RX pair.
  • Build the frame type first. Every command is trivial once framing and checksums are a solved problem.
  • Give the device its own error enum. The confirmation codes are the API; hiding them behind a generic error throws away the most useful information the sensor gives you.

The result is fingerprint-sensor — a small crate that turns the AS608’s twice-translated datasheet into an API you can actually enroll against. It is not glamorous. It is exactly the kind of quiet plumbing I like.

— Abu more posts →