(Multi Channel) Association#

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.

SAssociationInfo#

typedef struct SAssociationInfo SAssociationInfo

CC_Association_Init#

void CC_Association_Init (void )

Remarks

• Must be invoked by CC_Association.c only

CC_Association_Reset#

void CC_Association_Reset (void )

Remarks

• Must be invoked by CC_Association.c only

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.

Returns

• enum type NODE_LIST_STATUS

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.

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

• command handler return code

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.

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.

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.

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().

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!

Returns

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

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.

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.

ApplicationGetLastActiveGroupId#

uint8_t ApplicationGetLastActiveGroupId (void )

Returns the latest used association group.

Returns

• Latest used association group.

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(). Returns

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

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.

Returns

• command handler return code

FREE_VALUE#

#define FREE_VALUE

0x00FF

NOT_VALID_GROUP_ID#

#define NOT_VALID_GROUP_ID

0

Invalid group ID.

LIFELINE_GROUP_ID#

#define LIFELINE_GROUP_ID

1

LIFELINE group ID.

LIFELINE_ENDPOINT_ALLOWED#

#define LIFELINE_ENDPOINT_ALLOWED

0

The only allowed endpoint of the Lifeline group!

ZAF_FILE_SIZE_ASSOCIATIONINFO#

#define ZAF_FILE_SIZE_ASSOCIATIONINFO

(sizeof(SAssociationInfo))