Skip to content

Zigate.Coordinator

Jump to bottom
Nouknouk edited this page Jul 10, 2018 · 7 revisions

features:

  • uses the Zigate.Driver for low-level interaction with the zigate key.
  • exposes the availables devices, their endpoints / clusters / attributes and actions on them (get/set attribute's values, ...)
  • keeps a trace of the devices included in the network, for persistance on next run.
  • stores metadata related to zigbee devices' specifications: endpoints/clusters/attributes.
  • provides a simple API to start/stop the inclusion mode (to include/Exclude a zigbee device in the Zigate's network.
  • recognises devices, and creates appropriate values, events, actions objects, to interact easily with the device.

instanciation:

const Zigate = require('node-zigate');

let coordinator = new Zigate.Coordinator({
    log:          // (optional ; default='nolog') ; can be 'console', ...
    loadsavepath: // (optional ; default = '' <=> no persistence of network devices__)
    // + all options available for the underlying Zigate.Driver instance
});

  • log can be a string for console log's output: (nolog,console,trace,debug,info,warn,error)

    cf. Logs for more information.

  • loadsavepath is the path+filename where the persistent information about devices included in the network, their characteristics, etc... will be stored (in JSON format). Example: './zigate_network.json'.

if no loadsavepath is provided, the informations will not be persisted, and auto-detection of devices types won't work

detect available Zigate ports:

You can use the static function Driver.guessZigatePorts() (cf. Zigate.Driver)

start & stop coordinator:

coordinator.start(port, options)

  • port is optional ; if none provided (or '' or 'auto'), the port of the Zigate key will be auto-detected.
  • options is optional ; for the moment, it can only contain a 'port' attribute.

The metohd start() return a promise, fullfilled when the connexion to the Zigate + its configuration as a 'zigbee coordinator' is done.

coordinator.stop()

  • returns a promise, fullfilled when the connexion to the Zigate has been closed (it is also fullfilled if the coordinator was not connected)

sample use case:

Zigate = require('../');
let coordinator = new Zigate.Coordinator({
    log: 'console',
    loadsavepath: './network_devices.json',
});

coordinator.start();

include a new zigbee device into the network

coordinator.startInclusion(timeInSeconds)

  • returns a promise, fullfilled if the inclusion mode has been well started.
  • when inclusion starts, an event inclusion_start is emitted by the coordinator.
  • when inclusion time expired, an event inclusion_stop is emitted by the coordinator.

coordinator attributes & functions:

  • coordinator.log: the logging system
  • coordinator.status: a status string (stopped, starting, started or stopping)
  • coordinator.devices: an array of all zigbee device objects registered in the coordinator.
  • coordinator.device(0x1234): returns the device with network address 0x1234 (or null if none exist).

Devices & related data:

  • Each device has got [0...n] endpoints
  • Each endpoint has got [0...n] clusters
  • Each cluster has got [0...n] attributes (which store data)
  • Each cluster has got [0...n] commands (to perform actions)

Those endpoints, clusters, attributes, commands are references with their 'id' (a unique number, often written in hexadecimal)

Get the devices data:

  coordinator.devices.forEach( (device) => {
    console.log("device "+device.hex);

    device.endpoints.forEach( (endpoint) => {
        console.log("  endpoint "+endpoint.hex);

        endpoint.clusters.forEach( (cluster) => {
            console.log("    cluster "+cluster.hex);

            cluster.attributes.forEach( (attribute) => {
                console.log("      attribute "+attribute.hex+" type="+JSON.stringify(attribute.type));
            });
            cluster.commands.forEach( (command) => {
                console.log("      command "+command.hex+" type="+JSON.stringify(command.type));
            });
        });
    });
  });

Getters:

get ... code
array of all devices coordinator.devices
one device by address coordinator.device(0x1234)
array of all endpoints of a device device.endpoints
one endpoint by id device.endpoint(0x0001)
array of all clusters of an endpoint endpoint.clusters
one cluster by id endpoint.cluster(0xff01)
array of all attributes of a cluster cluster.attributes
one attribute by id cluster.attribute(0x0005)
array of all commands of a cluster cluster.commands
one command by id cluster.command(0x0001);
array of all commands of a whole device device.attributes

common API of device / endpoints / clusters / attributes / commands objects:

get ... type code
the unique id of the object (except devices)  Number myobject.id
the address of a device Number mydevice.address
the hexadecimal id of the object string myobject.hex
the type of the object  object myobject.type
the type of the object object myobject.type
the parent device of an attribute / cluster / endpoint object myobject.device
the parent endpoint of an attribute / cluster object myobject.endpoint
the parent cluster of an attribute object myobject.cluster

devices: known models & auto-recognition:

When a device is included in the network, the coordinator may recognize the model of device you just included (like "Xiaomi Aquara temperature sensor"). In such case, it will add specific data to the device instance:

  • values, which are (read/write) user-friendly data (like 'temperature', 'presence', 'battery')
  • actions, which are functions you can call (work in progress)
  • events, which may be fired (like 'button pushed', 'motion detected', ...)

To get the list of device model currently supported, look in the folder /devices of the module (one definition file per model).

getters:

Same principle as for endpoints:

  coordinator.devices.forEach( (device) => {
    console.log("device "+device.hex);

    device.values.forEach( (value) => {
        console.log("  value "+value.id+" = "+value());
    });

    device.actions.forEach( (action) => {
        console.log("  action "+action.id);
    });

    device.events.forEach( (event) => {
        console.log("  event "+event.id);
    });
  });

  myButtondevice.event('push_x2').on('push_x2', () => {
    console.log("my Xiaomi push button has been double clicked")
  }

Events fired:

catch them like any event in nodejs:

coordinator.on('start' function() { /* do something */ })

by Coordinator:

  • coordinator status: starting, started, stop, reset, error,
  • inclusion status: inclusion_start, inclusion_stop,
  • device_add, device_remove,
  • endpoint_add,
  • attribute_add, attribute_change
  • command_add,
  • action_exec,
  • event_fire

by a device:

  • endpoint_add,
  • cluster_add,
  • attribute_add, attribute_change,
  • command_add,
  • value_add, value_remove, value_changed,
  • action_add, action_remove, action_exec,
  • event_add, event_remove,
  • device_remove

by a value:

value_change

by an attribute:

attribute_change

by a command:

command_exec

Clone this wiki locally