Send Public Profile Commands with the API
You can use the XBee API using the Explicit Transmit API frame (0x11) to send commands in public profiles such as Smart Energy and Home Automation. Sending public profile commands with the Explicit Transmit API frame requires some formatting of the data payload field. Most of the public profile commands fit into the Zigbee cluster library (ZCL) architecture as described in Send Zigbee cluster library (ZCL) commands with the API.
The following table shows how you can use the Explicit API frame to send a demand response and load control message (cluster ID 0x701) in the smart energy profile (profile ID 0x0109) in the revision 14 Smart Energy specification. The device sends a “Load Control Event”message (command ID 0x00) and to a device with 64- bit address of 0x0013A200 40401234 with a 16-bit address of 0x5678. The event starts a load control event for water heaters and smart appliances for a duration of 1 minute, starting immediately.
Note When sending public profile commands, set the AO command to 1 to enable the explicit receive API frame. This provides indication of the source 64- and 16-bit addresses, cluster ID, profile ID, and endpoint information for each received packet. This information is required to properly decode received data.
Frame specific data
| Frame Fields | Offset |
Description |
||
|---|---|---|---|---|
| Frame type | 3 | |||
| Frame ID | 4 | Identifies the serial port data frame for the host to correlate with a subsequent transmit status. If set to 0, no transmit status frame will be sent out the serial port. | ||
| 64-bit destination address | MSB 5 | The 64-bit address of the destination device (big endian byte order). For unicast transmissions, set to the 64-bit address of the destination device, or to 0x0000000000000000 to send a unicast to the coordinator. Set to 0x000000000000FFFF for broadcast. | ||
| 6 | ||||
| 7 | ||||
| 8 | ||||
| 9 | ||||
| 10 | ||||
| 11 | ||||
| LSB 12 | ||||
| 16-bit destination network address | MSB 13 | The 16-bit address of the destination device (big endian byte order). Set to 0xFFFE for broadcast, or if the 16-bit address is unknown. | ||
| LSB 14 | ||||
| Source endpoint | 15 | Set to the source endpoint on the sending device. (0x41 arbitrarily selected). | ||
| Destination endpoint | 16 | Set to the destination endpoint on the remote device. (0x42 arbitrarily selected). | ||
| Cluster ID | MSB 17 | Set to the cluster ID that corresponds to the ZCL command being sent. 0x0701 = Demand response and load control cluster ID | ||
| LSB 18 | ||||
| Profile ID | MSB 19 | Set to the profile ID supported on the device. 0x0109 = Smart Energy profile ID. | ||
| LSB 20 | ||||
| Broadcast radius | 21 | Sets the maximum number of hops a broadcast transmission can traverse. If set to 0, the transmission radius will be set to the network maximum hops value. | ||
| Transmit options | 22 | All bits must be set to 0. | ||
| Data payload | ZCL frame header | Frame control | 23 | Bitfield that defines the command type and other relevant information in the ZCL command. For more information, see the ZCL specification. |
| Transaction sequence number | 24 | A sequence number used to correlate a ZCL command with a ZCL response. (The hardware version response will include this byte as a sequence number in the response.) The value 0x01 was arbitrarily selected. | ||
| 25 | Since the frame control “frame type” bits are 01, this byte specifies a cluster-specific command. Command ID 0x00 in the Demand Response and Load Control cluster is a Load Control Event command. For more information, see the Smart Energy specification. | |||
| ZCL payload - load control event data | Issuer event ID | 26 |
The 4-byte unique identifier. Note The 4-byte ID is sent in little endian byte order (0x78563412). The event ID in this example (0x12345678) is arbitrarily selected. |
|
| 27 | ||||
| 28 | ||||
| 29 | ||||
| Device class | 30 |
This bit encoded field represents the Device Class associated with the Load Control Event. A bit value of 0x0014 enables smart appliances and water heaters. Note The 2-byte bit field value is sent in little endian byte order. |
||
| 31 | ||||
| Utility enrollment group | 32 | Used to identify sub-groups of devices in the device-class. 0x00 addresses all groups. | ||
| Start time | 33 | |||
| 34 | ||||
| 35 | ||||
| 36 | ||||
| Duration in minutes | 37 | This 2-byte value must be sent in little endian byte order. | ||
| 38 | ||||
| Criticality level | 39 | Indicates the criticality level of the event. In this example, the level is “voluntary”. | ||
| Cooling temperature | 40 |
Requested offset to apply to the normal cooling set point. A value of 0xFF indicates the temperature offset value is not used. |
||
| Heating temperature offset | 41 |
Requested offset to apply to the normal heating set point. A value of 0xFF indicates the temperature offset value is not used. |
||
| Cooling temperature set point | 42 |
Requested cooling set point in 0.01 degrees Celsius. A value of 0x8000 means the set point field is not used in this event. Note The 0x80000 is sent in little endian byte order.
|
||
| 43 | ||||
| Heating temperature set point | 44 |
Requested heating set point in 0.01 degrees Celsius. A value of 0x8000 means the set point field is not used in this event. Note The 0x80000 is sent in little endian byte order. |
||
| 45 | ||||
| Average load adjustment percentage | 46 | Maximum energy usage limit. A value of 0x80 indicates the field is not used. | ||
| Duty cycle | 47 | Defines the maximum “On” duty cycle. A value of 0xFF indicates the duty cycle is not used in this event. | ||
| Duty cycle event control | 48 | A bitmap describing event options. | ||
Example
In this example, the Frame Control field (offset 23) is constructed as follows:
| Name | Bits | Example Value Description |
|---|---|---|
| Frame Type | 0-1 | 01 - Command is specific to a cluster |
| Manufacturer Specific | 2 | 0 - The manufacturer code field is omitted from the ZCL Frame Header. |
| Direction | 3 | 1 - The command is being sent from the server side to the client side. |
| Disable Default Response | 4 | 0 - Default response not disabled |
| Reserved | 5-7 | Set to 0. |
For more information, see the Zigbee cluster library specification.
| Frame fields | Offset |
Example |
||
|---|---|---|---|---|
| Start delimiter | 0 | 0x7E | ||
| Length | MSB 1 | 0x00 | ||
| LSB 2 | 0x19 | |||
| Frame type | 3 | 0x11 | ||
| Frame ID | 4 | 0x01 | ||
| 64-bit destination address | MSB 5 | 0x00 | ||
| 6 | 0x13 | |||
| 7 | 0xA2 | |||
| 8 | 0x00 | |||
| 9 | 0x40 | |||
| 10 | 0x40 | |||
| 11 | 0x12 | |||
| LSB 12 | 0x34 | |||
| 16-bit destination network address | MSB 13 | 0x56 | ||
| LSB 14 | 0x78 | |||
| Source endpoint | 15 | 0x41 | ||
| Destination endpoint | 16 | 0x42 | ||
| Cluster ID | MSB 17 | 0x07 | ||
| LSB 18 | 0x01 | |||
| Profile ID | MSB 19 | 0x01 | ||
| LSB 20 | 0x09 | |||
| Broadcast radius | 21 | 0x00 | ||
| Transmit options | 22 | 0x00 | ||
| Data payload | ZCL frame header | Frame control | 23 | 0x09 |
| Transaction sequence number | 24 | 0x01 | ||
| 25 | 0x00 | |||
| ZCL payload - load control event data | Issuer event ID | 26 | 0x78 | |
| 27 | 0x56 | |||
| 28 | 0x34 | |||
| 29 | 0x12 | |||
| Device class | 30 | 0x14 | ||
| 31 | 0x00 | |||
| Utility enrollment group | 32 | 0x00 | ||
| Start time | 33 | 0x00 | ||
| 34 | 0x00 | |||
| 35 | 0x00 | |||
| 36 | 0x00 | |||
| Duration in Minutes | 37 | 0x01 | ||
| 38 | 0x00 | |||
| Criticality level | 39 | 0x04 | ||
| Cooling temperature | 40 | 0xFF | ||
| Heating temperature offset | 41 | 0xFF | ||
| Cooling temperature set point | 42 | 0x00 | ||
| 43 | 0x80 | |||
| Heating temperature set point | 44 | 0x00 | ||
| 45 | 0x80 | |||
| Average load adjustment percentage | 46 | 0x80 | ||
| Duty cycle | 47 | 0xFF | ||
| Duty cycle event control | 48 | 0x00 | ||
| Checksum | 49 | 0x5B | ||
PDF
