Tutorial

This tutorial will show you how to build a ZigBee IoT network with zigbee-shepherd. Let's control your ZigBee devices and do something fun!

1. Hardware

Use CC2530 or CC2531 as the Coordinator.

Step1. Prepare your hardware

SmartRF05EB + CC2530EM
CC2531 USB Dongle

Step2. Connect your CC2530/31 to your PC

Connect to PC

Step3. Programming the SoC with ZNP image file

Download:

Programmer

2. How to use zigbee-shepherd?

1. Create a folder /zbserver and a server.js in it

$ mkdir zbserver && cd zbserver

/zbserver$ touch server.js

2. Install the `zigbee-shepherd` module in /zbserver folder

/zbserver$ npm install zigbee-shepherd

3. Edit server.js, Start ZigBee Server

[1] zigbee-shepherd usage

var ZShepherd = require('zigbee-shepherd');
var zserver = new ZShepherd('/dev/ttyACM0');

// see [1]
zserver.on('ready', function () {
    console.log('Server is ready.');
});

zserver.start(function (err) {
    if (err)
        console.log(err);
});

Note: If you don't know the system path of the serial port, install serialport globally, then use command line tool serialport-list to list all available serial ports.

$ npm install -g serialport

$ serialport-list
/dev/ttyACM0    usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B000106B6C5-if00   Texas_Instruments
/dev/ttyS0
/dev/ttyS1
...

4. Test the Server

/zbserver$ node server.js

5. Permit ZigBee devices join the network

var ZShepherd = require('zigbee-shepherd');
var zserver = new ZShepherd('/dev/ttyACM0');

// see [1]
zserver.on('ready', function () {
    console.log('Server is ready. Allow devices to join the network within 180 secs.');
    console.log('Waiting for incoming clients or messages...');
    zserver.permitJoin(180);
});

zserver.on('permitJoining', function (joinTimeLeft) {
    console.log(joinTimeLeft);
});

// see [2]
zserver.on('ind', function (msg) {
    switch (msg.type) {
        case 'devIncoming':
            console.log('Device: ' + msg.data + ' joining the network!');
            msg.endpoints.forEach(function (ep) {
                console.log(ep.dump());  // endpoint information
            });
            break;
        default:
            // Not deal with other msg.type in this example
            break;
    }
});

zserver.start(function (err) {
    if (err)
        console.log(err);
});

Run server.js and Let your ZigBee device join the network.

/zbserver$ node server.js

3. A simple application

In this section, we will use the GE LINK BULB A19 and OSRAM LIGHTIFY CLA60 to show you how to operate endpoint to simply build up a ZigBee application.

Target: Toggle the GE bulb, and you will receive the 'devChange' type indication of 'ind' event. Then operate the OSRAM bulb in the opposite status, namely GE on, OSRAM off and GE off, OSRAM on.

[1] zigbee-shepherd usage
[2] zserver 'ind' event and endpoint APIs
[3] ZCL functional command

var ZShepherd = require('zigbee-shepherd');
var zserver = new ZShepherd('/dev/ttyACM0');

// see [1]
zserver.on('ready', function () {
    console.log('Server is ready. Allow devices to join the network within 180 secs.');
    console.log('Waiting for incoming clients or messages...');
    zserver.permitJoin(180);
});

zserver.on('permitJoining', function (joinTimeLeft) {
    console.log(joinTimeLeft);
});

var geBulb,
    osramBulb,
    geBulbStatus,
    osramBulbStatus;

// see [2]
zserver.on('ind', function (msg) {
    switch (msg.type) {
        case 'devIncoming':
            console.log('Device: ' + msg.data + ' joining the network!');

            msg.endpoints.forEach(function (ep) {
                console.log(ep.dump());

                if (ep.devId === 544 && ep.clusters.has('genOnOff'))
                    osramBulb = ep;
                else if (ep.devId === 257 && ep.clusters.has('genOnOff'))
                    geBulb = ep;

                if (osramBulb && geBulb) {
                    setInterval(function () {
                        // see [3]
                        geBulb.functional('genOnOff', 'toggle', {}, function (err) {
                            if (!err)
                                console.log('GE BULB TOGGLE!');
                        });
                    }, 5000);
                }
            });
            break;

        case 'devChange':
            if (msg.endpoints[0].devId === 257) {
                geBulbStatus = msg.data.data.onOff;
                osramBulbStatus = !geBulbStatus ? 'on' : 'off';
                osramBulb.functional('genOnOff', osramBulbStatus, {}, function (err) {
                    if (!err)
                        console.log('OSRAM BULB ' + osramBulbStatus.toLowerCase() + '!');
                });
            }
            break;

        default:
            // Not deal with other msg.type in this example
            break;
    }
});

zserver.start(function (err) {
    if (err)
        console.log(err);
});

4. Installing Node.js on a Raspberry Pi 3

Install Node.js v4.7.0

$ wget https://nodejs.org/dist/v4.7.0/node-v4.7.0-linux-armv7l.tar.gz
$ tar -xvf node-v4.7.0-linux-armv7l.tar.gz
$ cd node-v4.7.0-linux-armv7l
$ sudo cp -R * /usr/local/