A Notebook for the Board on My Desk

This autumn I followed a long discussion about getting smart TVs to stop reporting home, and it left me wanting to understand the hardware side properly. My drawer of things I cannot throw out had two old ISP routers in it. One delivery of tiny screwdrivers and plastic pry tools later, one of them was open on my desk, and a few videos about UART made the next step look easy enough.

I took photos and asked Claude a beginner's question: why are some of these headers in pairs and others in a single row? It decided I was hacking something and declined. It was my own router, and the question is on page one of every tutorial. I sent feedback, which was mostly a sigh, and asked DeepSeek instead.

Next to the router there is now a USB serial adapter, a multimeter and a logic analyser clone that cost less than lunch. I am new to this, and what I kept losing was what I had already found. Which of the four pins was ground? What did the meter say on pin 2, and was the board powered at the time? Which speed gave readable text, and which capture was the good one? I had the answers in a text file, a folder of photos and a terminal scrollback, and none of them knew about the others.

So I built a notebook that does, and I built it with Claude. Once I explained that I wanted a project to learn on safely, it was a very good building partner. I asked for something comprehensive, with features I might grow into later, and it took that seriously.

PCB Visualizer is a local workbench for documenting the debug interfaces of a circuit board. Version 0.1.0 is out today, two weeks after I opened the router, MIT licensed, for Arch Linux.

What it does

You photograph the board and mark its headers on the photo. Each header gets a pin grid, and each pin gets a role, its readings and your notes. The serial console finds the speed, highlights bootloader and login prompts, and saves every session as a capture in the board's folder. Logic captures from sigrok open in the same project, the app decodes the UART, and it compares the decoded text with what the console saw.

Playbooks walk through the method one step at a time: find the header, find ground with the board unplugged, measure voltages with it powered, then connect. They check your answers against what the board folder recorded, and the safety steps come first.

For a beginner like me, the part I use most is the wiki: forty pages on electricity, schematics, tools, interfaces and boot. There is also a guided tutorial, Find the UART, on a practice board and a virtual board, so you can learn the whole sequence before you touch real hardware.

Where the data lives

Everything stays on your machine. The service listens only on this computer, and there is no account and nothing to sign in to. A board is a plain folder of files that you can read, copy and keep in git.

Router boot logs and config dumps are full of Wi-Fi keys and admin passwords, so git is off until you turn it on. When it is on, a commit guard scans every commit for secrets, and the app refuses to push to a public GitHub repository. Exports and copies for sharing are redacted by default. The board folder itself keeps what you recorded, because it is your notebook.

The optional assistant

There is an assistant, and it is off by default. When you turn it on, it can read the board, look at the photos and suggest labels, pin roles and console commands. Every suggestion waits for your approval, and an accepted pin role stays marked as a guess until you measure it. A confident wrong answer about which pin is TX can cost you an adapter, so the assistant suggests and you decide.

After the router question, I wanted the choice of model to be yours. You pick the model server: OpenRouter, the DeepSeek API, or a local Ollama on your own machine. If you choose a cloud service, the board data in your questions goes to that provider, and the privacy statement says exactly when data leaves the machine.

What was new this time

My first released project was a small game on itch.io, and I would prefer you did not go looking for it. ORRERY came next and reads the log file Elite Dangerous writes. Time Converter is a browser extension with no permissions. Kofte and the Macro Tracker are Android apps, and the Macro Tracker needed a small server I had said I would never need.

PCB Visualizer is about the size of the Macro Tracker in code, but it has more moving parts: a Python service, a browser interface, a small Rust desktop shell, a sigrok importer, forty wiki pages and the tests for all of it. It is also the first project where I run all of the infrastructure myself. Google Play and the browser stores distribute the others.

I had never built a package for Arch before. The plan was the AUR, but it closed new accounts in June during a wave of supply-chain attacks, and apart from a short reopening in July it has stayed closed. It was the second time on this project that the usual route was shut, and the answer was the same as with the router question: build my own. So I set up a signed repository. I build a package that carries its own Python, sign it with my own key and publish it from the same €6 Hetzner server that serves this page and the demo at pcb.lethio.com.

It is also the first project tied directly to a hobby. I expect to use it every time I open a board, and to spend a good part of my evenings on it for a while.

Getting it

On Arch Linux, the package comes from the signed repository, for the same reason this article lives on my own site first. The README has the three steps: trust the key, add the repository, install. After that, updates arrive with your normal pacman -Syu. An AUR package follows when the AUR takes new accounts again.

The source is on GitHub, and pcb.lethio.com walks through an investigation in the browser, with nothing to install. The roadmap lists what comes after: reading flash chips, an encrypted place for board secrets and an inventory of your tools.

It is MIT licensed. If it does almost what you need, fork it and make it yours.

The first board I document with it will be the router, and I will write that up when I get through it.