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.


Definition at line 77 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

_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.


Definition at line 86 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

Typedef Documentation#

cc_supervision_status_t#

typedef enum _SUPERVISION_STATUS_ cc_supervision_status_t

Status of Supervision.


Definition at line 95 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

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.


Definition at line 122 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

Function Documentation#

CmdClassSupervisionReportSend#

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

CmdClassSupervisionReportSend.

Parameters
[in]tx_options

Transmit options of type zaf_tx_options_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.

[in]status

Supervision status.

[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


Definition at line 142 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CommandClassSupervisionGetAdd#

void CommandClassSupervisionGetAdd (ZW_SUPERVISION_GET_FRAME * pPayload)

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

Parameters
[inout]pPayload

pointer to supervision get payload

Used by Framework and should not be used be application.


Definition at line 156 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CommandClassSupervisionGetWrite#

void CommandClassSupervisionGetWrite (ZW_SUPERVISION_GET_FRAME * pbuf)

Generates payload for Supervision Get command.

Parameters
[inout]pbuf

Pointer to supervision get payload

Used by Framework and should not be used be application.


Definition at line 166 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CommandClassSupervisionGetSetPayloadLength#

void CommandClassSupervisionGetSetPayloadLength (ZW_SUPERVISION_GET_FRAME * pbuf, uint8_t payLoadlen)

Sets the payload length in a Supervision Get command.

Parameters
[in]pbuf

Pointer to supervision get payload

[in]payLoadlen

Payload length to be set.

Used by Framework when sending supervision-encapsulated frames


Definition at line 175 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CommandClassSupervisionGetGetPayloadLength#

uint8_t CommandClassSupervisionGetGetPayloadLength (ZW_SUPERVISION_GET_FRAME * pbuf)

Gets the length of encapsulated payload from the frame.

Parameters
N/Apbuf

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


Definition at line 185 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

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
N/ApArgs

parameters for the handler


Definition at line 26 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/cc_supervision_handlers.h

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
N/Astatus

the required status

N/Aduration

the required duration


Definition at line 35 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/cc_supervision_handlers.h

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


Definition at line 26 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/src/cc_supervision_config_api.h

Macro Definition Documentation#

CC_SUPERVISION_EXTRACT_SESSION_ID#

#define CC_SUPERVISION_EXTRACT_SESSION_ID
Value:
(properties)

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


Definition at line 54 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CC_SUPERVISION_ADD_SESSION_ID#

#define CC_SUPERVISION_ADD_SESSION_ID
Value:
(properties)

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


Definition at line 55 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CC_SUPERVISION_EXTRACT_MORE_STATUS_UPDATE#

#define CC_SUPERVISION_EXTRACT_MORE_STATUS_UPDATE
Value:
(status)

extract more status update field bit 7, CC SUPERVISION_REPORT


Definition at line 56 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CC_SUPERVISION_ADD_MORE_STATUS_UPDATE#

#define CC_SUPERVISION_ADD_MORE_STATUS_UPDATE
Value:
(status)

status values: {0,1}.

Set bit 7, CC SUPERVISION_REPORT


Definition at line 57 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CC_SUPERVISION_EXTRACT_STATUS_UPDATE#

#define CC_SUPERVISION_EXTRACT_STATUS_UPDATE
Value:
(status)

extract more status update field bit 7, CC SUPERVISION_GET


Definition at line 58 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h

CC_SUPERVISION_ADD_STATUS_UPDATE#

#define CC_SUPERVISION_ADD_STATUS_UPDATE
Value:
(status)

status values: {0,1}.

Set bit 7, CC SUPERVISION_GET


Definition at line 59 of file /mnt/raid/workspaces/ws.OEhokVcbw/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Supervision/inc/CC_Supervision.h