MeshCore for Home Assistant

This is a custom Home Assistant integration for MeshCore mesh radio nodes. It allows you to monitor and control MeshCore nodes via USB, BLE, or TCP connections.

⚠️ Work in Progress: This integration is under active development. BLE connection method hasn't been thoroughly tested yet.

Core integration is powered by meshcore-py.

---

📖 Documentation

➡️ View Full Documentation

Everything you need to know:

• ✅ Complete feature list
• ✅ Configuration guides
• ✅ Sensor documentation
• ✅ Service descriptions
• ✅ Automation examples
• ✅ Dashboard templates
• ✅ Troubleshooting guides

---

Installation

HACS Installation (Recommended)

1. Make sure you have HACS installed
2. Add this repository as a custom repository in HACS:
   • Go to HACS > Integrations
   • Click on the three dots in the top right corner
   • Select "Custom repositories"
   • Add the URL of this repository
   • Select "Integration" as the category
3. Click "Install" on the MeshCore integration

Manual Installation

1. Copy the custom_components/meshcore directory to your Home Assistant custom_components directory
2. Restart Home Assistant

Quick Start

1. Go to Settings > Devices & Services
2. Click + Add Integration and search for "MeshCore"
3. Follow the setup wizard to configure your connection

For detailed configuration instructions, see the documentation.

MQTT Upload (Addon/Container Env)

Configuration can be done in the Home Assistant Web UI:

• Settings -> Devices & Services -> MeshCore -> Configure
• MQTT Global Settings
• MQTT Broker Settings (Broker 1-4)

Auth-token mode is easy install by default:

• meshcore-decoder is optional.
• If meshcore-decoder is not available, the integration automatically falls back to in-process Python signing (PyNaCl).
• Signing key is pulled from the connected node via export_private_key().
• If private key export is disabled/blocked on firmware, auth-token upload cannot start.

Map Auto Uploader (map.meshcore.dev)

When enabled (off by default), the integration automatically uploads repeater and room server adverts to map.meshcore.dev when your Companion hears them. This integrates the map.meshcore.dev-uploader bot directly into the MeshCore Home Assistant integration—no separate bot needed. Enable in Global Settings if you want Map Auto Uploader.

• Uses the same connection as Home Assistant (USB, BLE, or TCP)
• Requires private key export on firmware (ENABLE_PRIVATE_KEY_EXPORT=1)
• Replay protection and signature verification built-in

Development

Local Development Setup

1. Clone this repository
2. Copy custom_components/meshcore to your Home Assistant config directory
3. Restart Home Assistant
4. Add the integration through the UI

Testing

Run tests with pytest:

pytest tests/

Support and Development

• Report issues on GitHub Issues
• Contributions are welcome via pull requests
• Documentation contributions are also welcome!

Requirements

• Home Assistant (version 2023.8.0 or newer)
• MeshCore node with firmware that supports API commands
• For BLE: Bluetooth adapter on the Home Assistant host (direct connection only; proxy connections don't work with PIN pairing)
• For USB: USB port on the Home Assistant host

License

This project is licensed under the MIT License - see the LICENSE file for details.