Meshtastic Home Assistant Integration

For nodes selected during configuration, you can use device triggers and device actions in Home Assistant automations.

Triggers

Triggers are available when messages are sent or received. Gateway nodes provide more granular triggers, allowing you to filter by specific channels or direct messages.

Actions

• Send Direct Message
• Request Telemetry
• Request Position

Important: Always include a delay before performing an action if the automation was triggered by a Meshtastic device trigger. This prevents the action from being dropped if the device is still busy processing the incoming message.

- id: '1800000042000'
  alias: Ping Sample
  description: 'Reply back after message from device'
  triggers:
  - device_id: e3376b45b4912c27cffb46c58e4998e4
    domain: meshtastic
    type: message.sent
    trigger: device
  actions:
  - delay:
      seconds: 10
  - device_id: e3376b45b4912c27cffb46c58e4998e4
    domain: meshtastic
    type: send_message
    message: PONG {{ trigger.event.data.message }}

If you prefer not to use the notify platform (to avoid cluttering Home Assistant with many entities), you can listen for the meshtastic_api_text_message event. This allows you to handle all incoming channel and direct messages in a single automation.

Event Data Structure

When a message is received, the event contains the following data:

trigger:
  event:
    event_type: meshtastic_api_text_message
    event_data:
      data:
        from: 1127918844
        to:
          node: null
          channel: 0
        gateway: 862525748
        message: Sample Message

• from: The node ID of the sender.
• to.node: The node ID of the gateway (for direct messages).
• to.channel: The gateway channel ID (for channel messages).
• gateway: The gateway node ID.

Filtering and Replying

• Filter by Gateway Node: Use {{ trigger.event.data.data.to.node == <NODE_ID> }}.
• Filter by Channel: Use {{ trigger.event.data.data.to.channel == 0 }} (where 0 is typically LONGFAST).
• Replying: Use the meshtastic.send_text action. Always include a delay (at least 2 seconds) before replying to ensure the device is idle.

action: meshtastic.send_text
metadata: {}
data:
  ack: false
  from: "{{ trigger.event.data.data.gateway }}"
  to: "{{ trigger.event.data.data.from }}"
  text: "ECHO: {{ trigger.event.data.data.message }}"

Because Meshtastic firmware typically allows only one connection at a time, this integration provides a workaround by exposing an HTTP API for each configured gateway. This allows the Meshtastic Web Client to connect to Home Assistant, which then acts as a proxy to your nodes.

This method enables interaction with nodes that do not support TCP or are connected via serial/Bluetooth.

Security Warning: Enabling this feature provides unauthenticated access to your gateway nodes to anyone who can reach your Home Assistant instance, as the Meshtastic HTTP API does not support authentication. Only use this in trusted environments.

### To access the web client:

**In Home Assistant:**
1. Enable the feature in the integration configuration.
2. Navigate to the "Meshtastic" menu item (reload the Home Assistant interface if it is not visible).
3. Press the "Open" button of the desired gateway to launch the web client.

**Inside the Meshtastic Web Client:**
4. Press "New Connection" (the correct hostname should be pre-populated).
5. Press "Connect".

The ClientProxyTransport class extends StreamingClientTransport to wrap standard asyncio StreamReader and StreamWriter objects. It provides specialized methods for reading and writing Meshtastic protobuf packets over a TCP connection.

Key methods:

• read_to_radio_packet(): Asynchronously reads bytes from the stream, parses them as a mesh_pb2.ToRadio protobuf message, and returns a tuple of (packet_bytes, to_radio_message). Returns None if no packet is available or an error occurs.
• write_from_radio_packet(from_radio): Takes a mesh_pb2.FromRadio object, serializes it to bytes, wraps it in a frame using StreamingClientTransport.build_frame, and writes it to the stream.
• is_connected: A property that returns True for this transport implementation.

# Example conceptual usage of ClientProxyTransport
from asyncio import StreamReader, StreamWriter

# Assuming reader and writer are provided by an asyncio server
transport = ClientProxyTransport(reader, writer)

# Reading a packet
result = await transport.read_to_radio_packet()
if result:
    packet_bytes, to_radio = result
    # Process packet...

# Writing a packet
# from_radio is a mesh_pb2.FromRadio instance
await transport.write_from_radio_packet(from_radio)

The MeshtasticTcpProxy class acts as a bridge between a MeshInterface (the gateway/radio connection) and multiple TCP clients. It starts a TCP server that listens for incoming connections and forwards packets between the TCP clients and the Meshtastic radio.

Initialization:

• interface: A MeshInterface instance representing the connection to the Meshtastic hardware.
• host: The IP address to bind the server to (defaults to None, meaning all interfaces).
• port: The TCP port to listen on (defaults to 4403).

Lifecycle Management:

• start(): Starts the TCP server and begins a background task to forward packets from the radio to all connected TCP clients.
• stop(): Cancels the forwarding task and closes the TCP server.
• The class supports the asynchronous context manager pattern (async with).

Behavior:

• When a TCP client connects, the proxy creates a dedicated pair of tasks: one to forward packets from the client to the radio (forward_to_radio) and one to forward packets from the radio to the client (forward_from_radio).
• If a client sends a ToRadio packet with the disconnect field set to True, the proxy will disconnect that specific client.

from custom_components.meshtastic.aiomeshtastic import MeshInterface
from custom_components.meshtastic.meshtastic_tcp.server import MeshtasticTcpProxy

async def run_proxy(mesh_interface: MeshInterface):
    # Initialize proxy on port 4403
    proxy = MeshtasticTcpProxy(interface=mesh_interface, host='0.0.0.0', port=4403)
    
    # Use as an async context manager to ensure start() and stop() are called
    async with proxy:
        # The proxy is now running and listening for TCP clients
        # Keep the loop alive
        await asyncio.Event().wait()