Modules
	HAL: libdigiapix (Digi ConnectCore)
	Support for Digi International products using libdigiapix to control GPIO pins.

	HAL: DOS16/OpenWatcom
	DOS platform (using Watcom C cross compiler)

	HAL: EFM32/Simplicity Studio

	HAL: Freescale/Codewarrior (Programmable XBee)
	Freescale HCS08 platform (XBee Programmable using CodeWarrior).

	HAL: Freescale KL25/mbed.org
	Freescale KL25 platform using mbed.org.

	HAL: POSIX (Linux/Mac)
	POSIX platforms (e.g., Linux, BSD, Mac OS X).

	HAL: Rabbit/Dynamic C
	Rabbit 4000/5000/6000 processors using Dynamic C 10.

	HAL: Win32/MinGW/gcc
	32-bit Windows (Win32) using MinGW and gcc.

Files
file	platform.h
	Common header for Hardware Abstraction Layer.

Macros
#define	XBEE_BEGIN_DECLS
	Macro defined to. More...

#define	XBEE_END_DECLS
	Macro defined to. More...

#define	ZCL_TIME_EPOCH_DELTA_1980 ((UINT32_C(20) * 365 + 5) * 24 * 60 * 60)
	For 1/1/1980 epoch (Rabbit), add 20 years, plus 5 leap days (1980, 1984, 1988, 1992, 1996) to get to ZigBee epoch of 1/1/2000. More...

#define	ZCL_TIME_EPOCH_DELTA_1970 ((UINT32_C(30) * 365 + 7) * 24 * 60 * 60)
	For 1/1/1970 epoch (Win32, Unix), add 30 years, plus 7 leap days (1972, 1976, 1980, 1984, 1988, 1992, 1996) to get to ZigBee epoch of 1/1/2000. More...

#define	TRUE 1

#define	FALSE 0

#define	xbee_get_unaligned16(p) ((uint16_t FAR )(p))

#define	xbee_get_unaligned32(p) ((uint32_t FAR )(p))

#define	xbee_set_unaligned16(p, v) (uint16_t FAR )(p) = (v)

#define	xbee_set_unaligned32(p, v) (uint32_t FAR )(p) = (v)

#define	_TABLE_ENTRIES(array) ((sizeof (array)) / (sizeof (*array)))
	Helper macro for calculating the number of entries in an array.

#define	XBEE_TIMER_COMPARE(a, op, b) ( ((int16_t)((uint16_t)(a) - (uint16_t)(b))) op 0 )
	Compare two uint16_t timer values, with proper handling of rollover (e.g., 0xFFFF < 0x0000). More...

#define	XBEE_SET_TIMEOUT_MS(delay) ((uint16_t)xbee_millisecond_timer() + (delay))
	Macro used to load a variable with an expiration time, later used with XBEE_CHECK_TIMEOUT_MS() macro. More...

#define	XBEE_CHECK_TIMEOUT_MS(timer) ((int16_t)((uint16_t)xbee_millisecond_timer() - (timer)) >= 0)
	Macro used to check a timer set by XBEE_SET_TIMEOUT_MS(). More...

#define	XBEE_SET_TIMEOUT_SEC(delay) ((uint16_t)xbee_seconds_timer() + (delay))
	Macro used to load a variable with an expiration time, later used with XBEE_CHECK_TIMEOUT_SEC() macro. More...

#define	XBEE_CHECK_TIMEOUT_SEC(timer) ((int16_t)((uint16_t)xbee_seconds_timer() - (timer)) >= 0)
	Macro used to check a timer set by XBEE_SET_TIMEOUT_SEC(). More...

Functions
uint32_t()	xbee_seconds_timer (void)
	Platform-specific function to return the number of elapsed seconds. More...

uint32_t()	xbee_millisecond_timer (void)
	Platform-specific function to return the number of elapsed milliseconds. More...

int	hexstrtobyte (const char FAR *p)
	Converts two hex characters (0-9A-Fa-f) to a byte. More...

int	xbee_readline (char *buffer, int length)
	This function is a non-blocking version of gets(), used to read a line of input from the user. More...

void	hex_dump (const void FAR *address, uint16_t length, uint16_t flags)
	Helper function for printing a hex dump of memory to stdout. More...

int	memcheck (const void FAR *src, int c, size_t length)
	Test whether a block of memory is set to a single byte value. More...

error codes
These error names are used throughout the library. Some platforms don't define them in errno.h, so we define them here using arbitrary values.
#define	E2BIG 20007
	argument list too long (POSIX.1)

#define	EACCES 20016
	permission denied (POSIX.1)

#define	EAGAIN 20014
	resource temporarily unavailable (POSIX.1)

#define	EBADMSG 20010
	bad message (POSIX.1)

#define	EBUSY 20003
	device or resource busy (POSIX.1)

#define	ECANCELED 20017
	operation canceled (POSIX.1)

#define	EEXIST 20004
	file exists (POSIX.1)

#define	EILSEQ 20013
	illegal byte sequence (POSIX.1, C99)

#define	EINVAL 20001
	invalid argument (POSIX.1)

#define	EIO 20002
	input/output error (POSIX.1)

#define	EMSGSIZE 20018
	message too long (POSIX.1)

#define	ENODATA 20000
	no message is available on the STREAM head read queue (POSIX.1)

#define	ENOENT 20006
	no such file or directory (POSIX.1)

#define	ENOSPC 20005
	no space left on device (POSIX.1)

#define	ENOSYS 20015
	function not implemented (POSIX.1)

#define	ENOTSUP 20011
	operation not supported (POSIX.1)

#define	EPERM 20019
	operation not permitted (POSIX.1)

#define	ETIMEDOUT 20012
	connection timed out (POSIX.1)

Platform-specific Macros
Documentation for things that must be defined in the platform-specific header files.
#define	XBEE_RESET_FN NULL
	Function pointer to pass to xbee_dev_init() in shared sample code for the xbee_reset_fn parameter. More...

#define	XBEE_IS_AWAKE_FN NULL
	Function pointer to pass to xbee_dev_init() in shared sample code for the xbee_is_awake_fn parameter. More...

#define	XBEE_SERIAL_MAX_BAUDRATE 115200
	Maximum baud rate supported by serial ports. More...

#define	XBEE_UNUSED_PARAMETER(p) (void) p
	Functions with unused parameters (common due to the use of function pointers) can use this macro to dismiss compiler warnings about unused parameters. More...

#define	PACKED_STRUCT struct
	Deprecated macro, replaced by XBEE_PACKED(). More...

#define	INTERRUPT_DISABLE
	Disable CPU interrupts (at the level of the serial port driver, at least).

#define	INTERRUPT_ENABLE
	Enable CPU interrupts (at the level of the serial port driver, at least). More...

platform_far
Macros related to supporting far (>16-bit) pointers.
#define	FAR
	On platforms with "far" pointers, define to the proper keyword; empty definition if not required.

#define	CAST_FAR_TO_NEAR(p) (p)
	On platforms with "far" pointers, define to a series of explicit casts to convert a "far" pointer back to "near". More...

#define	PRIsFAR "s"
	Literal string format specifier for printing a far string, typically `"s"`.

#define	PRIpFAR "p"
	Literal string format specifier for printing a far pointer, typically `"p"`.

platform_inttypes
Macros typically defined in <inttypes.h>, define manually if inttypes.h is not available on this platform.
#define	PRId16 "hd"
	Format specifier for 16-bit signed (usually `"d"` or `"hd"`)

#define	PRId32 "ld"
	Format specifier for 32-bit signed (usually `"ld"` or `"d"`)

#define	PRIu16 "hu"
	Format specifier for 16-bit unsigned (usually `"u"` or `"hu"`)

#define	PRIu32 "lu"
	Format specifier for 32-bit unsigned (usually `"lu"` or `"u"`)

#define	PRIx16 "hx"
	Format specifier for 16-bit lowercase hex (usually `"x"` or `"hx"`)

#define	PRIx32 "lx"
	Format specifier for 32-bit lowercase hex (usually `"lx"` or `"x"`)

#define	PRIX16 "hX"
	Format specifier for 16-bit uppercase hex (usually `"X"` or `"hX"`)

#define	PRIX32 "lX"
	Format specifier for 32-bit uppercase hex (usually `"lX"` or `"X"`)

Flags to pass to hex_dump().
#define	HEX_DUMP_FLAG_NONE 0x0000
	Default settings (no prefix).

#define	HEX_DUMP_FLAG_OFFSET 0x0001
	Prefix each line with the memory offset (0000: xx xx xx).

#define	HEX_DUMP_FLAG_ADDRESS 0x0002
	Prefix each line with the address (uses p specifier) (000000: xx xx xx).

#define	HEX_DUMP_FLAG_TAB 0x0004
	Prefix each line with a tab character.

Detailed Description

Macro Definition Documentation

#define CAST_FAR_TO_NEAR ( p ) (p)

On platforms with "far" pointers, define to a series of explicit casts to convert a "far" pointer back to "near".

Only appropriate for pointers that are known to be near.

Referenced by xbee_cmd_init_device().

#define INTERRUPT_ENABLE

Enable CPU interrupts (at the level of the serial port driver, at least).

INTERRUPT_DISABLE/INTERRUPT_ENABLE are used without nesting in the library, so these can be low-level functions or in-line assembler. Note that uses of these macros add a semicolon.

Referenced by xbee_dev_tick(), xbee_ser_rx_flush(), xbee_ser_tx_flush(), and xbee_ser_write().

#define PACKED_STRUCT struct

Deprecated macro, replaced by XBEE_PACKED().

Defaults to just [struct].

#define XBEE_BEGIN_DECLS

Macro defined to.

1 extern "C" {

when used by a C++ compiler. Used (along with XBEE_END_DECLS) for header file declarations to allow linking C-compiled code into C++ projects.

#define XBEE_CHECK_TIMEOUT_MS ( timer ) ((int16_t)((uint16_t)xbee_millisecond_timer() - (timer)) >= 0)

Macro used to check a timer set by XBEE_SET_TIMEOUT_MS().

See the documentation for XBEE_SET_TIMEOUT_MS() for a code example on proper use of this macro.

Parameters

[in] timer 16-bit variable set by XBEE_SET_TIMEOUT_MS().

Return values

TRUE	Time specified in call to XBEE_SET_TIMEOUT_MS() has elapsed.
FALSE	Time specified has not yet elapsed.

See also: XBEE_SET_TIMEOUT_MS(), XBEE_SET_TIMEOUT_SEC(), XBEE_CHECK_TIMEOUT_SEC()

Referenced by _sxa_io_process_response(), and xbee_dev_reset().

#define XBEE_CHECK_TIMEOUT_SEC ( timer ) ((int16_t)((uint16_t)xbee_seconds_timer() - (timer)) >= 0)

Macro used to check a timer set by XBEE_SET_TIMEOUT_SEC().

See the documentation for XBEE_SET_TIMEOUT_SEC() for a code example on proper use of this macro.

Parameters

[in] timer 16-bit variable set by XBEE_SET_TIMEOUT_SEC().

Return values

TRUE	Time specified in call to XBEE_SET_TIMEOUT_SEC() has elapsed.
FALSE	Time specified has not yet elapsed.

See also: XBEE_SET_TIMEOUT_SEC(), XBEE_SET_TIMEOUT_MS(), XBEE_CHECK_TIMEOUT_MS()

Referenced by xbee_cmd_tick().

#define XBEE_END_DECLS

Macro defined to.

1 }

when used by a C++ compiler. Used (along with XBEE_BEGIN_DECLS) for header file declarations to allow linking C-compiled code into C++ projects.

#define XBEE_IS_AWAKE_FN NULL

Function pointer to pass to xbee_dev_init() in shared sample code for the xbee_is_awake_fn parameter.

Set to NULL by default.

#define XBEE_RESET_FN NULL

Function pointer to pass to xbee_dev_init() in shared sample code for the xbee_reset_fn parameter.

Set to NULL by default.

#define XBEE_SERIAL_MAX_BAUDRATE 115200

Maximum baud rate supported by serial ports.

Gen3 bootloader interface (xbee_bl_gen3.c) will switch up to 921600 if supported. Defaults to [115200].

#define XBEE_SET_TIMEOUT_MS ( delay ) ((uint16_t)xbee_millisecond_timer() + (delay))

Macro used to load a variable with an expiration time, later used with XBEE_CHECK_TIMEOUT_MS() macro.

For timeouts longer than 32767 milliseconds (with less accuracy), use XBEE_SET_TIMEOUT_SEC()/XBEE_CHECK_TIMEOUT_SEC().

Parameters

[in] delay Timeout in milliseconds, from 1 to 32767.

Returns: Value to assign to an unsigned 16-bit variable (uint16_t) for use with CHECK_TIMEOUT_MS().

See also: XBEE_CHECK_TIMEOUT_MS(), XBEE_SET_TIMEOUT_SEC(), XBEE_CHECK_TIMEOUT_SEC()

 uint16_t t;
 
 t = XBEE_SET_TIMEOUT_MS(5000);      // 5 second timeout
 for (;;)
 {
    // do stuff or wait for something to happen
 
    if (XBEE_CHECK_TIMEOUT_MS(t))
    {
       // 5 seconds elapsed
       break;
    }
 }

Referenced by _sxa_io_process_response(), and xbee_dev_reset().

#define XBEE_SET_TIMEOUT_SEC ( delay ) ((uint16_t)xbee_seconds_timer() + (delay))

Macro used to load a variable with an expiration time, later used with XBEE_CHECK_TIMEOUT_SEC() macro.

For a more precise timeout, for values of 30 seconds or less, use XBEE_SET_TIMEOUT_MS()/XBEE_CHECK_TIMEOUT_MS() instead.

Parameters

[in] delay Timeout in seconds, from 1 to 32767.

Returns: Value to assign to an unsigned 16-bit variable (uint16_t) for use with XBEE_CHECK_TIMEOUT_SEC().

See also: XBEE_CHECK_TIMEOUT_SEC(), XBEE_SET_TIMEOUT_MS(), XBEE_CHECK_TIMEOUT_MS()

 uint16_t t;
 
 t = XBEE_SET_TIMEOUT_SEC(600);      // 10 minute timeout
 for (;;)
 {
    // do stuff or wait for something to happen
 
    if (XBEE_CHECK_TIMEOUT_SEC(t))
    {
       // 10 minutes elapsed
       break;
    }
 }

Referenced by _xbee_cmd_handle_response(), xbee_cmd_create(), and xbee_cmd_send().

#define XBEE_TIMER_COMPARE	(	a,
		op,
		b
	)	( ((int16_t)((uint16_t)(a) - (uint16_t)(b))) op 0 )

Compare two uint16_t timer values, with proper handling of rollover (e.g., 0xFFFF < 0x0000).

Parameters

[in]	a	first timer value (cast to uint16_t)
[in]	op	operand (> or <) to use when comparing two timers
[in]	b	second timer value (cast to uint16_t)

Returns: The equivalent to "a op b".

Note that when using the millisecond timer, you can only compare times within 32 seconds of each other.

 uint16_t t0;
 
 t0 = (uint16_t) xbee_millisecond_timer();
 do {
    some_stuff_here();
    delay = update_delay();
 } while (XBEE_TIMER_COMPARE( t0 + delay, >, xbee_millisecond_timer()));

#define XBEE_UNUSED_PARAMETER ( p ) (void) p

Functions with unused parameters (common due to the use of function pointers) can use this macro to dismiss compiler warnings about unused parameters.

Defaults to [ (void) p ].

Referenced by _xbee_cmd_handle_response(), _xbee_cmd_modem_status(), _xbee_dispatch_table_dump(), _xbee_handle_receive_explicit(), _xbee_handle_transmit_status(), _zcl_identify_time_get(), _zcl_time_time_get(), _zcl_time_timestatus_set(), xbee_cmd_init_device(), xbee_dev_dump_settings(), xbee_disc_atnd_response_handler(), xbee_disc_nodeid_cluster_handler(), xbee_disc_nodeid_frame_handler(), xbee_frame_dump_ext_mod_status_ss(), xbee_frame_dump_modem_status(), xbee_frame_dump_secure_session_resp(), xbee_frame_dump_transmit_status(), xbee_frame_dump_tx_status(), xbee_frame_write(), and zcl_invalid_cluster().

#define ZCL_TIME_EPOCH_DELTA_1970 ((UINT32_C(30) * 365 + 7) * 24 * 60 * 60)

For 1/1/1970 epoch (Win32, Unix), add 30 years, plus 7 leap days (1972, 1976, 1980, 1984, 1988, 1992, 1996) to get to ZigBee epoch of 1/1/2000.

Referenced by ebl_phy_desc().

#define ZCL_TIME_EPOCH_DELTA_1980 ((UINT32_C(20) * 365 + 5) * 24 * 60 * 60)

For 1/1/1980 epoch (Rabbit), add 20 years, plus 5 leap days (1980, 1984, 1988, 1992, 1996) to get to ZigBee epoch of 1/1/2000.

Function Documentation

void hex_dump	(	const void FAR *	address,
		uint16_t	length,
		uint16_t	flags
	)

Helper function for printing a hex dump of memory to stdout.

A reference implementation is provided in as util/hexdump.c. Dumps data in hex/printable format, 16 bytes to a line, to stdout.

Parameters

[in]	address	Address of data to dump.
[in]	length	Number of bytes to dump.
[in]	flags	One of HEX_DUMP_FLAG_NONE HEX_DUMP_FLAG_OFFSET HEX_DUMP_FLAG_ADDRESS HEX_DUMP_FLAG_TAB

References FAR, HEX_DUMP_FLAG_ADDRESS, HEX_DUMP_FLAG_OFFSET, HEX_DUMP_FLAG_TAB, and PRIpFAR.

Referenced by _pxbee_ota_transparent_rx(), _sxa_disc_process_node_data(), _sxa_io_process_response(), _xbee_frame_dispatch(), _xbee_frame_load(), _zcl_send_read_from_zdo_match(), _zcl_write_attributes(), _zdo_active_ep_respond(), _zdo_match_desc_respond(), wpan_envelope_dump(), xbee_cmd_send(), xbee_ipv4_envelope_dump(), xbee_ser_read(), xbee_ser_write(), zcl_command_dump(), zcl_envelope_payload_dump(), zcl_general_command(), zcl_identify_command(), zcl_ota_upgrade_cluster_handler(), zcl_print_attribute_value(), zcl_time_client(), zdo_handler(), and zdo_send_response().

int hexstrtobyte ( const char FAR * p )

Converts two hex characters (0-9A-Fa-f) to a byte.

Parameters

[in] p String of hex characters to convert.

Return values

-1	Error (invalid character or string less than 2 bytes).
0-255	The byte represented by the first two characters of p.

Examples

hexstrtobyte("FF") returns 255
hexstrtobyte("0") returns -1 (error because < 2 characters)
hexstrtobyte("ABCDEF") returns 0xAB (ignores additional chars)

Referenced by addr64_parse().

int memcheck	(	const void FAR *	src,
		int	c,
		size_t	length
	)

Test whether a block of memory is set to a single byte value.

Parameters

[in]	src	starting address
[in]	c	value to compare each byte to
[in]	length	number of bytes to compare

Return values

0	length bytes from src are set to c
<0	length bytes from src would sort before length bytes of c
>0	length bytes from src would sort before length bytes of c

See also: memcmp, memset

References FAR.

Referenced by xbee_bl_gen3_install_state(), xbee_comm_SC(), and zcl_comm_sas_is_valid().

uint32_t() xbee_millisecond_timer ( void )

Platform-specific function to return the number of elapsed milliseconds.

OK for this counter to rollover. Used for timing and should have a resolution of at least 60ms.

Rabbit has 1ms resolution.
HCS08 has 4ms resolution.
DOS has 18 ticks/second (55.55ms resolution)

(Function name wrapped in parentheses so platforms can use a macro function of the same name.)

Returns: Number of elapsed milliseconds.

See also: XBEE_MS_TIMER_RESOLUTION

References FAR.

int xbee_readline	(	char *	buffer,
		int	length
	)

This function is a non-blocking version of gets(), used to read a line of input from the user.

It waits for a string from stdin terminated by a return. It should be called repeatedly, until it returns a value other than -EAGAIN. The input string, stored in buffer is null-terminated without the return.

The user should make sure only one process calls this function at a time.

Parameters

[in,out]	buffer	buffer to store input from user
[in]	length	size of buffer

Return values

>=0	User ended the input with a newline, return value is number of bytes written.
-EAGAIN	User has not completed a line.
-EINVAL	NULL buffer or length is less than 1.
-ENODATA	User entered CTRL-D to end input.

References EAGAIN, EINVAL, and ENODATA.

uint32_t() xbee_seconds_timer ( void )

Platform-specific function to return the number of elapsed seconds.

On some platforms, this is the equivalent of an "uptime".

On other platforms, it may reflect the value of the RTC, which might not be synchronized with a time server and might include leap seconds.

Regardless, it should consistently report elapsed time and not jump on clock synchronization.

In addition to determining timeouts, the ZCL Time Cluster makes use of it to report current time.

(Function name wrapped in parentheses so platforms can use a macro function of the same name.)

Returns: Number of elapsed seconds.

Modules

Files

Macros

Functions

error codes

Platform-specific Macros

platform_far

platform_inttypes

Detailed Description

Macro Definition Documentation

Function Documentation