<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

Note:

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

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

[
    {
        "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

Unicast

Broadcast

Multicast

Failed Request

An example of a failed request.

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

References