@samantha-uk/zigzag-panel

Table of Contents

• Description
• Installation
  • Prerequisites
  • Installation Steps
• Plugins
  • data
  • layout
  • render
• Configuration
• Usage
• Key to display icons & legends
• Know Issues
• Contributing
  • License

Description

Zigzag-panel is a custom panel for Home Assistant that displays a graphical layout of Zigbee devices and the connections between them.

In Zigzag, Zigbee devices are known as Zigs and the connections between them as Zags.

Zigzag-panel is built using the Zigzag web component.

Zigzag is currently an alpha release. There are likely to be a number of issues and new releases may be frequent.

Installation

At present the installation of Zigzag is a manual process.

Prerequisites

• Home Assistant - version 2020.12.0 or more recent.
• ZHA - A Home Assistant Zigbee Integration. The plugin architecture of Zigzag means new sources of Zigbee information can be easily added. Support for zigbee2mqtt is under investigation.

Installation Steps

You will need to:

• Copy the zigzag directory (and its contents) to a zigzag directory in the www folder of your Home Assistant server. It should then look something like this (There may be a number of .map files also.):

└── www
    └── zigzag
        ├── plugins
        │   ├── plugin-data-file.esm.js
        │   ├── plugin-data-gen.esm.js
        │   ├── plugin-data-zha.esm.js
        │   ├── plugin-layout-d3.esm.js
        │   └── plugin-render-pixi.esm.js
        ├── zigzag-panel-config.yaml
        └── zigzag-panel.esm.js

• Copy the contents of zigzag/zigzag-panel-config.yaml into your Home Assistant configuration.yaml file.
• Restart Home Assistant.
• Zigzag should appear as an entry on the left of the display, which if you select should display your Zigbee network. If not, check in the console of your web browser for any error messages.

Plugins

Plugins allow Zigzag behaviour to be configured. A plugin based approach was selected to facilitate:

• Performance - Only the code for the behaviour you want needs to be downloaded to your browser when it is required (lazy-loading).
• Extensibility - To add (for instance) a new source of Zigbee data (zigbee2mqtt for example).

Plugins may be authored as part of the Zigzag project or by third parties.

data

The data plugin is used to specify where Zigzag will read the details of Zigs and Zags.

Plugin Type	Description	More Info
file	Gets Zigzag information from a json file	file
gen	Gets Zigzag information from a json file and then generates more entires (Used for performance tuning)	gen
zha	Gets Zigzag information from the Home Asssistant ZHA integration	zha

layout

The layout plugin contains the logic Zigzag uses to arrange the layout of Zigs.

Plugin Type	Description	More Info
d3	Uses D3 forces module to layout the Zigs. file	d3

render

The render plugin is what displays the Zigzag network on the screen.

Plugin Type	Description	More Info
pixi	Uses PixiJS to display a 2d view. file	pixi
three	Uses three.js to display a 3d view.	three

Configuration

Configuration of Zigzag panel allows you to specify which plugins it will use. Configuration is carried out by editing entries in the Home Assistant configuration.yaml file.

So if you wanted to use file based data, with d3 layout and being rendered using three you would edit the zigzag-panel section configuration.yaml as follows.

panel_custom:
  - name: custom-panel-zigzag
    sidebar_title: Zigzag
    sidebar_icon: mdi:zigbee
    url_path: zigzag
    module_url: /local/zigzag/zigzag-panel.esm.js
    trust_external_script: true
    config:
      who: world

      zigzag:
        plugin-path: "/local/zigzag/plugins"
        plugin-data:
          type: "file"
          filepath: "/local/zigzag/devices.json"

        plugin-layout:
          type: "d3"

        plugin-render:
          type: "three"

Plugin specific configuration items are documented in their respective readme files (Links to these are in the tables above).

Usage

You can zoom in/out and pan around to examine the graph. You can change the location of a Zag by dragging it. Once this is done it will remain locked in that position (Displaying a small lock icon). To unlock a Zig, click/press for about half a second and when you release it will unlock.

Key to display icons & legends

TBD

Know Issues

• It doesn't correctly Zoom to Fit on initial display. Clicking the ZOOM TO FIT button will work.

Contributing

Contributions, issues and feature requests are welcome. Feel free to check the issues page if you would like to contribute. Check the contributing guide.

License

Licensed under MIT.