ZCL library Documentation

Presentation

The ZCL library allows facilitating the development of application which interfaces with the Cleode UBee™ dongle.
It provides services for the following functionalities:

• Management and configuration of UBee.
• Reception of association events, update of Zigbee nodes.
• Reading of present Zigbee nodes in the network.
• Emission and reception of commands ZCL.
• Subscription to receive notifications of Zigbee nodes.
• Authorization of Zigbee nodes to be gone into the network.
• Creation and deletion of bindings between Zigbee nodes.
• Creation of groups and scenes on Zigbee nodes of the network.

Technical characteristics

The ZCL library is a dynamic library written in C++. It is useful in a multi-thread environment.
The developper never has to release the objects instantiated by the library.
It works on the following operating systems:

• Windows XP and more
• Linux 2.6.19 and more
• Max OSX and more
• Windows CE 6.0 and more

The library also contains a connector to interface with Java via JNI for Windows, Linux or Mac OSX operating systems.

First use

C++ example

The best way of implementing the ZCL library is to compile and to execute the "testZCL.cpp" file supplied with the CD.
This source file allows to understand by the example the use of the ZCL library.
It is a console application which shows in a simple way the use of the ZCL library.

• Subscribe to receive the events of Zigbee nodes which are already present in the network or which appear later.
• Start the communication with UBee dongle and discover the network if an UBee is detected on any port USB.
• List the Zigbee nodes present in the network.
• Send the different ZCL commands and display the responses.
• Tap 'h' to display the help menu.

Java example

The example in Java is a graphic application which displays in a table Zigbee nodes discovered on the network and below the notifications received from these Zigbee nodes.
It is possible to change the description of location by double-clicking in the corresponding field and by validating by the "Return" key.
A double-click on the field "ModelIdentifier" of a ZPlug sends a "Toggle" command which allows to change the state of the ZPlug.

Installation steps

Copy the "licence.lic" file in the "test" directory.

• Windows
• Linux
• Mac OSX
• Java
  
  

Windows

1) Install the driver of the UBee dongle on the Windows computer.

Contact the support of CLEODE in case of problem.

2) Compile the example file "testZCL.cpp".

Copy the "testZCL.cpp" file in the "test" directory.

On Windows with MSVC ( MicroSoft Visual C++)

Copy the "zcl.dll" and "zcl.lib" files compiled by MSVC-x32 in the "test" directory.

cl /I..\Includes /EHsc /FeTestZCL.exe testZCL.cpp zcl.lib 

On Windows with GCC version < 4.0

Copy the "zcl.dll" file compiled by GCC-x32 in the "test" directory.

 g++ -I..\Includes -Wall -L. -lzcl -o TestZCL.exe testZCL.cpp

On Windows with GCC version >= 4.0

Copy the "zcl.dll" file compiled by GCC-x32 in the "test" directory.

 g++ -I..\Includes -Wall -Wl,--enable-auto-import -o TestZCL.exe testZCL.cpp -L. -lzcl\n

or

 g++ -I..\Includes -Wall -static-libgcc -static-libstdc++ -Wl,--enable-auto-import -o TestZCL.exe testZCL.cpp -L. -lzcl

3) Plug the UBee dongle on the USB port of the Windows computer.

Check on "Device Manager (Port COM et LPT)" dialog box, the presence of the UBee dongle as an "FDTI" USB Serial Port.

4) Run the console application by the following command :

 TestZCL.exe

If the UBee dongle is detected, the message below will be displayed :

 Ubee Started
 Tap 'q' to quit the program, 'h' for help

Otherwise, it will be the one below :

 Ubee NOT Started
 Tap 'q' to quit the program, 'h' for help

5) Associate a ZPLug and a ZRC in the Zigbee network

Push the switch on the UBee to allow ZRC and ZPlug to join the network for testing the whole of ZCL commands.

Linux

1) Install the driver of the UBee dongle on the Linux computer.

Contact the support of CLEODE in case of problem.

2) Compile the example file "testZCL.cpp".

Copy the "testZCL.cpp", "run.sh" and "libzcl.so" (compiled by GCC-x32) files in the "test" directory.

 g++ -I..\Includes -Wall -o TestZCL testZCL.cpp -L. -lzcl -lpthread

3) Plug the UBee dongle on the USB port of the Linux computer.

Check by the "dmesg" command that the UBee dongle is linked to a ttyUSBx.

4) Run the console application by the following command :

 ./run.sh

If the UBee dongle is detected, the message below will be displayed :

 Ubee Started
 Tap 'q' to quit the program, 'h' for help

Otherwise, it will be the one below :

 Ubee NOT Started
 Tap 'q' to quit the program, 'h' for help

5) Associate a ZPLug and a ZRC in the Zigbee network

Push the switch on the UBee to allow ZRC and ZPlug to join the network for testing the whole of ZCL commands.

Max OSX

1) Install the driver of the UBee dongle on the Max OSX computer.

Contact the support of CLEODE in case of problem.

2) Compile the example file "testZCL.cpp".

Copy the "testZCL.cpp", "run.sh" and "libzcl.dylib" (compiled by GCC-x64) files in the "test" directory.

 g++ -m64 -I../Includes -Wall -o TestZCL testZCL.cpp -L. -lzcl -lpthread

3) Plug the UBee dongle on the USB port of the Max OSX computer.

Check by the "dmesg" command that the UBee dongle is linked to a tty.usbserial.

4) Run the console application by the following command :

 ./run.sh

If the UBee dongle is detected, the message below will be displayed :

 Ubee Started
 Tap 'q' to quit the program, 'h' for help

Otherwise, it will be the one below :

 Ubee NOT Started
 Tap 'q' to quit the program, 'h' for help

5) Associate a ZPLug and a ZRC in the Zigbee network

Push the switch on the UBee to allow ZRC and ZPlug to join the network for testing the whole of ZCL commands.

Java

1) Install the driver of the UBee dongle on the Windows, Linux or Mac OSX computer.

Contact the support of CLEODE in case of problem.

2) Compile the example file "TestZCL.java".

Copy the "TestZCL.java" file in the "test" directory.

On Windows

Copy the "zcl-connector.jar" and "zcl.dll" (compiled by MSVC or GCC) files in the "test" directory.

javac -cp zcl-connector.jar TestZCL.java 

On Linux

Copy the "zcl-connector.jar" and "libzcl.so" files in the "test" directory.

javac -cp zcl-connector.jar TestZCL.java 

On Mac OSX

Copy the "zcl-connector.jar" and "libzcl.dylib" files in the "test" directory.

javac -cp zcl-connector.jar TestZCL.java 

3) Plug the UBee dongle on the USB port of the Max OSX computer.

On Windows

Check on "Device Manager (Port COM et LPT)" dialog box, the presence of the UBee dongle as an "FDTI" USB Serial Port.

On Linux

Check by the "dmesg" command that the UBee dongle is linked to a ttyUSBx.

On Mac OSX

Check by the "dmesg" command that the UBee dongle is linked to a tty.usbserial.

4) Run the graphic application by the following command

On Windows

java -cp .;zcl-connector.jar TestZCL 

On Linux or Mac OSX

java -Djava.library.path=. -cp .:zcl-connector.jar TestZCL 

5) Associate a ZPLug and a ZRC in the Zigbee network

Push the switch on the UBee to allow ZRC and ZPlug to join the network for testing the whole of ZCL commands.