Overview

This page describes how to develop against the Gateway API. It goes over the basics of initializing a GatewayClient object, and interacting with Device references.

Initializing GatewayClient

Initialize a GatewayClient by passing in a ConnectionInfo object, which contains details about what the connection type is (i.e. a zigbee uart port) and a string describing where to connect to it.

In the following example, we also pass in a lambda that will handle device events by simply printing them out. In a real application, you can replace this with your own event handling method, or an object that implements the DeviceEventListener interface.

Initializing GatewayClient

// example of a lambda implementation of the DeviceEventListener parameter.
final GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyS1"),
    (event) -> {
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID());
    }
);

Once constructed, the GatewayClient will automatically connect to the device, configure it as a Combined Interface, and form a network. Otherwise, on any failure, it will throw a GatewayConnectionException.

Scanning for Devices

To join a device to the network, you first have to open the permit join window on the GatewayClient.

The following example shows how to call "scanForDevices" on all known connections for a duration of 30 seconds. It also implements a callback displaying the status of the command. The expected result should be "NETWORK_OPEN".

Scanning for Devices (i.e. opening the permit join window)

for (ConnectionInfo c: gw.getConnectionInfo()) {
    gw.scanForDevices(c, 30).thenAccept( status -> {
        System.out.println("Status for connection " + c.getValue() + " is " + status);
    });
}

Once the permit join window is open, you can initiate the pairing process from a secondary (i.e. remote) device.

Note: You can close the permit join window by calling "scanForDevices" with 0 as the "duration" parameter.

Interacting with Devices

When a device joins the network, you should see a DeviceEvent. For example, the lambda we passed into GatewayClient should print something like the following:

Device Event: ADD
Device ID: 00244600000f1472_1

Getting Properties

getProperties()

You can use the Device API to request properties of the connected device.

For example, to automatically discover the properties of a device the first time the GatewayClient becomes aware of it, you can run the following code from the DeviceEventListener callback:

Discovering Properties

if (event.getStatus() == DeviceEventStatus.ADD) {
    final Collection<Property> properties = event.getDevice().getProperties();
    for (Property p : properties) {
        System.out.println("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
    }
}

getProperty()

You can also get specific properties using the getProperty() method. For example, to get the "OnOff" property from a LightDevice, you could do something like the following:

Get a Property

final Property p = device.getProperty("OnOff").getFuture().get(5, TimeUnit.SECONDS);
System.out.println("name: " + p.getName() + ", value: " + p.getValue());

Updating Properties

You can update a Device Property by providing the name and value.

For example, to update the "OnOff" property, you could do something like the following:

Updating a Property

Property property = new Property("OnOff, "boolean", "true");
gw.getDevice(id).updateProperty(property);

LightDevice

The Gateway API will return a specific type of class for certain devices. Specific device classes, such as LightDevice, will have their own convenience methods that allow you to skip using the getProperty/updateProperty API's.

For example, for a LightDevice, you could interact with it as follows:

LightDevice API

final Device d = gw.getDevice(id);
if (d instanceof LightDevice) {
    final LightDevice light = (LightDevice) d;
    light.off();
    light.on();
	light.readLevel();
	light.moveToLevel(50);
} else {
    System.out.println("device is not a light");
}

See the LightDevice API for more info.

ThermostatDevice

The Gateway API will return a specific type of class for certain devices. Specific device classes, such as ThermostatDevice, will have their own convenience methods that allow you to skip using the getProperty/updateProperty API's.

For example, for a ThermostatDevice, you could interact with it as follows:

ThermostatDevice API

final Device d = gw.getDevice(id);
if (d instanceof ThermostatDevice) {
	final ThermostatDevice device = (ThermostatDevice) d;
	device.readMode();
	device.changeMode(SystemMode.AUTO);
} else {
	System.out.println("device is not a thermostat");
}

See the ThermostatDevice API for more info.

Conclusion

This programming guide has shown how to initialize a GatewayClient, join devices, get their properties, and interact with them in a simple way.

To explore further, please see the API documentation.

Programming Guide