Frames: Node Discovery (0x95)

Code related to "Node Discovery" (the ATND command, 0x95 frames) More...

Files
file	discovery.h
	Note that Node Discovery isn't supported on XBee Smart Energy firmware.
file	xbee_discovery.c
	Code related to "Node Discovery" (the ATND command, 0x95 frames).

Data Structures
struct	xbee_node_id1_t
	< ATMY value [0xFFFE on DigiMesh] ATSH and ATSL null-terminated ATNI value (variable length) More...
struct	xbee_node_id2_t
	< ATMP value [0xFFFE on DigiMesh] More...
struct	xbee_frame_node_id_t
	format of 0x95 frames received from XBee More...
struct	xbee_node_id_t
	parsed Node ID in host-byte-order and fixed length fields More...

Macros
#define	XBEE_DISC_MAX_NODEID_LEN   20
	Maximum length of a Node ID string (ATNI value) (excludes null terminator).
#define	XBEE_DISC_DIGI_DATA_CLUSTER_ENTRY
	Include xbee_disc_nodeid_cluster_handler in the cluster table for the the Digi Data endpoint. More...
#define	XBEE_FRAME_HANDLE_ATND_RESPONSE   { XBEE_FRAME_LOCAL_AT_RESPONSE, 0, xbee_disc_atnd_response_handler, NULL }
	Include xbee_disc_atnd_response_handler in xbee_frame_handlers[].
#define	XBEE_FRAME_HANDLE_AO0_NODEID   { XBEE_FRAME_NODE_ID, 0, xbee_disc_nodeid_frame_handler, NULL }
	Include xbee_disc_nodeid_frame_handler in xbee_frame_handlers[] (only necessary if ATAO is set to 0). More...

Functions
int	xbee_disc_nd_parse (xbee_node_id_t FAR *parsed, const void FAR *source, int source_length)
	Parse a Node Discovery response and store it in an xbee_node_id_t structure. More...
void	xbee_disc_node_id_dump (const xbee_node_id_t FAR *ni)
	Debugging function used to dump an xbee_node_id_t structure to stdout. More...
const char *	xbee_disc_device_type_str (uint8_t device_type)
	Return a string ("Coord", "Router", "EndDev", or "???") description for the "Device Type" field of a Node ID message. More...
int	xbee_disc_nodeid_cluster_handler (const wpan_envelope_t FAR *envelope, void FAR *context)
	Process messages sent to the Node ID Message cluster (0x0095) of the Digi Data endpoint (0xE8) when ATAO != 0. More...
int	xbee_disc_atnd_response_handler (xbee_dev_t *xbee, const void FAR *raw, uint16_t length, void FAR *context)
	Process AT Command Response frames (type 0x88), looking for ATND responses to parse and pass to Node ID handlers. More...
int	xbee_disc_nodeid_frame_handler (xbee_dev_t *xbee, const void FAR *raw, uint16_t length, void FAR *context)
	Process Node Identification frames (type 0x95), sent when ATAO = 0. More...
int	xbee_disc_add_node_id_handler (xbee_dev_t *xbee, xbee_disc_node_id_fn fn)
	Designate a function to receive parsed Node ID messages on a given XBee device. More...
int	xbee_disc_remove_node_id_handler (xbee_dev_t *xbee, xbee_disc_node_id_fn fn)
	Remove a function registered to receive parsed Node ID messages on a given XBee device. More...
int	xbee_disc_discover_nodes (xbee_dev_t *xbee, const char *identifier)
	Send an ATND command to the XBee, initiating node discovery for all nodes or a specific node's "node identification" (ATNI) string. More...
int	_xbee_disc_parse_and_pass (xbee_dev_t *xbee, const void FAR *node_data, int length)
	Common function used to parse Node ID messages from various sources, and then pass them on to registered receivers. More...

Detailed Description

Code related to "Node Discovery" (the ATND command, 0x95 frames)

Macro Definition Documentation

#define XBEE_DISC_DIGI_DATA_CLUSTER_ENTRY

Value:

{ DIGI_CLUST_NODEID_MESSAGE, xbee_disc_nodeid_cluster_handler, NULL, \
      WPAN_CLUST_FLAG_INPUT | WPAN_CLUST_FLAG_NOT_ZCL}

Include xbee_disc_nodeid_cluster_handler in the cluster table for the the Digi Data endpoint.

#define XBEE_FRAME_HANDLE_AO0_NODEID   { XBEE_FRAME_NODE_ID, 0, xbee_disc_nodeid_frame_handler, NULL }

Include xbee_disc_nodeid_frame_handler in xbee_frame_handlers[] (only necessary if ATAO is set to 0).

Function Documentation

int _xbee_disc_parse_and_pass	(	xbee_dev_t *	xbee,
		const void FAR *	node_data,
		int	length
	)

Common function used to parse Node ID messages from various sources, and then pass them on to registered receivers.

Parameters

[in]	xbee	XBee device that received the message
[in]	node_data	pointer to raw Node ID message
[in]	length	length of Node ID message

Return values

0	Node ID message parsed and passed on to any registered receivers
-EINVAL	invalid parameter passed to function
-EBADMSG	error parsing Node ID message

See also

xbee_disc_nd_parse, xbee_disc_add_node_id_handler, xbee_disc_remove_node_id_handler

References xbee_dev_t::node_id_handler, and xbee_disc_nd_parse().

Referenced by xbee_disc_atnd_response_handler(), xbee_disc_nodeid_cluster_handler(), xbee_disc_nodeid_frame_handler(), and xbee_disc_remove_node_id_handler().

int xbee_disc_add_node_id_handler	(	xbee_dev_t *	xbee,
		xbee_disc_node_id_fn	fn
	)

Designate a function to receive parsed Node ID messages on a given XBee device.

Parameters

[in]	xbee	XBee device to monitor
[in]	fn	function to receive parsed Node ID messages

Return values

0	function assigned
-EINVAL	invalid parameter passed to function
-ENOSPC	can't assign handler to device

See also

xbee_disc_remove_node_id_handler

References EINVAL, ENOSPC, and xbee_dev_t::node_id_handler.

int xbee_disc_atnd_response_handler	(	xbee_dev_t *	xbee,
		const void FAR *	raw,
		uint16_t	length,
		void FAR *	context
	)

Process AT Command Response frames (type 0x88), looking for ATND responses to parse and pass to Node ID handlers.

This function parses the frame and then passes an xbee_node_id_t structure on to Node ID handlers configured with xbee_disc_add_node_id_handler(). If the ATND command fails or returns a timeout, it passes a NULL xbee_node_id_t to the functions.

Do not call this function directly, it should be included in the XBee Frame Handlers table by using the macro XBEE_FRAME_HANDLE_ATND_RESPONSE.

See the function help for xbee_frame_handler_fn() for full documentation on this function's API.

See also

XBEE_FRAME_HANDLE_ATND_RESPONSE, xbee_disc_nodeid_frame_handler, xbee_disc_nodeid_cluster_handler

References _xbee_disc_parse_and_pass(), EINVAL, FAR, xbee_dev_t::node_id_handler, XBEE_AT_RESP_ERROR, XBEE_AT_RESP_STATUS, XBEE_AT_RESP_SUCCESS, and XBEE_UNUSED_PARAMETER.

const char * xbee_disc_device_type_str

(

uint8_t

device_type

)

Return a string ("Coord", "Router", "EndDev", or "???") description for the "Device Type" field of a Node ID message.

Parameters

[in]

device_type

the device_type field from a Node ID message

Returns

pointer to a string describing the type, or "???" if device_type is invalid

See also

xbee_node_id_t

Referenced by _sxa_disc_handle_frame_0x95(), and xbee_disc_node_id_dump().

int xbee_disc_discover_nodes	(	xbee_dev_t *	xbee,
		const char *	identifier
	)

Send an ATND command to the XBee, initiating node discovery for all nodes or a specific node's "node identification" (ATNI) string.

Responses from remote nodes are parsed and then passed on to Node ID handlers configured with xbee_disc_add_node_id_handler().

Parameters

[in]	xbee	XBee device to use as the target
[in]	identifier	the ATNI (node identification) string of a device on the network, or NULL to discover all devices

Return values

0	command sent
-EINVAL	an invalid parameter was passed to the function
-EBUSY	transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

See also

xbee_disc_add_node_id_handler, xbee_disc_remove_node_id_handler

References EINVAL, xbee_cmd_execute(), and XBEE_DISC_MAX_NODEID_LEN.

int xbee_disc_nd_parse	(	xbee_node_id_t FAR *	parsed,
		const void FAR *	source,
		int	source_length
	)

Parse a Node Discovery response and store it in an xbee_node_id_t structure.

Parameters

[out]	parsed	buffer to hold parsed Node ID message
[in]	source	source of Node ID message, starting with the 16-bit network address
[in]	source_length	number of bytes in source of Node ID message

Return values

0	Node ID message parsed and stored in /a parsed
-EINVAL	invalid parameter passed to function
-EBADMSG	error parsing Node ID message

References be16toh, EBADMSG, EINVAL, FAR, WPAN_NET_ADDR_UNDEFINED, and XBEE_DISC_MAX_NODEID_LEN.

Referenced by _sxa_disc_process_node_data(), and _xbee_disc_parse_and_pass().

void xbee_disc_node_id_dump

(

const xbee_node_id_t FAR *

ni

)

Debugging function used to dump an xbee_node_id_t structure to stdout.

Parameters

[in]

ni

pointer to an xbee_node_id_t structure

References be32toh, PRIsFAR, PRIx32, and xbee_disc_device_type_str().

int xbee_disc_nodeid_cluster_handler	(	const wpan_envelope_t FAR *	envelope,
		void FAR *	context
	)

Process messages sent to the Node ID Message cluster (0x0095) of the Digi Data endpoint (0xE8) when ATAO != 0.

This function parses the frame and then passes an xbee_node_id_t structure on to Node ID handlers configured with xbee_disc_add_node_id_handler().

Do not call this function directly, it should be included in the Cluster table of the Digi Data endpoint by using the macro XBEE_DISC_DIGI_DATA_CLUSTER_ENTRY.

Hosts communicating to XBee modules running with ATAO set to zero do not need to use this handler.

See the function help for wpan_aps_handler_fn() for full documentation on this function's API.

See also

XBEE_DISC_DIGI_DATA_CLUSTER_ENTRY, xbee_disc_nodeid_frame_handler, xbee_disc_atnd_response_handler

References _xbee_disc_parse_and_pass(), EINVAL, and XBEE_UNUSED_PARAMETER.

int xbee_disc_nodeid_frame_handler	(	xbee_dev_t *	xbee,
		const void FAR *	raw,
		uint16_t	length,
		void FAR *	context
	)

Process Node Identification frames (type 0x95), sent when ATAO = 0.

These frames are sent to the host when ATAO is set to 0 and a remote node:

• Has ATD0 set to 1, and someone presses the commissioning button once.
• Has ATJN set to 1, and has joined the network.

This function parses a the frame and then passes an xbee_node_id_t structure on to Node ID handlers configured with xbee_disc_add_node_id_handler().

Do not call this function directly, it should be included in the XBee Frame Handlers table by using the macro XBEE_FRAME_HANDLE_AO0_NODEID. Hosts communicating to XBee modules running with ATAO set to a non-zero value do not need to use this handler.

See the function help for xbee_frame_handler_fn() for full documentation on this function's API.

See also

xbee_disc_nodeid_cluster_handler, xbee_disc_atnd_response_handler

References _xbee_disc_parse_and_pass(), EINVAL, FAR, and XBEE_UNUSED_PARAMETER.

int xbee_disc_remove_node_id_handler	(	xbee_dev_t *	xbee,
		xbee_disc_node_id_fn	fn
	)

Remove a function registered to receive parsed Node ID messages on a given XBee device.

Parameters

[in]	xbee	XBee device to monitor
[in]	fn	function to receive parsed Node ID messages

Return values

0	function removed
-EINVAL	invalid parameter passed to function
-ENOENT	function isn't assigned to this XBee module

See also

xbee_disc_remove_node_id_handler

References _xbee_disc_parse_and_pass(), EINVAL, ENOENT, FAR, and xbee_dev_t::node_id_handler.