MeterMind
by jrperson
README.md
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/metermind-dark.svg">
<img src="docs/metermind-light.svg" alt="MeterMind" width="220">
</picture>
</p>
# MeterMind
<p align="center">
<img src="docs/meter-and-boards.jpg" alt="Five MeterMind boards in front of a Digcreat XDM1041-DG; the connected one's status LED is green" width="480"><br>
<a href="board/">Order your own board</a> · <a href="https://jrperson.github.io/MeterMind/">Install the firmware</a>
</p>
MeterMind lets an AI agent use a bench multimeter more easily, and now wireless! It's made for the
OWON XDM1041 (and tested on a rebadged one, the Digcreat XDM1041-DG). Plug the little MeterMind
board into the back of the meter, put it on your WiFi, and your agent can set up the meter and take
readings on its own.
**Why I made it.** The meter's serial connection is full of gotchas: set commands never answer,
commands sent while it's busy just vanish, and readings stay stale for a moment after you change
modes ([PROTOCOL.md](PROTOCOL.md)). I had a protocol file that smoothed all of that out, and I had
to add it to every project that used the meter. Now that work lives on the board, so every project
gets the same clean, easy-to-use interface. No cable, no copied code.
No board? You can still skip the gotchas: [PROTOCOL.md](PROTOCOL.md) documents every one, and the
Python version in `bridge/` runs on your computer with the meter plugged in over USB, serving the
same API ([below](#run-it-without-the-board)).
The board serves:
- **An MCP server** at `/mcp`, so AI agents can configure the meter and take measurements.
- **An HTTP/JSON API and a WebSocket stream** ([API.md](API.md)). No client library needed.
- **A dashboard** at `http://metermind.local/` that works like the meter's front panel: the same
screen, keys, ranges and speeds, live readings, and the jacks the leads should be in.
- **Raw SCPI on TCP port 5025** for lab software such as PyVISA.
## Install the firmware
**From the browser:** open the [web installer](https://jrperson.github.io/MeterMind/) in Chrome or
Edge, connect the board's USB-C port to the computer, press **Install** and pick the board's
serial port. The installer is built from `flasher/` by the release workflow.
**From source** ([ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/v5.5.4/esp32s3/) 5.5.2 or later in the 5.5 series; releases are built with 5.5.4):
```sh
. ~/esp/esp-idf-v5.5/export.sh
cd firmware
idf.py build
idf.py -p /dev/cu.usbserial-XXXX flash monitor # the board's USB-C port
```
`tools/build_flasher.sh` makes the same release build the installer ships (from
`sdkconfig.defaults` only) and assembles `flasher/` for local testing.
## Connect it to WiFi
On first start the status LED blinks blue and the board opens its own network,
**MeterMind-XXXX**. Join it from a phone or laptop; the setup page opens by itself (or browse to
`http://192.168.4.1/`). Pick your 2.4 GHz network and enter its password. Then rejoin your own
network and open `http://metermind.local/`. Hold BOOT for 3 s to change the network later.
Details, the serial console and the LED colours: [firmware/README.md](firmware/README.md).
## Use it
```sh
curl metermind.local/api/reading
curl -X POST metermind.local/api/measure -d '{"function":"dcv","samples":5}'
curl -X PUT metermind.local/api/config -d '{"function":"res","range":5000}'
```
Add it to Claude Code as an MCP server:
```sh
claude mcp add --transport http metermind http://metermind.local/mcp
```
PyVISA: `rm.open_resource("TCPIP::metermind.local::5025::SOCKET", read_termination="\n")`.
### The test leads
The meter cannot sense where the leads are plugged in, so you tell the bridge: tap the jack the
red lead is in on the dashboard, or `PUT /api/leads`. The bridge then refuses a function or range
that does not suit that jack, for example volts with the red lead in a current jack (which blows
the fuse when the leads touch a voltage source). The dashboard can override after asking you; AI
agents cannot, and are told to ask you instead. The setting starts as "not set" after a restart,
and until it is set, current functions are refused. Rules: [API.md](API.md#get-apileads-put-apileads).
## How it works
- **One task owns the meter.** The ESP32-S3 is a USB host to the meter's CH340 serial chip. A
single task holds the link; every client's request goes through its queue, so requests never
collide. It polls readings 10 times a second, paces and verifies every set command, and holds
readings back after a function or range change until the meter has settled (also while it is
still autoranging).
- **One operation layer for every transport.** REST, WebSocket, MCP and raw SCPI call the same
operations (`bridge.c`), so they validate and behave the same way.
- **The board** switches the meter's USB power through a current-limited switch: the firmware can
power-cycle a stuck meter link and reports an overload. It also runs the WiFi setup network,
mDNS (`metermind.local`, `_metermind._tcp`) and the status LED.
- **A Python prototype** in `bridge/` serves the same API on a computer with the meter connected
over USB. The firmware is a module-for-module port of it, and the two are kept in step.
| Path | What it is |
|---|---|
| `firmware/` | The ESP32-S3 firmware (ESP-IDF); see [firmware/README.md](firmware/README.md) |
| `bridge/` | The Python prototype; `bridge/static/index.html` is the dashboard both serve |
| `flasher/` | The web installer page (ESP Web Tools) |
| `board/` | Order files for the board and how to order it |
| `API.md` | The network API: REST, WebSocket, MCP, SCPI |
| `PROTOCOL.md` | What was learned about the meter's USB and SCPI behaviour |
| `tools/smoke_test.py` | End-to-end test against a real meter |
| `tools/build_flasher.sh` | Release build and installer assembly |
## The board
The firmware runs on the MeterMind board: an ESP32-S3-MINI-1-N8, a USB-A socket that connects to
the meter through a rigid USB-A-male to USB-B-male adapter, meter USB power through a 0.5 A
current-limited switch, USB-C for 5 V power (1 A or more) and a CH340C serial console with
auto-reset, an RGB status LED, and BOOT and RESET buttons.
It's open hardware: [`board/`](board/) has the gerbers, BOM, placement file and schematic, and a
step-by-step guide to ordering it assembled from JLCPCB. The pin map is in
`firmware/main/board.h`; other ESP32-S3 boards with a USB host port should run the firmware after
adjusting it (untested).
## Run it without the board
The Python prototype runs on a computer with the meter plugged in over USB:
```sh
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python -m bridge # finds the meter's CH340; --mdns advertises metermind.local
```
It serves the same dashboard and API at http://localhost:8041 (MCP: `http://localhost:8041/mcp`).
## Tests
- `tools/smoke_test.py [http://metermind.local]`: end-to-end against a real meter, through the
board or the prototype. **Disconnect the probes first.** It switches functions (including DC
current on the open input), checks the lead rules, MCP and the raw SCPI port, and restores the
lead setting afterwards.
- `firmware/tests/run_tests.sh`: host tests for the firmware's parser, checked against the
prototype's.
## Security
There is no authentication: anyone on your network can drive the meter, change the lead setting
and override it. Requests from web pages on other sites are refused (`Origin` check), which
blocks DNS-rebinding attacks. The WiFi setup network is open unless you set
`CONFIG_BRIDGE_SETUP_PASSWORD`; it only accepts WiFi changes while setup mode is on (BOOT held for
3 s, or no network saved). Run MeterMind on a network you trust.
## Status
- [x] Protocol mapped: queries, set commands, ranges, timing quirks
- [x] Python prototype: REST, WebSocket, MCP, raw SCPI, mDNS, dashboard
- [x] Firmware on the v0.1 board: all transports, WiFi setup with a captive portal, front-panel
dashboard, lead setting; smoke test passes on the board
- [x] Web installer
- [ ] Firmware updates over WiFi (two OTA slots are reserved; the update code is not written yet)
- [ ] Front-panel features the bridge cannot drive yet: Run/Stop, Math, Record, Dual, Rel, and the
secondary display
## Licence
Copyright (C) 2026 plasmata
The board design in `board/` is open hardware under the CERN-OHL-S v2 ([board/LICENSE](board/LICENSE)).
Everything else is software:
MeterMind is free software: you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version. It is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; see [LICENSE](LICENSE) for details.
Built with, under their own licences: ESP-IDF and Espressif's `led_strip`, `mdns`,
`usb_host_cdc_acm` and `usb_host_ch34x_vcp` components (Apache-2.0), cJSON (MIT), ESP Web Tools,
which the installer page loads (Apache-2.0), and for the prototype pyserial (BSD), aiohttp
(Apache-2.0) and zeroconf (LGPL). The logo and credit lettering are drawn with the Orbitron font
(SIL Open Font License 1.1).
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data