This layer makes use of lower layers to perform updates on XBee modules.

More...

Files
file	bl_gen3.h
	Code to interface with the "Gen3" XBee bootloader.

file	firmware.h

file	xbee_bl_gen3.c
	Support code for bootloader used on "Gen3" products (including S3B, S6, S6B, XLR, Cellular, SX, SX868, S8).

file	xbee_firmware.c
	API related to updating XBee firmware on the local XBee module.

Data Structures
struct	xbee_gen3_extended_ver_t

struct	xbee_gen3_update_t

struct	xbee_fw_oem_state_t

struct	xbee_fw_source_t

struct	xbee_fw_buffer_t

struct	xbee_gen3_page_ver0_t
	< XBEE_GEN3_CMD_UPLOAD_PAGE More...

struct	xbee_gen3_page_ver1_t
	< XBEE_GEN3_CMD_UPLOAD_PAGE More...

struct	xbee_oem_header_t

Macros
#define	XBEE_GEN3_UPLOAD_PAGE_SIZE 512

#define	XBEE_GEN3_FW_LOAD_TIMEOUT_MS 10000

#define	XBEE_GEN3_STATUS_BUF_SIZE 60
	Minimum size of buffer passed to xbee_bl_gen3_install_status()

#define	XBEE_FW_LOAD_TIMEOUT 5000

#define	xbee_fw_install_hcs08_state(source) xbee_fw_install_ebl_state( source)
	See documentation for xbee_fw_install_ebl_state().

#define	xbee_fw_status_hcs08(source, buff) xbee_fw_status_ebl( source, buff)
	See documentation for xbee_fw_status_ebl().

#define	XBEE_GEN3_CMD_BL_VERSION 'B'

#define	XBEE_GEN3_CMD_EXTENDED_VER 'V'

#define	XBEE_GEN3_CMD_REGION_CODE 'N'

#define	XBEE_GEN3_CMD_INITIALIZE 'I'

#define	XBEE_GEN3_CMD_PROTOCOL_VER 'L'

#define	XBEE_GEN3_CMD_MAX_BAUDRATE 'X'

#define	XBEE_GEN3_CMD_NEW_BAUDRATE 'R'

#define	XBEE_GEN3_CMD_UPLOAD_PAGE 'P'

#define	XBEE_GEN3_CMD_UPLOAD_FINISHED 'F'

#define	XBEE_GEN3_CMD_VERIFY_FW 'C'

#define	XBEE_GEN3_RSP_SUCCESS 'U'
	Successful responses from the bootloader end with XBEE_GEN3_RSP_SUCCESS.

#define	XBEE_GEN3_RSP_FAILURE '\x11'
	Generic failure response from bootloader.

#define	XBEE_GEN3_RSP_UPLOAD_CRC_ERR '\x12'
	Checksum/CRC invalid.

#define	XBEE_GEN3_RSP_UPLOAD_VERIFY_ERR '\x13'
	flash write failed

#define	_TIME_ELAPSED(x) (xbee_millisecond_timer() - source->timer > (x))

#define	_xbee_firmware_debug

#define	_TIME_ELAPSED(x) (xbee_millisecond_timer() - source->timer > (x))

#define	_TIME_ELAPSED(x) (xbee_millisecond_timer() - source->timer > (x))

#define	XBEE_OEM_MAGIC_NUMBER 0x93FD

#define	XBEE_OEM_OFS_MAGIC_NUMBER 0

#define	XBEE_OEM_OFS_CHECKSUM 2

#define	XBEE_OEM_OFS_IMAGE_LEN 4

#define	XBEE_OEM_OFS_HEADER_LEN 8

#define	XBEE_OEM_OFS_MODULE_ID 10

#define	XBEE_OEM_OFS_SW_COMPAT_LEVEL 11

#define	XBEE_OEM_OFS_FW_VERSION 12

#define	XBEE_BOOTLOADER_ACK 'U'

#define	XBEE_BOOTLOADER_NAK 0x11

#define	XBEE_OEM_FLAG_NONE 0x0000

#define	XBEE_OEM_FLAG_FORCEUPDATE 0x0001

Enumerations
enum	xbee_gen3_state_t { XBEE_GEN3_STATE_INIT, XBEE_GEN3_STATE_ENTER_BOOTLOADER, XBEE_GEN3_STATE_GET_BL_VERSION, XBEE_GEN3_STATE_BL_VERSION, XBEE_GEN3_STATE_BL_PROTOCOL, XBEE_GEN3_STATE_BAUD_RATE, XBEE_GEN3_STATE_EXT_VERSION, XBEE_GEN3_STATE_START_TRANSFER, XBEE_GEN3_STATE_SEND_PAGE, XBEE_GEN3_STATE_LOAD_PAGE, XBEE_GEN3_STATE_VERIFY, XBEE_GEN3_STATE_SUCCESS, XBEE_GEN3_STATE_FAILURE }

enum	{ XBEE_FW_STATE_INIT, XBEE_FW_STATE_RESET, XBEE_FW_STATE_TOGGLE, XBEE_FW_STATE_BREAK, XBEE_FW_STATE_PROMPT, XBEE_FW_STATE_XMODEM_WAIT, XBEE_FW_STATE_XMODEM_SEND, XBEE_FW_STATE_XMODEM_DONE, XBEE_FW_STATE_FINAL_PROMPT, XBEE_FW_STATE_CMD_PENDING, XBEE_FW_STATE_CMD, XBEE_FW_STATE_PARSE_RESPONSE, XBEE_FW_STATE_CMD_HV, XBEE_FW_STATE_CMD_COMPAT, XBEE_FW_STATE_CMD_VR, XBEE_FW_STATE_CMD_CF1, XBEE_FW_STATE_CMD_SL, XBEE_FW_STATE_CMD_PROG, XBEE_FW_STATE_CMD_FR, XBEE_FW_STATE_BOOTLOADER, XBEE_FW_STATE_TX_START, XBEE_FW_STATE_TX_BLOCK, XBEE_FW_STATE_SENDING, XBEE_FW_STATE_RX_BLOCK, XBEE_FW_STATE_RX_FAIL, XBEE_FW_STATE_DONE, XBEE_FW_STATE_FAILURE, XBEE_FW_STATE_SUCCESS }

Functions
void	xbee_gen3_dump_extended_ver (const xbee_gen3_extended_ver_t *ver)

int	xbee_bl_gen3_install_init (xbee_dev_t xbee, xbee_gen3_update_t source)
	Prepare to install new firmware on an attached XBee module. More...

uint16_t	xbee_bl_gen3_install_state (xbee_gen3_update_t *source)
	Return a unique value identifying the install state. More...

int	xbee_bl_gen3_install_tick (xbee_gen3_update_t *source)
	Install the firmware image stored in source. More...

const char *	xbee_bl_gen3_install_status (xbee_gen3_update_t *source, char buffer[XBEE_GEN3_STATUS_BUF_SIZE])
	Return a string describing the current state of the firmware update. More...

int	xbee_fw_install_init (xbee_dev_t xbee, const wpan_address_t FAR target, xbee_fw_source_t *source)
	Prepare to install new firmware on an attached XBee module. More...

int	xbee_fw_install_ebl_tick (xbee_fw_source_t *source)
	Drive the firmware update process for boards that use .EBL/.GBL files to store their firmware. More...

unsigned int	xbee_fw_install_ebl_state (xbee_fw_source_t *source)
	Returns a unique value indicating the state of the .EBL/.GBL install process. More...

char FAR *	xbee_fw_status_ebl (xbee_fw_source_t source, char FAR buffer)
	Update \a buffer with the current install status of \a source. More...

int	xbee_fw_install_hcs08_tick (xbee_fw_source_t *source)
	Drive the firmware update process for the HCS08 application on Programmable XBee modules. More...

int	xbee_fw_install_oem_tick (xbee_fw_source_t *source)
	Install the firmware image stored in source. More...

char FAR *	xbee_fw_status_oem (xbee_fw_source_t source, char FAR buffer)
	Update buffer with the current install status of source. More...

int	xbee_fw_buffer_init (xbee_fw_buffer_t fw, uint32_t length, const char FAR address)
	Helper function for setting up an xbee_fw_buffer_t for use with a source firmware image held entirely in a buffer. More...

int	xbee_fw_read_byte (xbee_fw_source_t *source)

uint16_t	xbee_fw_read_uint16 (xbee_fw_source_t *source)

uint32_t	xbee_fw_read_uint32 (xbee_fw_source_t *source)

uint16_t	xbee_fw_hex2word (const char *pString)

int	_xbee_oem_verify (xbee_fw_source_t *source)

int	_xbee_fw_send_request (xbee_fw_source_t source, const FAR char request, int next_state)

int	_xbee_fw_buffer_seek (void FAR *context, uint32_t offset)
	Helper function used when the source firmware image is entirely held in a buffer. More...

int	_xbee_fw_buffer_read (void FAR context, void FAR buffer, int16_t bytes)
	Helper function used when the source firmware image is entirely held in a buffer. More...

Detailed Description

This layer makes use of lower layers to perform updates on XBee modules.

Driver layer for performing XBee firmware updates.

Both file formats are supported – .ebl (ZNet, Zigbee, Smart Energy) and .oem (DigiMesh).

Function Documentation

int _xbee_fw_buffer_read	(	void FAR *	context,
		void FAR *	buffer,
		int16_t	bytes
	)

Helper function used when the source firmware image is entirely held in a buffer.

Parameters

[in]	context	address of xbee_fw_buffer_t object
[out]	buffer	destination buffer to read bytes into
[in]	bytes	number of bytes to read

Return values

-ENODATA	no more bytes available to read
0-bytes	number of bytes read

References ENODATA, and FAR.

Referenced by xbee_fw_buffer_init().

int _xbee_fw_buffer_seek	(	void FAR *	context,
		uint32_t	offset
	)

Helper function used when the source firmware image is entirely held in a buffer.

Parameters

[in]	context	address of xbee_fw_buffer_t object
[in]	offset	offset to new position

Return values

-EINVAL	offset greater than length of file
0	seek successful

References EINVAL, FAR, and PRIu32.

Referenced by xbee_fw_buffer_init().

int _xbee_oem_verify ( xbee_fw_source_t * source )

Validate the firmware image stored in source. Checks the header, length and checksum.

Parameters

[in] source Firmware source initialized with seek and read functions.

Return values

0	Source contains a valid firmware image.
-EILSEQ	Source does not contain a valid firmware image.
-EIO	I/O error reading from firmware image
-EBADMSG	Firmware checksum failed, image is bad.

References be16toh, be32toh, EBADMSG, EILSEQ, EIO, FAR, PRIsFAR, and PRIu32.

Referenced by xbee_fw_install_oem_tick().

int xbee_bl_gen3_install_init	(	xbee_dev_t *	xbee,
		xbee_gen3_update_t *	source
	)

Prepare to install new firmware on an attached XBee module.

Parameters

[in]	xbee	XBee device to install firmware on. Must have been set up with xbee_dev_init().
[in]	source	Structure with function pointer for reading contents of new firmware image.

 // Function prototype for function that will provide firmware
 // bytes when called by xbee_bl_gen3_install_tick().
 int my_firmware_read(void *context, void *buffer, int16_t bytes);
 
 xbee_gen3_update_t      fw;
 xbee_dev_t              xbee;
 
 xbee_dev_init(&xbee, ...);
 xbee_fw_install_init(&xbee, &fw);
 
 fw.read = &my_firmware_read;
 fw.context = NULL;

@retval     0           success
@retval     -EINVAL     NULL parameter passed to function

References EINVAL.

uint16_t xbee_bl_gen3_install_state ( xbee_gen3_update_t * source )

Return a unique value identifying the install state.

Used by caller to identify state changes.

Parameters

[in] source Structure used to track install status.

Returns: Value identifying a unique install state.

See also: xbee_bl_gen3_install_status

References xbee_gen3_update_t::buffer, xbee_gen3_update_t::context, memcheck(), xbee_gen3_update_t::page_num, xbee_gen3_update_t::page_offset, xbee_gen3_update_t::read, xbee_dev_t::serport, XBEE_GEN3_BL_FLAG_EOF, XBEE_GEN3_BL_FLAG_PROTO1, xbee_ser_putchar(), xbee_ser_rx_flush(), xbee_ser_tx_free(), and xbee_ser_write().

const char * xbee_bl_gen3_install_status	(	xbee_gen3_update_t *	source,
		char	buffer[XBEE_GEN3_STATUS_BUF_SIZE]
	)

Return a string describing the current state of the firmware update.

Can either return a fixed string, or a dynamic string copied to buffer.

Parameters

[in]	source	State variable to generate status string for.
[in]	buffer	Buffer (at least XBEE_GEN3_STATUS_BUF_SIZE bytes) to receive dynamic status string.

Returns: Returns buffer or a pointer to a fixed status string.

See also: xbee_bl_gen3_install_state

References xbee_gen3_update_t::bl_version, xbee_gen3_update_t::page_num, PRIu32, xbee_dev_t::serport, and XBEE_GEN3_BL_FLAG_PROTO1.

int xbee_bl_gen3_install_tick ( xbee_gen3_update_t * source )

Install the firmware image stored in source.

You must call xbee_bl_gen3_install_init() on the source before calling this tick function.

If successful, XBee module with boot into the new firmware image, which is typically at 9600 baud and "transparent" mode (ATAP=0).

Parameters

[in] source Structure used to track install status.

Return values

0	Successfully installed new firmware.
-EAGAIN	Firmware installation in progress (incomplete).
-EINVAL	NULL source.
-EBADMSG	Invalid state for firmware update process.
-ECANCELED	Transfer aborted after three CRC failures on a page or module reported a flash write error.
-EILSEQ	Bootloader verification of firmware failed.
-EIO	Couldn't establish communications with XBee module.

References xbee_gen3_update_t::bl_version, xbee_gen3_update_t::buffer, EAGAIN, EBADMSG, ECANCELED, EILSEQ, EINVAL, EIO, ENODATA, ETIMEDOUT, xbee_gen3_update_t::ext_ver, xbee_gen3_update_t::page_num, xbee_gen3_update_t::page_offset, xbee_gen3_update_t::read, xbee_dev_t::serport, XBEE_GEN3_BL_FLAG_PROTO1, XBEE_GEN3_BL_FLAG_QUERY_ONLY, XBEE_GEN3_BL_FLAG_RETRY_MASK, XBEE_GEN3_RSP_FAILURE, XBEE_GEN3_RSP_SUCCESS, XBEE_GEN3_RSP_UPLOAD_CRC_ERR, XBEE_GEN3_RSP_UPLOAD_VERIFY_ERR, xbee_ser_break(), xbee_ser_get_cts(), xbee_ser_getchar(), xbee_ser_open(), xbee_ser_putchar(), xbee_ser_read(), xbee_ser_rx_flush(), xbee_ser_rx_used(), and xbee_ser_set_rts().

int xbee_fw_buffer_init	(	xbee_fw_buffer_t *	fw,
		uint32_t	length,
		const char FAR *	address
	)

Helper function for setting up an xbee_fw_buffer_t for use with a source firmware image held entirely in a buffer.

Parameters

[out]	fw	structure to configure for reading firmware from a buffer
[in]	length	number of bytes in firmware image
[in]	address	address of buffer containing firmware

Return values

0	success
-EINVAL	invalid parameter

References _xbee_fw_buffer_read(), _xbee_fw_buffer_seek(), EINVAL, and FAR.

unsigned int xbee_fw_install_ebl_state ( xbee_fw_source_t * source )

Returns a unique value indicating the state of the .EBL/.GBL install process.

Parameters

[in] source object used to track state of transfer

Returns: unique value that changes whenever the transfer state changes

See also: xbee_fw_status_ebl

References xbee_xmodem_state_t::packet_num.

int xbee_fw_install_ebl_tick ( xbee_fw_source_t * source )

Drive the firmware update process for boards that use .EBL/.GBL files to store their firmware.

Parameters

[in,out] source object used to track state of transfer

Return values

0	update is in progress
1	update completed successfully
-EINVAL	source is invalid
-EIO	general failure
-ETIMEDOUT	connection timed out waiting for data from target

See also: xbee_fw_install_init, xbee_fw_install_ebl_state, xbee_fw_status_ebl

References EBADMSG, EINVAL, EIO, ETIMEDOUT, xbee_dev_t::reset, xbee_dev_t::serport, xbee_dev_reset(), xbee_ser_break(), xbee_ser_flowcontrol(), xbee_ser_getchar(), xbee_ser_open(), xbee_ser_putchar(), xbee_ser_rx_flush(), xbee_ser_set_rts(), xbee_ser_tx_flush(), XBEE_XMODEM_FLAG_128, XBEE_XMODEM_FLAG_FORCE_CRC, xbee_xmodem_set_source(), xbee_xmodem_tx_init(), xbee_xmodem_tx_tick(), and xbee_xmodem_use_serport().

Referenced by xbee_fw_install_hcs08_tick().

int xbee_fw_install_hcs08_tick ( xbee_fw_source_t * source )

Drive the firmware update process for the HCS08 application on Programmable XBee modules.

Parameters

[in,out] source object used to track state of transfer

Return values

0	update is in progress
1	update completed successfully
-EINVAL	source is invalid
-EIO	general failure
-ETIMEDOUT	connection timed out waiting for data from target

See also: xbee_fw_install_init, xbee_fw_install_ebl_state, xbee_fw_status_ebl

References xbee_fw_install_ebl_tick().

int xbee_fw_install_init	(	xbee_dev_t *	xbee,
		const wpan_address_t FAR *	target,
		xbee_fw_source_t *	source
	)

        Prepare to install new firmware on an attached XBee module.

The host must be able to control the reset pin of the XBee module.

Parameters

[in]	xbee	XBee device to install firmware on. Must have been set up with xbee_dev_init().
[in]	target	The current version of this library can only update the local XBee module, so this parameter should always be NULL. When over-the-air (OTA) updating is supported, this paramter will be the address of a remote module to update.
[in]	source	Structure with function pointers for seeking and reading from the new firmware image.

 // Function prototypes for functions that will provide firmware
 // bytes when called by xbee_fw_install_tick().
 int my_firmware_seek( uint32_t offset);
 int my_firmware_read( void FAR *buffer, int16_t bytes);
 
 xbee_fw_source_t  fw;
 xbee_dev_t        xbee;
 
 fw.seek = &my_firmware_seek;
 fw.read = &my_firmware_read;
 
 xbee_dev_init( &xbee, ...);
 xbee_fw_install_init( &xbee, &fw);

Return values

0	success
-EINVAL	NULL parameter passed to function
-EIO	XBee device passed to function doesn't have a callback for controlling the reset pin on the XBee module.

References EINVAL, EIO, and xbee_dev_t::reset.

int xbee_fw_install_oem_tick ( xbee_fw_source_t * source )

Install the firmware image stored in source.

You must call xbee_fw_install_init() on the source before calling this tick function.

If successful, XBee will be running the new firmware at 115,200 baud.

Parameters

[in] source Firmware source initialized with seek and read functions.

Return values

1	Successfully installed new firmware.
0	Firmware installation in progress (incomplete).
-EILSEQ	firmware does not contain a valid firmware image.
-EBADMSG	Firmware checksum failed, image is bad.
-EIO	Couldn't establish communications with XBee module.
-ENOTSUP	Firmware is not compatible with this hardware.

References _xbee_oem_verify(), EAGAIN, EBADMSG, EIO, ENODATA, ENOTSUP, PRIu16, PRIu32, xbee_dev_t::serport, xbee_dev_reset(), xbee_fw_read_byte(), XBEE_MODE_COMMAND, XBEE_MODE_IDLE, xbee_ser_break(), xbee_ser_flowcontrol(), xbee_ser_getchar(), xbee_ser_open(), xbee_ser_putchar(), xbee_ser_read(), xbee_ser_set_rts(), xbee_ser_tx_free(), and xbee_ser_write().

int xbee_fw_read_byte ( xbee_fw_source_t * source )

Todo:: check return value of source->read here and in _uint16 and _uint32?

References be16toh, and be32toh.

Referenced by xbee_fw_install_oem_tick().

char FAR * xbee_fw_status_ebl	(	xbee_fw_source_t *	source,
		char FAR *	buffer
	)

  Update \a buffer with the current install status of \a source.

Note that this string will only change if the return value of xbee_fw_install_ebl_state() has changed.

Parameters

[in]	source	State variable to generate status string for.
[out]	buffer	Buffer (at least 80 bytes) to receive dynamic status string.

Returns: Returns parameter 2 or a pointer to a fixed status string.

See also: xbee_fw_install_ebl_state

References xbee_xmodem_state_t::packet_num, PRIu16, xbee_xmodem_state_t::state, XBEE_XMODEM_STATE_EOF, XBEE_XMODEM_STATE_FAILURE, XBEE_XMODEM_STATE_FINAL_ACK, XBEE_XMODEM_STATE_FLUSH, XBEE_XMODEM_STATE_RESEND, XBEE_XMODEM_STATE_SEND, XBEE_XMODEM_STATE_SENDING, XBEE_XMODEM_STATE_START, XBEE_XMODEM_STATE_SUCCESS, and XBEE_XMODEM_STATE_WAIT_ACK.

char FAR * xbee_fw_status_oem	(	xbee_fw_source_t *	source,
		char FAR *	buffer
	)

Update buffer with the current install status of source.

Parameters

[in]	source	State variable to generate status string for.
[out]	buffer	Buffer (at least 80 bytes) to receive dynamic status string.

Returns: Returns parameter 2 or a pointer to a fixed status string.

References PRIu32.

Files

Data Structures

Macros

Enumerations

Functions

Detailed Description

Function Documentation