(Multi Channel) Association

Collaboration diagram for (Multi Channel) Association:

Data Structures
struct	ASSOCIATION_GROUP
	Contains associations for one group. More...
struct	ASSOCIATION_GROUP_PACKED
	Contains associations for one group packed for the file system. More...
struct	SAssociationInfo

Macros
#define	FREE_VALUE   0x00FF
#define	NOT_VALID_GROUP_ID   0
	Invalid group ID.
#define	LIFELINE_GROUP_ID   1
	LIFELINE group ID.
#define	LIFELINE_ENDPOINT_ALLOWED   0
	The only allowed endpoint of the Lifeline group!
#define	ZAF_FILE_SIZE_ASSOCIATIONINFO   (sizeof(SAssociationInfo))

Typedefs
typedef struct SAssociationInfo	SAssociationInfo

Enumerations
enum	NODE_LIST_STATUS {   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 }

Functions
NODE_LIST_STATUS	handleAssociationGetnodeList (uint8_t groupId, uint8_t ep, destination_info_t **ppListOfNodes, uint8_t *pListLen)
void	AssociationGetDestinationInit (destination_info_t *pFirstDestination)
bool	AssociationGetBitAdressingDestination (destination_info_t **ppNodeList, uint8_t *pListLength, destination_info_t *pNode)
uint32_t	AssociationGetSinglecastNodeCount (void)
destination_info_t *	AssociationGetNextSinglecastDestination (void)
uint8_t	AssociationGetSinglecastEndpointDestinationCount (void)
TRANSMIT_OPTIONS_TYPE_EX *	ReqNodeList (AGI_PROFILE const *const pProfile, cc_group_t const *const pCurrentCmdGrp, const uint8_t sourceEndpoint)

Detailed Description

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

Macro Definition Documentation

FREE_VALUE

#define FREE_VALUE   0x00FF

LIFELINE_ENDPOINT_ALLOWED

#define LIFELINE_ENDPOINT_ALLOWED   0

The only allowed endpoint of the Lifeline group!

LIFELINE_GROUP_ID

#define LIFELINE_GROUP_ID   1

LIFELINE group ID.

NOT_VALID_GROUP_ID

#define NOT_VALID_GROUP_ID   0

Invalid group ID.

ZAF_FILE_SIZE_ASSOCIATIONINFO

#define ZAF_FILE_SIZE_ASSOCIATIONINFO   (sizeof(SAssociationInfo))

Typedef Documentation

SAssociationInfo

typedef struct SAssociationInfo SAssociationInfo

Enumeration Type Documentation

NODE_LIST_STATUS

enum 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

Function Documentation

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

Parameters

[in,out]	ppNodeList	- Address of pointer to an element in the node list. The pointer will be updated as this function travels through the node list.
[in,out]	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.

Returns

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

AssociationGetDestinationInit()

void AssociationGetDestinationInit

(

destination_info_t *

pFirstDestination

)

Initializes the fetching of nodes before e.g. a transmission. It places a destination_node_list into the system.

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

Parameters

[in]

pFirstDestination

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

AssociationGetNextSinglecastDestination()

destination_info_t * AssociationGetNextSinglecastDestination

(

void

)

Returns the address of the next association like an iterator. 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.

AssociationGetSinglecastEndpointDestinationCount()

uint8_t AssociationGetSinglecastEndpointDestinationCount

(

void

)

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

AssociationGetDestinationInit() MUST have been invoked before this function.

Returns

Number of destination endpoints found in list.

AssociationGetSinglecastNodeCount()

uint32_t AssociationGetSinglecastNodeCount

(

void

)

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

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.

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

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.

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

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.

Returns

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