S.F.T. XMODEM Library
1.0
|
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. |
internal support functions
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;
unsigned char CalcCheckSum | ( | const char * | lpBuf, |
short | cbBuf | ||
) |
unsigned short CalcCRC | ( | const char * | lpBuf, |
short | cbBuf | ||
) |
Calculate 16-bit CRC for XMODEM packet.
lpBuf | A pointer to the XMODEM data buffer |
cbBuf | The length of the XMODEM data buffer (typically 128) |
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.
void GenerateSEQ | ( | XMODEM_BUF * | pBuf, |
unsigned char | bSeq | ||
) |
Generate a sequence number pair, place into XMODEM_BUF.
pBuf | A pointer to an XMODEM_BUF structure |
bSeq | An 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.
void GenerateSEQC | ( | XMODEMC_BUF * | pBuf, |
unsigned char | bSeq | ||
) |
Generate a sequence number pair, place into XMODEMC_BUF (the CRC version)
pBuf | A pointer to an XMODEM_BUF structure |
bSeq | An 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.
short GetXmodemBlock | ( | SERIAL_TYPE | ser, |
char * | pBuf, | ||
short | cbSize | ||
) |
Get an XMODEM block from the serial device.
ser | A 'SERIAL_TYPE' identifier for the serial connection |
pBuf | A pointer to the buffer that receives the data |
cbSize | The number of bytes/chars to read |
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.
static unsigned short my_htons | ( | unsigned short | sVal | ) | [static] |
Calculate checksum for XMODEM packet.
sVal | An unsigned short integer to be made 'high endian' by flipping bytes (as needed) |
This function assumes low-endian for Arduino, and performs a universal operation for 'indeterminate' architectures.
int ReceiveXmodem | ( | XMODEM * | pX | ) |
Generic function to receive a file via XMODEM (CRC or Checksum)
pX | A pointer to an 'XMODEM_BUF' with valid bCRC, ser, and file members |
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.
int SendXmodem | ( | XMODEM * | pX | ) |
Generic function to send a file via XMODEM (CRC or Checksum)
pX | A 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. |
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.
short ValidateSEQ | ( | XMODEM_BUF * | pX, |
unsigned char | bSeq | ||
) |
Validate the sequence number of a received XMODEM block.
pX | A pointer to an 'XMODEM_BUF' |
bSeq | The expected sequence number (block & 255) |
Call this function to validate a packet's sequence number against the block number
short ValidateSEQC | ( | XMODEMC_BUF * | pX, |
unsigned char | bSeq | ||
) |
Validate the sequence number of a received XMODEM block (CRC version)
pX | A pointer to an 'XMODEMC_BUF' |
bSeq | The expected sequence number (block & 255) |
Call this function to validate a packet's sequence number against the block number
int WriteXmodemBlock | ( | SERIAL_TYPE | ser, |
const void * | pBuf, | ||
int | cbSize | ||
) |
Send an XMODEM block via the serial device.
ser | A 'SERIAL_TYPE' identifier for the serial connection |
pBuf | A pointer to the buffer that receives the data |
cbSize | The number of bytes/chars to write |
Call this function to write data via the serial port, specifying the number of bytes to write.
int WriteXmodemChar | ( | SERIAL_TYPE | ser, |
unsigned char | bVal | ||
) |
Write a single character to the serial device.
ser | A 'SERIAL_TYPE' identifier for the serial connection |
bVal | The byte to send |
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.
void XModemFlushInput | ( | SERIAL_TYPE | ser | ) |
Read all input from the serial port until there is 1 second of 'silence'.
ser | A '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.
void XmodemTerminate | ( | XMODEM * | pX | ) |
int XReceiveSub | ( | XMODEM * | pX | ) |
Calling function for ReceiveXmodem.
pX | A pointer to an 'XMODEM_BUF' with valid ser, and file members |
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.
Calling function for SendXmodem.
pX | A pointer to an 'XMODEM_BUF' with valid ser, and file members |
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.