Python CLI

Python CLI

Run ha-taggle directly as a Python program. This suits Home Assistant Core users, developers, and anyone replaying their own recordings. Most people should use the add-on or Docker instead.

Tip

What you'll need

• Linux
• Python 3.11, 3.12 or 3.13
• The rtl_sdr program from an RTL-SDR driver. For the V4, install the RTL-SDR Blog driver as the V4 guide describes.
• The DVB TV driver released if it holds the dongle (see Docker driver troubleshooting)
• An MQTT broker

Install

On Debian/Ubuntu install venv support first:

sudo apt install python3-venv

Python 3.14 is excluded: the pinned NumPy/SciPy versions have no CPython 3.14 wheels. NumPy, SciPy, Paho MQTT and timezone data are pinned in requirements.txt.

git clone https://github.com/Spicynostalgia/ha-taggle.git
cd ha-taggle
python3 -m venv .venv
. .venv/bin/activate
pip install .
cp config.example.json config.json

A virtual environment (venv) keeps ha-taggle's libraries separate from your system's Python.

Edit config.json as shown in Installing with Docker, Step 2, with two changes for a host install:

• data_dir: ./data (instead of /data)
• mqtt.host: your broker's address (here localhost is fine if the broker runs on the same machine)

The two commands

Installing gives you two commands.

Command	What it does
taggle-rx	The receiver. It decodes radio and publishes to MQTT.
taggle-calibrate	A helper that works out litres per count from your readings. See Calibration.

taggle-rx options

Option	Meaning
--config FILE	Required. Your JSON config.
--scan MINUTES	Scan mode: print heard IDs and SNR, no MQTT, no disk writes (up to 1440 minutes)
--input FILE	Read a .cu8 recording, or - for standard input, instead of starting rtl_sdr
--start-utc TIME	Time of the first sample in a file, e.g. 2026-01-01T00:00:00Z

Examples

# Find your meter: listen for 65 minutes
taggle-rx --config config.json --scan 65

# Normal operation (starts rtl_sdr for you)
taggle-rx --config config.json

# Pipe from rtl_sdr yourself
rtl_sdr -f 922200000 -s 2400000 -g 40 - | taggle-rx --config config.json --input -

# Replay your own recording of your own meter
taggle-rx --config config.json --input own-meter.cu8 --start-utc 2026-01-01T00:00:00Z

Note

What's a .cu8 file? It's raw radio samples: pairs of unsigned 8-bit numbers called I/Q values. rtl_sdr writes this format. A file has no clock inside it, so you must tell ha-taggle when it started.

Running it all the time

Use whatever keeps services running on your system, such as a systemd service or tmux. Docker is often simpler. See Installing with Docker.

Technical detail: replay and package layout

Replays keep the recording timestamps for readings, but availability and the final “today”/neighbourhood refresh use the current wall clock (and your configured timezone for daily totals). An old recording can therefore show unavailable sensors and today: 0; replaying does not move the wall clock back.

The package source lives under addon/taggle_rx so Home Assistant can build from the add-on directory alone. Root pyproject.toml installs that same package. See Configuration reference for JSON options and Protocol for the unsigned 8-bit interleaved I/Q format.

Further reading

• Python docs: venv
• RTL-SDR Blog driver (GitHub)
• Osmocom rtl-sdr
• Wikipedia: in-phase and quadrature components