# Meshtastic Sensor Receiver

Subscribes to a Meshtastic channel over MQTT, decrypts the packets, and exposes
the results in Home Assistant via MQTT Discovery:

- **Last Message** — the most recent text message on the channel (with `from`,
  `to`, and timestamp as attributes).
- **Parsed sensors** — values pulled out of structured messages such as
  `🏠 T1:20.8°C T2:26.7°C H1:83.7%` become individual numeric sensors.
- **Link diagnostics** — `Last Seen`, `RSSI`, `SNR`, and `Hops Away`, derived
  from each packet's metadata (shown under the device's Diagnostic section).

This is the receiving counterpart to the **Meshtastic Sensor Broadcaster** add-on.

## Requirements

An MQTT broker configured in Home Assistant (e.g. the **Mosquitto broker**
add-on). The add-on discovers it automatically via the Supervisor — no manual
credentials needed for the HA side.

## Options

| Option | Description |
|--------|-------------|
| `source_broker` | MQTT broker the mesh packets arrive on. `mqtt.meshtastic.org` for the public server, or your local broker. |
| `source_port` | Broker port. `1883` plain, `8883` TLS. |
| `source_username` / `source_password` | Source broker credentials. Public server uses `meshdev` / `large4cats`. |
| `source_tls` | `true` when using port 8883. |
| `region` | Region code in the topic, e.g. `EU_868`, `US`. Use `+` to match any region. |
| `channel_name` | Exact (case-sensitive) channel name, e.g. `DET.Baulog`. |
| `channel_psk` | Base64 channel key from the Meshtastic app. `AQ==` is the default public key. |
| `match_prefix` | Only messages containing this string are parsed into sensors. Leave empty to parse every message. The Last Message sensor always updates. |
| `device_name` | Name of the HA device that groups the created entities. |
| `discovery_prefix` | MQTT Discovery prefix (default `homeassistant`). |
| `sensors` | List of `{label, name, device_class, unit}`. Each `label` (e.g. `T1`) is matched as `label:value` in the message. |

## How parsing works

The add-on scans each message for `LABEL:VALUE` pairs (units after the value are
ignored). For example:

```
🏠 T1:20.8°C T2:26.7°C T3:26.6°C H1:83.7% H2:54.4% H3:55.5%
```

produces `T1=20.8`, `T2=26.7`, `T3=26.6`, `H1=83.7`, `H2=54.4`, `H3=55.5`,
each published to the sensor configured with that `label`.

## Link diagnostics

These are created automatically (no config) from each received packet:

| Sensor | Source | Notes |
|--------|--------|-------|
| `Last Seen` | packet `rx_time` | Updates on every packet on the channel. |
| `RSSI` | packet `rx_rssi` (dBm) | Signal at the gateway. Omitted when the gateway originated the packet (value 0). |
| `SNR` | packet `rx_snr` (dB) | Published alongside RSSI. |
| `Hops Away` | `hop_start - hop_limit` | Number of hops the packet traveled. Requires firmware that reports `hop_start`. |

## Topics used

- Discovery: `{discovery_prefix}/sensor/{device}/{label}/config`
- State: `meshtastic_receiver/{device}/{label}`
- Last message: `meshtastic_receiver/{device}/last_message` (+ `/attributes`)
- Diagnostics: `meshtastic_receiver/{device}/{last_seen,rssi,snr,hops_away}`
- Availability: `meshtastic_receiver/{device}/status`

## Privacy note

On the public server your packets stay AES-encrypted in transit; only holders of
the channel PSK can read them. For full privacy and no traffic restrictions, run
a local MQTT broker and point both your node and `source_broker` at it.