Python CLI

Python CLI

Run ha-taggle directly as a Python program. This suits developers, existing Home Assistant Core users (a legacy installation method), 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 USB receiver (see Docker driver troubleshooting)
• An MQTT broker

Install

On Debian/Ubuntu install venv support first:

sudo apt install python3-venv git

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
git checkout --detach v0.3.0
python3 --version
python3 -m venv .venv
. .venv/bin/activate
pip install .
cp config.example.json config.json
chmod 600 config.json

These commands select release 0.3.0. Check python3 --version shows 3.11–3.13 before creating the environment. Run these commands in a terminal on the receiver host.

Run pip show ha-taggle inside this environment to check the installed receiver version.

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 pulse from your readings. See Calibration’s technical detail.

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	Required for a named --input file. Offset-aware ISO timestamp for its first sample, e.g. 2026-01-01T00:00:00Z. For live stdin, timestamps default to the incoming stream's wall-clock timing.

Examples

Prefer taggle-rx --config config.json: it starts rtl_sdr with your configured device, frequency, sample rate and gain. Stop any existing receiver process or service before scanning; only one program can use the USB receiver. Stop a foreground scan with Ctrl+C, then start normal mode without --scan.

In the advanced pipeline below, the options before | control acquisition. Change -d, -f, -s and -g there rather than in JSON. The supported sample rate remains 2400000.

# 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 -d 0 -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