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

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
0x01 = On

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
0x01 = Remote 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 ContextSent By Host/Module
Network UpModule






( 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:
0x00 = False
0x01 = True

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 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 ContextSent By Host/Module
Network UpModule

( 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
0x01 = Down

2

Rate

The rate of movement, in units per second.
0xFF = Maximum Rate

3

With OnOff

Flag for withOnOff:
0x00 = False
0x01 = True

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 ContextSent By Host/Module
Network UpModule

( 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
0x01 = Down

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:
0x00 = False
0x01 = True

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 ContextSent By Host/Module
Network UpModule

( 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 ContextSent By Host/Module
Network UpModule






( 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 ContextSent By Host/Module
Network UpHost






( 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 IndexField NameNotes

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
0x01 = ON

The Host must mirror the received On/Off Status on the physical device.

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 ContextSent By Host/Module
Network UpModule






( 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 IndexField NameNotes

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 ContextSent By Host/Module
Network UpModule

( 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 IndexField NameNotes

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 ContextSent By Host/Module
All ContextsModule