Configuration Reference

Configuration reference

Start with Installing the add-on or Installing with Docker. This page explains every receiver option when you need to change something. Set only your own transmitter ID; 123456 below is fictional.

The add-on uses YAML options on its Configuration tab, not Home Assistant's configuration.yaml. Docker and the Python CLI use JSON. These options describe release 0.3.0. Guided dial entry is the recommended calibration route.

Apply a change

Change	Apply it
Add-on receiver option	Save, then restart Taggle water meter
Docker receiver JSON	Save, then run docker compose restart taggle from its repository
Python receiver JSON	Save, stop and restart the receiver process
Return from Docker scan	End the one-off scan, then docker compose up -d taggle
Broker config	Restart the broker with docker compose -f mosquitto/compose.yaml restart mosquitto for the documented layout
First creation of HA www	Restart Home Assistant
Guided dial reading / unit selection	Submit and check Calibration status; no restart
Card JavaScript update	Reload the browser and refresh its cache as the card guide describes

Shared options

Defaults below come from addon/config.yaml and config.example.json. Docker's example starts with fictional [123456]; replace it. The receiver itself defaults to an empty meter list.

Option	Add-on default	Docker example/default	Meaning and allowed values
meter_ids	[]	[123456] in example; [] if omitted	List of your decimal transmitter IDs, integers 0–1048575. Duplicate IDs are removed. Required in normal operation unless log_all_meters is explicitly enabled; may be empty for a scan.
log_all_meters	false	false	Boolean. Explicitly allows other heard IDs, including in JSONL when logging is enabled. Leave off for normal use.
neighbourhood	true	true	Boolean. Collect anonymous nearby-meter aggregates. Setting false and restarting deletes neighbour state and salt; MQTT reconnect clears retained aggregate discovery/state. Your meter state is kept.
neighbourhood_min_meters	3	3	Integer privacy floor for each aggregate cohort. Add-on range 3 or greater, no upper bound specified. Standalone values below 3 are clamped to 3.
neighbourhood_litres_per_count	Unset (optional)	null	Assumed neighbour scale, not individual calibration. Add-on range 0.000001–1000000; standalone accepts any finite positive number or null. Unset uses the first configured meter's calibration, or raw pulses if it is uncalibrated.
frequency	922200000	922200000	SDR centre frequency in Hz; integer 921700000–922490000. This keeps the supported carrier inside the sampled band; it does not select every Taggle channel. Leave the default initially.
gain	40	40	SDR gain in dB, number 0–50. Try 49 for weak reception; reduce if overloaded.
device	"0"	"0"	RTL-SDR index or USB serial, as a string. Must be nonempty and must not start with -. Only one program may hold the USB receiver.
timezone	UTC	"UTC"	Valid installed IANA timezone name. Match Home Assistant, e.g. Australia/Brisbane, Australia/Sydney, Australia/Adelaide or Australia/Perth; Brisbane is not an Australia-wide default. Controls “today”, local photo clock times, expected transmission times and leak night windows. Scans always show UTC.
litres_per_count	[]	{}	Pinned per-meter litres per pulse; guided readings validate it and find the offset, but cannot replace it. IDs must be in meter_ids and within 0–1048575. Add-on values 0.000001–1000000; standalone values must be finite and positive. Leave empty for automatic guided calibration. See both formats below.
meter_reading_offset	[]	{}	Optional pinned absolute offset in litres, same per-meter formats as litres_per_count. Requires a pinned factor for the same meter; offset must be finite and may be negative.
dial_unit	m3	"m3"	Initial dial unit. Add-on accepts m3, kl, L; device selector displays m³, kL, L. Standalone also accepts aliases m³, kL, litres. The saved device selection wins.
calibration_max_uncertainty	0.02	0.02	Maximum full relative bounds width for a nonstandard fit. Standalone: finite number >0 and ≤1; add-on 0.000001–1. Exactly one standard candidate fitting the bounds applies automatically.
jsonl_logging	false	false	Boolean. Write decoded summaries to daily JSONL files under data_dir; no raw radio frames or encrypted bodies. No automatic rotation; manage retention yourself.

Leak detection options

These options are shared by the add-on and standalone JSON. Leak detection describes the complete rules, gaps, recovery and limitations. It runs for configured meters only and needs no litre calibration.

Option	Default	Meaning and allowed values
leak_detection	true	Boolean. False removes retained leak discovery and hint data on reconnect/restart.
leak_continuous_hours	24	Integer 1–168. All observed intervals in this horizon must have positive pulses with at least 80% coverage; a new observed zero clears this reason.
leak_night_start	"01:00"	Inclusive local start, strict 24-hour HH:MM.
leak_night_end	"05:00"	Exclusive local end, strict HH:MM; must differ from start. Earlier end times cross midnight.
leak_night_min_pulses	1	Integer 1–65535. Each observed night interval must reach it, with at least three observations; evaluation waits for the window to complete.

Removed options and upgrade behaviour

calibration_min_litres is retired: there is no minimum-usage gate. The copied standalone example may still contain it; the 0.3.0 loader ignores it with Ignoring unknown option calibration_min_litres. Remove it from your saved configuration. Unknown top-level options are ignored with a startup warning; unknown keys inside mqtt remain errors. Unknown options do not enable a feature, and add-on form/schema validation still applies.

Upgrade removes the old reading-number and separate photo-time discovery controls and pending photo time. Use one Dial reading text box with optional time in the same command. Existing readings, chosen unit and automatic solution live in private versioned state; back them up, not just config.

Calibration: two different formats

Leave litres_per_count and meter_reading_offset empty ([] in add-on options, {} in JSON) for guided calibration. Dial submissions need no configuration edits or restart. The following examples are advanced manual pins.

Add-on YAML is a list of objects with meter_id and value:

litres_per_count:
  - meter_id: 123456
    value: 2.5

Docker / Python JSON is a map from quoted transmitter ID to litres per pulse. Replace the existing property inside the complete copied config.json. This is a property fragment, not a complete JSON file: retain the outer braces, other settings and commas between properties:

"litres_per_count": {"123456": 2.5}

To remove a manual pin, clear meter_reading_offset and litres_per_count, Save and restart the receiver. Existing readings are solved again; a full reset is not required just to remove a pin. An offset pin uses the same format with the option name meter_reading_offset and an offset in litres instead of a factor. A factor alone enables usage litres; guided readings or an offset pin are needed for the absolute Meter reading.

2.5 is fictional, not a recommended value. Follow Calibration. Litre entities appear only once calibrated. Each newly recovered interval is added to total_litres at the litres per pulse active when first processed; previously stored intervals are not revalued or backfilled. A new frame can recover a recent earlier interval. Hourly and daily displays use the current factor.

Add-on-only option and managed settings

Option	Default	Meaning and range
scan_minutes	0	Integer 0–1440. 0 runs normally; a positive value scans for that many minutes, then stops. Use 65 initially, then return to 0 and restart. Scan prints heard IDs, with counts only for configured clear-format meters; no MQTT connection, saved state or log files.

The add-on fixes sample_rate at 2400000 samples/s, stores receiver data under /data/receiver inside its persistent /data, and gets MQTT host, port and credentials through Supervisor service discovery (mqtt:need). MQTT credentials are not add-on options. Default topic prefixes are taggle and homeassistant. Home Assistant selects the versioned amd64/aarch64 GHCR image by replacing {arch}; usb: true grants USB access. These packaging settings are not receiver options to paste into YAML.

Docker / Python options

Option	Docker example	Meaning and allowed values
sample_rate	2400000	Only 2400000 samples/s is supported.
data_dir	"/data"	Writable path for persistent state, salt and optional logs. Keep /data in Docker (mapped to ./data on the host); Python host installs normally use ./data, the receiver default if omitted. No numeric range.
mqtt.host	"mqtt"	Reachable broker hostname or IP string. Use the broker machine's LAN IP, e.g. 192.168.1.50. mqtt resolves only if that service/hostname exists, such as a service named mqtt on the same Compose network. Never use localhost for a separate broker from the receiver container: it means the receiver container itself. The Python loader defaults to localhost if omitted.
mqtt.port	1883	Integer 1–65535; match your broker.
mqtt.username	""	Broker username string; empty when authentication is not required.
mqtt.password	""	Broker password string; keep config private.
mqtt.topic_prefix	"taggle"	Nonempty MQTT prefix, no +, # or NUL; trailing / is stripped and the result must stay nonempty. Use a different prefix per receiver.
mqtt.discovery_prefix	"homeassistant"	Discovery prefix, same restrictions; match HA's MQTT discovery setting.

mqtt is the object containing the six keys above; edit host inside that object, not a literal mqtt.host key. Unknown MQTT keys are rejected. Use the broker-address instructions if unsure which LAN address to use. The example's MQTT values are also the loader defaults except for host. Docker/Python select scans with --scan 65, not a JSON scan_minutes key. CLI scans accept more than 0 and at most 1440 minutes. See Python CLI for file input and timestamps.

Technical detail: privacy and saved data

Neighbourhood comparison is on by default, but tracks other meters only by install-specific HMAC keys. With default logging, their IDs do not enter logs, saved state or MQTT; only group aggregates are published. Exceptions: scan output prints heard IDs, and explicit log_all_meters: true permits JSONL of other heard IDs when jsonl_logging is on.

New data directories use mode 0700; JSONL, state.json and neighbourhood.salt use 0600. State contains your own meter IDs, usage, dial readings, selected unit and automatic solution; keep it private and backed up. Deleting it loses the cumulative baseline. Config and local data are git-ignored. MQTT contains your configured IDs and usage plus anonymous aggregates; use a trusted broker and network. See Privacy and legal and Neighbourhood comparison.

Source references

• Add-on options and schema
• Standalone example
• Calibration guide