Files
file	device.h

file	xbee_device.c

Data Structures
struct	xbee_dev_t

struct	xbee_dev_t::rx
	Buffer and state variables used for receiving a frame. More...

struct	xbee_dispatch_table_entry

Typedefs
typedef struct xbee_dev_t	xbee_dev_t

typedef struct xbee_dispatch_table_entry	xbee_dispatch_table_entry_t

typedef PACKED_STRUCT	xbee_frame_modem_status_t

Enumerations
enum	xbee_dev_flags { XBEE_DEV_FLAG_CMD_INIT = 0x0001, XBEE_DEV_FLAG_QUERY_BEGIN = 0x0002, XBEE_DEV_FLAG_QUERY_DONE = 0x0004, XBEE_DEV_FLAG_QUERY_ERROR = 0x0008, XBEE_DEV_FLAG_QUERY_REFRESH = 0x0010, XBEE_DEV_FLAG_QUERY_INPROGRESS = 0x0020, XBEE_DEV_FLAG_IN_TICK = 0x0080, XBEE_DEV_FLAG_COORDINATOR = 0x0100, XBEE_DEV_FLAG_ROUTER = 0x0200, XBEE_DEV_FLAG_ENDDEV = 0x0400, XBEE_DEV_FLAG_ZNET = 0x0800, XBEE_DEV_FLAG_ZIGBEE = 0x1000, XBEE_DEV_FLAG_DIGIMESH = 0x2000, XBEE_DEV_FLAG_USE_FLOWCONTROL = (int)0x8000 }

enum	xbee_dev_mode { XBEE_MODE_UNKNOWN = 0, XBEE_MODE_BOOTLOADER, XBEE_MODE_API, XBEE_MODE_IDLE, XBEE_MODE_PRE_ESCAPE, XBEE_MODE_POST_ESCAPE, XBEE_MODE_COMMAND, XBEE_MODE_WAIT_IDLE, XBEE_MODE_WAIT_RESPONSE }

enum	xbee_dev_rx_state { XBEE_RX_STATE_WAITSTART = 0, XBEE_RX_STATE_LENGTH_MSB, XBEE_RX_STATE_LENGTH_LSB, XBEE_RX_STATE_RXFRAME }

enum	xbee_frame_type { XBEE_FRAME_LOCAL_AT_CMD = 0x08, XBEE_FRAME_LOCAL_AT_CMD_Q = 0x09, XBEE_FRAME_TRANSMIT = 0x10, XBEE_FRAME_TRANSMIT_EXPLICIT = 0x11, XBEE_FRAME_REMOTE_AT_CMD = 0x17, XBEE_FRAME_CREATE_SRC_ROUTE = 0x21, XBEE_FRAME_REG_JOINING_DEV = 0x24, XBEE_FRAME_LOCAL_AT_RESPONSE = 0x88, XBEE_FRAME_MODEM_STATUS = 0x8A, XBEE_FRAME_TRANSMIT_STATUS = 0x8B, XBEE_FRAME_ROUTE_INFORMATION = 0x8D, XBEE_FRAME_AGGREGATE_ADDRESSING = 0x8E, XBEE_FRAME_RECEIVE = 0x90, XBEE_FRAME_RECEIVE_EXPLICIT = 0x91, XBEE_FRAME_IO_RESPONSE = 0x92, XBEE_FRAME_SENDOR_READ = 0x94, XBEE_FRAME_NODE_ID = 0x95, XBEE_FRAME_REMOTE_AT_RESPONSE = 0x97, XBEE_FRAME_FW_UPDATE_STATUS = 0xA0, XBEE_FRAME_ROUTE_RECORD = 0xA1, XBEE_FRAME_DEVICE_AUTHENTICATED = 0xA2, XBEE_FRAME_ROUTE_REQUEST_INDICATOR = 0xA3, XBEE_FRAME_REG_JOINING_DEV_STATUS = 0xA4, XBEE_FRAME_JOIN_NOTIFICATION_STATUS = 0xA5 }

Functions
uint8_t	_xbee_checksum (const void FAR *bytes, uint_fast8_t length, uint_fast8_t initial)

_xbee_device_debug void	_xbee_dev_modem_status (wpan_dev_t *wpan, uint_fast8_t status)

void	_xbee_dispatch_table_dump (const xbee_dev_t *xbee)

int	_xbee_frame_dispatch (xbee_dev_t xbee, const void FAR frame, uint16_t length)

int	_xbee_frame_load (xbee_dev_t *xbee)

void	xbee_dev_dump_settings (xbee_dev_t *xbee, uint16_t flags)
	Print information to stdout about the XBee device. More...

void	xbee_dev_flowcontrol (xbee_dev_t *xbee, bool_t enabled)
	Control whether xbee_frame_write() checks the XBee CTS signal before sending frames. More...

int	xbee_dev_init (xbee_dev_t xbee, const xbee_serial_t serport, xbee_is_awake_fn is_awake, xbee_reset_fn reset)
	Initialize the XBee device structure and open a serial connection to a local, serially-attached XBee module. More...

int	xbee_dev_reset (xbee_dev_t *xbee)
	Toggles the reset line of the XBee device. More...

int	xbee_dev_tick (xbee_dev_t *xbee)
	Check for newly received frames on an XBee device and dispatch them to registered frame handlers. More...

int	xbee_frame_dump_modem_status (xbee_dev_t xbee, const void FAR frame, uint16_t length, void FAR *context)
	Frame handler for 0x8A (XBEE_FRAME_MODEM_STATUS) frames – dumps modem status to STDOUT for debugging purposes. More...

int	xbee_frame_write (xbee_dev_t xbee, const void FAR header, uint16_t headerlen, const void FAR *data, uint16_t datalen, uint16_t flags)
	Copies a frame into the transmit serial buffer to send to an XBee module. More...

void	xbee_identify (xbee_dev_t *xbee, bool_t identify)
	Programs with the ZCL Identify Server Cluster can call this function in their main loop to have the XBee module's association LED flash fast (100ms cycle) when in Identify Mode. More...

uint8_t	xbee_next_frame_id (xbee_dev_t *xbee)
	Increment and return current frame ID for a given XBee device. More...

Variables
uint16_t	bytes_in_frame
	bytes in frame being read; does not include checksum byte More...

uint16_t	bytes_read
	bytes read so far More...

void FAR *	context

char	escape_char
	value of CC (default '+') More...

uint32_t	firmware_version
	Value of XBee module's VR register (4-bytes on some devices) More...

enum xbee_dev_flags	flags
	Multi-purpose flags for tracking information about this device. More...

uint8_t	frame_data [XBEE_MAX_FRAME_LEN+1]
	bytes received, starting with frame_type, +1 is for checksum More...

uint8_t	frame_id
	if 0, match all frames of this type More...

uint8_t	frame_id
	last frame_id used for sending More...

uint8_t	frame_type
	if 0, match all frames More...

uint16_t	guard_time
	value of GT (default 1000) * 1ms More...

xbee_frame_handler_fn	handler

uint16_t	hardware_version
	Value of XBee module's HV register. More...

uint16_t	idle_timeout
	value of CT (default 100) * 100ms More...

xbee_is_awake_fn	is_awake
	Optional function to read AWAKE pin. More...

enum xbee_dev_mode	mode
	Current mode of the XBee device (e.g., boot loader, API, command). More...

uint32_t	mode_timer
	MS_TIMER value used for timeouts. More...

xbee_disc_node_id_fn	node_id_handler
	Optional function to receive parsed Node ID messages. More...

xbee_reset_fn	reset
	Optional function to control reset pin. More...

struct xbee_dev_t::rx	rx

xbee_serial_t	serport
	Platform-specific structure required by xbee_serial.c. More...

enum xbee_dev_rx_state	state
	current state of receiving a frame More...

uint8_t	status

wpan_dev_t	wpan_dev
	Generic WPAN device required by the ZigBee Networking layers of the API. More...

const xbee_dispatch_table_entry_t	xbee_frame_handlers []

Function Pointer Prototypes
Function pointer prototypes, forward declaration using "struct xbee_dev_t" instead of "xbee_dev_t" since we use the types in the xbee_dev_t definition.
typedef int(*	xbee_frame_handler_fn) (struct xbee_dev_t xbee, const void FAR frame, uint16_t length, void FAR *context)
	Standard API for an XBee frame handler in xbee_frame_handlers global. These functions are only called when xbee_dev_tick() or wpan_tick() are called and a complete frame is ready for processing. More...

typedef int(*	xbee_is_awake_fn) (struct xbee_dev_t *xbee)
	Function to check the XBee device's AWAKE pin to see if it is awake. More...

typedef void(*	xbee_reset_fn) (struct xbee_dev_t *xbee, bool_t asserted)
	Function to toggle the /RESET pin to the XBee device. More...

typedef void(*	xbee_disc_node_id_fn) (struct xbee_dev_t xbee, const struct xbee_node_id_t rec)
	Function to process parsed Node ID messages. More...

Detailed Description

This layer provides a frame-based interface to the XBee module. It uses a table of frame handlers to dispatch complete frames to higher layers of the API. If built with a dynamic

Typedef Documentation

typedef struct xbee_dev_t xbee_dev_t

Note

This structure must start with a wpan_dev_t so that the device can be used with the wpan library.
Uses function pointers for setting the reset pin and reading the awake pin on the XBee. User code should not call the reset function directly; use xbee_dev_reset() instead so the various network layers will know about the reset.

typedef void(* xbee_disc_node_id_fn) (struct xbee_dev_t *xbee, const struct xbee_node_id_t *rec)

Function to process parsed Node ID messages.

Programs can register a Node ID message handler with this signature to receive Node ID messages (either from ATND responses, Join Notifications, or as a result of Commissioning Button presses).

Parameters

[in]	xbee	XBee device that received the message
[in]	rec	parsed Node ID message or NULL if a targeted discovery timed out

See also: xbee_disc_add_node_id_handler, xbee_disc_remove_node_id_handler, xbee_disc_discover_nodes

typedef struct xbee_dispatch_table_entry xbee_dispatch_table_entry_t

typedef int(* xbee_frame_handler_fn) (struct xbee_dev_t *xbee, const void FAR *frame, uint16_t length, void FAR *context)

Standard API for an XBee frame handler in xbee_frame_handlers global. These functions are only called when xbee_dev_tick() or wpan_tick() are called and a complete frame is ready for processing.

Note: There isn't an actual xbee_frame_handler_fn function in the XBee libraries. This documentation exists as a template for writing frame handlers.

Parameters

[in]	xbee	XBee device that received frame.
[in]	frame	Pointer to frame data. Data starts with the frame type (the 0x7E start byte and frame length are stripped by lower layers of the driver).
[in]	length	Number of bytes in frame.
[in]	context	Handler-specific "context" value, chosen when the handler was registered with xbee_frame_handler_add.

Return values

0	successfully processed frame
!0	error processing frame

xbee_frame_modem_status_t

Initial value:

{

uint8_t frame_type

uint8_t

unsigned char uint8_t

A unsigned char variable 8 bits.

Definition: types.h:43

typedef int(* xbee_is_awake_fn) (struct xbee_dev_t *xbee)

Function to check the XBee device's AWAKE pin to see if it is awake.

Parameters

[in] xbee XBee device that received frame

Return values

!0	XBee module is awake.
0	XBee module is asleep.

typedef void(* xbee_reset_fn) (struct xbee_dev_t *xbee, bool_t asserted)

Function to toggle the /RESET pin to the XBee device.

Parameters

[in]	xbee	XBee device that received frame
[in]	asserted	non-zero to assert /RESET, zero to de-assert

Enumeration Type Documentation

enum xbee_dev_flags

Enumerator
XBEE_DEV_FLAG_CMD_INIT	xbee_cmd_init called
XBEE_DEV_FLAG_QUERY_BEGIN	started querying device
XBEE_DEV_FLAG_QUERY_DONE	querying completed
XBEE_DEV_FLAG_QUERY_ERROR	querying timed out or error
XBEE_DEV_FLAG_QUERY_REFRESH	need to re-query device
XBEE_DEV_FLAG_QUERY_INPROGRESS	query is in progress
XBEE_DEV_FLAG_IN_TICK	in xbee_dev_tick
XBEE_DEV_FLAG_COORDINATOR	Node Type is Coordinator.
XBEE_DEV_FLAG_ROUTER	Node Type is Router.
XBEE_DEV_FLAG_ENDDEV	Node Type is End Device.
XBEE_DEV_FLAG_ZNET	Firmware is ZNet.
XBEE_DEV_FLAG_ZIGBEE	Firmware is ZigBee.
XBEE_DEV_FLAG_DIGIMESH	Firmware is DigiMesh.
XBEE_DEV_FLAG_USE_FLOWCONTROL	Check CTS before sending.

enum xbee_dev_mode

Enumerator
XBEE_MODE_UNKNOWN	Haven't started communicating with XBee yet.
XBEE_MODE_BOOTLOADER	XBee is in the bootloader, not running firmware
XBEE_MODE_API	XBee is using API firmware.
XBEE_MODE_IDLE	idle mode, data sent is passed to remote XBee
XBEE_MODE_PRE_ESCAPE	command mode, can send AT commands to XBee
XBEE_MODE_POST_ESCAPE	wait for guard-time ms before sending +++
XBEE_MODE_COMMAND	wait guard-time ms for "OK\r" before command mode
XBEE_MODE_WAIT_IDLE	waiting for OK response to ATCN command
XBEE_MODE_WAIT_RESPONSE	sent a command and now waiting for a response

enum xbee_dev_rx_state

Enumerator
XBEE_RX_STATE_WAITSTART	waiting for initial 0x7E
XBEE_RX_STATE_LENGTH_MSB	waiting for MSB of length (first byte)
XBEE_RX_STATE_LENGTH_LSB	waiting for LSB of length (second byte)
XBEE_RX_STATE_RXFRAME	receiving frame and/or trailing checksum

enum xbee_frame_type

Possible values for the frame_type field of frames sent to and from the XBee module. Values with the upper bit set (0x80) are frames we receive from the XBee module. Values with the upper bit clear are for frames we send to the XBee.

Enumerator
XBEE_FRAME_LOCAL_AT_CMD	Send an AT Command to the local device (see xbee_atcmd.c, xbee_header_at_request_t). [ZigBee, DigiMesh]
XBEE_FRAME_LOCAL_AT_CMD_Q	Queue an AT command for batch processing on the local device. [ZigBee, DigiMesh]
XBEE_FRAME_TRANSMIT	Send data to a default endpoint and cluster on a remote device. [ZigBee, DigiMesh, not Smart Energy]
XBEE_FRAME_TRANSMIT_EXPLICIT	Send data to a specific endpoint and cluster on a remote device (see xbee_wpan.c). [ZigBee, DigiMesh]
XBEE_FRAME_REMOTE_AT_CMD	Send an AT command to a remote device on the network (see xbee_atcmd.c, xbee_header_at_request_t). [ZigBee, DigiMesh, not Smart Energy]
XBEE_FRAME_CREATE_SRC_ROUTE	Create Source Route (used with many-to-one routing) [ZigBee].
XBEE_FRAME_REG_JOINING_DEV	Register Joining Device (add device to trust center's key table) [Smart Energy, coordinator]
XBEE_FRAME_LOCAL_AT_RESPONSE	Response from local device to AT Command (see xbee_atcmd.c, xbee_cmd_response_t). [ZigBee, DigiMesh]
XBEE_FRAME_MODEM_STATUS	Current modem status (see xbee_frame_modem_status_t). [DigiMesh, ZigBee].
XBEE_FRAME_TRANSMIT_STATUS	Frame sent upon completion of a Transmit Request. [DigiMesh, ZigBee].
XBEE_FRAME_ROUTE_INFORMATION	Route Information Frame, sent for DigiMesh unicast transmissions with NACK or Trace Route Enable transmit options set. [DigiMesh]
XBEE_FRAME_AGGREGATE_ADDRESSING	Output when a node receives an address update frame and modifies its DH/DL registers. [DigiMesh]
XBEE_FRAME_RECEIVE	Data received on the transparent serial cluster, when ATAO is set to 0. [ZigBee, DigiMesh]
XBEE_FRAME_RECEIVE_EXPLICIT	Data received for specific endpoint/cluster (see xbee_wpan.c), when ATAO is non-zero. [ZigBee, DigiMesh]
XBEE_FRAME_IO_RESPONSE	[ZigBee, not Smart Energy]
XBEE_FRAME_SENDOR_READ	[ZigBee, not Smart Energy]
XBEE_FRAME_NODE_ID	[ZigBee, DigiMesh, not Smart Energy]
XBEE_FRAME_REMOTE_AT_RESPONSE	Response from remote device to AT Command (see xbee_atcmd.c, xbee_cmd_response_t). [ZigBee, DigiMesh, not Smart Energy]
XBEE_FRAME_FW_UPDATE_STATUS	Over-the-Air Firmware Update Status [ZigBee, not Smart Energy].
XBEE_FRAME_ROUTE_RECORD	Route records received in response to a Route Request. [ZigBee].
XBEE_FRAME_DEVICE_AUTHENTICATED	Information on device authenticated on Smart Energy network. [Smart Energy, coordinator]
XBEE_FRAME_ROUTE_REQUEST_INDICATOR	Many-to-One Route Request Indicator [ZigBee].
XBEE_FRAME_REG_JOINING_DEV_STATUS	Frame sent in response to Register Joining Device frame (XBEE_FRAME_REG_JOINING_DEV). [Smart Energy, coordinator]
XBEE_FRAME_JOIN_NOTIFICATION_STATUS	Frame notifying trust center that a device has attempted to join, rejoin or leave the network. Enabled by setting bit 1 of ATDO. [Smart Energy, coordinator]

Function Documentation

uint8_t _xbee_checksum	(	const void FAR *	bytes,
		uint_fast8_t	length,
		uint_fast8_t	initial
	)

_xbee_device_debug void _xbee_dev_modem_status	(	wpan_dev_t *	wpan,
		uint_fast8_t	status
	)

_xbee_device_debug void _xbee_dispatch_table_dump ( const xbee_dev_t * xbee )

_xbee_device_debug int _xbee_frame_dispatch	(	xbee_dev_t *	xbee,
		const void FAR *	frame,
		uint16_t	length
	)

_xbee_device_debug int _xbee_frame_load ( xbee_dev_t * xbee )

_xbee_device_debug void xbee_dev_dump_settings	(	xbee_dev_t *	xbee,
		uint16_t	flags
	)

Print information to stdout about the XBee device.

Default behavior is to print the name of the serial port, the XBee module's hardware version (ATHV), firmware version (ATVR), IEEE address (ATSH/ATSL) and network address (ATMY).

Assumes the user has already called xbee_cmd_init_device() and waited for xbee_cmd_query_status() to finish.

Parameters

[in]	xbee
[in]	flags	XBEE_DEV_DUMP_FLAG_NONE: default settings

See also: xbee_cmd_init_device(), xbee_cmd_query_status(), xbee_ser_portname()

_xbee_device_debug void xbee_dev_flowcontrol	(	xbee_dev_t *	xbee,
		bool_t	enabled
	)

Control whether xbee_frame_write() checks the XBee CTS signal before sending frames.

Flow control is enabled in xbee_dev_init() by default.

Parameters

[in,out]	xbee	XBee to configure
[in]	enabled	TRUE to enable checking CTS before sending

See also: xbee_dev_init(), xbee_frame_write()

_xbee_device_debug int xbee_dev_init	(	xbee_dev_t *	xbee,
		const xbee_serial_t *	serport,
		xbee_is_awake_fn	is_awake,
		xbee_reset_fn	reset
	)

Initialize the XBee device structure and open a serial connection to a local, serially-attached XBee module.

This function does not actually initiate communications with the XBee module. See xbee_cmd_init_device() for information on initializing the "AT Command" layer of the driver, which will read basic information from the XBee module.

Parameters

[in]	xbee	XBee device to initialize.
[in]	serport	Pointer to an xbee_serial_t structure used to initialize xbee->serport.
[in]	is_awake	Pointer to function that reads the XBee module's "ON" pin. The function should return 1 if XBee is on and 0 if it is off.

1 int is_awake( xbee_dev_t *xbee);

Parameters

[in] reset Pointer to function that asserts the XBee module's "/RESET" pin. If asserted is TRUE, puts the XBee into reset. If asserted is FALSE, takes it out of reset. No return value.

1 void xbee_reset( xbee_dev_t *xbee, bool_t asserted);

Return values

0	Success
-EINVAL	Invalid parameter (xbee is NULL, serport is not valid, etc.)
-EIO	Couldn't set serial port baudrate within 5% of serport->baudrate.

_xbee_device_debug int xbee_dev_reset ( xbee_dev_t * xbee )

Toggles the reset line of the XBee device.

Parameters

[in] xbee XBee device to reset.

Return values

0	Successfully toggled reset.
-EINVAL	Invalid xbee_dev_t passed to function.
-EIO	This XBee device doesn't have an interface to the module's reset pin.

_xbee_device_debug int xbee_dev_tick ( xbee_dev_t * xbee )

Check for newly received frames on an XBee device and dispatch them to registered frame handlers.

A program with an XBee interface needs to call this function often enough to keep up with inbound bytes.

Execution time depends greatly on how long each frame handler takes to process its frame.

Warning: This function is NOT re-entrant and will return -EBUSY if it is called when already running.

Parameters

[in] xbee XBee device to check for, and then dispatch, new frames.

Return values

>=0	Number of frames received and dispatched.
-EINVAL	If xbee isn't a valid device structure.
-EBUSY	If xbee_dev_tick() was called when it's already running for this device.

_xbee_device_debug int xbee_frame_dump_modem_status	(	xbee_dev_t *	xbee,
		const void FAR *	frame,
		uint16_t	length,
		void FAR *	context
	)

Frame handler for 0x8A (XBEE_FRAME_MODEM_STATUS) frames – dumps modem status to STDOUT for debugging purposes.

View the documentation of xbee_frame_handler_fn() for this function's parameters and return value.

See also: XBEE_FRAME_MODEM_STATUS_DEBUG, xbee_frame_handler_fn()

_xbee_device_debug int xbee_frame_write	(	xbee_dev_t *	xbee,
		const void FAR *	header,
		uint16_t	headerlen,
		const void FAR *	data,
		uint16_t	datalen,
		uint16_t	flags
	)

Copies a frame into the transmit serial buffer to send to an XBee module.

Header should include bytes as they will be sent to the XBee. Function accepts separate header and data to limit the amount of copying necessary to send requests.

This function should only be called after xbee has been initialized by calling xbee_dev_init().

By default, xbee_frame_write() checks the /CTS signal from the XBee before attempting to send, and will return -EBUSY if the XBee has deasserted CTS. Use xbee_dev_flowcontrol() to disable this check (necessary on a system without a connection to the XBee module's /CTS signal).

Parameters

[in]	xbee	XBee device to send to.
[in]	header	Pointer to the header to send. Header starts with the frame type (this function will pre-pend the 0x7E start-of-frame and 16-bit length). Pass `NULL` if there isn't a header and the entire frame is in the payload (data and datalen).
[in]	headerlen	Number of header bytes to send (starting with address passed in header). Ignored if header is `NULL`.
[in]	data	Address of frame payload or `NULL` if the entire frame content is stored in the header bytes (header and headerlen).
[in]	datalen	Number of payload bytes to send (starting with address passed in data). Ignored if data is `NULL`.
[in]	flags	Optional flags XBEE_WRITE_FLAG_NONE

Return values

0	Successfully queued frame in transmit serial buffer.
-EINVAL	xbee is `NULL` or invalid flags passed
-ENODATA	No data to send (headerlen + datalen == 0).
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).
-EMSGSIZE	Serial buffer can't ever send a frame this large.

See also: xbee_dev_init(), xbee_serial_write(), xbee_dev_flowcontrol()

void xbee_identify	(	xbee_dev_t *	xbee,
		bool_t	identify
	)

Programs with the ZCL Identify Server Cluster can call this function in their main loop to have the XBee module's association LED flash fast (100ms cycle) when in Identify Mode.

Parameters