Meshtastic Home Assistant Integration

A Home Assistant custom integration for Meshtastic mesh networking devices. Extends the upstream Meshtastic HA integration with MQTT as a first-class connection method — allowing you to monitor your entire Meshtastic mesh network without a physical device connected to your Home Assistant host.

Supports dual-mode operation: MQTT and device-based connections can run simultaneously, with nodes automatically merged into a single Home Assistant device.

Features

  • MQTT Connection — Subscribe to a Meshtastic MQTT broker and automatically discover all nodes on the mesh (no physical device required)
  • Device Connections — Connect directly via TCP, Bluetooth, or Serial (inherited from upstream)
  • Dual-Mode Operation — Run MQTT and device-based connections simultaneously
  • Automatic Node Discovery — Nodes created as HA devices with comprehensive sensors
  • Encrypted Traffic Decoding — AES-CTR decryption of encrypted Meshtastic channels using configurable keys
  • Send Messages via MQTT — Text messages, direct messages, and channel broadcasts
  • Full Entity Support — Sensors, binary sensors, device trackers, and notify platform per node
  • Comprehensive Telemetry — Battery, voltage, signal strength, position, telemetry, environment data

Installation

  1. Install HACS if you haven’t already
  2. In HACS: Integrations → three-dot menu → Custom repositories
  3. Add this repository URL and select “Integration” as the category
  4. Install the “Meshtastic” integration from HACS
  5. Restart Home Assistant
  6. Go to Settings → Devices & Services → Add Integration → Meshtastic

Option 2: Manual Installation

  1. Copy custom_components/meshtastic/ into your Home Assistant config/custom_components/ directory
  2. Restart Home Assistant
  3. Go to Settings → Devices & Services → Add Integration → Meshtastic

MQTT Configuration

When adding the integration, select MQTT as the connection type and provide:

SettingDescriptionDefault
Broker HostMQTT broker hostname or IP—
Broker PortMQTT broker port1883
UsernameMQTT username (optional)—
PasswordMQTT password (optional)—
TLSEnable TLS/SSL encryptionOff
Topic PatternMQTT topic to subscribe tomsh/US/2/e/#
Channel KeysChannel name → base64 encryption key pairsLongFast: AQ==

The default channel key AQ== is the standard Meshtastic encryption key for the LongFast channel.

Entities Per Node

Each discovered Meshtastic node gets a Home Assistant device with:

  • Sensors: Battery level, voltage, channel utilization, airtime, uptime, SNR, hops away, role, short/long name
  • Environment Sensors: Temperature, humidity, barometric pressure (when reported)
  • Device Tracker: GPS position (latitude, longitude, altitude)
  • Binary Sensor: Online/offline status
  • Notify Service: Send text messages to the node

Services

ServiceMQTT ModeDevice Mode
meshtastic.send_text✅✅
meshtastic.send_direct_message✅✅
meshtastic.broadcast_channel_message✅✅
meshtastic.request_telemetry❌✅
meshtastic.request_position❌✅
meshtastic.request_traceroute❌✅

Request-response services require a direct device connection (not available in MQTT-only mode).

Project Structure

homeassistant-meshtastic/
├── custom_components/meshtastic/      # The HA integration
│   └── aiomeshtastic/                 # Async Meshtastic library
│       ├── connection/                # Connection implementations
│       │   ├── mqtt.py
│       │   ├── decoder.py
│       │   ├── errors.py
│       │   ├── listener.py
│       │   └── streaming.py
│       ├── protobuf/                  # Meshtastic protobuf definitions
│       ├── interface.py
│       ├── packet.py
│       ├── errors.py
│       └── const.py
├── tests/                             # Comprehensive test suite
├── docs/                              # Full documentation
│   ├── api/
│   ├── user-guide.md
│   ├── developer-guide.md
│   └── features.md
├── .github/                           # CI workflows, templates
├── .vscode/launch.json                # Debug configurations
├── Makefile                           # Dev automation
├── requirements-dev.txt               # Dependencies
├── renovate.json                      # Dependency updates
└── README.md

Development

Prerequisites

  • Python 3.12+

Setup

git clone https://github.com/netnutmike/homeassistant-meshtastic.git
cd homeassistant-meshtastic
python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

Commands

make test           # Run tests
make lint           # Lint code
make lint-fix       # Auto-fix
make type-check     # Type checking
make verify-setup   # Verify prerequisites

Tech Stack

  • Home Assistant - Automation platform
  • Python 3.12+ - Primary language
  • MQTT - Message broker
  • Meshtastic Protocol - Mesh networking
  • AES-CTR - Encryption/decryption
  • asyncio - Async networking
  • pytest - Testing
  • mypy - Type checking

Status

Production Ready (April 2, 2026)

All major features complete and stable for production use:

  • Core MQTT connection fully implemented
  • Automatic node discovery and entity creation
  • Full message sending capabilities
  • Comprehensive telemetry and sensor support
  • Encrypted channel support
  • Complete test coverage
  • Full documentation suite
  • HACS integration ready
  • CI/CD workflows configured

Learn More