Home-Assistant Meshtastic Integration

Home Assistant Integration for Meshtastic.

Supported Features:

• Add meshtastic devices as gateways to interact with the mesh
  • Supports TCP, Serial & Bluetooth connection (also works with Bluetooth Proxy)
  • Home Assistant Zeroconf, Bluetooth & USB-Serial Auto-Discovery
  • Select which meshtastic nodes should be imported to home assistant
• Meshtastic node metrics
• Record received messages
• Send messages (as direct message or on broadcast channel)
• Record node position (as device tracker)
• Device triggers & actions for automations
• Various other service actions (e.g. request metrics, trace route)

For more details, see check the documentation.

Installation

Recommended: HACS

1. Add this repository as a custom repository to HACS:
2. Use HACS to install the integration.
3. Restart Home Assistant.
4. Set up the integration using the UI:

Alternatives

Alternatives

Manual

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called homeassistant-meshtastic.
4. Download all the files from the custom_components/meshtastic/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Meshtastic"

Configuration is done in the UI

Documentation

Supported Platforms

Sensor / Binary Sensor

For nodes selected as part of the configuration, metrics are exposed as corresponding sensors.

Even though integration is classified as local_polling it predominantly operates as local_push and home assistant is notified as soon as new state is available. Polling is only used as fallback should the push mechanism stop working.

Notification

All nodes from the gateway's node database are available as notification targets. Channels are available as targets as well.

Use this method as preferred way to send messages when you don't need control over the details (which gateway to use, acknowledgements, etc.)

Note: Support is based on new entity notification platform, for an example on how to use it, see official documentation.

Automation

For nodes selected as part of the configuration, device triggers and device actions are available. Prefer using device actions and triggers in your automation over using (service) actions.

Triggers

There are triggers when messages have been sent or have been received. Gateway nodes offer more triggers than other nodes. You can further refine the triggers to only fire when a message was sent/received on a particular channel or as direct message.

Actions

• Send Direct Message
• Request Telemetry
• Request Position

Note: Ensure you have a delay before the action if your automations are triggered by meshtastic device trigger, otherwise you risk that your action triggered message is being dropped by meshtastic firmware because it is still busy with receiving / sending other mesh messages.

Examples

Reply back after message received from device on arbitrary channel (including direct 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 }}

Logbook

Direct messages or channel messages are recorded in the log book. Each gateway has an entity for direct messages and its channels, you can navigate to the device and select the entitiy to see an extract of the logbook, or you can navigate to the logbook and filter for the desired entities there.

Note: When logbook is not enabled, messages are not recorded.

Device Tracker

For nodes selected as part of the configuration, their position is exposed as a device tracker. You can see the nodes on home assistant map accordingly and home assistant will report if node is at home or away.

Services / Actions

Use the available actions if you need more control compared to other methods to interact with meshtastic devices. Certain actions need you to understand meshtastic details and are not recommended for the average user.

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines

---