Tracer
A handheld debugger for a rig that is already built. Waveshare PocketTerm35 chassis, Raspberry Pi 5 inside, and a custom OS that boots straight into twelve diagnostic tools. Optional, never mounted in the vehicle, and entirely open source.
You do not need one of these
Tracer is a developer tool. It is not part of a TrailCurrent install, it is not mounted in the vehicle, and nothing on the platform requires it, waits for it, or works better because you own one. If you are building, running, or living in a rig, you can skip this page entirely and lose nothing.
It is here for the people writing firmware, building their own modules, or contributing to the project, who want an easier way to see what the system is actually doing once everything is bolted into places you cannot reach with a laptop.
What's Inside / Developer Tool
The Field Debugger
Once a system is installed, the modules go where they have to go, which is rarely anywhere convenient. Behind a wall panel, under a bunk, inside a cabinet. A laptop wants a surface and a spare hand. Tracer wants neither.
The hardware is off the shelf: a Waveshare PocketTerm35 handheld with a 3.5 inch touchscreen, a full QWERTY thumb keyboard, a D-pad with A, B, X and Y buttons, a speaker and a battery, with a Raspberry Pi 5 inside. Waveshare sells the chassis empty and the assembly is a screwdriver job.
The software is the project. Power on, splash screen, and then a grid of twelve tools. No desktop, no window manager, no login prompt, nothing between you and the thing you came to look at.
What It Is For
Three questions that are hard to answer once everything is installed.
What is the system actually saying?
Watch the live traffic between modules, sniff the vehicle's CAN bus, and see which modules are announcing themselves, standing right next to the module you are suspicious of.
Is the problem the rig or the app?
Tracer reads the system underneath the dashboard rather than through it, so when the app is the broken layer you still get a straight answer. Where the two disagree, that disagreement is the finding.
Can I make it happen on demand?
Emulate any module, send deliberately wrong values, and record a stretch of live traffic to replay later. Bugs that only appear on the road become bugs you can reproduce in the driveway.
Twelve Tools and a Settings Screen
Every tile carries its own live status line, so the answer is often on this screen before you open anything.
Every screen works from the buttons alone, and separately from touch alone. You can drive the whole device one-handed with your thumb on the D-pad, or put it down and tap.
There is no on-screen keyboard anywhere in the interface. The device has a real one.
Light and dark themes both ship, switchable live, so the screen is readable in a dim storage bay and in direct sun.
MQTT Inspector
The live message tree between every module, with payloads. Expand a branch, pause the feed, read what actually went past.
Discovery
Every module announcing itself on the network, and whether it has been onboarded.
Capture
Record a window of live traffic, name the session, and play it back later, on loop if you want.
Firmware
Push an update to Headwaters from a USB stick, without depending on the web layer being healthy.
Network
Signal, address, and five live reachability checks against everything the rig depends on.
Terminal
A real shell on the handheld, for the times a tool is not the right shape for the question.
Logs
Container and system logs pulled off the Headwaters box, filtered by level.
CAN Sniffer
Raw and decoded frames off the vehicle bus, named against the fleet's shared CAN database.
Headwaters
Container health, CPU, temperature and disk on the box that runs everything.
GNSS & Map
Fix quality, satellite count and position on an offline map.
Simulate
Emulate any module's CAN traffic, or send deliberately wrong values to see how the system copes.
Module Debug
A serial console for any board you plug into the USB port. ESP32, Arduino, Pico, an unbranded clone.
Making a Parked Trailer Think It Is Moving
Some of the most annoying bugs in a vehicle only exist while the vehicle is doing something. A rule that fires when you start driving. An alert that goes quiet above a certain speed. You cannot chase those from the driveway, and you should not be chasing them at highway speed with a laptop in the passenger seat.
Simulate lets the handheld pretend to be any module on the bus. Pick Bearing, choose the message that carries position and speed, fill in the values, and send it. Everything downstream reacts exactly as it would if the rig were rolling.
The whole list is generated from the fleet's shared CAN database, so when a module gains a new message, Tracer can simulate it the next time it starts, with no code change.
The Screens
Captured from the device.
Build One
Three things to buy. Everything else is free.
Some source links are affiliate links. They cost you nothing extra and send a small cut back to the project.
| Part | Notes | Source |
|---|---|---|
| Waveshare PocketTerm35 | The handheld chassis. Ships empty: screen, keyboard, buttons, speaker and battery, no compute. | Waveshare |
| Raspberry Pi 5 | Goes inside the chassis. Any memory configuration works. | Any Raspberry Pi reseller |
| microSD card | Holds the image. | Anywhere |
Then flash it
Assemble the Pi into the chassis, then clone the repository and run the image build. It asks you for a username and a password, writes a card, and that card boots to the launcher. The build instructions live in the repo and are kept current there rather than duplicated here.
If you would rather see it working before you commit to building one, the build log has the video and a walk through every tool.
Build instructions on GitHub
Where It Stands
Being straight about what is finished and what is not.
Working on real hardware
The image boots to the launcher on a flashed card and all twelve tools are implemented. Anything with nothing to report says so rather than showing a number. Nothing is invented to make a screen look busy.
Not finished yet
Touch has not been fully validated on the panel, and the WiFi join flow still needs a run on a freshly flashed card with no saved network. Both are in progress. The repository is the honest, current picture.
Tracer Is Open Source
The daemon, the interface, the image build and the documentation are all in the repository under the MIT license, same as everything else we make.
Read the story behind it in the build log.