For about a year, fixing something in the trailer meant sitting on the floor with a laptop balanced on one knee, screen turned sideways, one arm shoved into a cabinet. It worked. It was miserable. So we built the thing we actually wanted: a handheld that fits in one hand, boots in seconds, and knows how to ask our system what is wrong.
The laptop was the problem
Once a TrailCurrent system is actually installed, it stops being a thing on a workbench. The modules go where they need to go, which is almost never anywhere convenient. Behind a wall panel. Under a bunk. Inside a cabinet with a cable run you regret. The brain of the system sits in a compartment you have to kneel to reach.
A laptop wants a surface, a lap, and a hand for the trackpad. Troubleshooting a connector wants both of your hands. Those two facts fight each other every single time, and the laptop usually wins by taking over the only flat spot you have.
What we wanted was closer to what a mechanic reaches for. Something you hold, something with buttons you can find without looking, something that turns on and is immediately useful instead of asking you to open three windows first.
What Tracer is
Tracer is two things stacked together.
The hardware is off the shelf. It is a Waveshare PocketTerm35, a handheld shell with a 3.5 inch 640 by 480 touchscreen, a full QWERTY thumb keyboard, a D-pad with A, B, X and Y buttons, a speaker, and a battery. Inside it sits a Raspberry Pi 5. Waveshare sells the chassis empty. You supply the Pi, and the assembly is a screwdriver job.
The software is ours, and it is the actual project. Tracer is a custom Raspberry Pi OS image that boots straight into a full-screen launcher. No desktop. No window manager. No login prompt. Power on, splash screen, and then a grid of twelve tools you drive with the D-pad or your thumb.
Roughly, the twelve tools fall into four jobs:
- Listen to the rig. Watch the live message traffic between modules, sniff the vehicle's CAN bus, see which modules are announcing themselves on the network, and run reachability checks against the brain of the system.
- Check the brain. Container health, temperature and disk on the Headwaters box, its logs, and a plain shell when you need one.
- Push and poke. Deploy a Headwaters update package, or open a raw serial console to any board plugged into the USB port.
- Record and replay. Capture a window of live traffic, name it, and play it back later. Or make the system believe something that is not happening.
There is one design decision underneath all of it that is worth calling out, because it is the reason Tracer is useful at all. Tracer never talks to Headwaters through its web API. If it did, it could only ever tell you what the app already tells you, and when the backend is the broken layer, an app-shaped tool is blind to precisely the bug you are hunting. So Tracer reads the layers underneath: the message bus directly, the database through the container, the logs from the system journal. Where Tracer's answer and the app's answer disagree, that disagreement is the finding.
Making the 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 should fire when you start driving. An alert that is supposed to go quiet above a certain speed. A screen that behaves fine parked and gets strange on the highway.
You cannot chase those from the driveway, and you should not be chasing them at 65 miles an hour with a laptop in the passenger seat.
The Simulate tool solves this by letting the handheld pretend to be any module in the system. Pick Bearing, our location module, choose the message that reports position and speed, fill in the values you want, and put it on the bus. Everything downstream reacts exactly as it would if the rig were actually rolling down the road. Your rules fire. Your screens update. Your alerts do whatever they were going to do, while the trailer sits in the driveway with the parking brake on.
The same trick works in the other direction. You can emulate a module that is not even fitted yet, or send a module deliberately wrong values to find out whether the system handles nonsense gracefully or falls over.
None of that list is typed in by hand. Tracer reads the fleet's shared CAN database, all 88 messages and 258 signals of it, and builds the module list, the message list, the field names, the units and the valid ranges from that. When a module gains a new message, Tracer can simulate it the next time it starts, with no code change.
When the thing you would normally use is the thing that is broken
Normally you push an update to the rig from your browser or from the app. That works right up until the update path itself is what is misbehaving, and then you are stuck trying to use the broken tool to fix the broken tool.
Tracer's Firmware tool does the same job the manual way. It browses a USB stick, copies the package to the box over an encrypted connection, unpacks it and runs the deployment script, which is the same sequence our own deployment documentation describes for doing it by hand. Different path, same result, and it does not care whether the web layer is healthy.
Module Debug is the equivalent for the small boards. Plug any board into the USB port, ESP32 or otherwise, and you get a raw serial console with the keyboard live. Nothing is filtered or reformatted. It is the same view you would get sitting at a desk, except you are sitting on the floor of a trailer holding it in one hand.
You do not need one of these
This part matters, so we are going to be blunt about it.
Tracer is optional. It is not mounted in the vehicle. It is not part of the system. Nothing on the TrailCurrent platform requires it, waits for it, or works better because you own one. If you are building a rig, running one, or living in one, you can ignore this entire project and lose absolutely nothing.
Tracer is a bench tool for the people doing development work against the platform: us, contributors, and anyone building their own modules who wants an easier way to see what the system is actually doing. It sits alongside Headwaters and Peregrine in the module list because it is built and documented the same way, not because it belongs in the same category of usefulness for a typical owner.
We would rather say that clearly than let a shopping list grow by one item that nobody needs.
The part that has nothing to do with us
Here is where this gets useful to people who will never own a travel trailer.
"Make a Raspberry Pi boot straight into my own application, full screen, with no desktop behind it" is a thing an enormous number of people want and a surprising number of people give up on. Most guides get you to a desktop with an app auto-starting on top of it, which is not the same thing and never feels like it.
Tracer is a complete, working, public answer to that. The whole image build is in the repository: the config, the layer that installs the packages and trims the boot chain, the systemd units, the splash screen generator, the permission rules, and the documentation for compiling and flashing it. It is built with rpi-image-gen, the Raspberry Pi Foundation's own image tool, pinned to a known good commit. If you want a Pi that boots into one thing and only one thing, you can lift that layer and swap our application for yours.
And along the way we found things about this specific handheld that anybody who buys one will eventually run into. They are written up in the repository, with the command output behind them where there is any:
- The screen is plain HDMI. Waveshare ships an overlay with "dpi" in its name and files it in a folder that suggests otherwise, and there is a lot of confusion online about which display driver you need. Take the overlay apart and it contains a touch controller and no display node at all. The panel reports 640 by 480 as its native mode and the stock Raspberry Pi graphics stack drives it with nothing special added. That removes a whole category of work most people expect to do.
- There is no gamepad. The D-pad and the A, B, X, Y buttons look like a game controller and are not one. To the Pi they are literally a keyboard, and those four buttons are the letter keys A, B, X and Y. Which means the moment your app has a text field, four of your buttons have to stop being buttons and start typing. Only Start and Select carry no character, so they are the only two that can safely mean the same thing everywhere.
- The power button needed taming. Out of the box a short press kills the unit outright, which is a bad trait in something that lives in a bag and gets brushed against. The image makes a short press arrive at the application as an event instead, so it can put up a "shut down?" dialog. A long press still powers off at the system level, as the escape hatch.
- The buttons have a single point of failure. Every button and the speaker hang off one small controller chip, and its reset button is exposed on the back of the case. Double tap it by accident and every button on the device dies at once until you recover it over USB. The touchscreen is on a separate connection and keeps working, which is why we made every screen fully usable by touch alone rather than treating touch as a nice extra.
All of it is at github.com/trailcurrentoss/TrailCurrentTracer under the MIT license, same as everything else we make. The daemon is Python with no third party packages at all. The interface is plain JavaScript with no framework and no build step, so changing a screen is editing a file and refreshing.
That is the giveback we care about most. We needed one specific tool for one specific system, and the parts underneath it turned out to be reusable by anyone pointing a small computer at a problem.
If you want to build one
You need three things: the chassis, a Raspberry Pi 5, and a microSD card. Everything else is free.
The chassis is the Waveshare PocketTerm35. That link carries our affiliate tag, which costs you nothing and sends a small cut back to the project. If you would rather not, strip ?aff_id=Trailcurrent off the URL and buy it clean. We would still rather you had the information.
Then clone the repository and follow docs/building.md. The build asks you for a username and a password every time and refuses to run without them, because a default credential that ships identically on every unit is not a placeholder, it is a shipped password recorded in public history forever.
Full details, screenshots of every tool, and the build steps are on the Tracer page.
Where it goes next
Being honest about the state of it: the launcher, the tools and the image all work on real hardware, and the button navigation is confirmed end to end. Two things are not finished. Touch has not been properly validated on the panel yet, and since touch is the recovery path when the buttons die, that is the next job rather than a polish item. The WiFi join flow also still needs a run on a freshly flashed card with no saved network.
After that, the interesting direction is the one this tool keeps pointing at. Every hour spent chasing a bug in an installed rig is an hour that tells us something about what the system should have told us on its own. The best outcome for Tracer is that we need it less over time.
New posts land here first, and the videos go up on the open source channel as we make them.