XMODEM (send-only)

Xmodem API used with firmware updates. More...

Files
file	xmodem.h
	Makes use of xbee/serial.h API for sending and receiving serial data.
file	xmodem_crc16.h
	Header for crc16_calc() function implemented in xmodem_crc16.c.
file	xmodem_crc16.c
	CRC16 implementation for use by XBee's Xmodem library if platform doesn't have an existing implementation.
file	xbee_xmodem.c
	Xmodem send implementation, used for XBee firmware updates.

Data Structures
struct	xbee_xmodem_state_t
	Structure used to track the state of an Xmodem send. More...

Typedefs
typedef int(*	xbee_xmodem_read_fn) (void FAR *context, void FAR *buffer, int16_t bytes)
	Function to assign to file.read or stream.read member of an xbee_xmodem_state_t object. More...
typedef int(*	xbee_xmodem_write_fn) (void FAR *context, const void FAR *buffer, int16_t bytes)
	Function to assign to stream.write member of an xbee_xmodem_state_t object. More...

Enumerations
enum	xbee_xmodem_state {   XBEE_XMODEM_STATE_FLUSH, XBEE_XMODEM_STATE_START, XBEE_XMODEM_STATE_SEND, XBEE_XMODEM_STATE_RESEND,   XBEE_XMODEM_STATE_SENDING, XBEE_XMODEM_STATE_WAIT_ACK, XBEE_XMODEM_STATE_EOF, XBEE_XMODEM_STATE_FINAL_ACK,   XBEE_XMODEM_STATE_SUCCESS, XBEE_XMODEM_STATE_FAILURE }
	Values for state member of xbee_xmodem_state_t. More...

Functions
int	xbee_xmodem_use_serport (xbee_xmodem_state_t *xbxm, xbee_serial_t *serport)
	Used for xmodem transfers over a simple serial port. More...
int	xbee_xmodem_set_source (xbee_xmodem_state_t *xbxm, void FAR *buffer, xbee_xmodem_read_fn read, const void FAR *context)
	Configure the data source for the Xmodem send. More...
int	xbee_xmodem_set_stream (xbee_xmodem_state_t *xbxm, xbee_xmodem_read_fn read, xbee_xmodem_write_fn write, const void FAR *context)
	Configure the stream used to communicate with the target. More...
int	xbee_xmodem_tx_init (xbee_xmodem_state_t *xbxm, uint16_t flags)
	Initialize state structure for use with xbee_xmodem_tx_tick() to send a file via Xmodem. More...
int	xbee_xmodem_tx_tick (xbee_xmodem_state_t *xbxm)
	Function to drive the Xmodem send state machine. More...
uint16_t	crc16_calc (const void FAR *data, uint16_t length, uint16_t current)
	Calculate CRC-16 of a data buffer using polynomial (0x1021) without reflection. More...
int	_xbee_xmodem_ser_read (void FAR *context, void FAR *buffer, int16_t bytes)
int	_xbee_xmodem_ser_write (void FAR *context, const void FAR *buffer, int16_t bytes)
int	_xbee_xmodem_getchar (xbee_xmodem_state_t *xbxm)
int	_xbee_xmodem_putchar (xbee_xmodem_state_t *xbxm, uint8_t ch)
int	_assemble_packet (xbee_xmodem_state_t *xbxm, uint16_t block_size)
uint16_t	_block_size (xbee_xmodem_state_t *xbxm)

Variables
const FAR uint16_t	crc16_table [256]
	Table for XMODEM and "False CCITT" CRC, calculated with standard 0x1021 polynomial. More...

Xmodem Control Characters
#define	XMODEM_NAK   0x15
	receiver requests XMODEM (with checksum), or did not receive last block
#define	XMODEM_CRC   'C'
	receiver requests XMODEM-CRC
#define	XMODEM_SOH   0x01
	start of 128-byte block
#define	XMODEM_STX   0x02
	start of 1024-byte block
#define	XMODEM_ACK   0x06
	acknowledge receipt of block
#define	XMODEM_CAN   0x18
	cancel transmission
#define	XMODEM_EOT   0x04
	sender is ending transmission

Detailed Description

Xmodem API used with firmware updates.

Typedef Documentation

typedef int(* xbee_xmodem_read_fn) (void FAR *context, void FAR *buffer, int16_t bytes)

Function to assign to file.read or stream.read member of an xbee_xmodem_state_t object.

Used to read data from the Xmodem receiver (ACK/NAK bytes) or the firmware source (e.g., file or embedded array).

Parameters

[in]	context	either file.context or stream.context from the xbee_xmodem_state_t object
[in,out]	buffer	buffer to store read data
[in]	bytes	maximum number of bytes to write to buffer

Return values

>0	number of bytes read
-ENODATA	no more bytes to read
-EINVAL	NULL pointer or negative byte count passed to function
0	no more bytes to read

typedef int(* xbee_xmodem_write_fn) (void FAR *context, const void FAR *buffer, int16_t bytes)

Function to assign to stream.write member of an xbee_xmodem_state_t object.

Used to write data to the Xmodem receiver (blocks of data).

Parameters

[in]	context	stream.context
[in]	buffer	bytes to send to the receiver
[in]	bytes	number of bytes to send

Return values

>=0	number of bytes sent
-EINVAL	NULL pointer or negative byte count passed to function
<0	irrecoverable error

Enumeration Type Documentation

enum xbee_xmodem_state

Values for state member of xbee_xmodem_state_t.

Enumerator
XBEE_XMODEM_STATE_FLUSH	flush receive buffer and wait
XBEE_XMODEM_STATE_START	waiting for NAK or CRC char
XBEE_XMODEM_STATE_SEND	start of another packet
XBEE_XMODEM_STATE_RESEND	resend last packet
XBEE_XMODEM_STATE_SENDING	sending bytes of packet
XBEE_XMODEM_STATE_WAIT_ACK	waiting for ACK of current packet
XBEE_XMODEM_STATE_EOF	reached end of file, close connection
XBEE_XMODEM_STATE_FINAL_ACK	waiting for final ACK from receiver
XBEE_XMODEM_STATE_SUCCESS	completed transfer was successful
XBEE_XMODEM_STATE_FAILURE	transfer failed

Function Documentation

int _xbee_xmodem_getchar

(

xbee_xmodem_state_t *

xbxm

)

Helper function to read a single character from the stream.

Parameters

[in]

xbxm

state structure

Return values

0-255	character read from stream
-ENODATA	stream is empty
<0	error reading from stream

References xbee_xmodem_state_t::context, ENODATA, xbee_xmodem_state_t::read, and xbee_xmodem_state_t::stream.

Referenced by xbee_xmodem_set_source(), and xbee_xmodem_tx_tick().

int _xbee_xmodem_putchar	(	xbee_xmodem_state_t *	xbxm,
		uint8_t	ch
	)

Helper function to write a single character to the stream.

Parameters

[in]	xbxm	state structure
[in]	ch	character to write

Return values

0	character was written to stream
-ENOSPC	could not write to stream
<0	error writing to stream

References xbee_xmodem_state_t::context, ENOSPC, xbee_xmodem_state_t::stream, and xbee_xmodem_state_t::write.

Referenced by xbee_xmodem_set_source(), and xbee_xmodem_tx_tick().

uint16_t crc16_calc	(	const void FAR *	data,
		uint16_t	length,
		uint16_t	current
	)

Calculate CRC-16 of a data buffer using polynomial (0x1021) without reflection.

Parameters

[in]	data	pointer to data to CRC
[in]	length	number of bytes to CRC
[in]	current	When calculating a CRC-16 over a stream or a large range of bytes, it is necessary to call crc16_calc multiple times.

• Use an initial value of 0x0000 to generate an "XMODEM" CRC.
• Use an initial value of 0xFFFF to generate a "FALSE CCITT" CRC.

Returns

CRC-16, without reflection, for length bytes of data, using current as the starting CRC and 0x1021 as a polynomial.

See also

http://regregex.bbcmicro.net/crc-catalogue.htm#appendix.a

References FAR.

Referenced by xbee_xmodem_tx_init().

int xbee_xmodem_set_source	(	xbee_xmodem_state_t *	xbxm,
		void FAR *	buffer,
		xbee_xmodem_read_fn	read,
		const void FAR *	context
	)

Configure the data source for the Xmodem send.

Parameters

[out]	xbxm	state structure to configure
[in]	buffer	buffer for use by xbee_xmodem_tx_tick – must be at least 5 bytes larger than the block size passed to xbee_xmodem_tx_init()
[in]	read	function used to read bytes to send to the target
[in]	context	context passed to read function

Return values

0	successfully configured data source
-EINVAL	invalid parameter passed in

References _xbee_xmodem_getchar(), _xbee_xmodem_putchar(), xbee_xmodem_state_t::buffer, xbee_xmodem_state_t::context, EINVAL, FAR, xbee_xmodem_state_t::file, and xbee_xmodem_state_t::read.

Referenced by xbee_fw_install_ebl_tick().

int xbee_xmodem_set_stream	(	xbee_xmodem_state_t *	xbxm,
		xbee_xmodem_read_fn	read,
		xbee_xmodem_write_fn	write,
		const void FAR *	context
	)

Configure the stream used to communicate with the target.

Associates function pointers and a context that are used to send data to and receive data from the target (device receiving data via Xmodem).

Parameters

[out]	xbxm	state structure to configure
[in]	read	function used to read bytes from the target
[in]	write	function used to send bytes to the target
[in]	context	context passed to read and write functions

Return values

0	successfully configured communication path to target
-EINVAL	invalid parameter passed in

See also

pxbee_ota_init, xbee_xmodem_use_serport

References xbee_xmodem_state_t::context, EINVAL, FAR, xbee_xmodem_state_t::read, xbee_xmodem_state_t::stream, and xbee_xmodem_state_t::write.

Referenced by pxbee_ota_init(), and xbee_xmodem_use_serport().

int xbee_xmodem_tx_init	(	xbee_xmodem_state_t *	xbxm,
		uint16_t	flags
	)

Initialize state structure for use with xbee_xmodem_tx_tick() to send a file via Xmodem.

Parameters

[out]	xbxm	state structure to initialize
[in]	flags	one of the following macros, indicating the block size to use for the transfer XBEE_XMODEM_FLAG_NONE XBEE_XMODEM_FLAG_64 XBEE_XMODEM_FLAG_128 XBEE_XMODEM_FLAG_1024

Return values

-EINVAL	invalid parameter passed in
0	initialized state, can pass it to xbee_xmodem_tx_tick

See also

pxbee_ota_init

References xbee_xmodem_state_t::buffer, xbee_xmodem_state_t::context, crc16_calc(), EINVAL, EIO, ENODATA, FAR, xbee_xmodem_state_t::file, xbee_xmodem_state_t::flags, xbee_xmodem_state_t::packet_num, xbee_xmodem_state_t::read, xbee_xmodem_state_t::state, xbee_xmodem_state_t::tries, XBEE_XMODEM_FLAG_1024, XBEE_XMODEM_FLAG_128, XBEE_XMODEM_FLAG_1K, XBEE_XMODEM_FLAG_64, XBEE_XMODEM_FLAG_CRC, XBEE_XMODEM_FLAG_USER, XBEE_XMODEM_MASK_BLOCKSIZE, XBEE_XMODEM_STATE_EOF, XBEE_XMODEM_STATE_START, XMODEM_SOH, and XMODEM_STX.

Referenced by pxbee_ota_init(), and xbee_fw_install_ebl_tick().

int xbee_xmodem_tx_tick

(

xbee_xmodem_state_t *

xbxm

)

Function to drive the Xmodem send state machine.

Call until it returns a non-zero result.

Return values

-EINVAL	invalid parameter passed in
-ETIMEDOUT	connection timed out waiting for data from target
<0	error on send, transfer aborted
0	transfer in progress, call function again
1	transfer completed successfully

References _xbee_xmodem_getchar(), _xbee_xmodem_putchar(), xbee_xmodem_state_t::buffer, xbee_xmodem_state_t::context, EINVAL, ENODATA, ETIMEDOUT, xbee_xmodem_state_t::flags, xbee_xmodem_state_t::offset, xbee_xmodem_state_t::packet_num, xbee_xmodem_state_t::read, xbee_xmodem_state_t::state, xbee_xmodem_state_t::stream, xbee_xmodem_state_t::timer, xbee_xmodem_state_t::tries, xbee_xmodem_state_t::write, XBEE_XMODEM_FLAG_CHECKSUM, XBEE_XMODEM_FLAG_CRC, XBEE_XMODEM_FLAG_FORCE_CRC, 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, XBEE_XMODEM_STATE_WAIT_ACK, XMODEM_ACK, XMODEM_CAN, XMODEM_CRC, XMODEM_EOT, and XMODEM_NAK.

Referenced by xbee_fw_install_ebl_tick().

int xbee_xmodem_use_serport	(	xbee_xmodem_state_t *	xbxm,
		xbee_serial_t *	serport
	)

Used for xmodem transfers over a simple serial port.

Associates the serial port with the xbee_xmodem_state_t and sets stream.read and stream.write function pointers to helper functions that read/write a serial port.

Must be called before xbee_xmodem_tx_tick() and either before or after xbee_xmodem_tx_init().

Parameters

[in,out]	xbxm	state object to configure for serial read/write
[in]	serport	port to use for transfer

Return values

0	successfully associated serport with xbxm
-EINVAL	NULL parameter passed in
<0	error assigning serport to xbxm

See also

pxbee_ota_init, xbee_xmodem_set_stream

References xbee_xmodem_set_stream().

Referenced by xbee_fw_install_ebl_tick().

Variable Documentation

const FAR uint16_t crc16_table[256]

Table for XMODEM and "False CCITT" CRC, calculated with standard 0x1021 polynomial.