https://github.com/teh-hippo/ha-matter-navigator

Read-only Home Assistant integration that visualises your Thread and Matter mesh and routing.
https://github.com/teh-hippo/ha-matter-navigator

hacs home-assistant homeassistant-integration matter mesh-network thread thread-network

Last synced: about 1 month ago
JSON representation

Read-only Home Assistant integration that visualises your Thread and Matter mesh and routing.

• Host: GitHub
• URL: https://github.com/teh-hippo/ha-matter-navigator
• Owner: teh-hippo
• License: mit
• Created: 2026-06-15T13:29:54.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2026-06-15T16:10:50.000Z (about 1 month ago)
• Last Synced: 2026-06-15T17:10:51.459Z (about 1 month ago)
• Topics: hacs, home-assistant, homeassistant-integration, matter, mesh-network, thread, thread-network
• Language: Python
• Size: 679 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Matter Navigator

A **strictly read-only** Home Assistant custom integration that visualises your

Thread / Matter-over-Thread mesh and routing as an interactive sidebar map, and

surfaces insights about link quality and topology.

![The Mesh Map panel: border routers at the centre, routers around them, and sleepy end devices on the outer ring with dashed links to their parents.](https://raw.githubusercontent.com/teh-hippo/ha-matter-navigator/main/docs/mesh-map.png)

> [!IMPORTANT]

> This integration is **read-only**. It only *reads* Matter diagnostics and

> *observes* mDNS. It never changes a value, sends a command, re-interviews,

> removes a device, or commissions anything. A CI guard fails the build if any

> write API is introduced.

## Why

Home Assistant's built-in Matter integration does not visualise the Thread mesh.

Where the Thread border routers are owned by another ecosystem (for example

Apple TVs), there is no OpenThread Border Router to query — so Matter Navigator

reconstructs the mesh from the **Matter Thread Network Diagnostics cluster

(`0x0035`)** read per device, joined by Extended Address (EUI-64), and labels

external border routers using passive mDNS (`_meshcop._udp`) discovery.

## What it shows

- A live force-directed graph of routers, children and border routers, with

  hierarchy (tree) and concentric (by-role) layouts.

- Link quality per hop encoded visually: colour = LQI, opacity = RSSI, width =

  path cost; child links are dashed and directed.

- A node drawer with Thread role, parent, the **route to a border router**

  (per-hop LQI / RSSI), and its neighbour list.

- Read-only health insights in the header: counts of **weak links** (marginal,

  still-maintained links) and **offline** nodes, each clickable to isolate them

  on the map.

- A zero-jank 60 second refresh that updates metrics in place and only re-lays

  the graph out when the set of nodes actually changes.

## Status

Working and installed via HACS as a custom repository. Built fixture-first

(offline) against a captured diagnostics snapshot; see `tests/`. Not yet

submitted to the default HACS store.

## Data sources (all read-only)

| Source | Use |

| --- | --- |

| Matter cluster `0x0035` (`read_attribute`) | Neighbour / route tables, roles |

| GeneralDiagnostics `0/51/0` | Each node's own EUI-64 (join key) |

| mDNS `_meshcop._udp` `xa` | Identify external border routers |

## Licence

MIT.