Remote-Terminal-for-MeshCore/README_HA.md

Home Assistant Integration

RemoteTerm can publish mesh network data to Home Assistant via MQTT Discovery. Devices and entities appear automatically in HA -- no custom component or HACS install needed.

Prerequisites

• Home Assistant with the MQTT integration configured
• An MQTT broker (e.g. Mosquitto) accessible to both HA and RemoteTerm
• RemoteTerm running and connected to a radio

Setup

1. In RemoteTerm, go to Settings > Integrations > Add > Home Assistant MQTT Discovery
2. Enter your MQTT broker host and port (same broker HA is connected to)
3. Optionally enter broker username/password and TLS settings
4. Select contacts for GPS tracking and repeaters for telemetry (see below)
5. Configure which messages should fire events (scope selector at the bottom)
6. Save and enable

Devices will appear in HA under Settings > Devices & Services > MQTT within a few seconds.

How MeshCore IDs Map Into Home Assistant

RemoteTerm uses each node's public key to derive a stable short identifier for MQTT topics:

• Full public key: ae92577bae6c4f1d...
• Node ID: ae92577bae6c (the first 12 hex characters, lowercased)
• Example MQTT topic: meshcore/ae92577bae6c/gps

When this README shows <node_id>, it always means that 12-character value. Node IDs appear in:

• MQTT discovery topics under homeassistant/...
• Runtime MQTT state topics under your configured prefix, usually meshcore/...

Entity IDs are different — HA auto-generates them from the device name and entity name, not from the node ID. For example, a radio named "MyRadio" produces entities like binary_sensor.myradio_connected and event.myradio_messages. A contact named "Alice" produces device_tracker.alice. You can find your actual entity IDs in Settings > Devices & Services > MQTT in HA, and you can rename them in HA's UI without affecting the integration.

You can also see the MQTT topic IDs in RemoteTerm's Home Assistant integration UI:

• What gets created in Home Assistant
• Published topic summary

What Gets Created

Local Radio Device

Always created. Updates every 60 seconds.

Entity	Type	Description
binary_sensor.<radio_name>_connected	Connectivity	Radio online/offline
sensor.<radio_name>_noise_floor	Signal strength	Radio noise floor (dBm)

Repeater Devices

One device per tracked repeater selected in the HA integration. Updates when telemetry is collected (auto-collect cycle (~8 hours or variable in settings), or when you manually fetch from the repeater dashboard).

Repeaters must first be added to the auto-telemetry tracking list in RemoteTerm's Radio settings section. Only auto-tracked repeaters appear in the HA integration's repeater picker.

Entity	Type	Unit	Description
sensor.<repeater_name>_battery_voltage	Voltage	V	Battery level
sensor.<repeater_name>_noise_floor	Signal strength	dBm	Local noise floor
sensor.<repeater_name>_last_rssi	Signal strength	dBm	Last received signal strength
sensor.<repeater_name>_last_snr	--	dB	Last signal-to-noise ratio
sensor.<repeater_name>_packets_received	--	count	Total packets received
sensor.<repeater_name>_packets_sent	--	count	Total packets sent
sensor.<repeater_name>_uptime	Duration	s	Uptime since last reboot

If RemoteTerm already has a cached telemetry snapshot for that repeater, it republishes it on startup so HA can populate the sensors immediately instead of waiting for the next collection cycle.

Contact Device Trackers

One device_tracker per tracked contact. Updates passively whenever RemoteTerm hears an advertisement with GPS coordinates from that contact. No radio commands are sent -- it piggybacks on normal mesh traffic.

Entity	Description
device_tracker.<contact_name>	GPS position (latitude/longitude)

Message Event Entity

A single radio-scoped event entity, event.<radio_name>_messages, fires for each message matching your configured scope. Each event carries these attributes:

Attribute	Example	Description
event_type	message_received	Always message_received
sender_name	Alice	Display name of the sender
sender_key	aabbccdd...	Sender's public key
text	hello	Message body
message_type	PRIV or CHAN	Direct message or channel
channel_name	#general	Channel name (null for DMs)
conversation_key	aabbccdd...	Contact key (DM) or channel key
outgoing	false	Whether you sent this message

Entity Naming

HA auto-generates entity IDs by slugifying the device name and entity name. For a radio named "My Radio", entities look like binary_sensor.my_radio_connected and event.my_radio_messages. For a repeater named "Hilltop", sensor.hilltop_battery_voltage. For a contact named "Alice", device_tracker.alice. You can rename entities in HA's UI without affecting the integration.

MQTT topic paths use the 12-character node ID (first 12 hex characters of the public key). For example:

• Local radio health: meshcore/<radio_node_id>/health
• Repeater telemetry: meshcore/<repeater_node_id>/telemetry
• Contact GPS: meshcore/<contact_node_id>/gps
• Message events: meshcore/<radio_node_id>/events/message

What Appears When

• Always created: the local radio device and its entities
• Created when selected in the HA integration: tracked repeater devices and tracked contact device trackers
• Populated only after data exists: contact GPS trackers need an advert with GPS; repeater sensors need telemetry, although cached repeater telemetry is replayed on startup when available
• Message event entity: always created once the HA integration is enabled for a connected radio

Common Automations

Low repeater battery alert

Notify when a tracked repeater's battery drops below a threshold.

GUI: Settings > Automations > Create > Numeric state trigger on sensor.<repeater_name>_battery_voltage, below 3.8, action: notification.

YAML:

automation:
  - alias: "Repeater battery low"
    trigger:
      - platform: numeric_state
        entity_id: sensor.hilltop_battery_voltage
        below: 3.8
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Repeater Battery Low"
          message: >-
            {{ state_attr('sensor.hilltop_battery_voltage', 'friendly_name') }}
            is at {{ states('sensor.hilltop_battery_voltage') }}V

Radio offline alert

Notify if the radio has been disconnected for more than 5 minutes.

GUI: Settings > Automations > Create > State trigger on binary_sensor.<radio_name>_connected, to off, for 00:05:00, action: notification.

YAML:

automation:
  - alias: "Radio offline"
    trigger:
      - platform: state
        entity_id: binary_sensor.myradio_connected
        to: "off"
        for: "00:05:00"
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "MeshCore Radio Offline"
          message: "Radio has been disconnected for 5 minutes"

Alert on any message from a specific room

Trigger when a message arrives in a specific channel. Two approaches:

Option A: Scope filtering (fully GUI, no template)

If you only care about one room, configure the HA integration's message scope to "Only listed channels" and select that room. Then every event fire is from that room.

GUI: Settings > Automations > Create > State trigger on event.<radio_name>_messages, action: notification.

YAML:

automation:
  - alias: "Emergency channel alert"
    trigger:
      - platform: state
        entity_id: event.myradio_messages
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Message in #emergency"
          message: >-
            {{ trigger.to_state.attributes.sender_name }}:
            {{ trigger.to_state.attributes.text }}

Option B: Template condition (multiple rooms, one integration)

Keep scope as "All messages" and filter in the automation. The trigger is GUI, but the condition uses a one-line template.

GUI: Settings > Automations > Create > State trigger on event.<radio_name>_messages > Add condition > Template > enter the template below.

YAML:

automation:
  - alias: "Emergency channel alert"
    trigger:
      - platform: state
        entity_id: event.myradio_messages
    condition:
      - condition: template
        value_template: >-
          {{ trigger.to_state.attributes.channel_name == '#emergency' }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Message in #emergency"
          message: >-
            {{ trigger.to_state.attributes.sender_name }}:
            {{ trigger.to_state.attributes.text }}

Alert on DM from a specific contact

YAML:

automation:
  - alias: "DM from Alice"
    trigger:
      - platform: state
        entity_id: event.myradio_messages
    condition:
      - condition: template
        value_template: >-
          {{ trigger.to_state.attributes.message_type == 'PRIV'
             and trigger.to_state.attributes.sender_name == 'Alice' }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "DM from Alice"
          message: "{{ trigger.to_state.attributes.text }}"

Alert on messages containing a keyword

YAML:

automation:
  - alias: "Keyword alert"
    trigger:
      - platform: state
        entity_id: event.myradio_messages
    condition:
      - condition: template
        value_template: >-
          {{ 'emergency' in trigger.to_state.attributes.text | lower }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Emergency keyword detected"
          message: >-
            {{ trigger.to_state.attributes.sender_name }} in
            {{ trigger.to_state.attributes.channel_name or 'DM' }}:
            {{ trigger.to_state.attributes.text }}

Track a contact on the HA map

No automation needed. Once a contact is selected for GPS tracking, their device_tracker entity automatically appears on the HA map. Go to Settings > Dashboards > Map (or add a Map card to any dashboard) and the tracked contact will show up when they advertise their GPS position.

Dashboard card showing repeater battery

Add a sensor card to any dashboard:

type: sensor
entity: sensor.hilltop_battery_voltage
name: "Hilltop Repeater Battery"

Or an entities card for multiple repeaters:

type: entities
title: "Repeater Status"
entities:
  - entity: sensor.hilltop_battery_voltage
    name: "Hilltop"
  - entity: sensor.valley_battery_voltage
    name: "Valley"
  - entity: sensor.ridge_battery_voltage
    name: "Ridge"

Troubleshooting

Devices don't appear in HA

• Verify the MQTT integration is configured in HA (Settings > Devices & Services > MQTT) and shows "Connected"
• Verify RemoteTerm's HA integration shows "Connected" (green dot)
• Check that both HA and RemoteTerm are using the same MQTT broker
• Subscribe to discovery topics to verify messages are flowing:

  mosquitto_sub -h <broker> -t 'homeassistant/#' -v
  

Stale or duplicate devices

If you see unexpected devices (e.g. a generic "MeshCore Radio" alongside your named radio), clear the stale retained messages:

mosquitto_pub -h <broker> -t 'homeassistant/binary_sensor/meshcore_unknown/connected/config' -r -n
mosquitto_pub -h <broker> -t 'homeassistant/sensor/meshcore_unknown/noise_floor/config' -r -n

Repeater sensors show "Unknown" or "Unavailable"

Repeater telemetry only updates when collected. Trigger a manual fetch by opening the repeater's dashboard in RemoteTerm and clicking "Status", or wait for the next auto-collect cycle (~8 hours).

If RemoteTerm already has cached telemetry for that repeater, it republishes the last known values on startup. If the sensors are still unknown or unavailable, it usually means no telemetry has ever been collected for that repeater yet.

Contact device tracker shows "Unknown"

The contact's GPS position only updates when RemoteTerm hears an advertisement from that node that includes GPS coordinates. If the contact's device doesn't broadcast GPS or hasn't advertised recently, the tracker will show as unknown.

Entity is "Unavailable"

Radio health entities have a 120-second expiry. If RemoteTerm stops sending health updates (e.g. it's shut down or loses connection to the broker), HA marks the entities as unavailable after 2 minutes. Restart RemoteTerm or check the broker connection.

Removing the Integration

Disabling or deleting the HA integration in RemoteTerm's settings publishes empty retained messages to all discovery topics, which removes the devices and entities from HA automatically.

Local Test Environment

For local development, RemoteTerm includes a helper that starts Mosquitto and Home Assistant with MQTT preconfigured:

./scripts/setup/start_ha_test_env.sh

That gives you:

• Home Assistant at http://localhost:8123
• Mosquitto at localhost:1883
• A pre-created HA MQTT integration using that broker

To watch all MQTT traffic during testing:

docker exec ha-test-mosquitto mosquitto_sub -h 127.0.0.1 -t '#' -v

To stop and clean up:

./scripts/setup/stop_ha_test_env.sh --clean

MQTT Topics Reference

Runtime/state topics (where data is published):

Topic	Content	Update frequency
meshcore/{node_id}/health	{"connected": bool, "noise_floor_dbm": int}	Every 60s
meshcore/{node_id}/telemetry	{"battery_volts": float, ...}	~8h or manual
meshcore/{node_id}/gps	{"latitude": float, "longitude": float, ...}	On advert
meshcore/{node_id}/events/message	{"event_type": "message_received", ...}	On message

Discovery topics (entity registration, under homeassistant/):

Pattern	Entity type
homeassistant/binary_sensor/meshcore_<node_id>/connected/config	Radio connectivity
homeassistant/sensor/meshcore_<node_id>/noise_floor/config	Noise floor sensor
homeassistant/sensor/meshcore_<node_id>/battery_voltage/config	Repeater battery
homeassistant/sensor/meshcore_<node_id>/*/config	Other repeater sensors
homeassistant/device_tracker/meshcore_<node_id>/config	Contact GPS tracker
homeassistant/event/meshcore_<node_id>/messages/config	Message event entity

The {node_id} is always the first 12 characters of the node's public key, lowercased.