discovery.h File Reference

Note that Node Discovery isn't supported on XBee Smart Energy firmware. More...

#include "xbee/platform.h"
#include "xbee/device.h"
#include "wpan/types.h"

Go to the source code of this file.

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

Detailed Description

Note that Node Discovery isn't supported on XBee Smart Energy firmware.

A host can initiate Node Discovery by sending an ATND command to its local XBee. The command can include a parameter of the NI string of a single node on the network to discover. See the xbee_disc_discover_nodes() API for sending this request.

Responses come in as AT Command Response frames (type 0x88) containing a Node ID message.

Additionally, nodes on a network will broadcast unsolicited (i.e., not in response to an ATND command) Node ID messages to the rest of the network in two instances:

1) The device has ATJN set to 1, and it has just joined the network.

2) The user has configured D0 as the commissioning button, and presses the commissioning button once.

The receiving node will pass the message on to the host in one of two ways:

1) If AO is set to 0, the host receives a Node ID frame (type 0x95).

2) If AO is non-zero, the host receives an Explicit Rx frame (type 0x91) for the Node ID Message cluster (0x0095) of the Digi Data endpoint (0xE8).

This library provides an API layer for handling these responses. The host needs to follow these steps to receive NODE ID messages.

1) Write a function to receive the messages, with the following signature: void node_discovered( xbee_dev_t *xbee, const xbee_node_id_t *rec)

2) Register that function at startup to receive messages: xbee_disc_add_node_id_handler( &my_xbee, &node_discovered);

3) Include the ATND Response handler in the xbee_frame_handlers table using the macro XBEE_FRAME_HANDLE_ATND_RESPONSE.

4) If using a module with ATAO set to 0, include the Node ID handler in the xbee_frame_handlers table using the macro XBEE_FRAME_HANDLE_AO0_NODEID.

5) If using a module with ATAO set to 1 or 3, include the Node ID Cluster handler in the Digi Data endpoint's cluster table, using the XBEE_DISC_DIGI_DATA_CLUSTER_ENTRY macro, and include the Explicit RX handler in the xbee_frame_handlers table using the macro XBEE_FRAME_HANDLE_RX_EXPLICIT.