Skip to content

Installing the Add on

Jump to bottom
ha-taggle edited this page Nov 2, 2026 · 4 revisions

Installing the add-on

The recommended path for Home Assistant OS. An add-on is a program managed by Home Assistant OS. Existing Supervised installations can use this legacy route, but upstream support for Supervised ended with Home Assistant 2025.12. This path was not re-tested in the November 2026 Docker VM run (tested hardware). Newer Home Assistant menus call add-ons apps. These instructions cover ha-taggle 0.3.0. Check the version shown on its Info tab; guided calibration is available.

Using Home Assistant Container or Core? Go to Installing with Docker instead.

Tip

What you'll need

  • Home Assistant OS or Supervised, on amd64 or aarch64 hardware
  • Your RTL-SDR and antenna (Hardware and antennas)
  • Your transmitter ID, if you've found it (Finding your meter). Not essential yet.
  • Admin access to Home Assistant

Step 1: Set up an MQTT broker

MQTT is a way for programs to pass messages. A broker is the post office in the middle: ha-taggle posts readings to it, and Home Assistant collects them.

Note

Already have MQTT working? If Home Assistant's MQTT integration is set up and the broker is one the Supervisor can discover (usually the Mosquitto add-on), skip to Step 2.

  1. Go to Settings → Apps (Add-ons) → Store.
  2. Search for Mosquitto broker, open it and click Install.
  3. Click Start. Turn on Start on boot.
  4. Check Mosquitto's Log tab: it should stay running without listener errors.
  5. Go to Settings → Devices & services. MQTT should appear as a discovered integration. Click Configure and Submit, keeping discovery enabled. See the Mosquitto add-on docs.

If MQTT is not discovered, choose Add integration → MQTT. For the standard Mosquitto add-on, use host core-mosquitto, port 1883, and a Home Assistant username/password. If needed, create a dedicated user in Settings → People → Users (enable Advanced Mode in your profile if Users is hidden). Names homeassistant and addons are reserved. This manual login is for HA's integration; the Supervisor supplies the receiver's credentials.

For automatic discovery, the Supervisor supplies ha-taggle's broker login. Mosquitto can also authenticate Home Assistant users without extra broker configuration.

Note

Why does ha-taggle use MQTT? Home Assistant's MQTT discovery lets a program announce "here are my sensors" and have them appear in HA automatically. You don't write any YAML for the sensors.

Step 2: Add the ha-taggle repository

The easy way: click this badge. It opens your own Home Assistant through My Home Assistant.

Add the Taggle add-on repository

The manual way:

  1. Go to Settings → Apps (Add-ons) → Store.
  2. Click the ⋮ menu (top right) → Repositories.
  3. Paste https://github.com/Spicynostalgia/ha-taggle and click Add, then Close.

If your menus look different, see HA's guide to installing a third-party app repository.

Step 3: Install

  1. Refresh the Store page in your browser.
  2. Find Taggle water meter and open it.
  3. Click Install and wait for installation to finish.
  4. Plug in the RTL-SDR (with the antenna and extension cable).

Warning

Nothing else may use the USB receiver. Stop any other SDR add-on (such as an ADS-B or rtl_433 add-on) that uses the same USB receiver.

Step 4: Configure

Open Taggle water meter → Configuration. In the form, meter_ids is a list of numbers: add your transmitter ID as one list item. Keep the other options. If using the ⋮ → Edit in YAML view, change the existing entry to meter_ids: [123456], replacing fictional 123456 with your ID. Do not paste Docker JSON or edit Home Assistant's configuration.yaml.

Match Home Assistant's named timezone: for example Australia/Brisbane, Australia/Sydney, Australia/Adelaide or Australia/Perth. Brisbane is not an Australia-wide default because daylight saving differs. Leave litres_per_count: [] for guided calibration.

Neighbourhood comparison is on by default. It publishes group figures using assumed litres per pulse, not individual neighbour IDs/usage. To disable before first Start, set neighbourhood: false. Read its assumptions and privacy exceptions.

If the label is unreadable, change these existing options to scan first. These are option fragments; keep the rest of the form/YAML. Replace the example timezone with yours:

meter_ids: []
scan_minutes: 65
timezone: Australia/Brisbane

If you know your ID, the YAML options look like this (fictional 123456 shown; use yours). Keep your timezone and chosen neighbourhood setting:

meter_ids:
  - 123456
log_all_meters: false
frequency: 922200000
gain: 40
device: "0"
timezone: Australia/Brisbane
litres_per_count: []
jsonl_logging: false
scan_minutes: 0
neighbourhood: true
neighbourhood_min_meters: 3

Leave the radio and logging settings at their defaults while checking first reception. Configure only your own ID and leave litres_per_count empty until measured.

Follow guided calibration to enter dial readings in Home Assistant; no maths, configuration edit or restart is needed for submissions. Advanced factor/offset pins use a list format, differing from Docker’s JSON map. See Configuration reference for complete formats, defaults and ranges.

Click Save.

Note

You don't type MQTT details anywhere. The add-on asks the Supervisor for them (mqtt:need) and never prints the password in its log.

Step 5: Start it

  1. Click Start on the Info tab. Turn on Start on boot.
  2. Open Log. Check that the add-on stays running and that Reading samples in async mode... appears. A V4 can also show RTL-SDR Blog V4 Detected. Fix startup errors before waiting. Normal mode logs Listening on 922.2 MHz, MQTT connected, configured-meter updates and a summary every 15 minutes. Scans have no MQTT or normal heartbeat; see log examples.
  3. Scanning? Follow First scan and water-use check. A scan has no MQTT connection; a completed scan stops. Before normal operation, confirm your ID, change scan_minutes to 0, Save, then Start/Restart this add-on.
  4. Normal mode? Open Settings → Devices & services → MQTT → Devices. Discovery should create Taggle 123456 (your ID) and the enabled Taggle neighbourhood device once MQTT connects, before a radio reading. If absent, check MQTT discovery.
  5. Leave it running for up to an hour. Open your Taggle device and check Last seen under Diagnostics and Last hour pulses. Then check ownership.

Before the first radio frame, meter values may be unknown or unavailable. Neighbourhood values, rather than device discovery, wait for enough meters to qualify. See Entities reference for navigation and identifiers. Never leave fictional 123456 configured.

Where is my data kept?

State is saved under the add-on’s persistent /data/receiver folder, including dial readings, selected unit and automatic calibration. It survives restarts and upgrades. Include the add-on's data in Home Assistant backups before updating. Keep your measured litres_per_count options too. Reinstalling or deleting state does not repair reception. If you lose it, your running total starts again. See Home Assistant backups.

Updating

Back up first, then use Update on Taggle water meter when a released update is available. Check its version on Info and check card updates separately. Keep existing add-on data so running totals and calibration survive. Update receiver and card together to 0.3.0.

Further reading

ha-taggle is experimental, receive-only and unofficial. It is not affiliated with Taggle Systems or any council or utility. Only receive your own meter, and never touch the utility's equipment. All IDs in this wiki are fictional. · Repository · Report an issue · Glossary

ha-taggle wiki

🌐 Project website

Start here

Setup

Using it

Reference and optional background

Help

Clone this wiki locally