This guide will show you how to complete a CLI-driven demo of Gateway API's zigbee features. After reviewing these steps, you will be able to form a zigbee network and communicate with third-party zigbee devices.

You'll need:

1. RapidConnect Gateway loaded with RapidConnect v3.0.8 or higher and the latest Gateway API Standalone JAR. Both of these should be pre-loaded by MMB.

You'll need:

1. macOS, Windows, or Linux environment that can run Java.

2. Java Runtime Environment, recommended version 1.8.

3. Latest release of the Gateway API Standalone JAR, which is available here.

4. RapidConnect USB Stick loaded with RapidConnect v3.0.8 or higher.

5. Install the driver for the RapidConnect USB Stick. It is available under the heading "Step 1: Install Hardware Drivers" here.

In general, a runnable JAR file can be executed as follows:

The example commands below show how to execute the GAPI Sample Application in various scenarios.

The GAPI Sample Application is pre-loaded on each RapidConnect Gateway unit.

To exercise its features, start by connecting the gateway to your LAN.

Next, follow the instructions in to establish an SSH connection to the gateway.

You can now execute the GAPI Sample Application using the following command (replacing the name of the JAR file with the correct name):

Enter the serial port:

After opening a terminal application and navigating to the folder where you have placed the Sample App JAR file, enter the following command:

When prompted to enter a serial port, enter the correct path to access the RapidConnect hardware from your Mac or Linux Machine. Usually, this will be the following path:

After opening a command prompt and navigating to the folder where you have placed the Sample App JAR file, enter the following command:On a Windows PC Connected to a RapidConnect USB Stick or Development Board

When prompted to enter a serial port, enter the correct COM Port number corresponding to the RapidConnect hardware (e.g. "COM1").

After you have completed the steps shown above, the Sample App will instantiate a GatewayClient object, which will automatically connect to the RapidConnect hardware, configure it as a "Combined Interface" Zigbee device, and form a network. Once this has happened, you can type 'h' to see a list of commands:

When the GatewayClient is instantiated, it will automatically form a network on the best available channel.

Type 'p' to open the Permit Join Window for 30 seconds.

To join a device, ensure that you have followed its commissioning process (e.g. specific sequence of button presses). Take note of the device ID when it connects. If you don't have any devices available, you can use RapidConnect Desktop to configure a unit of RapidConnect hardware as a Dimmable Light, and then Join the Network after you've opened the Permit Join window on the GatewayClient.

You can always type 'd' to get a list of all connected devices and their ID's, types, and device categories that they belong to.

You can also filter by specific device type, such as Dimmable Light, Thermostat, etc.

When a Device joins the network, only minimal properties are known about it. Users of the API must specifically request certain properties from the remote device before they can interact with them further (such as binding, or configuring reporting, etc).

There are two ways of doing so: 1) discovering all the properties on the remote device, or 2) reading specific properties on the remote device on an as-needed basis.

Type 'discoverAll', and enter the Device ID from above to trigger a read of the all the properties of the remote device. Note that this can be slow if the remote device has many properties, and/or is a sleepy end-device. This method typically wouldn't be called more than once, if at all, in a production application.

In the case of a Light device, this is what you would see.

In order to avoid requesting all the properties of a device (which can be slow) you can request specific properties by using 'getProperty'. If a specific property doesn't exist on the remote device, you will simply get an error. If a property does exist, it will be added to the known list of Property objects for the Device, returned to the application, and its last known value will be cached.

Once Properties have been discovered or read at least once, the Device will store a list of them, as well as their last known values.

You can also get the last known (cached) value of a specific property

Once Properties have been discovered or read at least once, the Device will store a list of them and their last known values. To refresh the known list of Properties and get their values from the remote device, you can use 'getProperty' or 'getProperties'.

This concludes the basic GatewayClient API demo. To use the sample CLI application to interact with Devices, see the Device API section below.

Note that this API is currently under active development and subject to change.

The Device API consists of a "Generic API", as well as a "Device Specific API".

The Generic API is intended to give users access to the underlying protocol, while the Device Specific API (for example LightDevice, or ThermostatDevice) is intended to abstract away the details of the underlying protocol and offer a simpler interface for controlling devices.

If the remote device is a zigbee device, you can use the 'getProperty' and 'updateProperty' methods, using the name of the zigbee attribute itself. See Zigbee Attribute Names for a full list of attribute names that can be used with the API.

Here's an example using the "IdentifyTime" attribute:

The Protocol Properties API is intended to give users access to the underlying protocol. It uses JSON strings as the primary means of communicating with the underlying protocol.

For example, properties for zigbee devices are passed through as JSON strings. Each Cluster property contains all of its attributes and their values.

Type 'getProtocolProperties' and then enter the Device ID from above to trigger a read of the properties of the remote device. This is only intended to be used to speak to devices that don't have a device-specific API (see below).

Properties for zigbee devices are passed through as JSON strings. Each Cluster property contains all known (i.e. discovered or read at least once) attributes and their values.

This can be used to update a specific property, by specifying the property name and value.

A property update takes an array of JSON objects. For zigbee devices, each JSON object is a "write attribute record" consisting of an attributeId (in LSB bytes), a type, and a byte string.

A request to get a property requires only the property name. 

For zigbee devices, this will return the Cluster property, which contains an array of all its attributes and values.

Note that this API is currently under active development and subject to change.

The LightDevice API is a "Device Specific API" which is intended to abstract the underlying protocol of the device, and present a high-level interface for interacting with Lights.

There are only two properties at the time of writing: OnOff, and CurrentLevel (for a Dimmable Light).

The device-specific API 'getProperties' will return any properties that have been defined for the device. For a Light, it would look like the following:

Note that if no properties have been discovered or read at least once, any call to 'getProperties' will return an empty list. For more details, see the API documentation for getProperties().

'getProperty' uses the name of the Property to return its current value.

'updateProperty' sets a new property value.

LightDevice contains a convenience method to configure the OnOff and Level properties to report any changes to the GatewayClient. You can enable reporting as follows:

Now, any registered PropertyUpdateListeners will be called when the OnOff or Level Property on the remote device changes. The Sample App, by default, will print updates to the console.

LightDevice contains some specific convenience methods, allowing users to interact with properties above from a method call instead of directly updating the properties themselves.

• on()

• off()

• moveToLevel(int)

• moveToLevel(int,int)

See the LightDevice API documentation for more details.

Note that this API is currently under active development and subject to change.

The ThermostatDevice API is a "Device Specific API" which is intended to abstract the underlying protocol of the device, and present a high-level interface for interacting with Thermostats.

The device-specific API 'getProperties' will return any properties that have been discovered for the device. For a Thermostat, it would look like the following:

Note that if no properties have been discovered or read at least once, any call to 'getProperties' will return an empty list. For more details, see the API documentation for getProperties().

'getProperty' uses the name of the Property to get its current value.

'updateProperty' sets a new value.

ThermostatDevice contains a convenience method to configure the Local Temperature property to report any changes to the GatewayClient. You can enable reporting as follows:

Now, any registered PropertyUpdateListeners will be called when the Local Temperature Property on the remote device changes. The Sample App, by default, will print updates to the console.

Change the mode of the Thermostat

This tutorial has demonstrated how to use the Gateway API to instantiate a GatewayClient, form a network, and control a remote Device. Now that we've performed a simple demo, we can begin to explore the API in more detail and write an application that makes use of the GatewayClient. See the pages below for more information.

• API

• GatewayClient

• Device

• ZigbeeDevice

• LightDevice

• ThermostatDevice

• Zigbee Attribute Names

• Basic Initialization

The SimpleCli.java file contains the source code for the above CLI demonstration. It shows how to instantiate the GatewayClient object, and interact with Device, ThermostatDevice, and LightDevice objects.

1. Download and unzip the sample project: Downloads

2. Open Eclipse

3. Go to File → Import

4. Expand the 'General' folder and select 'Existing Projects into Workspace' from the list

5. Browse to the project folder and select it, then finish importing the project.

6. To run the project, right click the 'gateway-sampleapp.launch' configuration file from the 'Project Explorer' view, and select Run As → gateway-sampleapp

   1. The project takes an optional argument to know which serial port to connect to, or it can be provided at runtime.

The SimpleCli.java file contains the entry point to the program and starts a simple command line interface. Its purpose is to exercise the Gateway API.

You can export the project to a runnable standalone JAR file, which can be run on a Linux, macOS, or Windows platform, by following these steps:

1. Right-click the project in Eclipse, and select "Export...".

2. Select "Runnable JAR".

3. Choose Launch Configuration "gateway-sampleapp".

4. Select an Export Destination.

5. For the Library Handling option, ensure that "Extract required libraries into generated JAR" is selected.

6. Click Finish.