Supervision#

Description#

CC Supervision is built into the Application Framework and handles Supervision communication on S2 encapsulated frames. Supervision is only supported for Set and Report commands.

Command Class Supervision is default configuration to not support more Supervision reports on a Supervision Get command. In Supervision Get command is 'more status updates' field set to CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED.

Default configuration#

The default setting is that CC Supervision supports only one Supervision Report per Supervision Get command. In Supervision Get command, the 'more status updates' field is set to CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED.

Handle more Supervision Reports#

Device has the possibility to inform destination node that there is an operation in progress. Example is Wall controller with a display showing that a device is working (CC_SUPERVISION_STATUS_WORKING) until target value is reached (CC_SUPERVISION_STATUS_SUCCESS). Please see cc_supervision_report_recived_handler() for more details.

Control Supervision Reports#

Device has the possibility to send more Supervision Reports to report ongoing Request job. Example application Doorlock Keypad reports when Doorlock operation is started and also sends a new report when it's finished. For this purpose, cc_supervision_get_received_handler() can be used. Please see cc_supervision_get_received_handler() for more details.

Modules#

SUPERVISION_GET_RECEIVED_HANDLER_ARGS

_cc_supervision_report_event

Supervision Events

Enumerations#

enum

cc_supervision_more_status_updates_t {

CC_SUPERVISION_MORE_STATUS_UPDATES_THIS_IS_LAST

CC_SUPERVISION_MORE_STATUS_UPDATES_REPORTS_TO_FOLLOW

}

Enum type is used in CC SUPERVISION_REPORT to allow a receiving node to advertise application status updates in future Supervision Report Commands.

enum

_SUPERVISION_STATUS_ {

CC_SUPERVISION_STATUS_NOT_SUPPORTED

CC_SUPERVISION_STATUS_WORKING

CC_SUPERVISION_STATUS_FAIL

CC_SUPERVISION_STATUS_CANCEL

CC_SUPERVISION_STATUS_NOT_FOUND

CC_SUPERVISION_STATUS_SUCCESS = 0xFF

}

Status of Supervision.

Typedefs#

typedef enum _SUPERVISION_STATUS_

cc_supervision_status_t

Status of Supervision.

typedef struct _cc_supervision_report_event

cc_supervision_report_event

Structure used by supervision_event_handler() to process upcoming events Registered for CC Supervision.

Functions#

bool

CmdClassSupervisionReportSend(zaf_tx_options_t *tx_options, uint8_t properties, cc_supervision_status_t status, uint8_t duration)

CmdClassSupervisionReportSend.

void

CommandClassSupervisionGetAdd(ZW_SUPERVISION_GET_FRAME *pPayload)

Creates payload for Supervision Get command by calling CommandClassSupervisionGetWrite and updates supervision session ID.

void

CommandClassSupervisionGetWrite(ZW_SUPERVISION_GET_FRAME *pbuf)

Generates payload for Supervision Get command.

void

CommandClassSupervisionGetSetPayloadLength(ZW_SUPERVISION_GET_FRAME *pbuf, uint8_t payLoadlen)

Sets the payload length in a Supervision Get command.

uint8_t

CommandClassSupervisionGetGetPayloadLength(ZW_SUPERVISION_GET_FRAME *pbuf)

Gets the length of encapsulated payload from the frame.

void

cc_supervision_get_received_handler(SUPERVISION_GET_RECEIVED_HANDLER_ARGS *pArgs)

Invoked upon reception of a Supervision Get This function is weakly defined in CC_Supervision.c and can be defined in the application if desired.

void

cc_supervision_report_recived_handler(cc_supervision_status_t status, uint8_t duration)

Invoked upon reception of a Supervision Report This function is weakly defined in CC_Supervision.c and can be defined in the application if desired.

bool

cc_supervision_get_default_status_updates_enabled()

Returns whether transmission of status updates is enabled or disabled by default.

Macros#

#define

CC_SUPERVISION_EXTRACT_SESSION_ID (properties)

extract session id from properties bits [0..5]

#define

CC_SUPERVISION_ADD_SESSION_ID (properties)

add session id from properties bits [0..5]

#define

CC_SUPERVISION_EXTRACT_MORE_STATUS_UPDATE (status)

extract more status update field bit 7, CC SUPERVISION_REPORT

#define

CC_SUPERVISION_ADD_MORE_STATUS_UPDATE (status)

status values: {0,1}.

#define

CC_SUPERVISION_EXTRACT_STATUS_UPDATE (status)

extract more status update field bit 7, CC SUPERVISION_GET

#define

CC_SUPERVISION_ADD_STATUS_UPDATE (status)

status values: {0,1}.

Enumeration Documentation#

cc_supervision_more_status_updates_t#

cc_supervision_more_status_updates_t

Enum type is used in CC SUPERVISION_REPORT to allow a receiving node to advertise application status updates in future Supervision Report Commands.

Enumerator
CC_SUPERVISION_MORE_STATUS_UPDATES_THIS_IS_LAST	CC_SUPERVISION_MORE_STATUS_UPDATES_THIS_IS_LAST.
CC_SUPERVISION_MORE_STATUS_UPDATES_REPORTS_TO_FOLLOW	CC_SUPERVISION_MORE_STATUS_UPDATES_REPORTS_TO_FOLLOW.

_SUPERVISION_STATUS_#

_SUPERVISION_STATUS_

Status of Supervision.

Enumerator
CC_SUPERVISION_STATUS_NOT_SUPPORTED	SUPERVISION_STATUS_NOT_SUPPORTED.
CC_SUPERVISION_STATUS_WORKING	SUPERVISION_STATUS_WORKING.
CC_SUPERVISION_STATUS_FAIL	SUPERVISION_STATUS_FAIL.
CC_SUPERVISION_STATUS_CANCEL	CC Supervision shouldn't do anything with this frame, report will be sent from somewhere else.
CC_SUPERVISION_STATUS_NOT_FOUND	CC handler was not found in CC handler map.
CC_SUPERVISION_STATUS_SUCCESS	SUPERVISION_STATUS_SUCCESS.

Typedef Documentation#

cc_supervision_status_t#

typedef enum _SUPERVISION_STATUS_ cc_supervision_status_t

Status of Supervision.

cc_supervision_report_event#

typedef struct _cc_supervision_report_event cc_supervision_report_event

Structure used by supervision_event_handler() to process upcoming events Registered for CC Supervision.

Function Documentation#

CmdClassSupervisionReportSend#

bool CmdClassSupervisionReportSend (zaf_tx_options_t * tx_options, uint8_t properties, cc_supervision_status_t status, uint8_t duration)

CmdClassSupervisionReportSend.

Parameters

Type	Direction	Argument Name	Description
zaf_tx_options_t *	[in]	tx_options	Transmit options of type zaf_tx_options_t
uint8_t	[in]	properties	includes: bit[0..5] Session ID bit[6] unused and bit[7] more status updates. This field is used to advertise if more Supervision Reports follow for the actual Session ID. [0] last report, [1] more report follow.
cc_supervision_status_t	[in]	status	Supervision status.
uint8_t	[in]	duration	The duration must comply with the following: 0x00 0 seconds. (Already at the Target Value.) 0x01-0x7F 1 second (0x01) to 127 seconds (0x7F) in 1 second resolution. 0x80-0xFD 1 minute (0x80) to 126 minutes (0xFD) in 1 minute resolution. 0xFE Unknown duration 0xFF Reserved

Returns

true if the frame was enqueued else false

CommandClassSupervisionGetAdd#

void CommandClassSupervisionGetAdd (ZW_SUPERVISION_GET_FRAME * pPayload)

Creates payload for Supervision Get command by calling CommandClassSupervisionGetWrite and updates supervision session ID.

Parameters

Type	Direction	Argument Name	Description
ZW_SUPERVISION_GET_FRAME *	[inout]	pPayload	pointer to supervision get payload

Used by Framework and should not be used be application.

CommandClassSupervisionGetWrite#

void CommandClassSupervisionGetWrite (ZW_SUPERVISION_GET_FRAME * pbuf)

Generates payload for Supervision Get command.

Parameters

Type	Direction	Argument Name	Description
ZW_SUPERVISION_GET_FRAME *	[inout]	pbuf	Pointer to supervision get payload

Used by Framework and should not be used be application.

CommandClassSupervisionGetSetPayloadLength#

void CommandClassSupervisionGetSetPayloadLength (ZW_SUPERVISION_GET_FRAME * pbuf, uint8_t payLoadlen)

Sets the payload length in a Supervision Get command.

Parameters

Type	Direction	Argument Name	Description
ZW_SUPERVISION_GET_FRAME *	[in]	pbuf	Pointer to supervision get payload
uint8_t	[in]	payLoadlen	Payload length to be set.

Used by Framework when sending supervision-encapsulated frames

CommandClassSupervisionGetGetPayloadLength#

uint8_t CommandClassSupervisionGetGetPayloadLength (ZW_SUPERVISION_GET_FRAME * pbuf)

Gets the length of encapsulated payload from the frame.

Parameters

Type	Direction	Argument Name	Description
ZW_SUPERVISION_GET_FRAME *	N/A	pbuf	Frame that contains the encapsulated command

Used by framework to calculate the length of the payload in supervision-encapsulated frames.

Returns

length of the payload

cc_supervision_get_received_handler#

void cc_supervision_get_received_handler (SUPERVISION_GET_RECEIVED_HANDLER_ARGS * pArgs)

Invoked upon reception of a Supervision Get This function is weakly defined in CC_Supervision.c and can be defined in the application if desired.

Parameters

Type	Direction	Argument Name	Description
SUPERVISION_GET_RECEIVED_HANDLER_ARGS *	N/A	pArgs	parameters for the handler

cc_supervision_report_recived_handler#

void cc_supervision_report_recived_handler (cc_supervision_status_t status, uint8_t duration)

Invoked upon reception of a Supervision Report This function is weakly defined in CC_Supervision.c and can be defined in the application if desired.

Parameters

Type	Direction	Argument Name	Description
cc_supervision_status_t	N/A	status	the required status
uint8_t	N/A	duration	the required duration

cc_supervision_get_default_status_updates_enabled#

bool cc_supervision_get_default_status_updates_enabled ()

Returns whether transmission of status updates is enabled or disabled by default.

Used by the Supervion Command Class initialization

Returns

true if enabled, false if disabled