(Multi Channel) Association#

CC Association and CC Multi Channel Association enable application level control of other devices.

For instance, a wall switch can control an LED bulb if an association to the LED bulb is created in the wall switch. Another example could be a motion sensor that turns on an LED bulb when motion is detected. Such associations can be created using either Association Set or Multi Channel Association Set.

Both CCs share a common module that stores the actual associations.

The specifications of CC Association and CC Multi Channel Association can be found in https://github.com/Z-Wave-Alliance/AWG/tree/main/source/management_command_classes/command_class_definitions

Modules#

ASSOCIATION_GROUP

ASSOCIATION_GROUP_PACKED

SAssociationInfo

Enumerations#

enum
NODE_LIST_STATUS_SUCCESS = 0
NODE_LIST_STATUS_NO_MORE_NODES
NODE_LIST_STATUS_ASSOCIATION_LIST_EMPTY
NODE_LIST_STATUS_ERROR_LIST
NODE_LIST_STATUS_ERR_NO_TABLE_ENDPOINT
NODE_LIST_STATUS_ERR_UNKNOWN_PROFILE
NODE_LIST_STATUS_ERR_ENDPOINT_OUT_OF_RANGE
NODE_LIST_STATUS_ERR_GROUP_NBR_NOT_LEGAL
NODE_LIST_STATUS_ERR_LIFELINE_PROFILE_NOT_SUPPORTED
NODE_LIST_STATUS_ERR_LIFELINE_SUPPORT_NOT_CC_BASIC
NODE_LIST_STATUS_ERR_PROFILE_LIFELINE_ONLY_SUPPORT_IN_GRP_1
}

Enum type NODE_LIST_STATUS is used for return status on API call AGI_NodeIdListGetNext.

Typedefs#

Functions#

handleAssociationGetnodeList(uint8_t groupId, uint8_t ep, destination_info_t **ppListOfNodes, uint8_t *pListLen)

Delivers a list of nodes in a given association group corresponding to a given endpoint.

AssociationRemove(uint8_t groupId, uint8_t ep, ZW_MULTI_CHANNEL_ASSOCIATION_REMOVE_1BYTE_V2_FRAME *pCmd, uint8_t cmdLength)

Removes all nodes or given node(s) from all groups or a given group.

void
AssociationGet(uint8_t endpoint, uint8_t *incomingFrame, uint8_t *outgoingFrame, uint8_t *outgoingFrameLength)

Handles an incoming (Multi Channel) Association Get command and composes a (Multi Channel) Association Report.

bool
AssociationAddNode(uint8_t groupID, uint8_t endpoint, MULTICHAN_DEST_NODE_ID *pNode, bool multiChannelAssociation)

Associates a given node in the given group for a given endpoint.

void
AssociationGetDestinationInit(destination_info_t *pFirstDestination)

Initializes the fetching of nodes before e.g.

bool
AssociationGetBitAdressingDestination(destination_info_t **ppNodeList, uint8_t *pListLength, destination_info_t *pNode)

Outputs a node where associations to multiple endpoints of that node exist.

uint32_t

Returns the number of associations after the bit addressing destinations are removed.

Returns the address of the next association like an iterator.

uint8_t

Returns the number of endpoint destinations in the active node association list.

uint8_t

Returns the latest used association group.

ReqNodeList(AGI_PROFILE const *const pProfile, cc_group_t const *const pCurrentCmdGrp, const uint8_t sourceEndpoint)

Returns TX options containing a list of nodes found in the association group that matches the given AGI profile, command class / command pair and source endpoint.

handleAssociationSet(uint8_t ep, ZW_MULTI_CHANNEL_ASSOCIATION_SET_1BYTE_V2_FRAME *pCmd, uint8_t cmdLength, uint8_t commandClass)

Handler for Association Set command.

Macros#

#define
FREE_VALUE 0x00FF
#define

Invalid group ID.

#define

LIFELINE group ID.

#define

The only allowed endpoint of the Lifeline group!

#define
ZAF_FILE_SIZE_ASSOCIATIONINFO (sizeof(SAssociationInfo))

Enumeration Documentation#

NODE_LIST_STATUS#

NODE_LIST_STATUS

Enum type NODE_LIST_STATUS is used for return status on API call AGI_NodeIdListGetNext.

Enum types from NODE_LIST_STATUS_SUCCESS to NODE_LIST_STATUS_ERROR_LIST deliver status on the call and after NODE_LIST_STATUS_ERROR_LIST deliver an error identifiers pointing to a problem in application AGI/association configuarion.

Enumerator
NODE_LIST_STATUS_SUCCESS
NODE_LIST_STATUS_NO_MORE_NODES
NODE_LIST_STATUS_ASSOCIATION_LIST_EMPTY
NODE_LIST_STATUS_ERROR_LIST

enum values higher than this is error identifiers

NODE_LIST_STATUS_ERR_NO_TABLE_ENDPOINT
NODE_LIST_STATUS_ERR_UNKNOWN_PROFILE
NODE_LIST_STATUS_ERR_ENDPOINT_OUT_OF_RANGE
NODE_LIST_STATUS_ERR_GROUP_NBR_NOT_LEGAL
NODE_LIST_STATUS_ERR_LIFELINE_PROFILE_NOT_SUPPORTED
NODE_LIST_STATUS_ERR_LIFELINE_SUPPORT_NOT_CC_BASIC
NODE_LIST_STATUS_ERR_PROFILE_LIFELINE_ONLY_SUPPORT_IN_GRP_1

Definition at line 44 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

Typedef Documentation#

SAssociationInfo#

typedef struct SAssociationInfo SAssociationInfo

Definition at line 35 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_file.h

Function Documentation#

CC_Association_Init#

void CC_Association_Init (void )
Parameters
N/A

Remarks

  • Must be invoked by CC_Association.c only


Definition at line 74 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

CC_Association_Reset#

void CC_Association_Reset (void )
Parameters
N/A

Remarks

  • Must be invoked by CC_Association.c only


Definition at line 81 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

handleAssociationGetnodeList#

NODE_LIST_STATUS handleAssociationGetnodeList (uint8_t groupId, uint8_t ep, destination_info_t ** ppListOfNodes, uint8_t * pListLen)

Delivers a list of nodes in a given association group corresponding to a given endpoint.

Parameters
[in]groupId

Association group ID.

[in]ep

Endpoint.

[out]ppListOfNodes

is out double-pointer of type MULTICHAN_NODE_ID deliver node list

[out]pListLen

length of list

Returns

  • enum type NODE_LIST_STATUS


Definition at line 91 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationRemove#

e_cmd_handler_return_code_t AssociationRemove (uint8_t groupId, uint8_t ep, ZW_MULTI_CHANNEL_ASSOCIATION_REMOVE_1BYTE_V2_FRAME * pCmd, uint8_t cmdLength)

Removes all nodes or given node(s) from all groups or a given group.

Parameters
[in]groupId

Association group ID.

[in]ep

Multi Channel Endpoint.

[in]pCmd

Pointer to the command containing the node IDs to remove.

[in]cmdLength

Length of the command.

See Association CC and Multi Channel Association CC for details. Returns

  • command handler return code


Definition at line 108 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGet#

void AssociationGet (uint8_t endpoint, uint8_t * incomingFrame, uint8_t * outgoingFrame, uint8_t * outgoingFrameLength)

Handles an incoming (Multi Channel) Association Get command and composes a (Multi Channel) Association Report.

Parameters
[in]endpoint

The endpoint from which the associated nodes must be read.

[in]incomingFrame

The incoming frame including CC and command.

[out]outgoingFrame

The composed frame ready for transmission.

[out]outgoingFrameLength

The total length of the outgoing frame.


Definition at line 124 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationAddNode#

bool AssociationAddNode (uint8_t groupID, uint8_t endpoint, MULTICHAN_DEST_NODE_ID * pNode, bool multiChannelAssociation)

Associates a given node in the given group for a given endpoint.

Parameters
N/AgroupID

ID of the group in which the association must be made.

N/Aendpoint

Endpoint for which the association must be made.

N/ApNode

Pointer to a node with info about node ID, endpoint, etc.

N/AmultiChannelAssociation

Specifies whether the associated node ID includes an endpoint or not.

The endpoint argument specifies the local endpoint for which the association is made. E.g. if this device would be a Wall Controller/Switch with 4 endpoints, one for each switch, and an association was to be made for endpoint 1. The associated node would receive something when button 1 is pressed (if of course button one represents endpoint 1). Returns

  • true if association is added, false otherwise.


Definition at line 144 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGetDestinationInit#

void AssociationGetDestinationInit (destination_info_t * pFirstDestination)

Initializes the fetching of nodes before e.g.

Parameters
[in]pFirstDestination

Address of the first association in a group. Retrieved by invoking handleAssociationGetnodeList().

a transmission. It places a destination_node_list into the system.

MUST be invoked before AssociationGetBitAdressingDestination(), AssociationGetSinglecastNodeCount() and AssociationGetNextSinglecastDestination().


Definition at line 165 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGetBitAdressingDestination#

bool AssociationGetBitAdressingDestination (destination_info_t ** ppNodeList, uint8_t * pListLength, destination_info_t * pNode)

Outputs a node where associations to multiple endpoints of that node exist.

Parameters
[inout]ppNodeList

- Address of pointer to an element in the node list. The pointer will be updated as this function travels through the node list.

[inout]pListLength

- Pointer to length of the node list. The value will be updated by this function.

[out]pNode

- Address of the memory to where the node is written.

The pNode [OUT] (list) will contain all the endpoints using bit addressing, for endpoints equal or less than 7.

Operation: For the first encounter of a nodeID and an endpoint, this function will search for the same nodeID and add their endpoints to the endpoint-field as bit-flags. First time this function encounters a node without a valid endpoint for bit-addressing, it will terminate and return false because the list is sorted.

If there are zero nodes with multiple endpoints associated, the function will return false and write NULL to the pointer returned, pNode.

If further nodes with multiple endpoints associated exist after the initial list is created, the function will return true and indicate that this function is not finished.

If the function returns true, the invoker must invoke the function again to get the next node.

If there are no more nodes with multiple endpoints, the function will return false, as this function is only designed to return node-destinations with endpoints.

Example with 6 associations in total: (This is a pre-sorted list in accordance to requirements of this function!) 3.1 3.2 4.1 4.2 5.1 6.0

destination_info_t * pNodeList    // Must point to the first node in an association group.
uint8_t              listLength;  // Must be set to the length of the node list.
destination_info_t   node;
bool                 moreNodes;

moreNodes = AssociationGetBitAdressingDestination(&pNodeList, &listLength, &node);
// moreNodes is TRUE. (4.1 is still showing endpoint destination)
// pNodeList now points to node 4 endpoint 1.
// listLength now equals 4. (the two from the top with endpoints are removed from list)
// Bit-addressing is set to TRUE. (because 3.1 and 3.2 are bit-addressed)
// --> The prepared node contains the first nodeID (3) including the two endpoints as bit addressing.

moreNodes = AssociationGetBitAdressingDestination(&pNodeList, &listLength, &node);
// moreNodes is TRUE. (5.1 is still showing endpoint destination)
// pNodeList now points to node 5 endpoint 1.
// listLength now equals 2. (the four destinations from the top with endpoints are removed from list)
// Bit-addressing is set to TRUE. (because 4.1 and 4.2 are bit-addressed)
// --> The prepared node contains the second nodeID (4) including the two endpoints as bit addressing.

moreNodes = AssociationGetBitAdressingDestination(&pNodeList, &listLength, &node);
// moreNodes is FALSE. (6.0 is not having an endpoint destination)
// pNodeList now points to node 6 with no endpoints.
// listLength now equals 2. (the four destinations from the top remain the only removed from list)
// Bit-addressing is set to FALSE. (5.1 was the only endpoint destination of nodeID 5)
// // --> The prepared node is not good for multichannel TX with bit-addressing. This terminates multichannel TX.

// The nodeID 6 destination is not processed for multichannel transmissions due to how the list is sorted!

Returns

  • Returns true if this function needs to be called again for a different nodeID with endpoints, otherwise false.


Definition at line 236 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGetSinglecastNodeCount#

uint32_t AssociationGetSinglecastNodeCount (void )

Returns the number of associations after the bit addressing destinations are removed.

Parameters
N/A

This function MUST be invoked AFTER AssociationGetBitAdressingDestination() has returned false.

Returns

  • Returns the number of remaining nodes when there are no more bit addressing nodes.


Definition at line 247 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGetNextSinglecastDestination#

destination_info_t * AssociationGetNextSinglecastDestination (void )

Returns the address of the next association like an iterator.

Parameters
N/A

This function needs to know beforehand how many items it needs to iterate through.

If the number of iterations are more than totalNodeCount, there will be repeated return of the same item. If the number of iterations are less than totalNodeCount, it will impact the next transmission using this iterator.

AssociationGetDestinationInit() MUST have been invoked before this function.

This function must be invoked only AFTER AssociationGetBitAdressingDestination() has returned false.

Continuously invoking this function will return the next association. If there are no more associations in the group, the first one in the same group will be returned and so forth.

If the group is empty, the function will ASSERT.

Returns

  • Address of an association.


Definition at line 267 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

AssociationGetSinglecastEndpointDestinationCount#

uint8_t AssociationGetSinglecastEndpointDestinationCount (void )

Returns the number of endpoint destinations in the active node association list.

Parameters
N/A

AssociationGetDestinationInit() MUST have been invoked before this function.

Returns

  • Number of destination endpoints found in list.


Definition at line 276 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

ApplicationGetLastActiveGroupId#

uint8_t ApplicationGetLastActiveGroupId (void )

Returns the latest used association group.

Parameters
N/A

Returns

  • Latest used association group.


Definition at line 283 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

ReqNodeList#

TRANSMIT_OPTIONS_TYPE_EX * ReqNodeList (AGI_PROFILE const *const pProfile, cc_group_t const *const pCurrentCmdGrp, const uint8_t sourceEndpoint)

Returns TX options containing a list of nodes found in the association group that matches the given AGI profile, command class / command pair and source endpoint.

Parameters
[in]pProfile

Pointer to AGI profile.

[in]pCurrentCmdGrp

Pointer to command class / command pair.

[in]sourceEndpoint

The endpoint for which the nodes are associated.

This function must be called to construct the TX options for ZW_TransportMulticast_SendRequest(). Returns

  • transmit option pointer of type TRANSMIT_OPTIONS_TYPE_EX. Return NULL if something vent wrong.


Definition at line 296 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

handleAssociationSet#

e_cmd_handler_return_code_t handleAssociationSet (uint8_t ep, ZW_MULTI_CHANNEL_ASSOCIATION_SET_1BYTE_V2_FRAME * pCmd, uint8_t cmdLength, uint8_t commandClass)

Handler for Association Set command.

Parameters
[in]ep

A given endpoint.

[in]pCmd

A command containing the nodes to save in the association database.

[in]cmdLength

Length of the command.

[in]commandClass

Caller command class. This function may be called from multiple command classes. This parameter tells which one was it.

Returns

  • command handler return code


Definition at line 53 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/src/CC_Association.h

Macro Definition Documentation#

FREE_VALUE#

#define FREE_VALUE
Value:
0x00FF

Definition at line 29 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

NOT_VALID_GROUP_ID#

#define NOT_VALID_GROUP_ID
Value:
0

Invalid group ID.


Definition at line 34 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

LIFELINE_GROUP_ID#

#define LIFELINE_GROUP_ID
Value:
1

LIFELINE group ID.


Definition at line 35 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

LIFELINE_ENDPOINT_ALLOWED#

#define LIFELINE_ENDPOINT_ALLOWED
Value:
0

The only allowed endpoint of the Lifeline group!


Definition at line 36 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_base.h

ZAF_FILE_SIZE_ASSOCIATIONINFO#

#define ZAF_FILE_SIZE_ASSOCIATIONINFO
Value:
(sizeof(SAssociationInfo))

Definition at line 37 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/ZAF/CommandClasses/Association/inc/association_plus_file.h