The HA clusters command set encompasses the following ZCL clusters for common HA applications:
- On/Off
- Level Control
- Power Configuration
- Lock/Unlock Door (under development)
The mandatory commands associated with a given HA cluster are only made available if that cluster is first appended to the application endpoint configuration. For example, the On/Off State Update command will only become available to the Host after it configures an application endpoint with the On/Off server cluster.
- ( PH:0x012, SH:0x00 ) - On/Off State Update Command
- ( PH:0x012, SH:0x20 ) - Move to Level Command
- ( PH:0x012, SH:0x21 ) - Level Move Command
- ( PH:0x012, SH:0x22 ) - Level Step Command
- ( PH:0x012, SH:0x23 ) - Level Stop Command
- ( PH:0x012, SH:0x24 ) - Check Battery Attribute Command
- ( PH:0x012, SH:0x25 ) - Move To Level With On/Off Status
- ( PH:0x012, SH:0x60 ) - Lock Door Command
- ( PH:0x012, SH:0x61 ) - Unlock Door Command
( PH:0x012, SH:0x00 ) - On/Off State Update Command
The On/Off State Update command is sent by the Module to the Host on reception of a network command that modifies the On/Off attribute value on the given endpoint (i.e. that which supports the On/Off server cluster). The command contains the current On/Off state and indicates if it was updated by a local or remote source.
Payload for On/Off State Update Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application On/Off server cluster. |
1 | New On/Off State | 0x00 = Off |
2 | Local/Remote Source | It should be noted that this byte has been retained for backwards compatibility with the RapidHA application stream. Regardless of the source of change to the On/Off State attribute (Host vs. Network), this byte will always be reported as 0x00 (Local Source). 0x00 = Local Source |
Expected Host Action
The Host shall modify its hardware output appropriately based on the new On/Off state. For example, if the given device is a light switch and the command indicates a new state of “On” the switch should be turned on.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x20 ) - Move to Level Command
The Move to Level command is sent by the Module to the Host on reception of a Move to Level command from the network, targeted to an endpoint on which the application supports the Level Control server cluster.
Payload for Move to Level Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
1 | Level | The applied Level value, 0x00-0xFF. |
2,3 | Transition Time | Time taken to move to the new level, in tenths of a second, or as close to this as the device is able. If the Transition Time value is 0xFFFF then the time taken to move to the new level shall instead be determined by the OnOffTransitionTime attribute. If OnOffTransitionTime, which is an optional attribute, is not present, the device shall move to its new level as fast as it is able. If the device is not able to move at a variable rate, the Transition Time field may be disregarded. |
4 | With OnOff | Flag for withOnOff: |
Expected Host Action
The Host shall modify its hardware output appropriately based on the new Level. For example, if the given device is a dimmer, the Host shall dim the connected light to the light level corresponding to the given Level value. In this example, if the Host controls multiple dimmers on disparate endpoints, the change in Level should only be applied to the dimmer identified by the target Endpoint ID.
If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster. The CurrentLevel attribute must be set to the value given in the Level field of the command payload. If the Level field is non-zero, the OnOff attribute must be set to On. Otherwise, the Level field is zero and the OnOff attribute must be set to Off.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x21 ) - Level Move Command
The Level Move command is sent by the Module to the Host on reception of a Move command from the network, targeted to an endpoint on which the application supports the Level Control server cluster. The command conveys both the expected Direction and Rate of movement.
Payload for Level Move Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
1 | Direction | 0x00 = Up |
2 | Rate | The rate of movement, in units per second. |
3 | With OnOff | Flag for withOnOff: This flag determines whether the CurrentLevel and OnOff attributes are independent or linked. |
Expected Host Action
The Host shall modify its hardware output appropriately based on the given Direction and Rate of movement specified. The movement is not expected to stop until reception of a Level Stop command or until further movement is not possible (i.e. maximum or minimum Level reached).
If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x22 ) - Level Step Command
The Level Step command is sent by the Module to the Host on reception of a Step command from the network, targeted to an endpoint on which the application supports the Level Control server cluster. The command conveys both the expected direction of movement (up or down) and unit size of each step.
Payload for Level Step Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
1 | Step Mode | 0x00 = Up |
2 | Step Size | The unit size of each step. |
3,4 | Transition Time | Transition time in tenths of a seconds for each step. |
5 | With OnOff | Flag for withOnOff: This flag determines whether the CurrentLevel and OnOff attributes are independent or linked. |
Expected Host Action
The Host shall modify its hardware output appropriately based on the given Step Mode, Step Size and Transition Time specified. The movement is not expected to stop until reception of a Level Stop command or until further movement is not possible (i.e., maximum or minimum Level reached).
If the withOnOff flag is “True” the Host must update the CurrentLevel attribute of the Level Control server cluster and the OnOff attribute of the On/Off cluster.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x23 ) - Level Stop Command
The Level Stop command is sent by the Module to the Host on reception of a Stop command from the network, targeted to an endpoint on which the application supports the Level Control server cluster.
Payload for Level Stop Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
Expected Host Action
The Host shall stop all Level Control movement on the specified hardware endpoint.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x24 ) - Check Battery Attribute Command
The Check Battery Attribute command is sent from the Host to the Module which triggers the Module to check the battery voltage. The command has no payload. It is recommended that this command be called after updating the battery voltage attribute.
Effect on Receipt
Module responds with a Status Response. If the battery voltage is lower than the threshold voltage, an alarm will be sent out through the OTA client.
Status Response to Check Battery Attribute Command
Error Status | Description |
---|---|
Success | Module received the command and will start check if battery voltage is lower than threshold. |
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Host |
( PH:0x012, SH:0x25 ) - Move To Level With On/Off Status
The Move to Level with On/Off status command is sent by the Module to the Host whenever the Current Level and OnOff status change as a result of incoming Level Control cluster commands.
When the Module receives incoming Level Control cluster commands (Move to Level, Move, Step) over the air, it computes the changes to Current Level and OnOff, and send the result to Host. If the level change requires a transition (e.g. move from 0 to 100 in 5 seconds), the Module will send the Host a series of Move To Level With OnOff Status every 50ms til the end of the transition time. Thus, the Module takes care of the ZigBee cluster logic; Host only needs to modify the hardware output based on the changes.
Payload for Move to Level With On/Off Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Level Control server cluster. |
1 | Level | The applied Level value, 0x00-0xFF. |
2,3 | Transition Time | Unused |
4 | On/Off Status | 0x00 = OFF |
Expected Host Action
The Host shall modify its hardware output appropriately based on the new Level and new OnOff status. For example, if the given device is a dimmer, the Host shall dim the connected light to the light level corresponding to the given Level value. In this example, if the Host controls multiple dimmers on disparate endpoints, the change in Level should only be applied to the dimmer identified by the target Endpoint ID.
The Host is otherwise required to mirror the state indicated by the On/Off Status parameter on the physical device.
Example Payload
- (Indicating Level 100, Transition Time 0, On/Off Status ON) F1 12 25 BB 05 16 64 00 00 01 72 01 [RHAMoveToLevel]
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x60 ) - Lock Door Command
The Lock Door command is sent by the Module to the Host on reception of Lock command from the network (Lock Door, Toggle, Recall Scene, etc.). The command has no payload.
This command is under development.
Payload for Lock Door Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Door Lock server cluster. |
Expected Host Action
The Host shall lock the door and confirm the new Lock State by issuing the Lock Confirm command. If the Module times out while waiting for the Lock Confirm response from the Host, it will report a failure to the network device that issued the original Lock command.
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |
( PH:0x012, SH:0x61 ) - Unlock Door Command
The Unlock Door command is sent by the Module to the Host on reception of an Unlock command from the network (Unlock Door, Toggle, Recall Scene, etc.). The command has no payload.
This command is under development.
Payload for Unlock Door Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Endpoint ID | Endpoint ID of the application Door Lock server cluster. |
Expected Host Action
The Host shall unlock the door and confirm the new Lock State by issuing the Lock Confirm command. If the Module times out while waiting for the Lock Confirm response from the Host, it will report a failure to the network device that issued the original Unlock Door command.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Module |