gertjanassies.dev

Spec-Driven Agents

2026-04-30T00:00:00+00:00

The Problem with AI-Assisted Development</a></h2>

When you use an AI coding agent in a single chat session to go from idea to implementation, things tend to blur. The agent holds the spec, the tests, and the code all in one context and when it decides to "adjust the spec" to make tests pass, or skips writing real tests because the implementation is already done, you've lost the discipline that makes software trustworthy.</p>

The usual answer is to impose rules: "don't change the spec", "write tests first". But rules in a single chat are easy to accidentally violate, hard to enforce, and easy to forget across sessions.</p>

Three Lanes, Three Agents</a></h2>

The spec-driven-agents</a> project is my answer to this: split the workflow into three isolated subagent lanes that communicate only via committed files</strong>. No shared chat history, no leaking context across lanes.</p>

Each agent has a clear job:</p>

@spec</code></strong> interviews you and produces a structured spec at specs/<slug>/spec.md</code>. It asks about acceptance criteria, scope, and edge cases and commits the result.</li>
@test</code></strong> reads only the spec and produces complete, executable Gherkin scenarios with real step definitions. Not stubs. The suite must be red because production code is missing, not because the steps throw "not implemented".</li>

@impl</code></strong> reads spec and features, verifies the suite is red for the right reasons, then drives it green one scenario at a time using classic TDD red, green, refactor.</li> </ul>

Lane Discipline</a></h2>
The key insight is that each agent communicates only through committed files</strong>. The @spec</code> agent writes to specs/</code>. The @test</code> agent writes to features/</code> and step definitions. The @impl</code> agent writes to src/</code> and unit tests. None of them touch each other's territory enforced both by OpenCode permission</code> frontmatter and by explicit prompt instructions.</p>
A per-project .spec-agents.toml</code> file holds the authoritative paths:</p>
Shown below is the template, once you run /init-spec-workflow</code> it will try to detect the language and fill the correct paths and commands</p>
# Generated by /init-spec-workflow. Edit freely; agents read this at runtime.
# This file is the per-project source of truth for spec-driven-agent paths and commands.

schema_version = 1
language = "__LANGUAGE__"

[paths]
specs            = "__SPECS__"
features         = "__FEATURES__"
acceptance_tests = "__ACCEPTANCE_TESTS__"
unit_tests       = "__UNIT_TESTS__"
src              = "__SRC__"
agentlog         = "__AGENTLOG__"

[commands]
test_acceptance = "__CMD_TEST_ACCEPTANCE__"
test_unit       = "__CMD_TEST_UNIT__"
build           = "__CMD_BUILD__"

[lanes]
# Optional extra glob patterns each agent is allowed to write to,
# beyond the corresponding [paths] entry. Useful for languages where
# tests live next to source (Go, Rust inline tests).
spec_writer_extra_writes  = []
test_author_extra_writes  = []
</code></pre>
If the file is missing, agents stop and tell you to run /init-spec-workflow</code>.</p>
Escalation Instead of Approximation</a></h2>
One discipline the @test</code> agent enforces that is very useful: if an Acceptance Criterion cannot be expressed as a pure-code assertion with the project's current test tooling, it does not</strong> approximate. It escalates.</p>
It appends a note to .agentlog/<slug>.md</code> and stops. You then go back to @spec</code> to rewrite or drop the AC, or you widen the project's test dependencies. No silent hand-waving.</p>
This matters because a test that says "this UI button is clicked" but actually just asserts that a function exists is worse than no test at all it gives false confidence.</p>
Getting Started</a></h2>

Note that this currently only works with opencode</p>
</blockquote>
The project installs with a single script:</p>
git clone https://github.com/gertjana/spec-driven-agents
cd spec-driven-agents
./install.sh
</code></pre>
This symlinks the agents, slash commands, and scaffold script into ~/.config/opencode/</code>. Then run opencode in any project:</p>
and within opencode run</p>
/init-spec-workflow
...

@spec let's spec a new "user-login" feature
# review specs/user-login/spec.md, edit if needed
@test user-login
@impl user-login
</code></pre>
Languages with auto-detected paths include Rust, Scala, JS/TS, Python, Go, Elixir, Java, and Kotlin.</p>
What I've Learned</a></h2>
Running some real sessions with this setup has surfaced a few recurring patterns worth noting:</p>
LLM's like to take shortcuts, in one of the first tests I did with this, the @test agent, only wrote test stubs as it 'couldn't write the tests as it did not yet know the implementation'</p>
Before @impl</code> writes any code, it must confirm the acceptance suite is red for production-side reasons. This catches a whole category of bugs where tests pass vacuously, wrong import path, wrong test command, tests not discovered before you've committed to an implementation direction.</p>
When @test</code> escalates, resist the urge to patch the test. Go back to the spec. Either the AC was too implementation-specific, too vague, or it assumed tooling you don't have. Fixing it at the spec level keeps the contract honest.</p>
The handoff from @spec</code> to @test</code> is not automatic, you read the spec first. This is a feature, not a bug. It's your last cheap chance to catch scope creep, missing edge cases, or criteria that sound right but won't survive contact with an actual test.</p>
Conclusion</a></h2>
In my opinion the two most important concepts in working with Agentic AI are context</strong> and guardrails</strong> and both are covered with this approach</p>

Context: The project itself and the detailed feature spec provide a clear context</li>
Guardrails: Implicit isolation between spec, test and implementation.</li>
</ul>
The Repo</a></h2>
The full project (agents, templates, slash commands and install script) is at github.com/gertjana/spec-driven-agents</a>.</p>



Random Numbers on a Homebrew FPGA CPU
2026-04-16T00:00:00+00:00
The CPU Project</a></h2>
As I wrote about previously</a>, I have been building an 8-bit CPU in Verilog, synthesized onto an Intel MAX1000 FPGA. The project cpu_in_fpga</a> is a simple CPU with 8 general-purpose registers, a hardware stack, an ALU.</p>
I wanted the programs you can run on it: "to do something" (the functional programmer in me would say: It needs to have side effects)</p>
Typically this is done through dedicated IN</code> and OUT</code> instructions. where the assembly program can access peripherals via port assignments (each port resembles a certain peripheral, like GPIO ports, an Analog Digital Converter, the 8 LED's on the board, etc)</p>
One of those peripherals I built is a pseudo-random number generator (PRNG), as any cpu will benefit from some randomness.</p>
This post walks through how it works, how the assembly program talks to it, and what you can see when it runs.</p>
The Galois LFSR</a></h2>
The PRNG is implemented as an 8-bit Galois Linear Feedback Shift Register</strong> (LFSR). An LFSR is a shift register where some of the bits are fed back through XOR gates to produce the next state. The "Galois" configuration places those XOR gates inside</em> the register, in parallel  making it fast in hardware.</p>
The specific polynomial used here is:</p>
x⁸ + x⁶ + x⁵ + x⁴ + 1   →   tap mask 0xB8
</code></pre>
In Verilog the next-state logic is just three lines:</p>
wire feedback = lfsr[0];           // output bit (LSB)
wire [7:0] shifted = lfsr >> 1;    // shift right
wire [7:0] next = feedback ? (shifted ^ TAP_MASK) : shifted;
</code></pre>
Each clock cycle the register shifts one position to the right. When the outgoing LSB is 1, the tap positions (bits 7, 5, 4, 3 are the set bits of 0xB8</code>) are XORed with the shifted value. When it is 0, no XOR happens and the register just shifts.</p>
This polynomial is maximal-length</strong>: starting from any non-zero seed it visits all 255 non-zero 8-bit values before cycling back. Zero is the only forbidden state as it would just keep shifting right, never ever changing, the PRNG circuit guards against it by silently replacing a seed of 0x00</code> with 0x01</code>.</p>
The LFSR runs on the 12 MHz board clock</strong>, independent of the CPU clock. The CPU runs at a divided-down rate, so every time the program reads the PRNG it samples a different phase of the sequence. The values are not cryptographically random, but they look completely unpredictable from the assembly program's point of view.</p>
IN and OUT Instructions</a></h2>
The CPU has two instructions for communicating with peripherals:</p>
Instruction</th> Encoding</th> Operation</th></tr></thead>

IN  Rd, port</code></td> 1000 ddd ppp xxxxxxxx</code></td> Rd = peripheral[port]</code></td></tr>
OUT Ra, port</code></td> 1001 aaa ppp xxxxxxxx</code></td> peripheral[port] = Ra</code></td></tr>
</tbody></table>
The relevant port assignments are:</p>
Port</th> Peripheral</th> IN</th> OUT</th></tr></thead>

0x01</code></td> PRNG</td> Read current LFSR value</td> Seed / reseed the LFSR</td></tr>
0x02</code></td> Onboard LEDs</td> </td> Set all 8 LEDs at once</td></tr>
</tbody></table>
Reading the PRNG</strong> (IN Rd, 0x01</code>) samples the 8-bit LFSR value at that instant.</p>
Seeding the PRNG</strong> (OUT Ra, 0x01</code>) loads the value in Ra</code> directly into the LFSR. At power-on the hardware already seeds it from a free-running counter so that each reset starts at a different point, but the program can override that at any time.</p>
Driving the LEDs</strong> (OUT Ra, 0x02</code>) writes all 8 bits of Ra</code> directly to the eight on-board LEDs. The LED register holds its state until the next write.</p>
The program</a></h2>
; prng.asm  hardware PRNG demo
; clk_div: 20
; name: Random
;
; Reads the FPGA programmed Galois PRNG and displays each value on the LEDs

.equ PRNG_PORT,    0x01
.equ LEDS_PORT,    0x02
.equ INITIAL_SEED, 0x2A

        LDI  R0, INITIAL_SEED     ; load seed value (42 decimal)
        OUT  R0, PRNG_PORT        ; write seed into the LFSR

loop:
        IN   R7, PRNG_PORT        ; sample current LFSR value
        OUT  R7, LEDS_PORT        ; show it on the LEDs
        JMP  loop                 ; repeat forever
</code></pre>
Let's step through it:</p>
LDI R0, INITIAL_SEED</code></strong>  Load Immediate. Puts the value 0x2A</code> (decimal 42) into register R0. This is the starting seed.</p>
OUT R0, PRNG_PORT</code></strong>  Write R0 to port 1. This reseeds the LFSR with 0x2A</code>, giving the sequence a deterministic starting point (on top of the hardware seed already applied at reset).</p>
IN R7, PRNG_PORT</code></strong>  Read port 1 into R7. Because the LFSR is running at 12 MHz and the CPU clock is divided down by 20 (the clk_div: 20</code> header directive), a meaningful number of LFSR cycles have elapsed since the last read. The value in R7 is effectively a fresh random byte every iteration.</p>
OUT R7, LEDS_PORT</code></strong>  Write R7 to port 2. The 8 LEDs instantly reflect the new random value.</p>
JMP loop</code></strong>  Unconditional jump back to loop</code>. The program runs forever.</p>
The result is a visually chaotic light pattern: each LED appears to toggle independently, with no visible periodicity.</p>
In Action</a></h2>
Here you see on the display register R7 being filled with the random number and the LEDS on the left display the binary version of it.</p>

</p>
Conclusions</a></h2>
A few things stand out from this tiny program:</p>
Hardware peripherals keep assembly programs simple.</strong> The LFSR logic  feedback polynomial, maximal-length sequence, zero-lock guard  is entirely in the RTL. The assembly programmer just reads a port. Eight lines of assembly are enough to drive a seemingly random light show.</p>
Clock domain separation is a feature.</strong> By running the PRNG on the board clock instead of the CPU clock, the sampling phase is always different. A synchronous PRNG clocked at the same rate as the CPU would return the same value on every read if the CPU read it every cycle. The asynchronous design sidesteps that entirely.</p>
The IN</code>/OUT</code> instruction pair is a clean peripheral interface.</strong> No memory-mapped registers, no special addressing modes  one instruction to read, one to write. For a small embedded CPU this keeps the decoder and the assembly programmer's mental model both straightforward.</p>
Seeding matters.</strong> The hardware seeds from a free-running counter at reset, but the program adds its own seed on top. For any application where reproducibility is useful (testing, procedural generation with a known seed) you can control the sequence completely. For applications where you want maximum apparent randomness, you can skip the OUT</code> and rely on the hardware seed.</p>
The full project, including the Verilog RTL, assembler, and all example programs, is at github.com/gertjana/cpu_in_fpga</a>.</p>


Experimenting with AI in FPGA Development
2026-03-10T00:00:00+00:00
The Premise</a></h2>
As an exercise to see how 'good' LLM's are getting I've asked it to build a small CPU (The likes of the Z80 or 6502) in an FPGA I had in a drawer, that project can be found here</a> if you're interested</p>
That is all working nice and dandy, giving me a chance to write some small assembly programs for it, bringing back fond memories from my youth.</p>
Improving the situation</a></h2>
But where it comes to visualisation, the MAX1000 FPGA board</a> has 8 leds in a row where i use the OUT Ra, 2</code> instruction to show the contents of one of the 8bit registers.</p>
For instance here it is running a program, that uses the SHL (Shift left) and SHR (Shift right) instructions to simulate the light pattern on the KITT car from the Knightrider television series.</p>

.equ LEFT_EDGE  0x80
.equ RIGHT_EDGE 0x01

        LDI  R1, LEFT_EDGE  
        LDI  R2, RIGHT_EDGE 
        MOV  R7, R1         
        OUT  R7, 2          ; display pattern on leds

scan_right:
        CMP  R7, R2         ; right edge reached?
        JZ   scan_left      ; yes -> reverse, scan left
        SHR  R7, R7         ; no  → step right
        OUT  R7, 2          
        JMP  scan_right

scan_left:
        CMP  R1, R7         ; left edge reached?
        JZ   scan_right     ; yes → reverse, scan right
        SHL  R7, R7         ; no  → step left
        OUT  R7, 2          
        JMP  scan_left
</code></pre>
Moar visuals</a></h2>
So lets add a small OLED Screen, the board has an 12 pin connector to interface with the outside world in a standardized manner, and you can buy amongst other things a 128x32 OLED Display based on the SSD1306 chip which has an SPI Interface to be able to control it.</p>
Now while the display is on order. I started the SPI Implementation. (It's a bit different from working with Arduino's as they have loads of libraries available)</p>
SPI requires at least 4 wires</p>

Enable (or Clock Select) low is telling the device on the other end. I'm going to send you some data now</li>
D/C (Data/Command) High meaning i'm sending data (text or pixels), Low meaning I'm sending you commands f.i. clear screen, set cursor</li>
MOSI (Master out, Slave in) the actual data</li>
Clock (Pulses for each data bit that is send out)</li>
</ul>
So Opencode with Claude Sonnet 4.6 in plan mode, I started warming it up to the SPI implementation. giving it links the the SPI protocol itself and the datasheet for the SSD1306 Display model and then asked it to implement a monitor that would show the content of the registers and flags, and the name of the program it is running.</p>
The resulting code is here rtl/oled_monitor.v</a></p>
So far so good It created the implementation and tests for the testbench simulator but I wanted to be more sure that it would work. the LLM had similar ideas, as it was asking about what should we do next? One of it's suggestions was to hook up an logic analyzer so I could judge whether or not it was correctly implemented.</p>
So I hooked up a logic analyzer</a>, set the protocol to SPI, so it recognizes the bytes of data, and let it run for a bit, the result is shown below</p>
</p>
Feedback loop</a></h2>
Now the idea I had then is to feed that image back into opencode and ask it to use the logic analyzer screenshot to verify the implementation itself.</p>
It did so, relating the code and timings to the SPI output and even found a couple of bugs:</p>
In summary:

1	DC possibly one byte late for first font byte per line (visible in screenshot as 0x7F sent with DC=0)
  High — display shows garbage on first column of each line's first char after page-set
2	Display On (0xAF) sent before VBAT+100ms delay, violating power-on sequence
  High — could damage display or fail to initialize
3	Reset applied before VDD is on
  Medium — deviates from Digilent spec
4	ST_DISP_ON state is dead code
  Low — code smell
5	SPI engine and FSM both modify spi_cs_n in same cycle when spi_done
  Medium — works in simulation but fragile in synthesis

The most directly confirmed bug from the screenshot is Bug 1 (DC=0 for the first font data byte after page commands), and Bug 2 (Display On sequencing). Would you like me to fix any of these?
</code></pre>
Asking it to fix it and repeating the exercise, I got a thumbs up. making the risk of this not working as low as possible, but still there, so there's still the possibility I have to dive into the datasheet. to look at probably timing issues. but fingers crossed.</p>
Conclusion</a></h2>
This way of working proofs that LLM's can make you pretty productive, but you need to make sure it has the right context and good feedback on what it has done.</p>
I also gave Claude the capture file with all the measurements, but that turned out to be too much for it. it went under and never surfaced again.</p>
What could we have done better? well, what we want to display, the fonts and the actual SPI protocol is all in one file. In a normal application that would be split up in the SPI implementation module with a clear interface. to be called from the application. but for a Proof of Concept this is fine.</p>
Can't wait for the display to arrive</p>
UPDATE</a></h2>
The display has arrived and after some tweaks (weak pull-up resistors) it's working, here's the knightrider example with a working display, showing the program name, registers, stack, flag and program counter</p>
</p>


Another approach to checked exceptions with the Result type
2026-02-13T00:00:00+00:00
As changes are greater that I will be doing more Java engineering in the near future, I wanted to up my skills as the last time I did some serious Java work was 12 years ago</p>
One of the things I like to do is take concepts that I learned from other languages that are not present in the languages Im focusing on.</p>
As I learned from (mostly functional) programming languages is that failures should be modelled in your application just as much as successes (the happy path) and that something called an Exception is not really a semantically good way of handling those.</p>
Java's checked exceptions often lead to verbose code, awkward abstractions, and layers of try-catch blocks that obscure business logic. What if there was a better way?</p>
Enter the Result type</strong> a functional programming pattern that represents operations that can succeed or fail, without resorting to exceptions for control flow.</p>
The application I chose to experiment with this, is a commandline application that manages filament (the rolls of plastic wire used in 3D-printing). so all the examples are from that sourcecode.</p>
The Problem with Checked Exceptions</a></h2>
Consider a typical repository method that reads from a file:</p>
public List<Filament> loadFilaments() throws IOException {
    return objectMapper.readValue(
        filePath.toFile(),
        new TypeReference<List<Filament>>() {}
    );
}
</code></pre>
This signature forces every caller to either handle IOException</code> or propagate it up the call stack. The problem compounds when you have multiple layers:</p>
// Service layer - forced to propagate
public List<Filament> getAllFilaments() throws IOException {
    return repository.loadFilaments();
}

// Command layer - more propagation
public String listAll() throws IOException {
    List<Filament> filaments = service.getAllFilaments();
    return formatFilaments(filaments);
}
</code></pre>
Or worse, developers start swallowing exceptions inappropriately just to avoid dealing with them:</p>
try {
    return service.getAllFilaments();
} catch (IOException e) {
    return Collections.emptyList(); // Silent failure!
}
</code></pre>
The Result Type Solution</a></h2>
The Result<T, E></code> type explicitly represents success or failure as a value, not an exception. Here's the interface:</p>
public sealed interface Result<T, E>
    permits Result.Success, Result.Failure {

    record Success<T, E>(T value) implements Result<T, E> {}
    record Failure<T, E>(E error) implements Result<T, E> {}
}
</code></pre>
Using Java's sealed interfaces and records (introduced in Java 17), we get exhaustive pattern matching and immutability for free.</p>
Wrapping with Result.of()</a></h2>
The key to adoption is making it easy to wrap</strong> potentially failing operations. The Result.of()</code> method handles this beautifully:</p>
@FunctionalInterface
interface ThrowingSupplier<T> {
    T get() throws Exception;
}

static <T, E> Result<T, E> of(
    ThrowingSupplier<T> supplier,
    Function<Exception, E> errorMapper
) {
    try {
        return new Success<>(supplier.get());
    } catch (Exception e) {
        return new Failure<>(errorMapper.apply(e));
    }
}
</code></pre>
Now our repository becomes exception-free:</p>
@Override
public Result<List<Filament>, String> loadAll() {
    if (!Files.exists(filePath)) {
        return new Failure<>("File not found: " + filePath);
    }

    return Result.of(
        () -> objectMapper.readValue(
            filePath.toFile(),
            new TypeReference<List<Filament>>() {}
        ),
        e -> "Failed to parse filament data: " + e.getMessage()
    );
}
</code></pre>
Notice how we:</p>

Handle the "file not found" case explicitly with a Failure</code></li>
Wrap the Jackson parsing with Result.of()</code> which catches any Exception</code></li>
Map exceptions to user-friendly error messages using the error mapper function</li>
In this case the Error type is a String, but we could just as easily pass on the Exception type itself.</li>
</ol>
Unwrapping with result.fold()</a></h2>
The fold()</code> method is where the magic happens. It forces you to handle both cases — success and failure — and produce a single unified result:</p>
default <R> R fold(
    Function<E, R> onFailure,
    Function<T, R> onSuccess
) {
    return switch (this) {
        case Success<T, E>(T value) -> onSuccess.apply(value);
        case Failure<T, E>(E error) -> onFailure.apply(error);
    };
}
</code></pre>
In practice, this looks incredibly clean at the command layer:</p>
@ShellMethod(key = "list", value = "Lists all filaments")
public String listAll(
    @ShellOption(defaultValue = "TABLE") OutputFormat format
) {
    return filamentService.getAllFilaments().fold(
        error -> "Failed to retrieve filaments: " + error,
        filaments -> formatFilaments(filaments, format)
    );
}
</code></pre>
No try-catch blocks. No exception propagation. Just two functions: one for the error path, one for the success path. The compiler ensures you handle both.</p>
Composition and Transformation</a></h2>
The real power emerges when composing multiple operations. The Result type provides map()</code>, flatMap()</code>, and mapError()</code> for elegant transformations:</p>
// Transform successful values
result.map(filaments -> filaments.size());

// Chain operations that also return Results
result.flatMap(filament ->
    calculateCost(filament.id(), length)
);

// Transform error types
result.mapError(msg ->
    new ErrorResponse(500, msg)
);
</code></pre>
Here's a real example from a cost calculation service:</p>
public Result<CostCalculation, String> calculateCost(
    int id,
    double length
) {
    return filamentRepository.findById(id)
        .flatMap(filament ->
            filamentTypeRepository.findById(filament.filamentTypeId())
                .map(type -> calculateCost(filament, type, length))
        );
}
</code></pre>
If either the filament or filament type lookup fails, the error propagates automatically. If both succeed, the calculation runs. All without a single try-catch block.</p>
Benefits in Practice</a></h2>
After refactoring to the Result type, I've noticed:</p>
Cleaner signatures</strong>: Methods declare exactly what can go wrong without forcing exception handling.</p>
// Before
List<Filament> getAllFilaments() throws IOException, ParseException

// After
Result<List<Filament>, String> getAllFilaments()
</code></pre>
Explicit error handling</strong>: Every .fold()</code> is a visible decision point where errors are handled.</p>
Better error messages</strong>: Error mapper functions let you provide context-specific messages at the failure point, not generic catch-all handlers.</p>
Composability</strong>: Chaining operations with flatMap()</code> creates pipelines that fail fast and propagate errors naturally.</p>
When to Use It</a></h2>
The Result type shines for:</p>

Repository/data access layers</strong>: File I/O, database queries, external API calls</li>
Business logic</strong>: Validation, calculations, domain operations that can fail</li>
Service boundaries</strong>: Clear success/failure contracts between layers</li>
</ul>
You might still want traditional exceptions for:</p>

Programmer errors</strong>: NullPointerException</code>, IllegalStateException</code></li>
Fatal errors</strong>: Out of memory, stack overflow</li>
Third-party code</strong>: When you don't control the interface</li>
</ul>
Conclusion</a></h2>
The Result type transforms error handling from an afterthought into a first-class concern. By wrapping potentially failing operations with Result.of()</code> in lower tiers and unwrapping with result.fold()</code> at boundaries, you create code that's more explicit, composable, and maintainable.</p>
Checked exceptions tried to force explicit error handling but ended up creating layers of ceremony. The Result type achieves the same goal through values instead of control flow — a more functional, more elegant approach.</p>
The full implementation is available in my Filament project</a>.</p>
the Result class specifically is here: Result.java</a></p>


Building a USB Keep-Awake Device with MicroPython
2025-12-02T00:00:00+00:00
Introduction</a></h2>
You know those viral videos about companies installing software to monitor if employees are actually working by tracking keyboard and mouse activity? Well, this post is certainly not about that, but about avoiding your laptop going to sleep during presentations, long-running tasks, or when you're just reading documentation on your screen.</p>
This is a story of building a pocket-sized USB device that prevents my laptop from sleeping, complete with pretty LED animations and using touch buttons to control it.
The entire project only took a couple of hours, thanks to MicroPython and the Adafruit Neo Trinkey</a>.</p>
Hardware</a></h2>
</p>
What is it?</strong></p>

A tiny SAMD21 microcontroller (the same chip family used in the original Arduino Zero)</li>
Four RGB NeoPixel LEDs built right into the board</li>
Two capacitive touch pads you can activate by simply touching them</li>
USB-A connector that plugs directly into your laptop</li>
Costs under €10</li>
</ul>
Why is it perfect for this project?</strong></p>

Plug-and-play</strong>: No breadboards, no wires, no soldering required. It's literally just plug it in and go.</li>
Visual feedback</strong>: The four NeoPixels give us beautiful RGB LED feedback so we always know what state our device is in.</li>
Touch controls</strong>: Two touch-sensitive pads mean we can toggle features without any physical buttons.</li>
Small form factor</strong>: It's so tiny you can leave it plugged in and forget about it.</li>
MicroPython ready</strong>: Adafruit has excellent support for running CircuitPython (a variant of MicroPython) on all their boards.</li>
</ol>
The beauty of this hardware choice is that you don't need any additional components. No resistors, no external LEDs, no complicated wiring diagrams. Everything you need is on this one tiny board. This makes it perfect for beginners or anyone who just wants to get a project done quickly without dealing with hardware complexity.</p>
What's MicroPython?</a></h2>
Before we dive into the code, let's talk about why MicroPython is such a game-changer for hardware projects.</p>
MicroPython</strong> is a lean and efficient implementation of Python 3 that's designed to run on microcontrollers. Think of it as taking the friendly, readable Python syntax you might know from web development or data science, and shrinking it down to fit on tiny hardware with limited memory and processing power.</p>
Why MicroPython is perfect for makers:</strong></p>

Instant gratification</strong>: No compile step. You write code, save it to the device, and it runs immediately.</li>
Interactive REPL</strong>: You can connect via serial and type commands interactively, perfect for testing and debugging.</li>
Rapid prototyping</strong>: Iterate quickly without the compile-upload-test cycle of traditional embedded development.</li>
Great libraries</strong>: Access to hardware features through simple, well-documented libraries.</li>
</ol>
CircuitPython vs MicroPython:</strong></p>
For this project, I'm actually using CircuitPython</strong>, which is Adafruit's fork of MicroPython. CircuitPython is specifically optimized for Adafruit hardware and includes additional libraries for their products. The differences are minor, think of CircuitPython as "MicroPython with batteries included for Adafruit boards."</p>
Installation</a></h3>
Getting started with CircuitPython on the Neo Trinkey is surprisingly simple:</p>
Step 1: Download CircuitPython</strong></p>

Visit circuitpython.org</a></li>
Find the Neo Trinkey M0 page</a></li>
Download the latest .UF2</code> file (around 150KB)</li>
</ul>
Step 2: Enter Bootloader Mode</strong></p>

Plug in your Neo Trinkey</li>
Look for the tiny reset button on the board</li>
Double-click it quickly (like double-clicking a mouse)</li>
The board will reboot and appear as a USB drive called TRINKETBOOT</code></li>
</ul>
Step 3: Install CircuitPython</strong></p>

Drag and drop the .UF2</code> file onto the TRINKETBOOT</code> drive</li>
The device will automatically reboot</li>
It now appears as a drive called CIRCUITPY</code></li>
That's it! CircuitPython is installed.</li>
</ul>
Step 4: Install Required Libraries</strong></p>

Download the Adafruit CircuitPython Library Bundle</a></li>
Extract the bundle and find the adafruit_hid</code> folder</li>
Copy the entire adafruit_hid</code> folder into the lib/</code> directory on your CIRCUITPY</code> drive</li>
</ul>
Now you're ready to write code! The entire installation process takes about 5 minutes.</p>
Development environment:</strong>
You can use any text editor you like. I personally use VS Code with the CircuitPython extension, but even Notepad works fine. Just edit the code.py</code> file on the CIRCUITPY</code> drive, save it, and your changes run immediately.</p>
In the end the files on the USB stick should look like this</p>
CIRCUITPY/
├── code.py
├── lib/
│   └── adafruit_hid/
└── boot_out.txt
</code></pre>
Software: How It Works</a></h2>
Now for the fun part—let's look at how the code works. The beauty of MicroPython is that the code is remarkably readable, even if you've never written embedded code before.</p>
The Big Picture</a></h3>
Our device has a simple state machine:</p>

Idle</strong> (blue LEDs) - Device is plugged in but not keeping the laptop awake</li>
Active</strong> (green LEDs) - Device is simulating user activity every 30 seconds</li>
Quiet mode</strong> - All LED animations are disabled for stealth operation</li>
</ol>
The user controls these states with two touch pads, and the device provides visual feedback through the NeoPixel LEDs.</p>
Initialization and Setup</a></h3>
import board
import touchio
import neopixel
import usb_hid
import time
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode
from adafruit_hid.mouse import Mouse

# Configuration
ACTION_INTERVAL = 30  # Seconds between keep-awake actions
ACTION_OFFSET = 5     # Seconds before first action
STATUS_LED_TIMEOUT = 2  # How long to show status LEDs

# Initialize hardware
pixels = neopixel.NeoPixel(board.NEOPIXEL, 4, brightness=0.2)
touch1 = touchio.TouchIn(board.TOUCH1)  # Left pad - toggle active
touch2 = touchio.TouchIn(board.TOUCH2)  # Right pad - toggle quiet mode
keyboard = Keyboard(usb_hid.devices)
mouse = Mouse(usb_hid.devices)
</code></pre>
This initialization is beautifully simple. We import the libraries we need and set up our hardware. The board</code> module gives us access to the specific pins on our Neo Trinkey, while neopixel</code>, touchio</code>, and usb_hid</code> let us control the LEDs, touch pads, and USB HID (Human Interface Device) functionality.</p>
Touch Detection</a></h3>
def check_touch_buttons():
    """Check if touch buttons are pressed and update state"""
    global is_active, quiet_mode

    # Touch 1: Toggle keep-awake on/off
    if touch1.value:
        is_active = not is_active
        flash_color((255, 0, 255))  # Magenta flash for feedback
        show_status_led()
        time.sleep(0.3)  # Debounce delay

    # Touch 2: Toggle quiet mode
    if touch2.value:
        quiet_mode = not quiet_mode
        flash_color((255, 128, 0))  # Orange flash for feedback
        time.sleep(0.3)  # Debounce delay
</code></pre>
Capacitive touch detection is incredibly simple with CircuitPython. The touch1.value</code> property returns True</code> when you touch the pad. We add a small delay (time.sleep(0.3)</code>) to debounce—preventing multiple triggers from a single touch.</p>
Keep-Awake Actions</a></h3>
Here's where the magic happens. We randomly choose one of three actions to simulate user activity:</p>
import random

def perform_keep_awake_action():
    """Randomly perform one of three keep-awake actions"""
    action = random.randint(1, 3)

    if action == 1:
        # Press F15 key (rarely used, non-intrusive)
        keyboard.send(Keycode.F15)
    elif action == 2:
        # Move mouse 1 pixel right and back
        mouse.move(x=1)
        time.sleep(0.1)
        mouse.move(x=-1)
    else:
        # Move mouse 1 pixel down and back
        mouse.move(y=1)
        time.sleep(0.1)
        mouse.move(y=-1)

    # Show action animation (unless in quiet mode)
    if not quiet_mode:
        circular_animation((255, 255, 0))  # Yellow animation
</code></pre>
Each action is subtle enough not to disrupt your work:</p>

F15 key</strong>: Most operating systems don't have this key mapped to anything, so pressing it registers activity without side effects</li>
Mouse movements</strong>: Tiny 1-pixel movements that you won't even notice</li>
</ul>
LED Animations</a></h3>
One of the most satisfying parts of this project is the LED feedback:</p>
def circular_animation(color):
    """Animate LEDs in a circular pattern"""
    for i in range(4):
        pixels.fill((0, 0, 0))  # Clear all
        pixels[i] = color        # Light up one LED
        pixels.show()
        time.sleep(0.1)
    pixels.fill((0, 0, 0))
    pixels.show()

def show_status_led():
    """Show current status with LED color"""
    if is_active:
        color = (0, 255, 0)  # Green for active
    else:
        color = (0, 0, 255)  # Blue for idle

    pixels.fill(color)
    pixels.show()
    time.sleep(STATUS_LED_TIMEOUT)
    pixels.fill((0, 0, 0))  # Turn off after timeout
    pixels.show()
</code></pre>
The circular animation gives visual confirmation that an action occurred, while the status LED provides quick feedback about the current state. Keeping the LEDs on for only 2 seconds prevents them from being distracting during use.</p>
Main Loop</a></h3>
is_active = False
quiet_mode = False
last_action_time = time.monotonic()

# Show initial status
show_status_led()

while True:
    # Check for touch button input
    check_touch_buttons()

    # Perform keep-awake action if active
    if is_active:
        current_time = time.monotonic()
        if current_time - last_action_time >= ACTION_INTERVAL:
            perform_keep_awake_action()
            last_action_time = current_time

    time.sleep(0.1)  # Small delay to prevent CPU spinning
</code></pre>
The main loop is refreshingly simple:</p>

Check if the user touched either button</li>
If we're active and enough time has passed, perform a keep-awake action</li>
Sleep briefly to avoid maxing out the CPU</li>
</ol>
The time.monotonic()</code> function gives us a steady clock that doesn't jump around due to time adjustments, perfect for timing-based logic.</p>
Conclusion</a></h2>
Building this keep-awake device was a perfect introduction to the makerspace world. In just a couple of hours, with about €10 worth of hardware and around 100 lines of Python code, I created something useful that hopefully sparks the imagination.</p>
What makes this project special:</strong></p>

No complicated hardware</strong>: Everything runs on a single, self-contained board</li>
Beginner-friendly code</strong>: If you can write Python, you can write MicroPython</li>
Immediate results</strong>: See your code changes take effect instantly</li>
</ul>
What you will learn:</strong></p>

How accessible hardware projects have become thanks to MicroPython</li>
The joy of having physical feedback (LEDs!) for your code</li>
How simple USB HID programming can be</li>
That you don't need to be an electrical engineer to build cool hardware projects</li>
</ul>
Next Steps</a></h3>
If you want to extend this project, here are some ideas:</p>

Play around with the colors and timings</li>
Make an annoyance device with no LEDs flashing, but randomly moves the mouse every now and then</li>
Randomly let it type 'All your base are belong to us' every now and then</li>
as a (not very secure) authentication device: store and let it type out your password when pressing one of the touch buttons</li>
</ul>
References and Resources</a></h3>

Project Repository</strong>: github.com/gertjana/trinkey_keep_alive</a></li>
Hardware</strong>: Adafruit Neo Trinkey</a></li>
CircuitPython</strong>: circuitpython.org</a></li>
CircuitPython Libraries</strong>: CircuitPython Bundle</a></li>
Adafruit Learning System</strong>: Tons of great tutorials at learn.adafruit.com</a></li>
</ul>
A word of caution</strong>: While this device is great for legitimate uses like preventing screen timeout during presentations or while running long tasks, please be mindful of your workplace policies. This isn't a tool for circumventing employee monitoring systems—that would be both unethical and likely against your employment terms. Use it responsibly!</p>
Now go forth and explore the makerspace! MicroPython and Adafruit make hardware projects accessible to everyone, and the only limit is your imagination. Happy making!</p>


Rust on ESP32 part 2.5 - Switching software to Rust no_std and Embassy
2025-10-03T00:00:00+00:00

This is a series of articles about using Rust to program an ESP32 Microcontroller by building a minimal EV Charger.</p>

Part 1: A Proof of Concept</a></li>
Part 2: A minimal EV Charger hardware setup</a></li>
Part 2.5: A rewrite using Rust no_std and the Embassy framework</a> (this article)</li>
Part 3: Network and Charger to backoffice communication (Wifi/ MQTT / OCPP)</li>
Part 4: Optional: Charger to Car communication (Mode2)</li>
</ul>
</blockquote>
The old</a></h2>
It took me a while to get back to this, work and personal life took priority, but I've picked up this project again and rewrote it completely</p>
As you can see in the previous article, I was using standard Rust and was very low level spawning threads and sharing data through Mutexes</p>
Which meant I had to do most of the plumbing myself, which could lead to bugs and probably race-conditions.</p>
let org_charger: Arc<Mutex<Charger>> = Arc::new(Mutex::new(Charger{id: "1", state: "Available"}));

let charger = org_charger.clone();
thread:spawn(move || {
    loop {
        // do something with the charger
    }
});
</code></pre>
As the Charger</code> is wrapped in an Arc</code> (Atomically Reference Counted) each clone will produce a new Arc</code> Instance which points to the same allocation while increasing a reference count. The mutex is needed to keep the underlying Charger accessible to only one Thread at a time.</p>
The new</a></h2>
But this is all water under the bridge as I changed the implementation to use the Embassy Framework, which is similar to other async frameworks but specifically for small microcontrollers.</p>
I also switched to no_std</code> which is Rust without the standard library. This practically means no heap allocations, so we use &str</code> instead of String</code></p>
The above code will now look like this:</p>

#[esp_hal_embassy::main]
async fn main(spawner: Spawner) {
    let charger = mk_static!(Charger, Charger::new()); //the make_static! macro allows creating static variables initialized at runtime
    spawner.spawn(some_async_task(charger)).ok();
}

#[embassy_executor::task]
async fn some_async_task(charger) {
    loop {
        // do something with the charger
        Timer::after(Duration::from_millis(100)).await; // in case of non-blocking code wait a bit
    }
}
</code></pre>
This is more in line with how most async frameworks like Tokio work.</p>
Communication between Tasks is done with Channels where you are able to safely send and receive messages from other tasks which come in 2 flavours:</p>

many sender to 1 receiver</li>
1 publisher to many subscribers</li>
</ul>
The Charger is essentially a State Machine where certain events (cable inserted, card swiped) cause state transitions that produce other events (cable lock, current turns on, etc.)</p>
For instance, if the Charger's state is Available</code> and someone inserts a cable, the task watching that event will send a message to the state machine, which will change its state to Preparing</code> and broadcast that state change to a PubSubChannel. A task responsible for controlling the LED color will then change the color from green to white.</p>

Note that that task is in waiting state until a message comes in, taking no cpu time what so ever or need delays to 'free up' the thread.</p>
</blockquote>
Channels workings</a></h3>
Normal channel</a></h5>
A normal channel can have multiple tasks putting messages in there, in our case changes in the hardware that will cause state changes.</p>
/// Message queue for charger input events
pub static STATE_IN_CHANNEL: Channel<CriticalSectionRawMutex, InputEvent, 10> = Channel::new();

// task sending a message
#[embassy_executor::task]
async fn cable_detect_task(charger) {
    ...
    STATE_IN_CHANNEL.send(InputEvent.CableInserted).await;
    ...
}

// task sending a message
#[embassy_executor::task]
async fn receiving_task(charger) {
    ...
    let event = STATE_IN_CHANNEL.receive().await; // blocks until message arrives
    ...
}
</code></pre>
Publish/Subscribe:</a></h5>
In our case state changes that needs to be propagated to the hardware</p>
/// PubSub channel for charger state changes
pub static STATE_PUBSUB: PubSubChannel<
    CriticalSectionRawMutex,
    (ChargerState, heapless::Vec<OutputEvent, 2>),
    10, // capacity
    6, // max subscribers
    1, // max publishers
> = PubSubChannel::new();

// task that publishes
#[embassy_executor::task]
async fn publish_task() {
    let publisher = STATE_PUBSUB.publisher().unwrap();
    loop {
        ...
        publisher.publish_immediate(some_message);
    }
}

// task subscribed to the pubsub channel
#[embassy_executor::task]
async fn subscribe_task() {
    ...
    let mut subscriber = charger::STATE_PUBSUB.subscriber().unwrap();
    loop {
        if let embassy_sync::pubsub::WaitResult::Message((new_state, output_event)) =
            subscriber.next_message().await // this blocks until a message has been received
            // do something with the message
        {
    }
    ...
}
</code></pre>
so we have:</p>

Tasks reacting to things happening on the hardware site (Insert Cable, Swipe Card, etc.)</li>
A charger state machine task that changes state based on these events (Available, Preparing, Charging, etc.)</li>
Tasks that listen to these state changes and interact with the hardware (Led that set the right color, Solenoid locking cable, Relay switching Power to the Cable, etc.)</li>
Tasks that communicate through MQTT to an OCPP Backend, provide a Wifi network stack, queries an NTP server for the current time, but thats for the next article.</li>
</ul>
The State Machine</a></h2>
Here's how the state machine looks:
</p>
And if you're brave, here's the complete architecture, (every green or blue rectangle is an embassy task, all communication between tasks go through channels)
</p>
Hardware</a></h2>
I changed the ESP32 from an S3 (Xtensa CPU Architecture) to a C6 (RISC-V Architecture), primarily to avoid having to install the entire Xtensa SDK on my laptop. This also dramatically improved compilation times from a couple of minutes to around 35 seconds.</p>
I added an addressable Multi color LED (WS1218</a>) and a RFID Reader (RC522</a>)</p>
The updated schematic:</a></h3>

A nice 3D Rendering made with Fusion360</a></h3>

Front with Acrylate cover</a></h3>
The 3D printed part covers the pins that might contain high voltages.
</p>
Back showing ESP32-C6, connectors and Relay</a></h3>

You can find all the schematic and PCB files in the kicad subdirectory of the project</a></p>
The Result</a></h2>

We now have an application that is very responsive to what's happening</li>
Embassy handles the concurrency, which will reduce bugs and possible race conditions</li>
It will handle the scarce resources of embedded microcontroller's a lot better</li>
</ul>
Conclusion</a></h2>
It's possible to write safe async code in rust on ESP32 microcontrollers.
Working within the no_std</code> constraints was more manageable than expected, especially with the help of crates like 'alloc' and 'heapless' which help with alternative ways of allocation where needed.</p>
The Embassy framework helps me to use the same programming concepts as in normal applications using for instance the Tokio async runtime.</p>
For future articles, I will discuss network communication, setting up Wifi, getting the time from an NTP Server and talking to a backoffice using MQTT and the OCPP Protocol</p>
If you're interested in getting started with Embassy and Rust on microcontrollers, I highly recommend the Embassy book</a> as an excellent starting point.</p>
References</a></h2>

Code/Design files: https://github.com/gertjana/charger-esp32c6-embassy/</li>
ESP32-C6 microcontroller: https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/</li>
Embassy Framework: https://embassy.dev/</li>
</ul>


Rust on ESP32 part 2 - The hardware
2024-01-25T00:00:00+00:00

This is a series of articles about using Rust to program an ESP32 Microcontroller by building a minimal EV Charger.</p>

Part 1: A Proof of Concept</a></li>
Part 2: A minimal EV Charger hardware setup</a> (this article)</li>
Part 3: Network and Charger to backoffice communication (Wifi/ MQTT / OCPP)</li>
Part 4: Optional: Charger to Car communication (Mode2)</li>
</ul>
</blockquote>
The previous article</a> was about try-ing to get Rust running on a esp32 microcontroller.</p>
In there I started to set up as a charger for an Electric Vehicle, lets dive more into that by desiging the hardware.</p>
A simple as possible charger should:</p>

Have a way to detect whether a cable is inserted or not (or simulated by a switch)</li>
be able to lock the cable with a solenoid (or simulated by a led)</li>
Allow swiping a card to start charging (or simulated with a button)</li>
Have a relay to apply power to the cable</li>
Visualize the state of the charger (the M5 Stamp has a multicolor led onboard, and I've added a small OLED display I had lying around)</li>
</ul>
Putting all this into a schematic it looks something like this:</p>

Managing State</a></h2>
As a Charger goes through several states during it's operation (Available, Occupied, Charging, Error)
a FSM (Finite State Machine) looks like a good way to model this.</p>
A FSM works as follows:</p>
Whenever something happens (an InputEvent), a cable gets inserted/removed or some form of authentication is provided, a transision is made from one state to the next, resulting in an output event, for instance to tell the charger to lock the cable and start charging.</p>

Every Arrow is a transition</code> call with the current State</code> and an InputEvent</code> to a new State</code> with an OutputEvent</code>.</p>
code wise that will look like this:</p>
impl Charger {
    pub fn transition(&mut self, input: ChargerInput) -> Result<(State, ChargerOutput), Error) {
        let output = match (input, self.state.clone()) {
            (ChargerInput::PlugIn, State::Available) => {
                self.set_state(State::Occupied);
                ChargerOutput::Unlocked
            }
            (ChargerInput::PlugOut, State::Occupied) => {
                self.set_state(State::Available);
                ChargerOutput::Unlocked
            }
            (ChargerInput::Swipe, State::Occupied) => {
                self.set_state(State::Charging);
                ChargerOutput::LockedAndPowerIsOn
            }
            (ChargerInput::Swipe, State::Charging) => {
                self.set_state(State::Occupied);
                ChargerOutput::Unlocked
            }
            _ => {
                Err("An invalid transistion occurred")
            }
        }
       Ok((self.get_state(), output))
    }
</code></pre>
So now all it left is a bit of logic to do the transitions whenever an event happens</p>
    // setup is skipped, see previous blog, or code

    button.enable_interrupt().unwrap();
    notification.wait(esp_idf_svc::hal::delay::BLOCK);

    match charger.transition(charger::ChargerInput::Swipe) {
        Ok((ChargerState::Charging, charger::ChargerOutput::LockedAndPowerIsOn)) => {
            relay.set_high().unwrap();
            solenoid.set_high().unwrap();
        }
        Ok((_, charger::ChargerOutput::Unlocked)) => {
            relay.set_low().unwrap();
            solenoid.set_low().unwrap();
        }
        ...
    }
</code></pre>

The GPIO Port is configured as input with an pull-up resistor with the button connected to ground, meaning whenever the button is pressed, it will connect the input to ground (0) and when released the pull-up resistor will 'pull' it to teh +5V (1) again (creating a Positive Edge (0 -> 1) event).</p>
As we have configured the button in the code to subscribe to a positive edge event, the code will unblock whenever the button is released.</p>
We then call the transition function with the current state and the input event Swipe</code> which will give us a new state Chargng</code> and a output LockedAndPowerIsOn</code>, we then set the hardware to whatever the output is telling us.</p>
So that's the hardware done, I've added a small oled display with an i2c interface, with the rust library that exists for this display, displaying information is a breeze:</p>
let peripherals = Peripherals::take().unwrap();
let i2c = peripherals.i2c0;
let sda = peripherals.pins.gpio21;
let scl = peripherals.pins.gpio20;

let i2c_config = I2cConfig::new().baudrate(100_000.into());
let i2c = I2cDriver::new(i2c, sda, scl, &i2c_config)?;

let interface = I2CDisplayInterface::new(i2c);
let display = Ssd1306::new(
        interface, DisplaySize128x64, DisplayRotation::Rotate180).into_terminal_mode();

display.init();
display.clear();

write!(display, "Hello World");
</code></pre>
Here's how it looks on a breadboard, I'm using the button and led that are on the m5 Stamp to simulate the swiping of a card and displaying the charger state, a blue led to simulate the relay and a jumper to simulate the inserting of a cable.</p>

The next article will focus on sending and retrieving OCPP Messages to a backend by configuring the Wifi and MQTT Publisher and Subscriber.</p>
references</a></h2>

Code: https://github.com/gertjana/charger_rust_esp32_c3/tree/cad15fb3a088cdd82d7dbfd5f9d16512b37e4d6f</li>
esp-idf-template: https://github.com/esp-rs/esp-idf-template</li>
M5 Stamp ESP32-C3U: https://docs.m5stack.com/en/core/stamp_c3u</li>
The embedded rust book:  https://docs.rust-embedded.org/book/</li>
Espresiff ESP-32: https://www.espressif.com/en/products/socs/esp32</li>
</ul>


Rust on ESP32
2024-01-04T00:00:00+00:00

This is a series of articles about using Rust to program an ESP32 Microcontroller by building a minimal EV Charger.</p>

Part 1: A Proof of Concept</a> (this article)</li>
Part 2: A minimal EV Charger hardware setup</a></li>
Part 3: Network and Charger to backoffice communication (Wifi/ MQTT / OCPP)</li>
Part 4: Optional: Charger to Car communication (Mode2)</li>
</ul>
</blockquote>
For the last couple of months, I've been learning myself how to program in rust</a></p>
The main reason was I was intrigued by Rust's ownership / borrow model, which allows for functional programming, without the need of making everything immutable.</p>
Immutable comes with copying values (instead of passing references) all over the place, which can become an issue when you want to sqeeze every bit of performance out of your application.</p>
As rust is considered more of a systems language, being close to the hardware, using it to write applications for microcontrollers makes sense.</p>
Luckily the makers of the ESP 32 chip espressif</a> also created and maintain a development environment for these chips.
What they also did was create a bunch of rust crates that allows access to the chip hardware and features.</p>
There are two modes to write your code, no_std</code> and std</code></p>
With the no_std</code>, you cannot use Rust its standard library, which makes your application smaller, but you have to do a lot yourself, there are peripheral access and hardware abstraction crates and crates to setup wifi, logging, storage, etc, these are very much device specific. but you have to do all the wiring up.</p>
Therefore I will focus on the higher level std</code> approach which allows the use of all the goodies the standard library brings, plus more device independent abstractions which makes the code much more portable to other ESP32 devices.</p>
Application model</a></h2>
The application model for the std</code> mode look like this:</p>

The following libraries are made available</p>
Library</th> Description</th></tr></thead>

esp-idf-svc</td> Services like Wifi, Mqtt, Http</td></tr>
embedded-svc</td> device independent api and abstractions for the services</td></tr>
esp-idf-hal</td> safe wrappers around esp-idf-sys</td></tr>
embedded-hal</td> device independent api and common traits for the hardware</td></tr>
esp-idf-sys</td> unsafe bindings to the ESP hardware and features</td></tr>
</tbody></table>
A filtered out dependency tree from cargo tree</code> shows how the libraries depend on each other</p>
├── esp-idf-hal v0.42.5
│   ├── embedded-hal v0.2.7
│   ├── esp-idf-sys v0.33.7
├── esp-idf-svc v0.47.3
│   ├── embedded-svc v0.26.4
│   ├── esp-idf-hal v0.42.5
|   ├── esp-idf-sys v0.33.7
</code></pre>


Use case</a></h2>
As my daily work is all about allowing EV Drivers to charge their cars, I've decided to make a small EV charger</p>
For this I need to control GPIO (General Purpose Input Output) Pins to enable charging (relay), lock the cable (solenoid), display the charger state (multicolor led) and communicate to a backend (MQTT / IoT)</p>

hardware</a></h3>
I decided to use a M5 Stamp C3U</a> that I had lying around which is based on the ESP-32 C3U chip, a 1 core 32 bits RISC-V cpu running on 160Mhz</p>
It has 400Kb RAM and 4Mb Flash and has Wifi and Bluetooth capabilities</p>
There are 14 GPIO Pins, that can be setup als digital or analog input/ouput, and some of them use serial protocols like UART, I2C, I2S and SPI
so plenty to play around with</p>
setup</a></h3>
To get started I used the cookiecutter template Espressif has created: https://github.com/esp-rs/esp-idf-template</a></p>
This should also be your starting point, if you want to play with it yourselves.</p>
After installing the prerequisites a simple</p>
cargo generate esp-rs/esp-idf-template cargo
</code></pre>
will after answering a few questions generate a project for you.</p>
to build and flash it hook up your device to an usb port and do</p>
> cargo build
   Compiling rust-esp-charger v0.1.0 (/Users/gertjan/Projects/rust-esp-charger)
    Finished dev [optimized + debuginfo] target(s) in 1.96s
</code></pre>
and then:</p>
> espflash flash target/riscv32imc-esp-espidf/debug/rust-esp-charger
[2024-01-04T12:53:07Z INFO ] Detected 4 serial ports
[2024-01-04T12:53:07Z INFO ] Ports which match a known common dev board are highlighted
[2024-01-04T12:53:07Z INFO ] Please select a port
❯ /dev/cu.usbmodem1101 - USB JTAG_serial debug unit
  /dev/tty.usbmodem1101 - USB JTAG_serial debug unit
  /dev/cu.Bluetooth-Incoming-Port
  /dev/tty.Bluetooth-Incoming-Port
[2024-01-04T12:54:07Z INFO ] Serial port: '/dev/cu.usbmodem1101'
[2024-01-04T12:54:07Z INFO ] Connecting...
[2024-01-04T12:54:07Z INFO ] Using flash stub
Chip type:         esp32c3 (revision v0.3)
Crystal frequency: 40MHz
Flash size:        4MB
Features:          WiFi, BLE
MAC address:       84:f7:03:27:96:ec
App/part. size:    559,520/4,128,768 bytes, 13.55%
[00:00:04] [========================================]     271/271
[2024-01-04T12:54:13Z INFO ] Flashing has completed!

</code></pre>
The target might differ depending on the type of your ESP32 , but the rest should be the same.</p>
If you do</p>
> espflash monitor
</code></pre>
It will show you all the messages logged to the console, you can also add --monitor</code> to the flash command to do it in one go</p>
The Code</a></h2>
My first thoughts were that I would have to create multiple running tasks, that would handle controlling the hardware and communicating with the backend. so first I had to find out how to do that in rust and how I can communicate changes to those tasks.</p>
As the C code IDF Framwork is based on the FreeRTOS Kernel, I knew about things like xTaskPinnedToCore()</code> which runs a task in parallel to the main thread, and the xQueue*</code> API to send receive messages between tasks, unfortunately xTaskPinnedToCore() only allows C functions as a parameter, so no Rust goodies in there (or at least not to my knowledge, what's the signature of a rust function in C?)</p>
But as I can use the standard library, std::thread::spawn</code> is available to which I can pass a closure, but how to communicate changes?</p>
When you access a variable in the closure that is defined outside of the closure the compiler will make you use the move</code> keyword to explicitly move ownership to the closure.</p>
So for instance: if you have a simple Charger</code> struct that has a field state</code>, which holds the state of the charger (Available, Occupied, Charging, Error)
and you want to access that from within the thread, the compiler will complain about the last line that the charger's ownership has moved to the thread. as seen in the snippet below</p>
let mut charger = Charger{id: "1", state: "Available"}

thread:spawn(move || {
    println!("Charger from thread: {:?}", charger);
    loop {
        charger.state = "Charging";
        // sleep a bit
    }
});

println!("Charger from main: {:?}", charger);
</code></pre>
To solve this we need to use two concepts from rust synchronisation utilities.</p>

std::sync::Arc<T></code> Arc stands for Atomically Reference Counted, This will keep a reference for each time you clone the object, and makes sure the original object is updated with any changes.</li>
std::sync::Mutex<T></code> A Mutex will lock the object so only one thread can update the object at a time</li>
</ul>
So to get the above working:</p>
let org_charger: Arc<Mutex<Charger>> = Arc::new(Mutex::new(Charger{id: "1", state: "Available"}));

let charger = org_charger.clone();
thread:spawn(move || {
    println!("Charger from thread: {:?}", charger);
    loop {
        charger.state = "Charging";
        // sleep a bit
    }
});

let charger = org_charger.clone();
loop {
    println!("Charger from main: {:?}", charger);
    // sleep a bit
}
</code></pre>
Note that because the charger moves into the thread, I can reuse the charger var as the first one is no longer in scope, also note that the object does not need to be mutable anymore.</p>
Now how to control the leds, relays, buttons that are needed to make this charger functional?</p>
That's done through the "General Purpose Input Output" or GPIO, working with GPIO is pretty straightforward:</p>
Here we turn a led on when a button is pressed.</p>
use esp_idf_hal::delay::FreeRtos;
use esp_idf_hal::gpio::*;
use esp_idf_hal::peripherals::Peripherals;

let peripherals = Peripherals::take()?;
let mut led = PinDriver::output(peripherals.pins.gpio4)?;
let mut button = PinDriver::input(peripherals.pins.gpio9)?;

button.set_pull(Pull::Down)?;

loop {
    // we are using thread::sleep here to make sure the watchdog isn't triggered
    FreeRtos::delay_ms(10);

    if button.is_high() {
        led.set_low()?;
    } else {
        led.set_high()?;
    }
}
</code></pre>
Doing a button in a more async 'wait until pressed then do something' is a bit more involved:</p>
First set up the button and an interrupt:</p>
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::hal::gpio::{InterruptType, PinDriver, Pull};
use esp_idf_svc::hal::task::notification::Notification;

let mut button = PinDriver::input(peripherals.pins.gpio9)?; // pin 9 is the onboard button on the M5 Stamp C3U
button.set_pull(Pull::Up)?;
button.set_interrupt_type(InterruptType::PosEdge)?;

let notification = Notification::new();
let notifier = notification.notifier();

unsafe {
    button
        .subscribe(move || {
            notifier.notify_and_yield(NonZeroU32::new(1).unwrap());
        })?;
}
</code></pre>
Here we have created an interrupt that will notify when the button is pressed in this case on a Positive Edge (when the button is released).</p>
Now we can enable the interrupt and block until it is interrupt by someone pressing the button.</p>
loop {
    button.enable_interrupt()?;
    notification.wait(esp_idf_svc::hal::delay::BLOCK); // code blocks until button interrupts
    println!("Button was pressed and released");
}
</code></pre>
We do this in a separate thread so it won't block the rest</p>
The M5 Stamp that i'm using has an onboard multicolor led (SK6812 chip) attached to a gpio port, there is a rust library for that and other multicolor led, or ledstrips call smart_leds</code></p>
use smart_leds_trait::{SmartLedsWrite, White};
use ws2812_esp32_rmt_driver::driver::color::LedPixelColorGrbw32;
use ws2812_esp32_rmt_driver::{LedPixelEsp32Rmt, RGBW8};

fn main() -> Result {
    let driver = LedPixelEsp32Rmt::<RGBW8, LedPixelColorGrbw32>::new(0, 2)?; //Onboard led is attached to pin2
    let red = RGBW8::from((255, 0, 0, White(0)));
    let color = std::iter::repeat(red).take(1);
    driver.write(color)?;
}
</code></pre>
In the code linked at the bottom, I combined all the above in an application that runs on the ESP32-C3U and will cycle through all the charger states when the onboard button is pressed. showing the correct color on the onboard led and output the charger state in the console.</p>
Proving that you can run Rust on an ESP32, access the hardware and run code concurrently while being able to access shared objects.</p>
Thanks for reading, the next articles will most likely expand on this and be about:</p>

Controlling a minimal hardware setup for a charger (Relay, Led, Button) based on the charger's state</li>
Setup Wifi and MQTT to communicate with a backend, using the OCPP protocol</li>
Optionally: Control Pilot (CP) communications between the charger and the car over a Type2 Mennekes connector</li>
</ul>
References</a></h2>

Code: https://github.com/gertjana/charger_rust_esp32_c3/tree/806cba4c933c5211d2c4f4759c223452b8426158</li>
esp-idf-template: https://github.com/esp-rs/esp-idf-template</li>
M5 Stamp ESP32-C3U: https://docs.m5stack.com/en/core/stamp_c3u</li>
The embedded rust book:  https://docs.rust-embedded.org/book/</li>
Espresiff ESP-32: https://www.espressif.com/en/products/socs/esp32</li>
</ul>


Redis Migration
2023-10-10T00:00:00+00:00
I've read about dragonflydb</a>:</p>

Dragonfly is a drop-in Redis® replacement that is optimized for data-intensive, low latency applications. Applications built on Dragonfly get the full speed, reliability, and scalability that modern cloud hardware makes possible, allowing them to deliver incredible experiences to their users while reducing both costs and complexity.</p>
</blockquote>
so reading between all the marketing mumbo jumbo, it sounds like it's really fast and could replace any redis instance.</p>
So as a small exercise  I decided to migrate this blog which uses redis to dragonflydb.</p>
For the migration I followed the practice of first continously replicating the data, and then switch the application to the new one, and it turned out to be pretty easy:</p>
Prerequisites: the old redis-instance</code> and a fresh dragonfly-instance</code> one and redis-cli</code> installed.</p>
> redis-cli -h <dragonfly-instance> -p 6379

# an empty db
dragonfly-instance:6379> KEYS *
(empty array)

# with no replication
dragonfly-instance:6379> INFO replication
# Replication
role:master
connected_slaves:0
master_replid:68ffe35f52d262f9e86b7e14de8ee98020764bb6

# turn on replication
dragonfly-instance:6379> REPLICAOF <old redis-instance> 6379
OK

dragonfly-instance:6379> INFO replication
# Replication
role:replica
master_host:<old redis-instance>
master_port:6379
master_link_status:up
master_last_io_seconds_ago:1
master_sync_in_progress:0

# we now have all the data here
dragonfly-instance:6379> KEYS *
# shows all the migrated keys, but for obvious reasons I've omitted them
</code></pre>
Now I stop and update the server to use the new instance</p>
now I turn off replication, this is needed as replica's are read only.</p>
dragonfly-instance:6379> REPLICAOF NO ONE
OK
</code></pre>
And now start the application again.</p>
And that's it, the blog is now using dragonflydb instead of redis.</p>
Now all is needed is to get those millions and millions of visitors to this blog. so i can reap the benefits of the speed of dragonflydb. /s</p>


Implement page stats
2023-07-14T00:00:00+00:00
In a previous blog</a> I talked about a blog I created with Sveltekit</a>
and after I added some SEO related metadata. I wanted to see if it's actually being found and read.</p>
I could of course just add google analytics or something similar, but I'm learning about Svelte and Typescript. so lets if we can implement a simple pageview counter, storing it in redis.
which is a superfast key/value database making it ideal for this kind of data.</p>
Upstash</a> provides one free redis db when you signup and after creating a database, you can copy paste the connection string from the dashboard.</p>
Im using ioredis</a>, the offical redis client written in typescript;</p>
npm install -D ioredis
</code></pre>
Creating the client is a simple as creating a new Redis(connection_string)</code>. In the case I populate the REDIS_CONNECTION</code> env variable with the url from upstach</p>
import Redis from 'ioredis';

const connection = () => {
  let connection = process.env.REDIS_CONNECTION ?? "redis://localhost:6379";
  return new Redis(connection);
}
</code></pre>
Then I need a function to increment the pageview</p>
import { dev } from '$app/environment';

export const incrementPageView: (slug: string) => Promise<number>  = async (slug: string) => {
  let prefix = "prod";
  if (dev) { prefix = "dev"; }
 return await redis().incr(`${prefix}:post:${slug}:views`);
}
</code></pre>
incr(key: string)</code> creates the key with value 1 if it doesn't exist, increments it otherwise and returns the updated value.</p>
I add an prefix to the key to differentiate between my dev environment and the 'production' one. (only got one free db)</p>
now I want a page to list all the pageviews for that I need a function that returns all those</p>
type PageView = {
    slug: string;
    views: number;
}

export const getPageViews: () => Promise<PageView[]> = async () => {
  let prefix = "prod";
  if (dev) { prefix = "dev"; }

  const keys = await connection().keys(`${prefix}:post:*:views`);

  if (keys.length != 0) {
    const views: string[] = (await redis().mget(...keys)).map((view) => view ?? '0');

    return keys.map((key, index) => {
        return {
            slug: key.split(':')[2],
            views: parseInt(views[index])
        }
    });
  } else {
    return [];
  }
};
</code></pre>
let's go through this, Redis doesn't have functionality to return a list of key/values in one go, so first I have to get the keys</p>
  const keys: string[] = await connection().keys(`${prefix}post:*:views`);
</code></pre>
.. and then the values, Redis has the mget</code> call where you specify multiple keys as arguments. ...</code> is the so called spread operator which transforms an array into a list of arguments.</p>
  const views: PageView[] = await redis().mget(...keys).map((view) => view ?? '0');
</code></pre>
when a key doesn't exists its return's null</code> for that key, so the result type for mget is Promise<(string | null)[]></code> where null should never happen as i'm getting the keys from the same data. to get to a Promise<string[]></code> type I just map null's to '0'</code> with the ??</code> operator. then I merge both the slug from the key and the views into the PageView[] result;</p>
In the end I only have to do 2 calls.</p>
one thing to remember is that the keys()</code> method is blocking and goes over every key in your database, so for high traffic/low latency applications you are better of using scan()</code> which is not blocking but only returns a subset, meaning have to call it multiple times to get all the results. I might update my code to do this, but for the purpose of this blog it's fine.</p>
So now what's left is to call the incrementPageviews()</code> method, in the server side load method that is called whenever a page is requested:</p>
import { incrementPageView } from '$lib/server/redis.ts';

export const load: PageServerLoad = async ({ params }) => {
  const { slug } = params;

  ...

  let pageviews = await incrementPageView(slug);

  return {
    ...,
    pageviews: pageviews,
  }
</code></pre>
I also return the pageviews, so it can be displayed on the page somewhere if needed</p>
To show all pageviews  on a page I created a component:</p>
<!-- /src/components/PageView.svelte -->
<script lang="ts">
  import  type { PageView } from '$lib/types';

  export let data: PageView[];
  // sort on number of page views
  let sorted: PageView[] = data.sort((a, b) => b.views - a.views);
</script>


{#if sorted.length === 0}
  <p>No pageviews yet.</p>
{:else}
  <table class="pageviews">
    <thead>
      <tr>
          <th>Page</th>
          <th>Views</th>
      </tr>
    </thead>
    <tbody>
      {#each sorted as item}
        <tr>
          <td>{item.slug}</td>
          <td class="views">{item.views}</td>
        </tr>
      {/each}
    </tbody>
  </table>
{/if}
</code></pre>
and the page i'm using it in:</p>
// /stats/+page.server.ts
import type { PageServerLoad } from './$types';
import { getPageViews } from '$lib/server/redis.ts';

export const load: PageServerLoad = (async () => {
    return {
        pageviews: getPageViews(),
    };
  })
</code></pre>
<!-- /stats/+page.md -->
<script lang="ts">
  import PageViews from '$src/components/PageViews.svelte'

  import type { PageData } from './$types';
  export let data: PageData;
</script>

# Pageviews

<PageViews data={data.pageviews} />
</code></pre>
Further steps</a></h2>
I may want to implement some more functionality, calculate reading time, based on the nr of words. and then a metric to calculate the reading time.</p>
If I do the redis data is going to move to hashsets where the slug is a hash under which several sets of metrics can be stored.</p>


Made a new Blog
2023-06-27T00:00:00+00:00

gertjanassies.dev

Spec-Driven Agents

Getting Started</a></h2> Note that this currently only works with opencode</p> </blockquote> The project installs with a single script:</p>

Random Numbers on a Homebrew FPGA CPU

Experimenting with AI in FPGA Development

Another approach to checked exceptions with the Result type

When to Use It</a></h2> The Result type shines for:</p> Repository/data access layers</strong>: File I/O, database queries, external API calls</li> Business logic</strong>: Validation, calculations, domain operations that can fail</li>

Building a USB Keep-Awake Device with MicroPython

The Big Picture</a></h3> Our device has a simple state machine:</p> Idle</strong> (blue LEDs) - Device is plugged in but not keeping the laptop awake</li> Active</strong> (green LEDs) - Device is simulating user activity every 30 seconds</li>

Rust on ESP32 part 2.5 - Switching software to Rust no_std and Embassy

The Result</a></h2> We now have an application that is very responsive to what's happening</li> Embassy handles the concurrency, which will reduce bugs and possible race conditions</li>

Rust on ESP32 part 2 - The hardware

Rust on ESP32

Redis Migration

Implement page stats

Made a new Blog