fakemeter

A Linux BLE peripheral emulator that impersonates Bluetooth multimeters, so a meter's official phone app connects to it and decodes frames you craft. Set a known reading (e.g. 4.200 V DC); if the app displays it, the decode is correct — if it differs, you've found a bug. A hardware-free way to verify BLE multimeter decode logic (built to validate the uni-t-mmu-ble drivers).

   ┌─────────────────────────┐         BLE         ┌──────────────────────────┐
   │  fakemeter (this tool)  │  advertise 0xFFF0   │   phone                  │
   │  ───────────────────    │ ──────────────────▶ │   ┌────────────────────┐ │
   │  craft bytes for a      │                     │   │ vendor app /       │ │
   │  KNOWN reading, e.g.    │   notify (0xFFF4)   │   │ Web-Bluetooth app  │ │
   │  "4.200 V DC"           │ ──── frame bytes ──▶│   │ DECODES + DISPLAYS │ │
   │                         │                     │   └────────────────────┘ │
   │  (you know the input)   │ ◀── writes (0xFFF3) │   (human reads output)   │
   └─────────────────────────┘     logged          └──────────────────────────┘

Eleven profiles across the OWON, Voltcraft, UNI-T, AiCare and BDM families — five live-validated against the real vendor apps (table below).

Requirements

• Linux with BlueZ (tested on 5.72) and a working BLE adapter — hciconfig should show it UP RUNNING.
• bluezero, which sits on the distro's python3-gi + python3-dbus (PyGObject). Those don't pip-build cleanly, so install them from apt and let the install see them (below).

Install

sudo apt install python3-gi python3-dbus            # system BLE stack

pipx install --system-site-packages fakemeter       # isolated CLI, recommended
# — or into a venv —
python3 -m venv --system-site-packages .venv && . .venv/bin/activate
pip install fakemeter

Both give you the fakemeter command. (From source: clone, then pip install -e . in the same kind of --system-site-packages venv.)

Run

fakemeter --profile voltcraft        # advertises + opens a REPL

--profile takes any id from the table. Connect the vendor app to the advertised device — it shows the initial 4.200 V DC. Drive it from the REPL:

p           play a preset             v 230.5 V    set value / function / prefix
f hold      toggle a flag             r            re-send the current frame
raw <hex>   inject an arbitrary frame s            voltcraft bit-sweep
series <id> / auth <mode> / walk on|off            ?  help        q  quit

Useful flags:

• --name NAME — advertised name. Several apps only list an exact model name (see Gotchas) — pass the real one, not the *-FAKE default.
• --adapter hciN — which adapter (default hci0; also accepts a BD address).
• --self-check — publish, verify advert + GATT, run encoder round-trips, exit. No phone needed; confirms the host is sane.
• --no-walk — fixed reading (for precise byte-mapping). --no-unsolicited — disable the raw-HCI no-CCCD delivery path. -v — log every notify / write.

Profiles

"Live-validated" = a reading was read off the real vendor app's screen. "Byte-verified" = the encoder round-trips bit-exact against a port of the app's own decoder, but hasn't been put on-screen yet.

Verifying a decode

1. fakemeter --profile <id> --name <exact-model>.
2. Open the vendor app (or nRF Connect / a Web-Bluetooth client) and connect.
3. It shows the initial reading. Set values (v 230.5 V), toggle flags (f hold), play presets (p) — if the display matches what you sent, the decode is right. Changing the value live proves it's not a static template; raw <hex> maps any byte/bit to the screen.

Gotchas

The practical ones — full detail in docs/PROGRESS.md.

• Use the real model name. App scan lists are filtered: Bluetooth DMM accepts only Bluetooth DMM/ZY; UNI-T Smart Measure only exact models (UT60BT, UT219P, …). ai-care instead gates on advertised manufacturer-data, which the profile emits automatically — so any --name works there.
• OWON apps need an LE-only adapter. They connectGatt(AUTO); on a dual-mode adapter Android picks Classic and bonds, blocking LE GATT. Run sudo btmgmt --index 0 bredr off and clear the phone's cached device record.
• The OWON BLE4.0 (Java) app never subscribes via CCCD. fakemeter still reaches it by injecting ATT notifications over a raw HCI socket (on by default for stream profiles). That path needs CAP_NET_RAW: sudo setcap cap_net_raw+ep "$(readlink -f "$(which python3)")". Apps that subscribe normally use the standard BlueZ path and need no extra privilege.
• Restarting drops a phone's bond (stale LTK → "incorrect PIN"). Clear it on both sides: bluetoothctl remove <addr> + toggle the phone's Bluetooth, then re-add from the app's scan screen.

Tests

pip install pytest && pytest -q      # 262 passed

Pure-Python (no BLE hardware needed): each profile round-trips readings through its encoder and a port of the matching decoder (tests/decode_*.py), checking value / unit / decimal point / sign, plus the FFF1 auth math, the interactive reactions, the meter-core engine, and the raw-HCI PDU layout. CI runs them on Python 3.10–3.13.

Docs

• docs/PROGRESS.md — per-profile validation log, protocol details, and gotchas in full.
• docs/adding-a-profile.md — how to add a profile + the layering map (base → meter_core → owon_base/uni_t_base → per-model).
• docs/voltcraft-measurement-protocol.md, docs/owon-voltcraft-handshake.md — the R10W measurement frame and the OWON FFF1/FFF2 connect handshake.

License

MIT — see LICENSE.