S.F.T. XMODEM Library  1.0
XModem Internal

Data Structures

struct  _XMODEM_BUF_
 Structure defining an XMODEM CHECKSUM packet. More...
struct  _XMODEMC_BUF_
 Structure defining an XMODEM CRC packet. More...
struct  _XMODEM_
 Structure that identifies the XMODEM communication state. More...

Typedefs

typedef struct _XMODEM_BUF_ XMODEM_BUF
 Structure defining an XMODEM CHECKSUM packet.
typedef struct _XMODEMC_BUF_ XMODEMC_BUF
 Structure defining an XMODEM CRC packet.
typedef struct _XMODEM_ XMODEM
 Structure that identifies the XMODEM communication state.

Functions

unsigned char CalcCheckSum (const char *lpBuf, short cbBuf)
 Calculate checksum for XMODEM packet.
static unsigned short my_htons (unsigned short sVal)
 Calculate checksum for XMODEM packet.
unsigned short CalcCRC (const char *lpBuf, short cbBuf)
 Calculate 16-bit CRC for XMODEM packet.
void GenerateSEQ (XMODEM_BUF *pBuf, unsigned char bSeq)
 Generate a sequence number pair, place into XMODEM_BUF.
void GenerateSEQC (XMODEMC_BUF *pBuf, unsigned char bSeq)
 Generate a sequence number pair, place into XMODEMC_BUF (the CRC version)
short GetXmodemBlock (SERIAL_TYPE ser, char *pBuf, short cbSize)
 Get an XMODEM block from the serial device.
int WriteXmodemChar (SERIAL_TYPE ser, unsigned char bVal)
 Write a single character to the serial device.
int WriteXmodemBlock (SERIAL_TYPE ser, const void *pBuf, int cbSize)
 Send an XMODEM block via the serial device.
void XModemFlushInput (SERIAL_TYPE ser)
 Read all input from the serial port until there is 1 second of 'silence'.
void XmodemTerminate (XMODEM *pX)
 Terminate the XMODEM connection.
short ValidateSEQ (XMODEM_BUF *pX, unsigned char bSeq)
 Validate the sequence number of a received XMODEM block.
short ValidateSEQC (XMODEMC_BUF *pX, unsigned char bSeq)
 Validate the sequence number of a received XMODEM block (CRC version)
int ReceiveXmodem (XMODEM *pX)
 Generic function to receive a file via XMODEM (CRC or Checksum)
int SendXmodem (XMODEM *pX)
 Generic function to send a file via XMODEM (CRC or Checksum)
int XReceiveSub (XMODEM *pX)
 Calling function for ReceiveXmodem.
int XSendSub (XMODEM *pX)
 Calling function for SendXmodem.

Detailed Description

internal support functions


Typedef Documentation

typedef struct _XMODEM_ XMODEM

Structure that identifies the XMODEM communication state.

typedef struct _XMODEM_
{
  SERIAL_TYPE ser;     // identifies the serial connection, data type is OS-dependent
  FILE_TYPE file;      // identifies the file handle, data type is OS-dependent

  union
  {
    XMODEM_BUF xbuf;   // XMODEM CHECKSUM buffer
    XMODEMC_BUF xcbuf; // XMODEM CRC buffer
  } buf;               // union of both buffers, total length 133 bytes

  unsigned char bCRC;  // non-zero for CRC, zero for checksum

} XMODEM;
typedef struct _XMODEM_BUF_ XMODEM_BUF

Structure defining an XMODEM CHECKSUM packet.

typedef struct _XMODEM_BUF_
{
   char cSOH;                   // ** SOH byte goes here             **
   unsigned char aSEQ, aNotSEQ; // ** 1st byte = seq#, 2nd is ~seq#  **
   char aDataBuf[128];          // ** the actual data itself!        **
   unsigned char bCheckSum;     // ** checksum gets 1 byte           **
} PACKED XMODEM_BUF;
typedef struct _XMODEMC_BUF_ XMODEMC_BUF

Structure defining an XMODEM CRC packet.

typedef struct _XMODEMC_BUF_
{
   char cSOH;                   // ** SOH byte goes here             **
   unsigned char aSEQ, aNotSEQ; // ** 1st byte = seq#, 2nd is ~seq#  **
   char aDataBuf[128];          // ** the actual data itself!        **
   unsigned short wCRC;         // ** CRC gets 2 bytes, high endian  **
} PACKED XMODEMC_BUF;

Function Documentation

unsigned char CalcCheckSum ( const char *  lpBuf,
short  cbBuf 
)

Calculate checksum for XMODEM packet.

Parameters:
lpBufA pointer to the XMODEM data buffer
cbBufThe length of the XMODEM data buffer (typically 128)
Returns:
An unsigned char value to be assigned to the 'checksum' element in the XMODEM packet

Definition at line 236 of file xmodem.c.

unsigned short CalcCRC ( const char *  lpBuf,
short  cbBuf 
)

Calculate 16-bit CRC for XMODEM packet.

Parameters:
lpBufA pointer to the XMODEM data buffer
cbBufThe length of the XMODEM data buffer (typically 128)
Returns:
A high-endian 16-bit (unsigned short) value to be assigned to the 'CRC' element in the XMODEM packet

This method uses the 'long way' which is SMALLER CODE for microcontrollers, but eats up a bit more CPU. Otherwise, you'd have to pre-build the 256 byte table and use "the table lookup" method.

Definition at line 296 of file xmodem.c.

void GenerateSEQ ( XMODEM_BUF pBuf,
unsigned char  bSeq 
)

Generate a sequence number pair, place into XMODEM_BUF.

Parameters:
pBufA pointer to an XMODEM_BUF structure
bSeqAn unsigned char, typically cast from an unsigned long 'block number'

This function generates the sequence pair for the XMODEM packet. The 'block number' is initially assigned a value of '1', and increases by 1 for each successful packet. That value is 'truncated' to a single byte and assigned as a sequence number for the packet itself.

Definition at line 394 of file xmodem.c.

void GenerateSEQC ( XMODEMC_BUF pBuf,
unsigned char  bSeq 
)

Generate a sequence number pair, place into XMODEMC_BUF (the CRC version)

Parameters:
pBufA pointer to an XMODEM_BUF structure
bSeqAn unsigned char, typically cast from an unsigned long 'block number'

This function generates the sequence pair for the XMODEM packet. The 'block number' is initially assigned a value of '1', and increases by 1 for each successful packet. That value is 'truncated' to a single byte and assigned as a sequence number for the packet itself.

Definition at line 411 of file xmodem.c.

short GetXmodemBlock ( SERIAL_TYPE  ser,
char *  pBuf,
short  cbSize 
)

Get an XMODEM block from the serial device.

Parameters:
serA 'SERIAL_TYPE' identifier for the serial connection
pBufA pointer to the buffer that receives the data
cbSizeThe number of bytes/chars to read
Returns:
The number of bytes/chars read, 0 if timed out (no data), < 0 on error

Call this function to read data from the serial port, specifying the number of bytes to read. This function times out after no data transferred (silence) for a period of 'SILENCE_TIMEOUT' milliseconds. This allows spurious data transfers to continue as long as there is LESS THAN 'SILENCE_TIMEOUT' between bytes, and also allows VERY SLOW BAUD RATES (as needed). However, if the transfer takes longer than '10 times SILENCE_TIMEOUT', the function will return the total number of bytes that were received within that time.
The default value of 5 seconds, extended to 50 seconds, allows a worst-case baud rate of about 20. This should not pose a problem. If it does, edit the code.

Definition at line 435 of file xmodem.c.

static unsigned short my_htons ( unsigned short  sVal) [static]

Calculate checksum for XMODEM packet.

Parameters:
sValAn unsigned short integer to be made 'high endian' by flipping bytes (as needed)
Returns:
A (possibly) byte-flipped high-endian unsigned short integer

This function assumes low-endian for Arduino, and performs a universal operation for 'indeterminate' architectures.

Definition at line 259 of file xmodem.c.

int ReceiveXmodem ( XMODEM pX)

Generic function to receive a file via XMODEM (CRC or Checksum)

Parameters:
pXA pointer to an 'XMODEM_BUF' with valid bCRC, ser, and file members
Returns:
A zero value on success, negative on error, positive on cancel

The calling function will need to poll for an SOH from the server using 'C' and 'NAK' characters (as appropriate) until an SOH is received. That value must be assigned to the 'buf' union (as appropriate), and the bCRC member assigned to non-zero if the server responded to 'C', or zero if it responded to 'NAK'. With the bCRC, ser, and file members correctly assigned, call THIS function to receive content via XMODEM and write it to 'file'.
This function will return zero on success, a negative value on error, and a positive value if the transfer was canceled by the server.

Definition at line 811 of file xmodem.c.

int SendXmodem ( XMODEM pX)

Generic function to send a file via XMODEM (CRC or Checksum)

Parameters:
pXA pointer to an 'XMODEM_BUF' with valid ser, and file members, and the polled 'NAK' value assigned to the cSOH member (first byte) within the 'buf' union.
Returns:
A zero value on success, negative on error, positive on cancel

The calling function will need to poll for a 'C' or NAK from the client (as appropriate) and assign that character to the cSOH member in the 'buf' union (either xbuf or xcbuf since the 'cSOH' will always be the first byte). Then call this function to send content via XMODEM from 'file'.
It is important to record the NAK character before calling this function since the 'C' or 'NAK' value will be used to determine whether to use CRC or CHECKSUM.
This function will return zero on success, a negative value on error, and a positive value if the transfer was canceled by the receiver.

Definition at line 994 of file xmodem.c.

short ValidateSEQ ( XMODEM_BUF pX,
unsigned char  bSeq 
)

Validate the sequence number of a received XMODEM block.

Parameters:
pXA pointer to an 'XMODEM_BUF'
bSeqThe expected sequence number (block & 255)
Returns:
A zero value on success, non-zero otherwise

Call this function to validate a packet's sequence number against the block number

Definition at line 775 of file xmodem.c.

short ValidateSEQC ( XMODEMC_BUF pX,
unsigned char  bSeq 
)

Validate the sequence number of a received XMODEM block (CRC version)

Parameters:
pXA pointer to an 'XMODEMC_BUF'
bSeqThe expected sequence number (block & 255)
Returns:
A zero value on success, non-zero otherwise

Call this function to validate a packet's sequence number against the block number

Definition at line 790 of file xmodem.c.

int WriteXmodemBlock ( SERIAL_TYPE  ser,
const void *  pBuf,
int  cbSize 
)

Send an XMODEM block via the serial device.

Parameters:
serA 'SERIAL_TYPE' identifier for the serial connection
pBufA pointer to the buffer that receives the data
cbSizeThe number of bytes/chars to write
Returns:
The number of bytes/chars written, < 0 on error

Call this function to write data via the serial port, specifying the number of bytes to write.

Definition at line 611 of file xmodem.c.

int WriteXmodemChar ( SERIAL_TYPE  ser,
unsigned char  bVal 
)

Write a single character to the serial device.

Parameters:
serA 'SERIAL_TYPE' identifier for the serial connection
bValThe byte to send
Returns:
The number of bytes/chars written, or < 0 on error

Call this function to write one byte of data to the serial port. Typically this is used to send things like an ACK or NAK byte.

Definition at line 558 of file xmodem.c.

void XModemFlushInput ( SERIAL_TYPE  ser)

Read all input from the serial port until there is 1 second of 'silence'.

Parameters:
serA 'SERIAL_TYPE' identifier for the serial connection

Call this function to read ALL data from the serial port, until there is a period with no data (i.e. 'silence') for 1 second. At that point the function will return.
Some operations require that any bad data be flushed out of the input to prevent synchronization problems. By using '1 second of silence' it forces re-synchronization to occur in one shot, with the possible exception of VERY noisy lines. The down side is that it may slow down transfers with a high data rate.

Definition at line 666 of file xmodem.c.

void XmodemTerminate ( XMODEM pX)

Terminate the XMODEM connection.

Parameters:
pXA pointer to the 'XMODEM' object identifying the transfer

Call this function prior to ending the XMODEM transfer. Currently the only thing it does is flush the input.

Definition at line 758 of file xmodem.c.

int XReceiveSub ( XMODEM pX)

Calling function for ReceiveXmodem.

Parameters:
pXA pointer to an 'XMODEM_BUF' with valid ser, and file members
Returns:
A zero value on success, negative on error, positive on cancel

This is a generic 'calling function' for ReceiveXmodem that checks for a response to 'C' and 'NAK' characters, and sets up the XMODEM transfer for either CRC or CHECKSUM mode.
This function will return zero on success, a negative value on error, and a positive value if the transfer was canceled by the receiver.

Definition at line 1232 of file xmodem.c.

int XSendSub ( XMODEM pX)

Calling function for SendXmodem.

Parameters:
pXA pointer to an 'XMODEM_BUF' with valid ser, and file members
Returns:
A zero value on success, negative on error, positive on cancel

This is a generic 'calling function' for SendXmodem that checks for polls by the receiver, and places the 'NAK' or 'C' character into the 'buf' member of the XMODEM structure so that SendXmodem can use the correct method, either CRC or CHECKSUM mode.
This function will return zero on success, a negative value on error, and a positive value if the transfer was canceled by the receiver.

Definition at line 1304 of file xmodem.c.