ha-zigbee-mesh-map

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #android #machine-learning #rust #deep-learning #linux #nodejs #awesome #kubernetes #awesome-list

ha-zigbee-mesh-map

(★ 16)

An interactive Zigbee mesh visualization card for Home Assistant.

ha-zigbee-mesh-map 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# <img src="https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/icon.png" width="32" height="32" alt="icon"> Zigbee Mesh Map Card

[![HACS Default](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
[![Release](https://img.shields.io/github/v/release/lubomir-moric/ha-zigbee-mesh-map)](https://github.com/lubomir-moric/ha-zigbee-mesh-map/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/lubomir-moric/ha-zigbee-mesh-map/blob/main/LICENSE)
[![Stars](https://img.shields.io/github/stars/lubomir-moric/ha-zigbee-mesh-map.svg)](https://github.com/lubomir-moric/ha-zigbee-mesh-map/stargazers)

[![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=lubomir-moric&repository=ha-zigbee-mesh-map&category=plugin)

A modern Lovelace card for Home Assistant that visualizes your Zigbee mesh network from Zigbee2MQTT. Interactive graph with zoom, pan, drag, configurable colors, LQI-based link quality indicators, and automatic updates when the topology changes.

⚠️ **Zigbee2MQTT Only** — this card is not compatible with ZHA or DeCONZ.

## ✨ Features

- Interactive force-directed and radial tree layouts with zoom, pan, and drag
- Device search with fulltext matching and click-to-highlight
- **Star view** — click a highlighted node again to isolate it and its direct neighbours, then single-click to navigate between stars
- Bidirectional LQI display with color-coded signal quality
- Three view modes switchable from the footer: radial tree, force graph, and full mesh
- Asymmetric and weak link detection
- Fully configurable colors, sizing, and layout parameters

### Search & highlight

Click the 🔍 icon in the toolbar to open the search bar. Type to filter devices by friendly name — all matching nodes and their direct links are highlighted while the rest of the map dims. If nothing matches, the entire map dims.

Clicking a node fills the search bar with its name and highlights its connections. Clicking the map background clears the search and restores the full view. The ✕ button inside the search bar clears the text without closing it.

![Search](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/map-search.png)

### Parent-child view (default)

Shows direct routing connections — the backbone and device-to-router links.

**Dark theme**

![Dark theme](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/map-backbone-dark.png)

**Light theme**

![Light theme](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/map-backbone-light.png)

### Full mesh view (`link_filter: all`)

Shows all neighbor/sibling links with the backbone and direct routes emphasised.

![Full mesh](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/map-all.png)

### Star view

Click a highlighted node a second time (or click any node while already in star mode) to enter **star view** — only the selected node and its direct neighbours are rendered, with all other nodes and links removed. The cursor changes to 🔍 zoom-in on actionable nodes as a visual hint.

A breadcrumb pill (`★ Node Name ✕`) appears at the top-left. Click any neighbour to navigate to its star view (zoom level is preserved). Exit by clicking the ✕ on the pill, pressing Escape, or switching to another view mode.

Star view respects `min_lqi` and `min_lqi_mode`: in **remove** mode, weak links and their orphaned nodes are hidden; in **dim** mode, they remain visible but faded.

![Star view](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/map-star.png)

> **Use case:** Planning to re-pair a device to a different router? Open star view on the device to see all its current neighbours and their link qualities at a glance — then click each candidate router to compare its own neighbourhood and signal strengths before deciding where to re-pair the device.

## 📦 Installation

### Method 1: Via HACS (Recommended)

The easiest way to install is directly through HACS:

1. Click the button below to open the repository in your Home Assistant instance:
   [![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=lubomir-moric&repository=ha-zigbee-mesh-map&category=plugin)
2. Click **Download** in the bottom right corner.
3. Reload your browser or clear your cache after installation.

*Alternatively, open HACS, navigate to **Frontend**, click the three dots/search icon, and search for `Zigbee Mesh Map Card`.*

### Method 2: Manual Installation

If you don't use HACS, you can install the card manually:

1. Download the `ha-zigbee-mesh-map.js` file from the [latest release](https://github.com/lubomir-moric/ha-zigbee-mesh-map/releases).
2. Upload the file to your Home Assistant installation inside the `/config/www/` directory (e.g., `/config/www/zigbee-mesh-map/ha-zigbee-mesh-map.js`).
3. Register the resource in Home Assistant:
   * Go to **Settings** → **Dashboards**.
   * Click the three dots in the top right and select **Resources**.
   * Click **Add Resource**.
   * Set the URL to `/local/zigbee-mesh-map/ha-zigbee-mesh-map.js` and the type to `JavaScript Module`.

## 📡 Zigbee Network Map Sensor (Required)

You must expose your Zigbee network map as a Home Assistant sensor. Add the following to your `configuration.yaml`:

```yaml
mqtt:
  sensor:
    - name: Zigbee2MQTT Network Map
      state_topic: zigbee2mqtt/bridge/response/networkmap
      unique_id: zigbee2mqtt_networkmap
      value_template: "{{ now().strftime('%Y-%m-%d %H:%M:%S') }}"
      json_attributes_topic: zigbee2mqtt/bridge/response/networkmap
      json_attributes_template: "{{ value_json.data.value | tojson }}"
```

The network map sensor carries a large JSON payload that Home Assistant will try to record. To avoid the `State attributes exceed maximum size of 16384 bytes` warning and unnecessary database bloat, exclude it from the recorder in your `configuration.yaml`:

```yaml
recorder:
  exclude:
    entities:
      - sensor.zigbee2mqtt_networkmap
```

## 🧩 Usage

Add the card to your Lovelace dashboard:

```yaml
type: custom:zigbee-mesh-map
entity: sensor.zigbee2mqtt_networkmap
title: Zigbee Mesh
```

### 🔄 Refreshing the Map

Define a script that publishes the Zigbee2MQTT networkmap request. Add this to your `scripts.yaml` (the script key determines the entity ID — `script.zigbee_map_refresh`):

```yaml
zigbee_map_refresh:
  alias: Zigbee map refresh
  sequence:
    - action: mqtt.publish
      data:
        topic: zigbee2mqtt/bridge/request/networkmap
        payload: '{"type":"raw","routes":false}'
```

Alternatively, create the script via **Settings → Automations & Scenes → Scripts → Add Script** in the HA UI. The entity ID is auto-generated from the script name — check it under **Settings → Devices & Services → Entities** and set `refresh_script` in your card config if it differs from the default `script.zigbee_map_refresh`.

Optionally, create an automation to refresh the map periodically (e.g. every hour):

```yaml
alias: "Zigbee: refresh map"
description: Refresh Zigbee map every hour
triggers:
  - hours: /1
    trigger: time_pattern
conditions: []
actions:
  - action: script.zigbee_map_refresh
    metadata: {}
    data: {}
mode: single
```

### ⚙️ Full Configuration

All parameters are optional — if omitted, defaults are used:

```yaml
type: custom:zigbee-mesh-map
entity: sensor.zigbee2mqtt_networkmap
refresh_script: script.zigbee_map_refresh
title: Zigbee Mesh Map
grid_options:
  columns: full                  # default card width (1–12, or "full")
  rows: 8                        # default card height in grid units

# --- View mode ---
view_mode: force                 # "force", "radial", or "all"

# --- Footer controls ---
show_modes: true                 # show/hide the entire mode switcher
show_mode_force: true            # show force-layout mode icon
show_mode_radial: true           # show radial-layout mode icon
show_mode_all: true              # show all-links mode icon
show_lqi_slider: true            # show min LQI slider (only visible in "all" view)
lqi_slider_step: 10              # slider snap increment (1–255)

# --- Display ---
show_lqi_labels: true            # show LQI values on links
lqi_format: both                 # "both" (XX/YY) or "avg" (single average)
show_node_labels: true           # show friendly names on nodes
font_size: 6                     # label font size in pixels

# --- Colors ---
coordinator_color: "#DB5228"     # coordinator node color
router_color: "#4A90D9"          # backbone router color (has children)
router_leaf_color: "#7BAFD4"     # leaf router color (no children)
end_device_color: "#97B552"      # end device node color
node_outline_color: "rgba(0,0,0,0.3)"  # "none", "#fff", "gray"
node_highlight_color: "#FFD700"        # outline color for search-matched nodes
lqi_colors:
  200: "#4CAF50"                 # >=200 excellent (green)
  150: "#FDD835"                 # >=150 good (yellow)
  100: "#FB8C00"                 # >=100 fair (orange)
  50: "#F44336"                  # >=50 poor (red)
  0: "#5F5F5F"                   # <50 very poor (gray)

# --- Node sizing ---
node_radius:
  coordinator: 10                # coordinator node radius
  router: 10                     # backbone routers (have children)
  router_leaf: 6                 # leaf routers (no children)
  end_device: 4                  # end device node radius

# --- Link quality ---
min_lqi: 50                      # LQI threshold for weak links
min_lqi_mode: remove             # "remove" (hide weak neighbor links) or "dim" (fade them). Only affects neighbor links — route and backbone links keep their full style.
link_style:
  backbone_width: 3.0            # backbone links (between core routers)
  backbone_opacity: 1
  backbone_dash: ""              # "" = solid
  route_width: 0.8               # route links (to leaf routers / end devices)
  route_opacity: 0.8
  route_dash: ""
  neighbor_width: 0.5            # neighbor links (relationship: 2, non-routing)
  neighbor_opacity: 0.6
  neighbor_dash: "3,2"           # SVG stroke-dasharray pattern
  dim_width: 0.5                 # weak link thickness (below min_lqi)
  dim_opacity: 0.2               # weak link opacity (below min_lqi)

# --- Zoom ---
zoom:
  min: 0.2                       # minimum zoom level
  max: 4                         # maximum zoom level
  initial: auto                  # "auto" (fit after initial settle) or number (e.g. 1.5)

# --- Layout: force ---
force_config:
  link_distance: 65              # ideal link length (higher = more spread)
  link_strength: 0.6             # how rigidly links hold distance (0–1)
  charge_strength: -80           # node repulsion (more negative = stronger)
  collide_radius: 35             # minimum spacing between nodes
  alpha_decay: 0.03              # simulation cooldown speed (lower = longer settle)
  all:                           # overrides applied only in "all" view (optional)
    charge_strength: -120
    link_distance: 80
  parent_child:                  # overrides applied only in "parent-child" view (optional)
    charge_strength: -50

# --- Layout: radial ---
radial_config:
  node_spacing: 1.0              # angular spacing between nodes (higher = more spread)
  level_depth: 80                # radial distance between depth levels (higher = wider rings)
```

You only need to specify the parameters you want to change. For nested objects (`node_radius`, `lqi_colors`, `force_config`, `radial_config`, `zoom`, `grid_options`), partial overrides are supported — unspecified keys keep their defaults.

> **Note:** `layout_options` (with `grid_columns` / `grid_rows`) still works on older HA versions. On HA 2024.x+ Sections dashboards, use `grid_options` with `columns` / `rows`.

`force_config` supports optional `all` and `parent_child` sub-objects. When present, those values override the global force settings for that specific view. If omitted, the global values apply to both views.

Three view modes are available via the footer icons: **radial** (tree radiating from coordinator), **force** (interactive physics simulation), and **all** (full mesh with all neighbor links, force layout). The initial mode is set by `view_mode`. Set `show_mode_force`, `show_mode_radial`, or `show_mode_all` to `false` to hide individual mode icons.

The card automatically fills the space assigned by HA's grid layout. Use `grid_options` to control the default size, or resize the card directly in the dashboard editor.

---

### 📊 Alternative List View: Zigbee Signal Strength Monitor

For a clean, filterable list view of your devices' signal strengths alongside the interactive mesh map, a companion card configuration is available in the `lovelace` directory.

It dynamically extracts parent routing names directly from your `sensor.zigbee2mqtt_networkmap` data, handles translation fallback, and calculates bidirectional Link Quality Indicator (LQI) averages.

![LQI Lovelace Card](https://raw.githubusercontent.com/lubomir-moric/ha-zigbee-mesh-map/main/media/LQI_lovelace_card.png)

#### 📝 What the Data Represents
* **LQI (Link Quality Indicator):** A metric that measures the signal strength and packet data quality between two Zigbee nodes. Higher values mean a more stable connection (scaled 0 to 255).
* **`XXX / YYY` Value:** This shows the **bidirectional link quality**. `XXX` represents the *downstream* LQI (Parent router to Device), while `YYY` represents the *upstream* LQI (Device back to Parent router).
* **Parent Node Link:** The secondary information row displays the friendly name of the direct parent routing node (`⬆️ Parent Name`) that the device is currently utilizing to communicate with the coordinator, alongside its localized base signal strength (`📡`).

⚠️ **Important Note on Entity Availability:** By default, Home Assistant often keeps the `*_linkquality` sensors disabled when discovering new devices from Zigbee2MQTT. **You must manually enable these entities** in your Home Assistant Settings (**Settings → Devices & Services → MQTT → Devices**) for this card to find and display them.

#### Prerequisites
To use this companion card, make sure you have the following frontend plugins installed via HACS:
* `custom:auto-entities`
* `custom:template-entity-row`
* `custom:card-mod`

#### Installation
1. Open the [lovelace/LQI_signal_card.yaml](lovelace/LQI_signal_card.yaml) file in this repository and copy the entire code block.
2. In your Home Assistant Dashboard, click **Edit Dashboard** in the top-right menu.
3. Click **Add Card**, select **Manual** (at the very bottom of the card list).
4. Paste the copied YAML code.

#### Customization
At the top of each block in the configuration file, you will find an explicit `======= CONFIGURATION =======` section. You can easily adjust these variables to match your personal naming styles or language preference:

* `networkmap`: The entity ID of your Zigbee2MQTT network map sensor.
* `suffix`: The string stripped from your entity names to compute clean friendly names (e.g., `Linkquality`).
* `text_not_found`: Fallback text if a parent node cannot be parsed.
* `text_coordinator`: Display name for your main Zigbee coordinator hub.

## 🛠 Requirements

- Home Assistant 2023.0+
- Zigbee2MQTT with `networkmap` enabled
- MQTT integration configured in HA

## 🧪 Troubleshooting

**The map does not refresh:**
- Ensure your script publishes `{"type":"raw","routes":false}`
- Check Zigbee2MQTT logs for map generation errors
- Verify the entity updates in Developer Tools → States

**Routing table errors:**
- Normal for many Tuya/Telink routers (e.g., TS011F)
- They do not support routing table queries

**Warning banner in the card:**
- "Entity not found" — check that `entity` matches your sensor's entity ID
- "Does not contain expected data"
  - verify your MQTT sensor template outputs `nodes` and `links` arrays
  - **After a Home Assistant reboot:** The map entity may be empty. The card will automatically request a refresh once — just wait for the data to arrive.
- "Refresh script not found" — create the script or set `refresh_script` to match your script's entity ID

**Testing without real data:**
- Add `mock_data: true` to your card config to render with built-in sample data
- Useful for testing layout, colors, and configuration options without a live Zigbee network
- Remove `mock_data` when done

**Debug logging:**
- Add `debug: true` to your card config to enable verbose console output (dropped links, etc.)
- Open browser Developer Tools → Console to see the messages

## 📄 License

MIT

## ✨ AI-Generated Project

This project was created with assistance from AI tools. Code and documentation were generated through iterative AI-guided development, then manually reviewed and refined.

ha-zigbee-mesh-map

ha-zigbee-mesh-map 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

ha-zigbee-mesh-map

ha-zigbee-mesh-map 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README