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

Note:

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

Read Attribute

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
		...
	}
});

An Example JSON Results. (Notice it is a json array of one)

Results

[
    {
        "gatewayApiVersion":"2.0.13",
        "protocolName":"zigbee",
        "protocolVersion":3,
        "messageType":"zcl_response",
        "message":{
            "sourceNode":"0xCD22",
            "sourceEndpoint":"0x01",
            "localEndpoint":"0x01",
            "clusterId":"0x0000",
            "encryption":"0x00",
            "frameControl":"0x18",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x13",
            "commandId":"0x01",
            "payload":"0x0000002003"
        }
    }
]

Write Attribute

Write Attribute Example

ZigBeeDevice device = ...

int clusterID = 0x0000 // Basic Cluster
int attributeID = 0x0075 // random attribute with read/write access control
short dataType = 0x21 // UInt16
byte[] value = new byte[]{(btye)0x34, (byte)0x12}; // writing the value 0x1234, Little-Endian

CompletableFuture<Property> results = device.writeAttribute(clusterID, attributeID, dataType, value)
results.whenComplete((propertyResult, error) -> {
	if (error != null) {
		// handle error of computation
	} else {
		String jsonResults = propertyResult.getValue()
		...
		// parse results
		...
	}
});

Response

[
    {
        "gatewayApiVersion":"2.0.14-SNAPSHOT",
        "protocolName":"zigbee",
        "protocolVersion":3,
        "messageType":"zcl_response",
        "message":{
            "sourceNode":"0x4544",
            "sourceEndpoint":"0x01",
            "localEndpoint":"0x01",
            "clusterId":"0x0000",
            "encryption":"0x00",
            "frameControl":"0x18",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x11",
            "commandId":"0x04",
            "payload":"0x00" //success
        }
    }
]

Unicast

Unicast Example

Broadcast

Broadcast Example

Multicast

Multicast Example

Failed Requests

Default Response

If there is an error with the request, you will get a default response with a status code.

e.g Default Response, Status Code 0x01 (Failure).

Note: Status Code of 0x00 mean success

Failed Request

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

ZCL Response

For certain situations, you could receive a ZCL Response with a failure status

[
    {
        "gatewayApiVersion":"2.0.14",
        "protocolName":"zigbee",
        "protocolVersion":3,
        "messageType":"zcl_response",
        "message":{
            "sourceNode":"0x4544",
            "sourceEndpoint":"0x01",
            "localEndpoint":"0x01",
            "clusterId":"0x0000",
            "encryption":"0x00",
            "frameControl":"0x18",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x12",
            "commandId":"0x04",
            "payload":"0x869900"
        }
    }
]

Status Codes

Data Types

References

How to Send and Handle ZigBee Protocol Passthrough Messages