Cluster/Endpoint layer

Files
file	aps.h
	Cluster/Endpoint layer for WPAN networks (ZigBee and DigiMesh).
file	wpan_aps.c
	Base WPAN/ZigBee layer, responsible for endpoints and clusters.

Data Structures
struct	wpan_envelope_t
	The "envelope" is used to gather all necessary information about a given frame on the network. More...
struct	wpan_cluster_table_entry_t
	Information on each cluster associated with an endpoint. More...
struct	wpan_endpoint_table_entry_t
	Information on each endpoint on this device. More...
struct	wpan_dev_t
	Structure used by the WPAN/ZigBee layers. More...
struct	wpan_conversation_t
	Used to track conversations (outstanding requests) on an endpoint. More...
struct	wpan_ep_state_t
	Volatile part of an endpoint record used to track conversations (requests waiting for responses). More...

Macros
#define	WPAN_CLUSTER_END_OF_LIST   0xFFFF
	Cluster ID used to mark the end of cluster_table in wpan_endpoint_table_entry_t. More...
#define	WPAN_CLUST_ENTRY_LIST_END   { WPAN_CLUSTER_END_OF_LIST }
	Macro for a wpan_cluster_table_entry_t that can be used to mark the end of the table. More...
#define	WPAN_DEV_IS_JOINED(dev)   ((dev)->flags & WPAN_FLAG_JOINED)
	Macro to test whether a device has joined the network. More...
#define	WPAN_DEV_IS_AUTHENTICATED(dev)   ((dev)->flags & WPAN_FLAG_AUTHENTICATED)
	Macro to test whether a device has authenticated with the trust center. More...
#define	WPAN_ENDPOINT_END_OF_LIST   0xFF
	Endpoint ID used to mark the end of endpoint_table in wpan_dev_t.
#define	WPAN_ENDPOINT_TABLE_END   { WPAN_ENDPOINT_END_OF_LIST }
	Macro for a wpan_endpoint_table_entry_t that can be used to mark the end of the table. More...
#define	WPAN_APS_PROFILE_ANY   0xFFFF
#define	WPAN_CONVERSATION_END   1
	end of conversation, no more responses expected
#define	WPAN_CONVERSATION_CONTINUE   2
	leave conversation open, more responses are expected
#define	WPAN_MAX_CONVERSATIONS   3
	Number of outstanding requests to track in a wpan_ep_state_t associated with an endpoint. More...
#define	WPAN_CONVERSATION_TIMEOUT   30
	Default conversation recycle timeout (seconds)
#define	wpan_aps_debug

Typedefs
typedef int(*	wpan_aps_handler_fn) (const wpan_envelope_t FAR *envelope, void FAR *context)
	General handler used in the cluster table. More...
typedef int(*	wpan_ep_handler_fn) (const wpan_envelope_t FAR *envelope, struct wpan_ep_state_t FAR *ep_state)
	General handler used in the endpoint table. More...
typedef int(*	wpan_endpoint_send_fn) (const wpan_envelope_t FAR *envelope, uint16_t flags)
	Function called by the WPAN APS layer to send a frame out on the network. More...
typedef int(*	_wpan_config_fn) (struct wpan_dev_t *dev,...)
	Function called by the WPAN APS layer to configure the underlying network device. More...
typedef int(*	wpan_tick_fn) (struct wpan_dev_t *dev)
	Function called by the WPAN APS layer to have the underlying device read and dispatch frames. More...
typedef const wpan_endpoint_table_entry_t *(*	wpan_endpoint_get_next_fn) (struct wpan_dev_t *dev, const wpan_endpoint_table_entry_t *ep)
	Custom function for walking the endpoint table. More...
typedef int(*	wpan_response_fn) (struct wpan_conversation_t FAR *conversation, const wpan_envelope_t FAR *envelope)
	Handler registered with wpan_conversation_register() to process responses to outstanding requests. More...

Enumerations
enum	wpan_clust_digi {   DIGI_CLUST_SLEEP_SYNC = 0x0009, DIGI_CLUST_SERIAL = 0x0011, DIGI_CLUST_LOOPBACK = 0x0012, DIGI_CLUST_ND_COMMAND = 0x0015,   DIGI_CLUST_DN_COMMAND = 0x0016, DIGI_CLUST_REMOTE_COMMAND = 0x0021, DIGI_CLUST_NR_COMMAND = 0x0022, DIGI_CLUST_IODATA = 0x0092,   DIGI_CLUST_WATCHPORT = 0x0094, DIGI_CLUST_NODEID_MESSAGE = 0x0095, DIGI_CLUST_DN_RESPONSE = 0x0096, DIGI_CLUST_REMOTE_RESPONSE = 0x00A1,   DIGI_CLUST_NR_RESPONSE = 0x00A2, DIGI_CLUST_INDIRECT_ROUTE_ERR = 0x00B0, DIGI_CLUST_PROG_XBEE_OTA_UPD = 0x1000, DIGI_CLUST_NBRFWUPDATE = 0x71FE,   DIGI_CLUST_REMFWUPDATE = 0x71FF, DIGI_CLUST_FWUPDATERESP = (int)0xF1FF }
	Digi Data cluster IDs (endpoint WPAN_ENDPOINT_DIGI_DATA) More...

Functions
int	wpan_tick (wpan_dev_t *dev)
	Calls the underlying hardware tick function to process received frames, and times out expired conversations. More...
const wpan_cluster_table_entry_t *	wpan_cluster_match (uint16_t match, uint8_t mask, const wpan_cluster_table_entry_t *entry)
	Search a cluster table for a matching cluster ID. More...
const wpan_endpoint_table_entry_t *	wpan_endpoint_get_next (wpan_dev_t *dev, const wpan_endpoint_table_entry_t *ep)
	Function used to walk a device's endpoint table. More...
const wpan_endpoint_table_entry_t *	wpan_endpoint_match (wpan_dev_t *dev, uint8_t endpoint, uint16_t profile_id)
	Walk a device's endpoint table looking for a matching endpoint ID and profile ID. More...
const wpan_endpoint_table_entry_t *	wpan_endpoint_of_envelope (const wpan_envelope_t *env)
	Look up the endpoint table entry for the source endpoint of an envelope. More...
const wpan_endpoint_table_entry_t *	wpan_endpoint_of_cluster (wpan_dev_t *dev, uint16_t profile_id, uint16_t cluster_id, uint8_t mask)
	Walk a device's endpoint table looking for a matching profile ID and cluster ID. More...
void	wpan_envelope_create (wpan_envelope_t *envelope, wpan_dev_t *dev, const addr64 FAR *ieee, uint16_t network_addr)
	Starting with a blank envelope, fill in the device, 64-bit IEEE address and 16-bit network address of the destination. More...
int	wpan_envelope_reply (wpan_envelope_t FAR *reply, const wpan_envelope_t FAR *original)
	Create a reply envelope based on the envelope received from a remote node. More...
int	wpan_envelope_send (const wpan_envelope_t FAR *envelope)
	Send a message to an endpoint using address and payload information stored in a wpan_envelope_t structure. More...
void	wpan_envelope_dump (const wpan_envelope_t FAR *envelope)
	Debugging function to dump the contents of an envelope to stdout. More...
int	wpan_conversation_register (wpan_ep_state_t FAR *state, wpan_response_fn handler, const void FAR *context, uint16_t timeout)
	Add a conversation to the table of tracked conversations. More...
int	wpan_conversation_response (wpan_ep_state_t FAR *state, uint8_t transaction_id, const wpan_envelope_t FAR *envelope)
	Searches the endpoint's table of active conversations (outstanding requests waiting for responses) for a given transaction. More...
uint8_t	wpan_endpoint_next_trans (const wpan_endpoint_table_entry_t *ep)
	Increment and return the endpoint's transaction ID counter. More...
int	wpan_envelope_dispatch (wpan_envelope_t *envelope)
	Find the matching endpoint for the provided envelope and have it process the frame. More...
void	wpan_conversation_delete (wpan_conversation_t FAR *conversation)
	Delete a conversation from an endpoint's conversation table. More...
void	_wpan_endpoint_expire_conversations (wpan_ep_state_t FAR *state)
	Walk an endpoint's conversation table and expire any conversations that have timed out. More...
int	_wpan_endpoint_dispatch (wpan_envelope_t *envelope, const wpan_endpoint_table_entry_t *ep)
	Dispatch a message for a given endpoint. More...

ZigBee Stack Profile IDs (WPAN_STACK_PROFILE_*)
4-bit values used in ZigBee beacons
#define	WPAN_STACK_PROFILE_PROPRIETARY   0x0
	Network Specific.
#define	WPAN_STACK_PROFILE_ZIGBEE   0x1
	ZigBee (2006)
#define	WPAN_STACK_PROFILE_ZIGBEE_PRO   0x2
	ZigBee PRO (2007)

Profile IDs
#define	WPAN_PROFILE_ZDO   0x0000
	ZigBee Device Object (aka ZigBee Device Profile)
#define	WPAN_PROFILE_SMART_ENERGY   0x0109
	Smart Energy Profile.
#define	WPAN_PROFILE_DIGI   0xC105
	Digi International, mfg-specific.

Manufacturer IDs (WPAN_MANUFACTURER_*)
Contact the ZigBee Alliance to have a Manufacturer ID assigned to your company. DO NOT use the Digi Manufacturer ID for your own manufacturer-specific profiles/clusters/attributes.
#define	WPAN_MANUFACTURER_DIGI   0x101E
	Digi International (MaxStream)
#define	WPAN_MANUFACTURER_DIGI2   0x1087
	Digi International.
#define	WPAN_MANUFACTURER_TEST1   0xFFF1
	Test Vendor #1.
#define	WPAN_MANUFACTURER_TEST2   0xFFF2
	Test Vendor #2.
#define	WPAN_MANUFACTURER_TEST3   0xFFF3
	Test Vendor #3.

List of fixed endpoints (WPAN_ENDPOINT_*)
#define	WPAN_ENDPOINT_ZDO   0x00
	ZigBee Device Object/Profile.
#define	WPAN_ENDPOINT_DIGI_SE   0x5E
	Digi Smart Energy.
#define	WPAN_ENDPOINT_DDO   0xE6
	Digi Device Objects.
#define	WPAN_ENDPOINT_DIGI_DEVICE   WPAN_ENDPOINT_DDO
#define	WPAN_ENDPOINT_DIGI_DATA   0xE8
	Digi Data.
#define	WPAN_ENDPOINT_BROADCAST   0xFF
	Broadcast Endpoint.

WPAN_CLUST_FLAG_*
Values for flags field of wpan_cluster_table_entry_t.
#define	WPAN_CLUST_FLAG_NONE   0x00
	no flags
#define	WPAN_CLUST_FLAG_INPUT   0x01
	input/server cluster (typically receives requests)
#define	WPAN_CLUST_FLAG_OUTPUT   0x02
	output/client cluster (typically receives responses)
#define	WPAN_CLUST_FLAG_INOUT   0x03
	both client and server cluster
#define	WPAN_CLUST_FLAG_SERVER   WPAN_CLUST_FLAG_INPUT
	alias name for input cluster (uses ZCL terminology)
#define	WPAN_CLUST_FLAG_CLIENT   WPAN_CLUST_FLAG_OUTPUT
	alias name for output cluster (uses ZCL terminology)
#define	WPAN_CLUST_FLAG_ENCRYPT   0x10
	Data sent or received by this cluster must be encrypted. More...
#define	WPAN_CLUST_FLAG_ENCRYPT_UNICAST   0x20
	Unicast data sent or received by this cluster must be encrypted, but unencrypted broadcast frames are OK. More...
#define	WPAN_CLUST_FLAG_NOT_ZCL   0x80
	this cluster is NOT using the ZigBee Cluster Library (ZCL)

WPAN_SEND_FLAG_*
Bitfields for flags parameter to a wpan_endpoint_send_fn().
#define	WPAN_SEND_FLAG_NONE   0x0000
	no special behavior
#define	WPAN_SEND_FLAG_ENCRYPTED   0x0001
	use APS layer encryption

Detailed Description

Macro Definition Documentation

#define WPAN_CLUST_ENTRY_LIST_END   { WPAN_CLUSTER_END_OF_LIST }

Macro for a wpan_cluster_table_entry_t that can be used to mark the end of the table.

#define WPAN_CLUST_FLAG_ENCRYPT   0x10

Data sent or received by this cluster must be encrypted.

Do not accept unencrypted broadcast messages. If using this flag on a non-ZCL cluster, be sure to set WPAN_CLUST_FLAG_NOT_ZCL as well.

Referenced by _pxbee_ota_xmodem_write(), _wpan_endpoint_dispatch(), pxbee_ota_init(), pxbee_ota_server_cmd(), wpan_envelope_reply(), wpan_envelope_send(), and zdo_mgmt_leave_req().

#define WPAN_CLUST_FLAG_ENCRYPT_UNICAST   0x20

Unicast data sent or received by this cluster must be encrypted, but unencrypted broadcast frames are OK.

If using this flag on a non-ZCL cluster, be sure to set WPAN_CLUST_FLAG_NOT_ZCL as well.

Referenced by _wpan_endpoint_dispatch().

#define WPAN_CLUSTER_END_OF_LIST   0xFFFF

Cluster ID used to mark the end of cluster_table in wpan_endpoint_table_entry_t.

Referenced by _match_desc_cluster_list(), _simple_desc_cluster_list(), wpan_cluster_match(), and zcl_time_find_servers().

#define WPAN_DEV_IS_AUTHENTICATED

(

dev

)

((dev)->flags & WPAN_FLAG_AUTHENTICATED)

Macro to test whether a device has authenticated with the trust center.

Parameters

[in]

dev

(wpan_dev_t FAR *) to test

Return values

0	device has authenticated
!0	device has not authenticated

#define WPAN_DEV_IS_JOINED

(

dev

)

((dev)->flags & WPAN_FLAG_JOINED)

Macro to test whether a device has joined the network.

Parameters

[in]

dev

(wpan_dev_t FAR *) to test

Return values

0	device has not joined the network
!0	device has joined the network

Referenced by xbee_cmd_init_device().

#define WPAN_ENDPOINT_TABLE_END   { WPAN_ENDPOINT_END_OF_LIST }

Macro for a wpan_endpoint_table_entry_t that can be used to mark the end of the table.

#define WPAN_MAX_CONVERSATIONS   3

Number of outstanding requests to track in a wpan_ep_state_t associated with an endpoint.

Referenced by _wpan_endpoint_expire_conversations(), wpan_conversation_register(), and wpan_conversation_response().

Typedef Documentation

typedef int(* _wpan_config_fn) (struct wpan_dev_t *dev,...)

Function called by the WPAN APS layer to configure the underlying network device.

Exact implementation is currently undefined, but this entry exists for future expansion of the API.

Parameters

[in]	dev	device to configure
	...	variable arguments to the function

Return values

0	configuration request processed successfully
>0	error parsing parameter #retval

typedef int(* wpan_aps_handler_fn) (const wpan_envelope_t FAR *envelope, void FAR *context)

General handler used in the cluster table.

Dispatcher searches an endpoint's cluster table for a matching cluster, and hands the frame off to the cluster's handler.

If the cluster's handler is set to NULL, or the frame is for a cluster ID that does not appear in the table, the dispatcher hands the frame off to the endpoint's handler.

Parameters

[in]	envelope	information about the frame (addresses, endpoint, profile, cluster, etc.)
[in,out]	context	user context (from cluster table)

Return values

0	handled data
!0	some sort of error processing data

typedef const wpan_endpoint_table_entry_t*(* wpan_endpoint_get_next_fn) (struct wpan_dev_t *dev, const wpan_endpoint_table_entry_t *ep)

Custom function for walking the endpoint table.

The application can define its own function to walk the endpoint table, possibly to support a dynamic table or a table where endpoints aren't always visible.

Parameters

[in]	dev	device with endpoint table to walk
[in]	ep	NULL to return first entry in table, or a pointer previously returned by this function to get the next entry

Return values

NULL	dev is invalid or reached end of table
!NULL	next entry from table

See also

wpan_endpoint_match(), wpan_cluster_match(), wpan_endpoint_get_next()

typedef int(* wpan_endpoint_send_fn) (const wpan_envelope_t FAR *envelope, uint16_t flags)

Function called by the WPAN APS layer to send a frame out on the network.

This is part of the glue that links the XBee layer with the WPAN/ZigBee layers.

Parameters

[in]	envelope	information about the frame (addresses, endpoint, profile, cluster, payload, etc.)
[in]	flags	flags related to sending, see WPAN_SEND_FLAG_* macros WPAN_SEND_FLAG_NONE: no special behavior WPAN_SEND_FLAG_ENCRYPTED: use APS layer encryption

Return values

0	frame sent
!0	error sending frame
-EMSGSIZE	payload is too large

Todo:

Add support for a broadcast radius? Don't send Tx Status? Use frame ID 0?

Todo:

come up with standard error codes for the following possible errors? outbound frame buffer is full, invalid data in envelope, payload is too big

typedef int(* wpan_ep_handler_fn) (const wpan_envelope_t FAR *envelope, struct wpan_ep_state_t FAR *ep_state)

General handler used in the endpoint table.

If a cluster's handler is set to NULL, or the frame is for a cluster ID that does not appear in the table, the dispatcher hands the frame off to the endpoint's handler.

Parameters

[in]	envelope	information about the frame (addresses, endpoint, profile, cluster, etc.)
[in,out]	ep_state	pointer to endpoint state structure

Return values

0	handled data
!0	some sort of error processing data

typedef int(* wpan_response_fn) (struct wpan_conversation_t FAR *conversation, const wpan_envelope_t FAR *envelope)

Handler registered with wpan_conversation_register() to process responses to outstanding requests.

Parameters

[in]	conversation	Pointer to entry in conversation table. Handler can use the pointer to access the context and transaction ID from the conversation, or request deletion of the conversation via wpan_conversation_delete(). Never NULL.
[in]	envelope	envelope with response or NULL if there was a timeout

Return values

WPAN_CONVERSATION_END	end of conversation, no more responses expected
WPAN_CONVERSATION_CONTINUE	leave conversation open, more responses are expected

typedef int(* wpan_tick_fn) (struct wpan_dev_t *dev)

Function called by the WPAN APS layer to have the underlying device read and dispatch frames.

Parameters

[in]

dev

device to tick

Returns

number of frames processed during the tick

Enumeration Type Documentation

enum wpan_clust_digi

Digi Data cluster IDs (endpoint WPAN_ENDPOINT_DIGI_DATA)

Enumerator
DIGI_CLUST_SLEEP_SYNC	DigiMesh Sleeping Router Sync.
DIGI_CLUST_SERIAL	Serial data.
DIGI_CLUST_LOOPBACK	Serial loopback transmit.
DIGI_CLUST_ND_COMMAND	Digi ND Command.
DIGI_CLUST_DN_COMMAND	Digi DN Command.
DIGI_CLUST_REMOTE_COMMAND	Remote Command Request.
DIGI_CLUST_NR_COMMAND	Digi NR Command.
DIGI_CLUST_IODATA	Unsolicited I/O data sample.
DIGI_CLUST_WATCHPORT	Unsolicited Watchport sensor.
DIGI_CLUST_NODEID_MESSAGE	Node ID Message.
DIGI_CLUST_DN_RESPONSE	Digi DN Response.
DIGI_CLUST_REMOTE_RESPONSE	Digi Remote Command Response.
DIGI_CLUST_NR_RESPONSE	Digi NR Response.
DIGI_CLUST_PROG_XBEE_OTA_UPD	Start OTA update of PXBee App.
DIGI_CLUST_NBRFWUPDATE	Neighbor FW update.
DIGI_CLUST_REMFWUPDATE	Remote FW update.
DIGI_CLUST_FWUPDATERESP	FW update response.

Function Documentation

int _wpan_endpoint_dispatch	(	wpan_envelope_t *	envelope,
		const wpan_endpoint_table_entry_t *	ep
	)

Dispatch a message for a given endpoint.

Should only be called from wpan_envelope_dispatch.

Looks up the cluster ID in the endpoint's cluster table and passes envelope off to the cluster handler (if a matching cluster was found) or the endpoint handler.

Parameters

[in]	envelope	structure containing all necessary information about message (endpoints, cluster, profile, etc.)
[in]	ep	endpoint to dispatch envelope to

Return values

0	successfully dispatched message
-ENOENT	no handler for this endpoint/cluster
!0	error dispatching messages

References wpan_envelope_t::cluster_id, wpan_endpoint_table_entry_t::cluster_table, wpan_cluster_table_entry_t::context, wpan_envelope_t::dest_endpoint, ENOENT, wpan_endpoint_table_entry_t::ep_state, FAR, wpan_cluster_table_entry_t::flags, wpan_cluster_table_entry_t::handler, wpan_endpoint_table_entry_t::handler, WPAN_CLUST_FLAG_ENCRYPT, WPAN_CLUST_FLAG_ENCRYPT_UNICAST, WPAN_CLUST_FLAG_INOUT, WPAN_CLUST_FLAG_NOT_ZCL, wpan_cluster_match(), WPAN_ENVELOPE_BROADCAST_ADDR, WPAN_ENVELOPE_RX_APS_ENCRYPT, and zcl_invalid_cluster().

Referenced by wpan_envelope_dispatch().

void _wpan_endpoint_expire_conversations

(

wpan_ep_state_t FAR *

state

)

Walk an endpoint's conversation table and expire any conversations that have timed out.

Parameters

[in]

state

endpoint state (from endpoint table)

References FAR, wpan_conversation_delete(), and WPAN_MAX_CONVERSATIONS.

Referenced by wpan_conversation_delete(), and wpan_tick().

const wpan_cluster_table_entry_t * wpan_cluster_match	(	uint16_t	match,
		uint8_t	mask,
		const wpan_cluster_table_entry_t *	entry
	)

Search a cluster table for a matching cluster ID.

Parameters

[in]	match	ID to match
[in]	mask	Flags to match against the flags member of the wpan_cluster_table_entry_t structure. If any flags match, the entry is returned. Typically one of WPAN_CLUST_FLAG_INPUT (or WPAN_CLUST_FLAG_SERVER) WPAN_CLUST_FLAG_OUTPUT (or WPAN_CLUST_FLAG_CLIENT)
[in]	entry	pointer to list of entries to search

Return values

NULL	entry is invalid or search reached WPAN_CLUSTER_END_OF_LIST without finding a match.
!NULL	Pointer to matching entry from table.

See also

wpan_endpoint_get_next(), wpan_endpoint_match()

References wpan_cluster_table_entry_t::cluster_id, wpan_cluster_table_entry_t::flags, and WPAN_CLUSTER_END_OF_LIST.

Referenced by _wpan_endpoint_dispatch(), _zcl_send_read_from_zdo_match(), _zdo_match_desc_respond(), and wpan_endpoint_of_cluster().

void wpan_conversation_delete

(

wpan_conversation_t FAR *

conversation

)

Delete a conversation from an endpoint's conversation table.

Parameters

[in,out]

conversation

conversation to delete

References _wpan_endpoint_expire_conversations(), and FAR.

Referenced by _wpan_endpoint_expire_conversations(), and wpan_conversation_response().

int wpan_conversation_register	(	wpan_ep_state_t FAR *	state,
		wpan_response_fn	handler,
		const void FAR *	context,
		uint16_t	timeout
	)

Add a conversation to the table of tracked conversations.

Parameters

[in,out]	state	endpoint state associated with sending endpoint
[in]	handler	handler to call when responses come back, or NULL to increment and return the endpoint's transaction ID
[in]	context	pointer stored in conversation table and passed to callback handler
[in]	timeout	number of seconds before generating timeout, or 0 for none

Return values

0-255	transaction ID to use in sent frame
-EINVAL	state is invalid (NULL)
-ENOSPC	table is full

See also

wpan_endpoint_next_trans

References EINVAL, ENOSPC, FAR, and WPAN_MAX_CONVERSATIONS.

Referenced by zdo_send_bind_req(), zdo_send_descriptor_req(), zdo_send_ieee_addr_req(), zdo_send_match_desc(), zdo_send_nwk_addr_req(), and zdo_simple_desc_request().

int wpan_conversation_response	(	wpan_ep_state_t FAR *	state,
		uint8_t	transaction_id,
		const wpan_envelope_t FAR *	envelope
	)

Searches the endpoint's table of active conversations (outstanding requests waiting for responses) for a given transaction.

Hands the response frame off to the handler registered to the conversation with wpan_conversation_register().

Parameters

[in]	state	endpoint state (from endpoint table) or NULL to look it up using the envelope
[in]	transaction_id	transaction ID from frame payload, used to look up conversation
[in]	envelope	envelope from response frame, passed to conversation's handler

Return values

-EINVAL	invalid parameter passed to function, or conversation not found in table
0	handler processed response
!0	handler reported an error while processing response

References EINVAL, wpan_endpoint_table_entry_t::ep_state, FAR, WPAN_CONVERSATION_CONTINUE, wpan_conversation_delete(), WPAN_CONVERSATION_END, wpan_endpoint_match(), and WPAN_MAX_CONVERSATIONS.

Referenced by zcl_general_command(), and zdo_handler().

const wpan_endpoint_table_entry_t * wpan_endpoint_get_next	(	wpan_dev_t *	dev,
		const wpan_endpoint_table_entry_t *	ep
	)

Function used to walk a device's endpoint table.

For most devices, this will just walk the entries in dev->endpoint_table. For custom applications a function may dynamically return entries.

Use of this function is the only way to walk the endpoint table.

Parameters

[in]	dev	device with endpoint table to walk
[in]	ep	NULL to return first entry in table, or a pointer previously returned by this function to get the next entry

Return values

NULL	dev is invalid or reached end of table
!NULL	next entry from table

See also

wpan_endpoint_match(), wpan_cluster_match()

References wpan_endpoint_table_entry_t::endpoint, wpan_dev_t::endpoint_get_next, wpan_dev_t::endpoint_table, and WPAN_ENDPOINT_END_OF_LIST.

Referenced by _zdo_active_ep_respond(), _zdo_match_desc_respond(), wpan_endpoint_match(), wpan_endpoint_of_cluster(), wpan_envelope_dispatch(), and wpan_tick().

const wpan_endpoint_table_entry_t * wpan_endpoint_match	(	wpan_dev_t *	dev,
		uint8_t	endpoint,
		uint16_t	profile_id
	)

Walk a device's endpoint table looking for a matching endpoint ID and profile ID.

Used by the endpoint dispatcher and ZDO layer to describe available endpoints on this device.

Parameters

[in]	dev	Device with endpoint table to search.
[in]	endpoint	Endpoint number to search for.
[in]	profile_id	Profile to match or WPAN_APS_PROFILE_ANY to search on endpoint number only.

Return values

NULL	dev is invalid or reached end of table without finding a match
!NULL	next entry from table

See also

wpan_endpoint_of_cluster(), wpan_endpoint_get_next(), wpan_cluster_match(), wpan_endpoint_of_envelope()

References wpan_endpoint_table_entry_t::endpoint, wpan_endpoint_table_entry_t::profile_id, and wpan_endpoint_get_next().

Referenced by _zdo_endpoint_of(), _zdo_simple_desc_respond(), wpan_conversation_response(), wpan_endpoint_of_envelope(), and wpan_envelope_dispatch().

uint8_t wpan_endpoint_next_trans

(

const wpan_endpoint_table_entry_t *

ep

)

Increment and return the endpoint's transaction ID counter.

Parameters

[in]

ep

entry from endpoint table

Return values

0-255

current transaction ID for endpoint

References wpan_endpoint_table_entry_t::ep_state.

Referenced by _zcl_comm_command_build(), zcl_client_read_attributes(), zcl_ota_upgrade_image_notify(), zcl_send_write_attributes(), and zdo_mgmt_leave_req().

const wpan_endpoint_table_entry_t * wpan_endpoint_of_cluster	(	wpan_dev_t *	dev,
		uint16_t	profile_id,
		uint16_t	cluster_id,
		uint8_t	mask
	)

Walk a device's endpoint table looking for a matching profile ID and cluster ID.

Used to find the correct endpoint to use for sending ZCL client requests.

Parameters

[in]	dev	Device with endpoint table to search.
[in]	profile_id	Profile to match or WPAN_APS_PROFILE_ANY to search on cluster ID only.
[in]	cluster_id	Cluster ID to search for.
[in]	mask	Flags to match against the flags member of the wpan_cluster_table_entry_t structure. If any flags match, the entry is returned. Typically one of WPAN_CLUST_FLAG_INPUT (or WPAN_CLUST_FLAG_SERVER) WPAN_CLUST_FLAG_OUTPUT (or WPAN_CLUST_FLAG_CLIENT)

Return values

NULL	dev is invalid or reached end of table without finding a match
!NULL	matching entry from table

See also

wpan_endpoint_match(), wpan_endpoint_get_next(), wpan_cluster_match()

References wpan_endpoint_table_entry_t::cluster_table, wpan_endpoint_table_entry_t::endpoint, wpan_endpoint_table_entry_t::profile_id, wpan_cluster_match(), and wpan_endpoint_get_next().

Referenced by _zcl_comm_command_build(), and zcl_time_find_servers().

const wpan_endpoint_table_entry_t * wpan_endpoint_of_envelope

(

const wpan_envelope_t *

env

)

Look up the endpoint table entry for the source endpoint of an envelope.

Parameters

[in]

env

Envelope for lookup. Uses env->source_endpoint and env->profile_id to find the endpoint table entry for env->dev.

Return values

NULL	invalid parameter, or reached end of table without finding a match
!NULL	entry from table

See also

wpan_endpoint_of_cluster(), wpan_endpoint_get_next(), wpan_cluster_match(), wpan_endpoint_match()

References wpan_envelope_t::dev, wpan_envelope_t::profile_id, wpan_envelope_t::source_endpoint, and wpan_endpoint_match().

Referenced by _zcl_comm_command_build(), and zcl_send_write_attributes().

void wpan_envelope_create	(	wpan_envelope_t *	envelope,
		wpan_dev_t *	dev,
		const addr64 FAR *	ieee,
		uint16_t	network_addr
	)

Starting with a blank envelope, fill in the device, 64-bit IEEE address and 16-bit network address of the destination.

The profile ID, cluster ID, source/destination endpoints and envelope options are all be set to zero.

Parameters

[out]	envelope	envelope to populate
[in]	dev	device that will send this envelope
[in]	ieee	64-bit IEEE/MAC address of recipient or one of WPAN_IEEE_ADDR_COORDINATOR (send to coordinator) WPAN_IEEE_ADDR_BROADCAST (broadcast packet) WPAN_IEEE_ADDR_UNDEFINED (use network address only)
[in]	network_addr	16-bit network address of recipient or one of WPAN_NET_ADDR_COORDINATOR for the coordinator (use the coordinator's actual IEEE address for the ieee parameter). WPAN_NET_ADDR_BCAST_ALL_NODES (broadcast to all nodes) WPAN_NET_ADDR_BCAST_NOT_ASLEEP (broadcast to awake nodes) WPAN_NET_ADDR_BCAST_ROUTERS (broadcast to routers/coordinator) WPAN_NET_ADDR_UNDEFINED (use 64-bit address only)

When sending broadcast packets, use WPAN_IEEE_ADDR_BROADCAST and WPAN_NET_ADDR_UNDEFINED. Don't set both addresses to broadcast.

When using DigiMesh protocol, always set the network_addr to WPAN_NET_ADDR_UNDEFINED.

See also

wpan_envelope_reply()

References wpan_envelope_t::dev, wpan_envelope_t::ieee_address, and wpan_envelope_t::network_address.

Referenced by _pxbee_ota_xmodem_write(), _zdo_envelope_create(), pxbee_ota_init(), zcl_ota_upgrade_image_notify(), and zdo_send_ieee_addr_req().

int wpan_envelope_dispatch

(

wpan_envelope_t *

envelope

)

Find the matching endpoint for the provided envelope and have it process the frame.

In the case of the broadcast endpoint (255), dispatches the frame to all endpoints matching the envelope's profile ID.

Looks up the destination endpoint and cluster ID in the device's endpoint table and passes envelope off to the cluster handler (if a matching cluster was found) or the endpoint handler.

Parameters

[in]

envelope

structure containing all necessary information about message (endpoints, cluster, profile, etc.)

Return values

0	successfully dispatched message
-ENOENT	no handler for this endpoint/cluster
!0	error dispatching messages

References _wpan_endpoint_dispatch(), wpan_envelope_t::dest_endpoint, wpan_envelope_t::dev, wpan_endpoint_table_entry_t::endpoint, ENOENT, wpan_envelope_t::profile_id, wpan_endpoint_table_entry_t::profile_id, WPAN_ENDPOINT_BROADCAST, wpan_endpoint_get_next(), wpan_endpoint_match(), WPAN_ENVELOPE_BROADCAST_EP, WPAN_ENVELOPE_CLUSTER_FLAGS, and wpan_envelope_dump().

Referenced by _xbee_handle_receive_explicit().

void wpan_envelope_dump

(

const wpan_envelope_t FAR *

envelope

)

Debugging function to dump the contents of an envelope to stdout.

Displays all fields from the envelope, plus the contents of the payload

Parameters

[in]

envelope

envelope to dump

References addr64_format(), ADDR64_STRING_LENGTH, hex_dump(), HEX_DUMP_FLAG_OFFSET, and PRIsFAR.

Referenced by wpan_envelope_dispatch(), wpan_envelope_send(), zcl_client_read_attributes(), zcl_send_response(), zcl_send_write_attributes(), and zdo_send_match_desc().

int wpan_envelope_reply	(	wpan_envelope_t FAR *	reply,
		const wpan_envelope_t FAR *	original
	)

Create a reply envelope based on the envelope received from a remote node.

Copies the interface, addresses, profile and cluster from the original envelope, and then swaps the source and destination endpoints.

Note that it may be necessary for the caller to change the cluster_id as well, after building the reply envelope. For example, ZDO responses set the high bit of the request's cluster ID.

Parameters

[out]	reply	Buffer for storing the reply envelope.
[in]	original	Original envelope, received from a remote node, to base the reply on.

Return values

0	addressed reply envelope
-EINVAL	either parameter is NULL or they point to the same address

See also

wpan_envelope_create()

References EINVAL, WPAN_CLUST_FLAG_ENCRYPT, and WPAN_ENVELOPE_RX_APS_ENCRYPT.

Referenced by _zcl_send_read_from_zdo_match(), pxbee_ota_server_cmd(), zcl_comm_response(), zcl_send_response(), and zdo_send_response().

int wpan_envelope_send

(

const wpan_envelope_t FAR *

envelope

)

Send a message to an endpoint using address and payload information stored in a wpan_envelope_t structure.

Parameters

[in]

envelope

envelope of request to send

Return values

0	request sent
!0	error trying to send request

References EINVAL, WPAN_CLUST_FLAG_ENCRYPT, wpan_envelope_dump(), WPAN_SEND_FLAG_ENCRYPTED, and WPAN_SEND_FLAG_NONE.

Referenced by _zcl_comm_command_send(), pxbee_ota_init(), pxbee_ota_server_cmd(), xbee_transparent_serial(), zcl_client_read_attributes(), zcl_comm_response(), zcl_ota_upgrade_image_notify(), zcl_send_response(), zcl_send_write_attributes(), zdo_mgmt_leave_req(), zdo_send_bind_req(), zdo_send_descriptor_req(), zdo_send_ieee_addr_req(), zdo_send_match_desc(), zdo_send_nwk_addr_req(), zdo_send_response(), and zdo_simple_desc_request().

int wpan_tick

(

wpan_dev_t *

dev

)

Calls the underlying hardware tick function to process received frames, and times out expired conversations.

Parameters

[in]

dev

WPAN device to tick

Return values

>=0	number of frames processed during the tick
-EINVAL	device does not have a tick function assigned to it
<0	some other error encountered during the tick

References _wpan_endpoint_expire_conversations(), EINVAL, wpan_endpoint_table_entry_t::ep_state, wpan_dev_t::tick, and wpan_endpoint_get_next().

Referenced by _sxa_io_process_response().