eCLD_ScenesCommandStoreSceneRequestSend

teZCL_Status eCLD_ScenesCommandStoreSceneRequestSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_ScenesStoreSceneRequestPayload
*psPayload);

Description

This function sends a Store Scene command to request that the target device saves the current settings of all other clusters on the device as a scene - that is, adds a scene containing the current cluster settings to the Scene table. The entry is stored using the scene ID and group ID specified in the payload of the command. If an entry exists with these IDs, its existing cluster settings are overwritten with the new settings.

Note that this command does not set the transition time and scene name fields (or for a new entry, they are set to null values). If this command is to create a new scene that requires particular settings for these fields, Add Group command should be used. The scene entry must be created in advance using the Add Group command, and the fields transition time and scene name should be pre-configured.

The device receiving this message generates a callback event on the endpoint on which the Scenes cluster was registered. If the request is sent to a single device (rather than to a group address), it then generates an appropriate Store Scene response indicating success, or failure (see Section 13.7.3).

You are required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Parameters

  • u8SourceEndPointId: ID or number of the local endpoint through which to send the request. This parameter is used both to send the message and to identify the instance of the shared structure holding the required attribute values.

  • u8DestinationEndPointId: ID or number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP.

  • psDestinationAddress: Pointer to a structure holding the address of the node to which the request is sent.

  • pu8TransactionSequenceNumber: Pointer to a location to receive the Transaction Sequence Number (TSN) of the request.

  • psPayload: Pointer to a structure containing the payload for this message (see Section 13.7.2).

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_F

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions