Sending Commands

The NXP implementation of the ZCL provides functions for sending commands between an On/Off cluster client and server. A command is sent from the client to one or more endpoints on the server. Multiple endpoints can usually be targeted using binding or group addressing.

Switching On and Off

A remote device (supporting the On/Off cluster server) can be switched on, switched off or, toggled between the on and off states by calling the function eCLD_OnOffCommandSend() on a cluster client. In the case of a toggle, if the device is initially in the on state it is switched off and if the device is initially in the off state it is switched on.

Timeout on the ‘On’ Command

On receiving an ‘On’ command, a timeout is applied such that the ‘on’ state is maintained for a specified duration before automatically switching to the ‘off’ state. This timeout is defined using the optional attributes u16OnConfigurableDurationand eDurationUnitOfMeasurement. The timeout duration in seconds is given by:

u16OnConfigurableDuration * 10^(power from eDurationUnitOfMeasurement)

The attribute u16OnConfigurableDuration can be set locally or remotely, while the attribute eDurationUnitOfMeasurement must be set locally. A maximum timeout duration can be defined locally via the optional attribute u16MaxDuration, which puts an upper limit on the value of u16OnConfigurableDuration.

The attribute u16OnConfigurableDuration can be set remotely using the eZCL_SendWriteAttributesRequest() function. On receiving this write request, the local ZCL checks that the requested duration is within the permissible range (see Section 2.3.3.1) - if the request exceeds the maximum permitted value, the timeout duration is clipped to this maximum.

For full details of the above attributes, refer to Section 14.2.

When an ‘On’ command is received, an E_ZCL_CBET_CLUSTER_CUSTOM event is generated. The application is responsible for implementing the timeout described above, if it is enabled. First, the application must check the attributes u16OnConfigurableDuration and eDurationUnitOfMeasurement to make sure they have valid values. If so, the application must start a timer to implement the timeout for the duration defined by these attributes. On expiration of the timer, the application must switch from the ‘on’ state to the ‘off’ state by (locally) writing to the bOnOff attribute.

Parent topic:Switching On and Off

On/Off with Transition Effect

If the Level Control cluster (see Chapter 16) is also used on the target device, an ‘On’ or ‘Off’ command can be implemented with a transition effect, as follows:

  • If the optional Level Control ‘On Transition Time’ attribute is enabled, an ‘On’ command results in a gradual transition. This transition is from the ‘off’ level to the ‘on’ level over the time-interval specified by the attribute.

  • If the optional Level Control ‘Off Transition Time’ attribute is enabled, an ‘Off’ command results in a gradual transition from the ‘on’ level to the ‘off’ level over the time-interval specified by the attribute.

Parent topic:Switching On and Off

Parent topic:Sending Commands

Switching Off Lights with Effect

In the case of lighting, lights can be (remotely) switched off with an effect by calling the function eCLD_OnOffCommandOffWithEffectSend() on an On/Off cluster client.

Two ‘off effects’ are available and there are variants of each effect:

  • Fade, with the following variants:

    • Fade to off in 0.8 seconds (default)

    • Reduce brightness by 50 % in 0.8 seconds then fade to off in 4 seconds

    • No fade

  • Rise and fall, with (currently) only one variant:

    • Increase brightness by 20 % (if possible) in 0.5 seconds then fade to off in 1 second (default)

Parent topic:Sending Commands

Switching On Timed Lights

In the case of lighting, lights can be switched on temporarily and automatically switched off at the end of a timed period. This kind of switch-on can be initiated remotely using the function CLD_OnOffCommandOnWithTimedOffSend() on an On/Off cluster client. In addition, a waiting time can be implemented after the automatic switch-off, during which the lights cannot be switched on again using the above function (although a normal switch-on is possible).

The following values must be specified:

  • Time for which the lights remain on (in tenths of a second)

  • Waiting time following the automatic switch-off (in tenths of a second)

In addition, the circumstances in which the command can be accepted must be specified - that is, accepted at any time (except during the waiting time) or only when the lights are already on. The latter case can be used to initiate a timed switch-off.

Parent topic:Sending Commands

Parent topic:On/Off Cluster