Zigate.Driver

features:

• communicates with the Zigate USB key using a serial port
• manages the opening/closing of the serial port
• can auto-detect the port to which the Zigate key is connected.
• has a set of commands that can be sent through the driver.send() function
• emits events for connexion/disconnexion & sending/reception of messages

instanciation:

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

let driver = new Zigate.Driver({
    log:          // (optional ; default='nolog') ; can be 'console', ...
    port:         // (optional ; default='')      ; can be '/dev/ttyUSBx', etc...)
    commandspath  // (optional ; default='node-zigate/commands') don't touch it until you know what you do
    responsespath // (optional ; default='node-zigate/responses') don't touch it until you know what you dodo)
});

• log can be a string for predefined console logs like (nolog,console,trace,debug,info,warn,error)

  cf. Logs for more information.

• port is the zigate USB port automatically opened right after the instanciation ; it is advised to not provide any port during instanciation, and make subsequent call to driver.open(port).

• commandspath is the folder in which all definitions of commands are stored ; by default it's the subfolder src/driver/commands of the module ; no need to touch it until you want to do specific stuff.

• responsespath is the folder in which all definitions of commands are stored ; by default it's the subfolder src/driver/responses of the module ; no need to touch it until you want to do specific stuff.

detect available Zigate ports:

The static function Driver.guessZigatePorts() returns a promis with a list of the ports of Zigate keys connected to the system.

sample use case:

const Zigate = require('node-zigate');
Zigate.Driver.guessZigatePorts()
  .then( (ports) => { 
    /* do something here with ports & their 'comName' attribute */
  });

returns something like:

[
  {
    "manufacturer": "Prolific Technology Inc.",
    "pnpId": "usb-Prolific_Technology_Inc._USB-Serial_Controller-if00-port0",
    "vendorId": "067b",
    "productId": "2303",
    "comName": "/dev/ttyUSB0"
  }
]

connect to the Zigate key:

open(port, callback)

• port is optional ; if no port provided (or empty string or 'auto'), the driver will make an attempt to auto-detect the zigate port. The auto-detection will choose the first USB key connected to the computed, which has the vendorId & ProductID of the Zigate key (vid=0x067b ; pid=0x2303).

• callback(error, driver) is optional ; if present, it will be called after connexion succeeded (err === undefined) or failed

driver.open(/* ... */) also returns a Promise, fullfilled if the connexion succeeded.

sample use case:

const Zigate = require('node-zigate');
let driver = new Zigate.Driver({ log:'console' });
driver.open()
  .then((driver) => {
    console.log("well connected to zigate key.");
  })
  .catch((err) => {
    console.error("error while connecting to zigate key: "+err);
  });

disconnect from the Zigate key:

driver.close(callback)

• callback(err) is optional ; in all casesn the method close() return a Promise, fullfilled if the connexion (was well opened) and has been successfully closed ; reject otherwise.

send a command

driver.send(command_name, command_parameters) sends a command to the zigate key

• command_name is a string (reset,start_network,devices_list, etc.). Full list of available commands can be gathered from the filename of the js files present in the subfolder 'src/driver/commands' (without the .js extension).

• command_parameters is an object containing parameters depending on the command itself. List of mandatory/optional parameters can be gathered from the files in in the subfolder 'src/driver/commands' (TODO: provide a complete list of commands & params)

• the function returns a promise which will be fullfilled with the response to that command. examples:

driver.send('channel_mask', {mask: 11}).then(response => { /* ... */);
driver.send('channel_mask', {mask: 11}).then(response => { /* ... */);
driver.send('devices_list').then(response => { /* ... */);
driver.send('permit_join', {duration: duration}).then(response => { /* ... */);
driver.send('descriptor_simple', {address: myDeviceAddress, endpoint:myDeviceEndpoint} )
// etc.

receive a response / notification

• When a response to a command is expected, the best way to retrieve it is to use the promise returned by driver.send(...). Example:

driver.send('version')
.then((response) => {
    console.log("version.major = " + response.major);
    console.log("version.installer = " + response.installer);
});

• To look for notifications initiated by the Zigate key without originating command, you should register to one of the following events emitted by the driver:

To listen to all responses/notifications received:

driver.on('response', (response) => {
  console.log('response received: '+response);
});

To listen to a specific type of response (example: 'version'):

driver.on('response_version', (response) => {
  console.log('response (version) received: '+response);
});

The Full list of available responses types can be gathered from the filename of the js files present in the subfolder 'src/driver/responses' (without the .js extension).

A response is an object which attributes depend on the response type itself. List of attributes can be gathered from the files in in the subfolder 'src/driver/responses' (TODO: provide a complete list of responses & attributes )

listen to events:

A Zigate.Driver instance is also an EventEmitter which throws the following events:

name	parameters	description
open	()	successfully connected to Zigate device
close	(port)	successfully disconnected from Zigate device
response	(response)	a response/notification has been received
response_xxx	(response)	a response/notification of type xxx has been received
command_started	(command, status)	a command has been sent (using driver.send()) status 'success' received
command_fullfilled	(command)	a command has been sent and status 'success' received
command_failed	(command, status)	a command has been sent and status 'failed' received
status_yyy	(status)	a status related to command of type yyy has been received
raw_out	(rawData)	(for debugging) raw data has been sent through serial port to zigate
raw_in	(rawData)	(for debugging) raw data has received through serial port from zigate
error	(err)	something bad happened (open error, corrupted frame received, unknown response received, underlying serial port error, etc.