px-lib  0.9.2
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers
px_xmodem.h : XMODEM-CRC receive module

Description

Receive or send a file via the XMODEM-CRC protocol.

File(s):

XMODEM-CRC is a simple file transfer protocol. The file is broken up into a series of packets that are sent to the receiver.

Each packet consists of:

A single character response is sent by the receiver to control the flow of packets:

To indicate the end of transfer, the transmitter sends:

See also
http://en.wikipedia.org/wiki/XMODEM

This module requires a few functions that must be defined externally. Macros are used to bind to these functions (for flexibility and optimisation) and must be defined in 'px_xmodem_cfg.h'.

Macros

#define PX_XMODEM_CFG_RD_U8(data)   px_xmodem_rd_u8(data)
 See if a received byte is available and store it in the specified location. More...
 
#define PX_XMODEM_CFG_WR_U8(data)   px_xmodem_wr_u8(data)
 Write one byte. More...
 
#define PX_XMODEM_CFG_TMR_START(time_ms)   px_xmodem_tmr_start(time_ms)
 Start timeout timer. More...
 
#define PX_XMODEM_CFG_TMR_HAS_EXPIRED()   px_xmodem_tmr_has_expired()
 See if timer has expired. More...
 

Typedefs

typedef void(* px_xmodem_on_rx_data_t) (const uint8_t *data, uint8_t bytes_received)
 Definition for a pointer to a function that will be called once a block of data has been received. More...
 
typedef bool(* px_xmodem_on_tx_data_t) (uint8_t *data, uint8_t bytes_to_send)
 Definition for a pointer to a function that will be called to supply data to send. More...
 

Functions

bool px_xmodem_receive_file (px_xmodem_on_rx_data_t on_rx_data)
 Blocking function that receives a file using the XMODEM-CRC protocol. More...
 
bool px_xmodem_send_file (px_xmodem_on_tx_data_t on_tx_data)
 Blocking function that sends a file using the XMODEM-CRC protocol. More...
 

Macro Definition Documentation

◆ PX_XMODEM_CFG_RD_U8

#define PX_XMODEM_CFG_RD_U8 (   data)    px_xmodem_rd_u8(data)

See if a received byte is available and store it in the specified location.

Parameters
[out]dataPointer to location where data byte must be stored
Return values
trueReceived byte is stored in specified location
falseNo received data available (receive buffer empty)

Definition at line 45 of file px_xmodem_cfg_template.h.

◆ PX_XMODEM_CFG_WR_U8

#define PX_XMODEM_CFG_WR_U8 (   data)    px_xmodem_wr_u8(data)

Write one byte.

This function blocks until space is available in the transmit buffer.

Parameters
[in]dataByte to be written

Definition at line 54 of file px_xmodem_cfg_template.h.

◆ PX_XMODEM_CFG_TMR_START

#define PX_XMODEM_CFG_TMR_START (   time_ms)    px_xmodem_tmr_start(time_ms)

Start timeout timer.

This function starts the XMODEM timeout timer.

Parameters
[in]time_msTime in milliseconds to wait before timer has expired

Definition at line 63 of file px_xmodem_cfg_template.h.

◆ PX_XMODEM_CFG_TMR_HAS_EXPIRED

#define PX_XMODEM_CFG_TMR_HAS_EXPIRED ( )    px_xmodem_tmr_has_expired()

See if timer has expired.

Return values
trueTimer has expired
trueTimer has not expired

Definition at line 72 of file px_xmodem_cfg_template.h.

Typedef Documentation

◆ px_xmodem_on_rx_data_t

typedef void(* px_xmodem_on_rx_data_t) (const uint8_t *data, uint8_t bytes_received)

Definition for a pointer to a function that will be called once a block of data has been received.

Definition at line 86 of file px_xmodem.h.

◆ px_xmodem_on_tx_data_t

typedef bool(* px_xmodem_on_tx_data_t) (uint8_t *data, uint8_t bytes_to_send)

Definition for a pointer to a function that will be called to supply data to send.

Definition at line 92 of file px_xmodem.h.

Function Documentation

◆ px_xmodem_receive_file()

bool px_xmodem_receive_file ( px_xmodem_on_rx_data_t  on_rx_data)

Blocking function that receives a file using the XMODEM-CRC protocol.

Parameters
on_rx_dataPointer to a function that will be called once a block of data has been received.
Return values
trueFile succesfully received
falseTimed out while trying to receive a file

Definition at line 228 of file px_xmodem.c.

◆ px_xmodem_send_file()

bool px_xmodem_send_file ( px_xmodem_on_tx_data_t  on_tx_data)

Blocking function that sends a file using the XMODEM-CRC protocol.

Parameters
on_tx_datapointer to a function that will be called to supply data to send.
Return values
trueFile succesfully sent
falseTimed out while trying to send a file

Definition at line 328 of file px_xmodem.c.