Structures

Custom Data Structure

The Scenes cluster requires extra storage space to be allocated to be used by internal functions. The structure definition for this storage is shown below:

typedef struct
{
    DLIST   lScenesAllocList;
    DLIST   lScenesDeAllocList;
    tsZCL_ReceiveEventAddress       sReceiveEventAddress;
    tsZCL_CallBackEvent             sCustomCallBackEvent;
    tsCLD_ScenesCallBackMessage     sCallBackMessage;
    tsCLD_ScenesTableEntry
           asScenesTableEntry[CLD_SCENES_MAX_NUMBER_OF_SCENES];
} tsCLD_ScenesCustomDataStructure;

The fields are for internal use and no knowledge of them is required.

Parent topic:Structures

Custom Command Payloads

The following structures contain the payloads for the Scenes cluster custom commands.

Add Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
    uint16                      u16TransitionTime;
    tsZCL_CharacterString       sSceneName;
    tsCLD_ScenesExtensionField  sExtensionField;
} tsCLD_ScenesAddSceneRequestPayload;

where:

u16GroupId is the group ID with which the scene is associated (0x0000 if there is no association with a group)
u8SceneId is the ID of the scene to be added to the Scene table (the Scene ID must be unique within the group associated with the scene)
u16TransitionTime is the amount of time, in seconds, that the device takes to switch to this scene
sSceneName is an optional character string (of up to 16 characters) representing the name of the scene
sExtensionField is a structure containing the attribute values of the clusters to which the scene relates

View Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesViewSceneRequestPayload;

where:

u16GroupId is the group ID with which the desired scene is associated
u8SceneId is the scene ID of the scene to be viewed

Remove Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesRemoveSceneRequestPayload;

where:

u16GroupId is the group ID with which the relevant scene is associated
u8SceneId is the scene ID of the scene to be deleted from the Scene table

Remove All Scenes Request Payload

typedef struct
{
    uint16                      u16GroupId;
} tsCLD_ScenesRemoveAllScenesRequestPayload;

where u16GroupId is the group ID for which all scenes are to be deleted.

Store Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesStoreSceneRequestPayload;

where:

u16GroupId is the group ID with which the relevant scene is associated
u8SceneId is the scene ID of the scene in which the captured cluster settings are to be stored

Recall Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesRecallSceneRequestPayload;

where:

u16GroupId is the group ID with which the relevant scene is associated
u8SceneId is the scene ID of the scene from which cluster settings are to be retrieved and applied

Get Scene Membership Request Payload

typedef struct
{
    uint16                      u16GroupId;
} tsCLD_ScenesGetSceneMembershipRequestPayload;

where u16GroupId is the group ID for which associated scenes are required.

Enhanced Add Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
    uint16                      u16TransitionTime100ms;
    tsZCL_CharacterString       sSceneName;
    tsCLD_ScenesExtensionField  sExtensionField;
} tsCLD_ScenesEnhancedAddSceneRequestPayload;

where:

u16GroupId is the group ID with which the scene is associated (0x0000 if there is no association with a group)
u8SceneId is the ID of the scene to be added to the Scene table (the Scene ID must be unique within the group associated with the scene)
u16TransitionTime100ms is the amount of time, in tenths of a second, that the device takes to switch to this scene
sSceneName is an optional character string (of up to 16 characters) representing the name of the scene
sExtensionField is a structure containing the attribute values of the clusters to which the scene relates

View Scene Request Payload

typedef struct
{
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesEnhancedViewSceneRequestPayload;

where:

u16GroupId is the group ID with which the desired scene is associated
u8SceneId is the scene ID of the scene to be viewed

Copy Scene Request Payload

typedef struct
{
    uint8       u8Mode;
    uint16      u16FromGroupId;
    uint8       u8FromSceneId;
    uint16      u16ToGroupId;
    uint8       u8ToSceneId;
} tsCLD_ScenesCopySceneRequestPayload;

where:

u8Mode is a bitmap indicating the required copying mode (only bit 0 is used):
- If bit 0 is set to ‘1’, then ‘copy all scenes’ mode is used, in which all scenes associated with the source group are duplicated for the destination group (and the scene ID fields are ignored)
- If bit 0 is set to ‘0’, then a single scene is copied
u16FromGroupId is the source group ID
u8FromSceneId is the source scene ID (ignored for ‘copy all scenes’ mode)
u16ToGroupId is the destination group ID
u8ToSceneId is the destination scene ID (ignored for ‘copy all scenes’ mode)

Parent topic:Structures

Custom Command Responses

The Scenes cluster generates responses to certain custom commands. The responses which contain payloads are detailed below:

Add Scene Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesAddSceneResponsePayload;

where:

eStatus is the outcome of the Add Scene command (success or invalid)
u16GroupId is the group ID with which the added scene is associated
u8SceneId is the scene ID of the added scene

View Scene Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
    uint8                       u8SceneId;
    uint16                      u16TransitionTime;
    tsZCL_CharacterString       sSceneName;
    tsCLD_ScenesExtensionField  sExtensionField;
} tsCLD_ScenesViewSceneResponsePayload;

where:

eStatus is the outcome of the View Scene command (success or invalid)
u16GroupId is the group ID with which the viewed scene is associated
u8SceneId is the scene ID of the viewed scene
u16TransitionTime is the amount of time, in seconds, that the device takes to switch to the viewed scene
sSceneName is an optional character string (of up to 16 characters) representing the name of the viewed scene
sExtensionField is a structure containing the attribute values of the clusters to which the viewed scene relates

Remove Scene Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesRemoveSceneResponsePayload;

where:

eStatus is the outcome of the Remove Scene command (success or invalid)
u16GroupId is the group ID with which the removed scene is associated
u8SceneId is the scene ID of the removed scene

Remove All Scenes Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
} tsCLD_ScenesRemoveAllScenesResponsePayload;

where:

eStatus is the outcome of the Remove All Scenes command (success or invalid)
u16GroupId is the group ID with which the removed scenes are associated

Store Scene Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
    uint8                       u8SceneId;
} tsCLD_ScenesStoreSceneResponsePayload;

where:

eStatus is the outcome of the Store Scene command (success or invalid)
u16GroupId is the group ID with which the stored scene is associated
u8SceneId is the scene ID of the stored scene

Get Scene Membership Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint8                       u8Capacity;
    uint16                      u16GroupId;
    uint8                       u8SceneCount;
    uint8                       *pu8SceneList;
} tsCLD_ScenesGetSceneMembershipResponsePayload;

where:

eStatus is the outcome of the Get Scene Membership command (success or invalid)
u8Capacity is the capacity of the Scene table of the device to receive more scenes - that is, the number of scenes that may be added (special values: 0xFE means that at least one more scene may be added, a higher value means that the remaining capacity of the table is unknown)
u16GroupId is the group ID to which the query relates
u8SceneCount is the number of scenes in the list of the next field
pu8SceneList is a pointer to the returned list of scenes from those queried that exist on the device, where each scene is represented by its scene ID

Enhanced Add Scene Response Payload

typedef struct
{
    zenum8     eStatus;
    uint16     u16GroupId;
    uint8      u8SceneId;
} tsCLD_ScenesEnhancedAddSceneResponsePayload;

where:

eStatus is the outcome of the Enhanced Add Scene command (success or invalid)
u16GroupId is the group ID with which the added scene is associated
u8SceneId is the scene ID of the added scene

Enhanced View Scene Response Payload

typedef struct
{
    zenum8                      eStatus;
    uint16                      u16GroupId;
    uint8                       u8SceneId;
    uint16                      u16TransitionTime;
    tsZCL_CharacterString       sSceneName;
    tsCLD_ScenesExtensionField  sExtensionField;
} tsCLD_ScenesEnhancedViewSceneResponsePayload;

where:

eStatus is the outcome of the Enhanced View Scene command (success or invalid)
u16GroupId is the group ID with which the viewed scene is associated
u8SceneId is the scene ID of the viewed scene
u16TransitionTime is the amount of time, in seconds, that the device takes to switch to the viewed scene
sSceneName is an optional character string (of up to 16 characters) representing the name of the viewed scene
sExtensionField is a structure containing the attribute values of the clusters to which the viewed scene relates

Copy Scene Response Payload

typedef struct
{
    uint8       u8Status;
    uint16      u16FromGroupId;
    uint8       u8FromSceneId;
} tsCLD_ScenesCopySceneResponsePayload;

where:

u8Status is the outcome of the Copy Scene command (success, invalid scene, or insufficient space for new scene)
u16FromGroupId is the source group ID for the copy
u8FromSceneId is the source scene ID for the copy

Parent topic:Structures

Scenes Table Entry

The following structure contains the data for a Scenes table entry (containing a saved scene):

typedef struct
{
    DNODE          dllScenesNode;
    bool           bActive;
    bool           bInTransit;
    uint16         u16GroupId;
    uint8          u8SceneId;
    uint16         u16TransitionTime;
    uint32         u32TransitionTimer;
    uint8          u8SceneNameLength;
    uint8          au8SceneName[CLD_SCENES_MAX_SCENE_NAME_LENGTH + 1];
    uint16         u16SceneDataLength;
    uint8          au8SceneData[CLD_SCENES_MAX_SCENE_STORAGE_BYTES];
#ifdef  CLD_SCENES_TABLE_SUPPORT_TRANSITION_TIME_IN_MS
    uint8          u8TransitionTime100ms;
#endif
} tsCLD_ScenesTableEntry;

where:

bActive is a boolean value indicating whether the scene is active (TRUE) or inactive (FALSE).
bInTransit is a boolean value indicating whether the scene is in a transitional state (TRUE) or a constant active/inactive state (FALSE).
u16GroupId is the identifier of the group to which the scene applies (the value 0x0000 is used to indicate that the scene is not associated with a group).
u8SceneId is the identifier of the scene and must be a unique value within the group with which the scene is associated.
u16TransitionTime is the length of time, in seconds, that the device takes to move from its current state to the scene state.
u32TransitionTimer is the elapsed time, in milliseconds, since the start of a currently active transition to the scene.
u8SceneNameLength is the number of characters in the name of the scene (and therefore the size of the array au8SceneName[] below). The value must not be greater than CLD_SCENES_MAX_SCENE_NAME_LENGTH, which is set in the compile-time options (see Section 13.9).
au8SceneName[] is an array containing the name of the scene, with one ASCII character in each array element. The number of elements in the array must be set in u8SceneNameLength above.
u16SceneDataLength is the number of items of data for the scene (and therefore the size of the array au8SceneData[] below). The value must not be greater than CLD_SCENES_MAX_SCENE_STORAGE_BYTES, which is set in the compile-time options (see Section 13.9).
au8SceneData[] is an array containing the data for the scene, with one data item in each array element. The data stored is dependent on the cluster to which the scene data applies. The number of elements in the array must be set in u16SceneDataLength above.
u8TransitionTime 100 ms is an optional that allows a fractional part to be added to the transition time (u16TransitionTime) of the scene. This value represents the number of tenths of a second in the range 0x00 to 0x09.

Parent topic:Structures

Parent topic:Scenes Cluster