Skip to main content

Install and Configure MeshCore for Home Assistant

If you upgrade from 2.x, read Upgrade to 3.0 first.

Requirements​

ItemRequirement
Home Assistant2025.6.0 or later
meshcore Python library2.3.11 or later. Home Assistant installs it automatically.
CompanionA MeshCore node with companion firmware for your connection type
USBA USB port on the Home Assistant host. The companion must have the USB companion firmware.
BLEA Bluetooth adapter on the Home Assistant host. A Bluetooth proxy does not work with PIN pairing.
TCPA network route to the companion (WiFi firmware) or to a TCP bridge

Each integration entry connects to one companion, and the public key of the companion identifies the entry. To use two companions, add the integration two times. See Two or more companions.

Install the integration​

Add Repository

  1. Make sure that HACS is installed.
  2. In HACS, open the three-dot menu.
  3. Select Custom repositories.
  4. Enter https://github.com/meshcore-dev/meshcore-ha.
  5. Select the type Integration.
  6. Select Add.
  7. Search for MeshCore.
  8. Select Download.
  9. Restart Home Assistant.

Manual installation​

  1. Download the latest release from GitHub.
  2. Copy custom_components/meshcore into the custom_components directory of your Home Assistant configuration.
  3. Restart Home Assistant.

Add the integration​

Add Integration

  1. Go to Settings > Devices & services.
  2. Select Add Integration.
  3. Search for MeshCore.
  4. Select MeshCore.
  5. In Connection Type, select usb, ble or tcp.
  6. Complete the form.
  7. Select Submit.

The connection must complete in 10 seconds. If you see "Failed to connect", correct the values and submit again.

ConnectionFieldDefault
USBUSB Device Path, for example /dev/ttyUSB0 or /dev/ttyACM0(required)
USBConnection Speed115200
BLEBluetooth Device(required)
TCPHost Address(required)
TCPPort5000

For BLE, the integration scans for 5 seconds. If it finds devices with "MeshCore" in the name, the field is a list. If not, type the address.

All three forms also have Enable Self Telemetry, Enable Self Diagnostics, their intervals and Contact Discovery Mode. You can change these later in Global Settings.

A new entry gets the title MeshCore Node <name>, the Governed traffic policy and no tracked nodes. See Mesh Traffic Policy. To add tracked nodes, see Remote Node Tracking.

Reconfigure the connection​

Use Reconfigure to change the connection type, port or host. The integration keeps all other settings, the tracked nodes and the MQTT brokers.

  1. Go to Settings > Devices & services > MeshCore.
  2. Open the three-dot menu of the entry.
  3. Select Reconfigure.
  4. Select the connection type.
  5. Enter the new values.
  6. Select Submit.

If the test passes, the entry reloads. If the new companion has a different public key, the integration changes the public key prefix in the entity IDs of the entry. It also creates the repair issue "MeshCore public key changed". Then do these steps:

  1. Update the automations, scripts and dashboards that use the old entity IDs.
  2. Dismiss the repair issue.

Configure the options​

Go to Settings > Devices & services > MeshCore > Configure. In Choose an action, select one of these actions:

ActionUse
Add Repeater StationTrack a repeater, room server or sensor node. See Remote Node Tracking.
Add Tracked ClientTrack a client. See Remote Node Tracking.
Manage Monitored DevicesEdit or remove a tracked node
Global SettingsChange the settings of the entry
Manage MQTT BrokersAdd, edit or remove a maximum of 6 MQTT brokers. See MQTT Upload.

Each Submit saves the change. To close the menu, select Done.

Most changes apply immediately, without a reload. A change to Enable Self Diagnostics or Enable CLI Console reloads the entry.

Reload the entry​

  1. Go to Settings > Devices & services > MeshCore.
  2. Open the three-dot menu of the entry.
  3. Select Reload.

Global Settings​

FieldRangeDefaultDescription
Message Poll Interval (seconds)1 to 3005The scheduling tick. The integration reads queued messages when the companion reports them, and after 60 seconds with no message. No mesh traffic.
Contact Discovery ModeEntity per contact, Data only, DisabledEntity per contactHow the integration keeps discovered contacts. See Contact Discovery Mode.
Limit Discovered Contactson / offoffLimits the number of discovered contacts
Maximum Discovered Contacts1 to 10000100The limit. The integration removes the oldest contacts first.
Enable Self Telemetryon / offoffRequests telemetry from the companion itself
Self Telemetry Interval (seconds)60 to 3600300The time between self telemetry requests
Enable Self Diagnosticson / offoffCreates 14 diagnostic sensors and 3 radio fault binary sensors for the companion. No mesh traffic.
Self Diagnostics Interval (seconds)60 to 3600300The time between diagnostic queries
Enable CLI Consoleon / offoffCreates the CLI Console sensor. See CLI Command Reference.
Enable Map Auto Uploader (map.meshcore.io)on / offoffUploads repeater, room server and sensor adverts. The firmware must have ENABLE_PRIVATE_KEY_EXPORT=1. See Map Auto Uploader.
Auto-Cleanup Stale Discovered Contacts (runs daily)on / offoffRemoves discovered contacts older than the threshold. Contacts on the companion stay.
Stale Contact Threshold (days)1 to 36530The age for the contact cleanup
Retrieve queued incoming messageson / offonDisable this setting when a phone must get the queued messages. See Share the companion with a phone.
Adaptive Channel Message Deliveryon / offoffFires an incoming channel message at the first reception data, in place of a fixed 500 ms wait. See RX_LOG correlation.
Flood Scope AllowlisttextblankComma-separated region scope names, for example myregion. The integration compares incoming scoped channel messages with these names. The flood_scope field of each rx_log_data entry gives the matched name, or null.
Expose Node Secrets in Eventson / offoffSends channel secrets and private key exports to the event bus and MQTT raw payloads
Auto-Remove Stale Neighborson / offoffRemoves neighbor entries and their sensors, one time each day, after the threshold
Stale Neighbor Threshold (days)1 to 3657The age for the neighbor cleanup
Mesh Traffic PolicyGovernedGovernedThe budget and the retry rules for mesh traffic. See Mesh Traffic Policy.

CAUTION: Do not enable Expose Node Secrets in Events on a system that other people can read. All users and tools that read the event bus or the MQTT broker will see the secrets.

Verify the installation​

  1. Go to Settings > Devices & services > MeshCore.
  2. Open the device of the companion and make sure that its sensors show values.
  3. If you added tracked nodes, make sure that each node has a device.

Solve problems​

MessageCauseAction
Failed to connectNo connection or node information in 10 secondsCheck the cable, power, port, address and companion firmware
Device is already configuredAn entry for this companion existsUse Reconfigure on that entry
Unexpected errorAn error that the integration did not expectRead the Home Assistant log
  • USB: make sure that the port path is correct and that Home Assistant has permission to use it. The Bluetooth companion firmware does not answer on USB.
  • BLE: use a direct adapter near the companion. For a companion that needs a PIN, you can use the external MeshCore BLE Bridge for ESPHome, which gives a TCP connection.
  • TCP: make sure that the host and port are correct and that no firewall blocks the connection.

For debug logging and other problems, see Troubleshooting.

Next steps​