<Document under development>

Introduction

The GatewayAPI aims to abstract away the underlying protocol, i.e Zigbee, but there are instances where clients/users will want direct access to the underlying protocol. This document will describe how to send ZCL/ Unicast, Broadcast Messages, and Multicast Messages. This document will describe the message format of the request and response.

API

...

The ZigBeeDevice

• CompletableFuture<Property> readAttribute(int clusterId, int attributeId)
• CompletableFuture<Property> readAttribute(int clusterId, int attributeId, int manufacturerCode, boolean isServer)
• CompletableFuture<Property> writeAttribute(int clusterId, int attributeId, short dataType, byte[] value)
• CompletableFuture<Property> writeAttribute(int clusterId, int attributeId, short dataType, byte[] value, int manufacturerCode, boolean isServer)
• CompletableFuture<Property> sendZclCommand(short commandId, byte[] payload, int clusterId)
• CompletableFuture<Property> sendZclCommand(short commandId, byte[] payload, int clusterId)
• CompletableFuture<Property> sendZclCommand(short commandID, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean requiresResponse)
• CompletableFuture<Collection<Property>> sendZclMulticastCommand(int groupID, short commandID, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean requiresResponse)
• CompletableFuture<Collection<Property>> sendZclMulticastCommand(String broadcastAddress, short commandID, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean requiresResponse)

CompletableFuture

See The Official JavaDoc For CompletableFuture on basic usages

Property

Represents a Property of a device, or action. It contains the name, value, type, and various meta-data

...

Every property result will be of type: json, and the value being a json array.

Read Attribute

ZigBeeDevice lightDevice = ...

int clusterID = 0x0000 // Basic Cluster
int attributeID = 0x0000 // Version Attribute
CompletableFuture<Property> results = lightDevice.readAttribute(clusterID, attributeID)

results.whenComplete((propertyResult, error) -> {
	if (error != null) {
		// handle error of computation
	} else {
		String jsonResults = propertyResult.getValue()
		...
		// parse results
		...
	}
});

...

// example, toggle command for on/off

ZigBeeDevice device = ...

short commandId = 0x02;
byte[] payload = new byte[0]; // no payload for toggle
int clusterId = 0x0006; // on off cluster
int manufacturerCode = 0;
boolean isServer = true; // client to server (end device)
boolean isClusterSpecific = true;
boolean requiresResponse = false;

CompletableFuture<Property> results = device.sendZclCommand(commandId, payload, clusterId, manufacturerCode, isServer, isClusterSpecific, requiresResponse)
results.whenComplete((propertyResult, error) -> {
	if (error != null) {
		// handle error of computation
	} else {
		String jsonResults = propertyResult.getValue()
		...
		// parse results
		...
	}
});

The response if requiresResponse = true or false, this command will always yield a default response as there is no actual response for the toggle command as per spec

[
    {
        "gatewayApiVersion":"2.0.13",
        "protocolName":"zigbee",
        "protocolVersion":3,
        "messageType":"default_response",
        "message":{
            "status":"0x00"
        }
    }
]

...

{
    "gatewayApiVersion":"2.0.14-SNAPSHOT",
    "protocolName":"zigbee",
    "protocolVersion":3,
    "messageType":"default_response",
    "message":{
        "status":"0x00"
    }
}

A single JSON response to indicate the broadcast command was sent (status code of success: 0x00)

Example of Sending Toggle Command (0x02)

// example, toggle command for on/off

ZigBeeDevice device = ...
String broadcastAddress = "0xFD";
short commandId = 0x02;
byte[] payload = new byte[0]; // no payload for toggle
int clusterId = 0x0006; // on off cluster
int manufacturerCode = 0;
boolean isServer = true; // client to server (end device)
boolean isClusterSpecific = true;
boolean requiresResponse = false;

CompletableFuture<Collection<Property>> results = device.sendZclBroadcastCommand(broadcastAddresscommandId, payload, clusterId, manufacturerCode, isServer, isClusterSpecific, requiresResponse)
results.whenComplete((properties, error) -> {
	if (error != null) {
		// handle error of computation
	} else {
		for (Property property : properties) {
			String json = property.getValue();
			
			// parse json and handle result
		}
	}
});

...

The response will be a single property in the collection with a default response indicating the message has been sent due to the fact the toggle command has no response

// property value:
{
    "gatewayApiVersion":"2.0.14-SNAPSHOT",
    "protocolName":"zigbee",
    "protocolVersion":3,
    "messageType":"default_response",
    "message":{
        "status":"0x00"
    }
}

...

// example add group command

ZigBeeDevice device = ...
int groupID = 1;
short commandId = 0x02;
byte[] payload = new byte[0]; // no payload for toggle
int clusterId = 0x0006; // on off cluster
int manufacturerCode = 0;
boolean isServer = true; // client to server (end device)
boolean isClusterSpecific = true;
boolean requiresResponse = true;

CompletableFuture<Collection<Property>> results = device.sendZclMulticastCommand(groupID, payload, clusterId, manufacturerCode, isServer, isClusterSpecific, requiresResponse)
results.whenComplete((properties, error) -> {
	if (error != null) {
		// handle error of computation
	} else {
		for (Property property : properties) {
			String json = property.getValue();
			
			// parse json and handle result
		}
	}
});

...

If there is an error with the request, you will get a default response with a status code. This means the request failed to be sent in some way. This usually means that the message failed to be sent to the device, or if requiresResponse = false, a default response will be sent to the user/client instead of a ZCL Response

...