Advanced Topics¶

Non-RTL-SDR Radios: SoapySDR and HackRF¶

Auto-detection only finds RTL-SDR USB dongles. SoapySDR, HackRF, and other non-RTL-SDR devices must be declared manually.

Create a config file in the add-on config directory that contains its own device line. The filename becomes the radio's log label.

Example hackrf.conf:

device    driver=hackrf
frequency 433.92M

Any config file that does not match a detected RTL-SDR radio but does contain a device line is launched as its own radio. These manual radios are launched after auto-detected RTL-SDR dongles and receive the next free ports.

As with per-radio overrides, do not add an output http://... line yourself. The add-on injects the assigned HTTP/WebSocket output.

Manual radios use template: identities because the add-on cannot derive RTL-SDR USB serial or USB-path data for them.

Logging¶

Two options control what appears in the add-on log:

log_received_messages appends output kv, so decoded sensor events appear in the log.
log_diagnostic_messages appends output log, so rtl_433 status and diagnostics appear in the log.

Both options default to off and can be enabled independently. Use received-message logging to confirm sensors are being decoded, and diagnostic logging when troubleshooting rtl_433 or radio startup behavior.

Signal-Level Metadata¶

The baked-in default config enables rtl_433 level reporting with report_meta level. Decoded messages include per-transmission frequency, signal strength (RSSI), signal-to-noise ratio (SNR), and noise level (all in dBm).

The companion Home Assistant integration exposes these values as optional diagnostic sensors on decoded devices. They are disabled by default; enable them from each device page when you need signal-quality history.

Discovery Payload Contract¶

This section is for developers of the companion integration and other discovery consumers; if you are only configuring radios, you can skip it.

The add-on publishes a Supervisor discovery message for the rtl_433 service. The top-level fields keep the original single-radio shape for compatibility, and the radios array describes every launched radio.

Example:

{
  "service": "rtl_433",
  "config": {
    "host": "<addon-hostname>",
    "port": 8434,
    "path": "/ws",
    "secure": false,
    "unique_id": "serial:abcd1234",
    "radios": [
      {
        "unique_id": "serial:abcd1234",
        "port": 8433,
        "path": "/ws",
        "serial": "abcd1234",
        "usbpath": "1-1.4"
      },
      {
        "unique_id": "usbpath:1-1.2",
        "port": 8434,
        "path": "/ws",
        "serial": "",
        "usbpath": "1-1.2"
      }
    ]
  }
}

Consumers must key on unique_id, not on host:port. Ports are assigned from 8433 upward in radio enumeration order and can shift when the connected-radio set changes.

The radios array is the current start's roster, not a durable inventory. A temporarily missing dongle is absent from that roster; consumers should treat a new unbound radio as the replacement signal rather than treating absence as permanent removal.

Migration From the Old Config Path¶

Previous add-ons read config files from /config/rtl_433/ in Home Assistant's main config directory. That path is no longer read.

Move any per-radio tuning into <id>.conf files in the add-on config directory:

Add-on	Current config directory
`rtl_433`	`/addon_configs/rtl433/`
`rtl_433 (next)`	`/addon_configs/rtl433-next/`

There is no separate config file required for the default case. The default rtl_433 config is baked into the image, and per-radio files only contain overrides or manual device declarations.

Generated Documentation Branch¶

This section is for contributors editing these docs, not for add-on users.

The published documentation site is generated by MkDocs and mike on the repository's gh-pages branch. Do not hand-edit generated files on that branch; update the Markdown sources in docs/ and let the workflow publish them.