Configuring Gateways

Gateways are the abstraction for interfacing with devices that can be controlled. These may be gateways such as Zigbee, ModBus, HTTP, etc. These are not interfaces that clients should control the controller with. Please see Configuring Interfaces for technologies such as HTTP(S), WS(S) or MQTT.

At current Gateways must be configured by adding a file to the appropriate configuration directory, they can not yet be configured at runtime.

Configuration files must be located in the <config>/gateways directory, see Running for the default location on your operating system, each interface is defined by a JSON file.

All gateways in the shimmeringbee/controller must conform to the shimmering/da interfaces, and may implement many of the capabilities dicated by that specification.

The name of the file will be the name of the gateway, and will be exposed by various APIs and interfaces.

ZDA (Zigbee Device Abstraction)

The ZDA provides a generic abstraction around the Zigbee protocol stack, the ZDA needs a Zigbee provider in order to implement the lower level functionality.

{
    "Type": "zda",
    "Config": {
        "Provider": {
            "Type": "zstack",
            "Config": {
                "Port": {
                    "Name": "/dev/ttyUSB0",
                    "Baud": 115200,
                    "RTS": false
                }
            }
        },
        "Network": {
            "PANID": 1234,
            "ExtendedPANID": 12345678,
            "NetworkKey": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ],
            "Channel": 15
        },
        "Rules": "/path/to/additional/rules"
    }
}

Provider

At current only the zstack provider is implemented, but in the future other providers such as deCONS or similar could be implemented. Z-Stack assumes a UART based connection to the coordinator stick.

At current the following chip based USB sticks are known to work:

• CC253X
  • Cheap Zigbee Sniffers from AliExpress - CC2531
• CC26X2R1
  • Electrolama zig-a-sig-ah! - CC2652R

They must already be running the Z-Stack coordinator firmware, graciously provided by Koenkk, author of zigbee2mqtt.

Please note that the zig-a-zig-ah requires the RTS flow control functionality of serial to be disabled. The port will usually be a /dev/ devices on *nix/macOS, on Windows it will simply be COM3 or similar.

Network Settings

The network block is the definition of your Zigbee network, here you must provide the PANID, Extended PANID, Channel and network security key. The PANID is 16-bit number, the Extended PANID is a 64-bit number, the network key is 16 8-bit numbers. These can all effectively (and should be random).

The channel can be between 11 and 26, however Zigbee Light Link requires devices operate on 11, 15, 20, or 25 (these are gaps between common 802.11 WiFi channels). The ZLL default is actully 15, if you live in a high population density area you may wish to choose a different channel.

Unless you have good reason to deviate from ZLL, choose one of the four. By deviating away from 15, some devices may take longer to pair, but still should after a while.

Note if you change any of the settings in the network block, you will have to repair ALL of your devices.