This layer provides a frame-based interface to the XBee module.

More...

Files
file	device.h

file	xbee_device.c
	Code related to processing XBee Frames.

Data Structures
struct	xbee_dispatch_table_entry_t

struct	xbee_dev_t

struct	xbee_frame_modem_status_t
	< XBEE_FRAME_MODEM_STATUS (0x8A) See XBEE_MODEM_STATUS_* More...

Macros
#define	xbee_zcl_identify(xbee) xbee_identify( xbee, zcl_identify_isactive() > 0)
	Programs with the ZCL Identify Server Cluster can call this macro in their main loop to have the XBee module's association LED flash fast (100ms cycle) when in Identify Mode. More...

#define	XBEE_DEV_MAX_DISPATCH_PER_TICK 5
	Maximum number of frames to dispatch per call to xbee_tick().

#define	XBEE_MAX_RFPAYLOAD 256
	Smart Energy and ZigBee are limited to 128 bytes, DigiMesh is 256 bytes.

#define	XBEE_MAX_RX_FRAME_LEN (XBEE_MAX_RFPAYLOAD + 18)
	Max Received Frame Size, including type, is for 0x91, Receive Explicit. More...

#define	XBEE_MAX_TX_FRAME_LEN (XBEE_MAX_RFPAYLOAD + 20)
	Max Transmitted Frame Size, including type, is for 0x11, Transmit Explicit. More...

#define	XBEE_MAX_FRAME_LEN XBEE_MAX_RX_FRAME_LEN
	Deprecated legacy macro, use XBEE_MAX_RX_FRAME_LEN instead.

#define	XBEE_DEV_STACK_VERSION_ADDR(x) ((uint8_t *)&(x).firmware_version + 3)
	Macro function to get a pointer to the LSB of the radio's firmware version. More...

#define	XBEE_FRAME_TABLE_END { 0xFF, 0, NULL, NULL }

#define	XBEE_DEV_DUMP_FLAG_NONE 0x0000

#define	XBEE_DEV_DUMP_FLAG_DEFAULT XBEE_DEV_DUMP_FLAG_NONE

#define	XBEE_WRITE_FLAG_NONE 0x0000

#define	XBEE_FRAME_MODEM_STATUS_DEBUG { XBEE_FRAME_MODEM_STATUS, 0, xbee_frame_dump_modem_status, NULL }
	Add this macro to the list of XBee frame handlers to have modem status changes dumped to STDOUT.

#define	_xbee_device_debug

Enumerations
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 }
	Possible values for the `frame_type` field of frames sent to and from the XBee module. More...

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_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 }

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

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

void	xbee_dev_dump_settings (xbee_dev_t *xbee, uint16_t flags)
	Print information to stdout about the XBee device. 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_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_dev_flowcontrol (xbee_dev_t *xbee, bool_t enabled)
	Control whether xbee_frame_write() checks the XBee CTS signal before sending frames. More...

void	_xbee_dispatch_table_dump (const xbee_dev_t *xbee)

uint8_t	_xbee_checksum (const void FAR *bytes, uint16_t length, uint_fast8_t initial)
	Calculate the checksum for an XBee frame. More...

int	_xbee_frame_load (xbee_dev_t *xbee)
	Check XBee's serial buffer for complete frames and pass them off to the dispatcher. More...

int	_xbee_frame_dispatch (xbee_dev_t xbee, const void FAR frame, uint16_t length)
	Function called by _xbee_frame_load() to dispatch any frames read. 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...

void	_xbee_dev_modem_status (wpan_dev_t *wpan, uint_fast8_t status)
	Receive modem status frames and update flags/state of wpan_dev_t. More...

Variables
const xbee_dispatch_table_entry_t	xbee_frame_handlers []
	Static table used for dispatching frames. More...

Flags used by functions in this module.
#define	XBEE_DEV_FLAG_NONE 0x0000

Values for the `options` field of many receive frame types.
#define	XBEE_RX_OPT_ACKNOWLEDGED 0x01

#define	XBEE_RX_OPT_BROADCAST 0x02
	XBee Receive Options: broadcast packet [ZigBee, DigiMesh].

#define	XBEE_RX_OPT_SENT_ENCRYPTED 0x10
	XBee Receive Options: received encrypted via Secure Session [XBee3].

#define	XBEE_RX_OPT_APS_ENCRYPT 0x20
	XBee Receive Options: APS-encrypted packet [ZigBee].

#define	XBEE_RX_OPT_FROM_END_DEVICE 0x40
	XBee Receive Options: packet from end device (if known) [ZigBee].

#define	XBEE_RX_OPT_MODE_MASK 0xC0
	XBee Receive Options: Mask for transmission mode [DigiMesh].

#define	XBEE_RX_OPT_MODE_NONE (0)
	XBee Receive Options: Mode not specified [DigiMesh].

#define	XBEE_RX_OPT_MODE_POINT_MULTIPOINT (1<<6)
	XBee Receive Options: Point-Multipoint [DigiMesh].

#define	XBEE_RX_OPT_MODE_REPEATER (2<<6)
	XBee Receive Options: Repeater Mode [DigiMesh].

#define	XBEE_RX_OPT_MODE_DIGIMESH (3<<6)
	XBee Receive Options: DigiMesh (not available on 10k product) [DigiMesh].

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

XBEE_MODEM_STATUS_*
Values for `status` member of xbee_frame_modem_status_t.
#define	XBEE_MODEM_STATUS_HW_RESET 0x00
	XBee Modem Status: Hardware reset [ZigBee, DigiMesh, Wi-Fi].

#define	XBEE_MODEM_STATUS_WATCHDOG 0x01
	XBee Modem Status: Watchdog timer reset [ZigBee, DigiMesh, Wi-fi].

#define	XBEE_MODEM_STATUS_JOINED 0x02
	XBee Modem Status: Joined network (routers and end devices) [ZigBee, Wi-Fi].

#define	XBEE_MODEM_STATUS_DISASSOC 0x03
	XBee Modem Status: Disassociated (left network) [ZigBee, Wi-Fi].

#define	XBEE_MODEM_STATUS_IP_CONFIG_ERROR 0x04
	XBee Modem Status: IP configuration error [Wi-Fi].

#define	XBEE_MODEM_STATUS_COORD_START 0x06
	XBee Modem Status: Coordinator started [ZigBee].

#define	XBEE_MODEM_STATUS_NETWORK_KEY_UPDATED 0x07
	XBee Modem Status: Network security key was updated [ZigBee].

#define	XBEE_MODEM_STATUS_WOKE_UP 0x0B
	XBee Modem Status: Network Woke Up [DigiMesh].

#define	XBEE_MODEM_STATUS_SLEEPING 0x0C
	XBee Modem Status: Network Went To Sleep [DigiMesh].

#define	XBEE_MODEM_STATUS_OVERVOLTAGE 0x0D
	XBee Modem Status: Voltage supply limit exceeded (XBee-PRO only) [ZigBee].

#define	XBEE_MODEM_STATUS_CLOUD_CONNECTED 0x0E
	XBee Modem Status: Device Cloud connected [Wi-Fi].

#define	XBEE_MODEM_STATUS_CLOUD_DISCONNECTED 0x0F
	XBee Modem Status: Device Cloud disconnected [Wi-Fi].

#define	XBEE_MODEM_STATUS_KEY_ESTABLISHED 0x10
	XBee Modem Status: Key establishment complete [Smart Energy].

#define	XBEE_MODEM_STATUS_CONFIG_CHANGE_IN_JOIN 0x11
	XBee Modem Status: Modem config changed while join in progress [ZigBee].

#define	XBEE_MODEM_STATUS_SS_ESTABLISHED 0x3B
	XBee Modem Status: Secure Session Established.

#define	XBEE_MODEM_STATUS_SS_ENDED 0x3C
	XBee Modem Status: Secure Session Ended.

#define	XBEE_MODEM_STATUS_SS_AUTH_FAILED 0x3D
	XBee Modem Status: Secure Session Authentication Failed.

#define	XBEE_MODEM_STATUS_STACK_ERROR 0x80
	XBee Modem Status: Network stack error [ZigBee].

Detailed Description

This layer provides a frame-based interface to the XBee module.

Device layer for XBee module interface.

It uses a table of frame handlers to dispatch complete frames to higher layers of the API.

Macro Definition Documentation

#define XBEE_DEV_STACK_VERSION_ADDR ( x ) ((uint8_t *)&(x).firmware_version + 3)

Macro function to get a pointer to the LSB of the radio's firmware version.

Typically used to define ZCL_STACK_VERSION_ADDR for the Basic cluster.

Parameters

[in] x name of xbee_dev_t to reference firmware_version from.

Returns: address of the low byte of the firmware version, taking the processor's endian-ness into account

#define XBEE_MAX_RX_FRAME_LEN (XBEE_MAX_RFPAYLOAD + 18)

Max Received Frame Size, including type, is for 0x91, Receive Explicit.

See also: XBEE_MAX_TX_FRAME_LEN

Referenced by _xbee_frame_load().

#define XBEE_MAX_TX_FRAME_LEN (XBEE_MAX_RFPAYLOAD + 20)

Max Transmitted Frame Size, including type, is for 0x11, Transmit Explicit.

See also: XBEE_MAX_RX_FRAME_LEN

#define XBEE_RX_OPT_ACKNOWLEDGED 0x01

XBee Receive Options: packet was acknowledged [ZigBee, DigiMesh]

#define xbee_zcl_identify ( xbee ) xbee_identify( xbee, zcl_identify_isactive() > 0)

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

Parameters

[in] xbee device to identify

See also: xbee_identify, zcl_identify_isactive, ZCL_CLUST_ENTRY_IDENTIFY_SERVER

Typedef Documentation

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

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, Wi-Fi, Cellular]
XBEE_FRAME_LOCAL_AT_CMD_Q	Queue an AT command for batch processing on the local device. [ZigBee, DigiMesh, Cellular]
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, Wi-Fi, Cellular]
XBEE_FRAME_MODEM_STATUS	Current modem status (see xbee_frame_modem_status_t). [DigiMesh, ZigBee, Wi-Fi, Cellular]
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,
		uint16_t	length,
		uint_fast8_t	initial
	)

Calculate the checksum for an XBee frame.

This function actually subtracts bytes from 0xFF, in order to determine the proper checksum byte so all bytes added together result in 0x00.

Frame checksums start with the frame type (first byte after frame length).

If calculating a checksum for an outgoing packet, sum all of the bytes using this function, and send the low byte of the result.

If verifying a received packet, summing all of the bytes after the length, including the packet's checksum byte, should result in 0x00.

Should only be used internally by this library.

Parameters

[in]	bytes	Buffer of bytes to add to sum, assumed non-NULL.
[in]	length	Number of bytes to add.
[in]	initial	Starting checksum value. Use 0xFF to start or the result of the previous call if summing multiple blocks of data.

Returns: Value from 0x00 to 0xFF that, when added to all bytes previously checksummed, results in a low byte of 0x00.

References FAR.

Referenced by _xbee_frame_load(), and xbee_frame_write().

void _xbee_dev_modem_status	(	wpan_dev_t *	wpan,
		uint_fast8_t	status
	)

Receive modem status frames and update flags/state of wpan_dev_t.

See also: xbee_frame_handler_fn()

References wpan_dev_t::address, wpan_dev_t::flags, WPAN_FLAG_AUTHENTICATED, WPAN_FLAG_JOINED, WPAN_NET_ADDR_COORDINATOR, WPAN_NET_ADDR_UNDEFINED, XBEE_MODEM_STATUS_COORD_START, XBEE_MODEM_STATUS_DISASSOC, XBEE_MODEM_STATUS_HW_RESET, XBEE_MODEM_STATUS_JOINED, XBEE_MODEM_STATUS_KEY_ESTABLISHED, and XBEE_MODEM_STATUS_WATCHDOG.

Referenced by _xbee_frame_dispatch().

void _xbee_dispatch_table_dump ( const xbee_dev_t * xbee )

Dump the contents of the frame dispatch table for XBee device xbee. Must have XBEE_DEVICE_VERBOSE defined.

Parameters

[in] xbee XBee device of table to dump.

References xbee_dispatch_table_entry_t::frame_id, xbee_dispatch_table_entry_t::frame_type, PRIpFAR, xbee_frame_handlers, and XBEE_UNUSED_PARAMETER.

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

Function called by _xbee_frame_load() to dispatch any frames read.

Scans through xbee->frame_handlers, matching the frame_type and frame_id (if frame_id is not zero). Passes the frame and context (from the frame handler table) to each matching handler.

Parameters

[in]	xbee	XBee device that received the frames.
[in]	frame	Address of bytes in frame, starting with the frame type byte. Note that the frame is still in network byte order – it is exactly as received from the XBee module.
[in]	length	Number of bytes in frame.

Returns: Currently returns 0 in all cases. May be updated at some point with various error messages (e.g., no handlers are registered for the given frame type and ID) or the number of handlers it was dispatched to

Return values

-EINVAL	Invalid parameter
>=0	number of handlers frame was dispatched to

References _xbee_dev_modem_status(), EINVAL, FAR, xbee_dispatch_table_entry_t::frame_id, xbee_dispatch_table_entry_t::frame_type, hex_dump(), HEX_DUMP_FLAG_NONE, PRIpFAR, xbee_dev_t::wpan_dev, xbee_frame_handlers, and XBEE_FRAME_MODEM_STATUS.

Referenced by _xbee_frame_load().

int _xbee_frame_load ( xbee_dev_t * xbee )

Check XBee's serial buffer for complete frames and pass them off to the dispatcher.

Should only be called after xbee has been initialized by calling xbee_dev_init(). Typically called by xbee_dev_tick().

Parameters

[in] xbee XBee device to read from.

Return values

0	No new frames waiting.
>0	Number of frames processed.
<0	Error.

See also: xbee_dev_init(), _xbee_frame_dispatch()

References _xbee_checksum(), _xbee_frame_dispatch(), xbee_dev_t::rx::bytes_in_frame, xbee_dev_t::rx::bytes_read, EINVAL, xbee_dev_t::rx::frame_data, hex_dump(), HEX_DUMP_FLAG_OFFSET, PRIu16, xbee_dev_t::serport, xbee_dev_t::rx::state, XBEE_DEV_MAX_DISPATCH_PER_TICK, XBEE_MAX_RX_FRAME_LEN, XBEE_RX_STATE_LENGTH_LSB, XBEE_RX_STATE_LENGTH_MSB, XBEE_RX_STATE_RXFRAME, XBEE_RX_STATE_WAITSTART, xbee_ser_invalid(), and xbee_ser_read().

Referenced by xbee_dev_tick().

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

References addr64_format(), ADDR64_STRING_LENGTH, wpan_dev_t::address, xbee_dev_t::firmware_version, xbee_dev_t::hardware_series, xbee_dev_t::hardware_version, PRIsFAR, PRIX32, xbee_dev_t::serport, xbee_dev_t::wpan_dev, xbee_ser_portname(), and XBEE_UNUSED_PARAMETER.

Referenced by _sxa_io_process_response().

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

References xbee_dev_t::flags, and XBEE_DEV_FLAG_USE_FLOWCONTROL.

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.

References EINVAL, xbee_dev_t::flags, xbee_dev_t::is_awake, xbee_dev_t::reset, xbee_dev_t::serport, XBEE_DEV_FLAG_USE_FLOWCONTROL, xbee_ser_flowcontrol(), and xbee_ser_open().

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.

References EINVAL, EIO, xbee_dev_t::reset, XBEE_CHECK_TIMEOUT_MS, XBEE_MODE_UNKNOWN, and XBEE_SET_TIMEOUT_MS.

Referenced by xbee_fw_install_ebl_tick(), and xbee_fw_install_oem_tick().

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.
-EIO	Error reading from serial port.

References _xbee_frame_load(), EBUSY, EINVAL, xbee_dev_t::flags, INTERRUPT_DISABLE, INTERRUPT_ENABLE, and XBEE_DEV_FLAG_IN_TICK.

Referenced by _sxa_io_process_response(), and _xbee_wpan_tick().

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

References EINVAL, FAR, XBEE_MODEM_STATUS_CLOUD_CONNECTED, XBEE_MODEM_STATUS_CLOUD_DISCONNECTED, XBEE_MODEM_STATUS_CONFIG_CHANGE_IN_JOIN, XBEE_MODEM_STATUS_COORD_START, XBEE_MODEM_STATUS_DISASSOC, XBEE_MODEM_STATUS_HW_RESET, XBEE_MODEM_STATUS_IP_CONFIG_ERROR, XBEE_MODEM_STATUS_JOINED, XBEE_MODEM_STATUS_KEY_ESTABLISHED, XBEE_MODEM_STATUS_NETWORK_KEY_UPDATED, XBEE_MODEM_STATUS_OVERVOLTAGE, XBEE_MODEM_STATUS_SLEEPING, XBEE_MODEM_STATUS_SS_AUTH_FAILED, XBEE_MODEM_STATUS_SS_ENDED, XBEE_MODEM_STATUS_SS_ESTABLISHED, XBEE_MODEM_STATUS_STACK_ERROR, XBEE_MODEM_STATUS_WATCHDOG, XBEE_MODEM_STATUS_WOKE_UP, and XBEE_UNUSED_PARAMETER.

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

References _xbee_checksum(), EBUSY, EINVAL, EMSGSIZE, ENODATA, FAR, xbee_dev_t::flags, htobe16, xbee_dev_t::serport, XBEE_DEV_FLAG_USE_FLOWCONTROL, xbee_ser_get_cts(), xbee_ser_invalid(), xbee_ser_tx_free(), xbee_ser_tx_used(), xbee_ser_write(), and XBEE_UNUSED_PARAMETER.

Referenced by _xbee_endpoint_send(), xbee_cmd_execute(), xbee_cmd_send(), xbee_cmd_simple(), xbee_fs_req_send_data(), xbee_ipv4_envelope_send(), xbee_register_device(), xbee_secure_session_request(), xbee_sms_send(), xbee_sock_connect(), xbee_sock_create(), xbee_sock_option(), xbee_sock_send(), xbee_sock_sendto(), and xbee_user_data_relay_tx().

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