xmodem.h : XMODEM-CRC receive module
[/xmodem_bootloader]

Receive a file via the XMODEM-CRC protocol. More...

Typedefs
typedef void(*	xmodem_on_rx_data_t )(u8_t *data, u8_t bytes_received)
	Definition for a pointer to a function that will be called once a frame has been received.
Functions
bool_t	xmodem_rx_file (xmodem_on_rx_data_t on_rx_data)
	Blocking function that receives a file transferred with the XMODEM-CRC protocol.

---

Detailed Description

Files: xmodem.h & xmodem.c

XMODEM is a simple file transfer protocol. The file is broken up into a series of 128-byte data packets that are sent to the receiver. The packet is prefixed with a 3 byte header containing a SOH character, a "block number" from 0-255, and the "inverse" block number (255 minus the block number). A 16-bit CRC is appended to the data.

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

• C (0x43) : ASCII 'C' to start an XMODEM transfer using CRC
• ACK (0x06) : Acknowledge
• NAK (0x15) : Not Acknowledge
• EOT (0x04) : End of Transmission

A callback function must be specified to handle the received data.

See also:

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

---

Function Documentation

bool_t xmodem_rx_file

(

xmodem_on_rx_data_t

on_rx_data

)

Parameters:

on_rx_data

Pointer to a function that will be called with each correctly received packet.

Return values:

	TRUE	File succesfully received
	FALSE	Timed out while trying to receive a file

Definition at line 213 of file xmodem.c.

References tmr_poll_has_exipred(), TMR_POLL_MS_TO_START_VAL, tmr_poll_start(), uart_poll_rx_byte(), and uart_poll_tx_byte().

{
    u8_t   retry_count    = XMODEM_MAX_RETRIES_START;
    bool_t first_ack_sent = FALSE;
    u8_t   data;

    // Reset packet number
    xmodem_packet_number = 1;

    // Repeat until transfer is finished or error count is exceeded
    while(retry_count--)
    {
        if(!first_ack_sent)
        {
            // Send initial start character to start transfer (with CRC checking)
            uart_poll_tx_byte(XMODEM_C);
        }

        // Receive packet
        switch(xmodem_rx_packet())
        {
        case XMODEM_NO_ERROR:
            // Pass received data on to handler
            (*on_rx_data)(xmodem_rx_buffer+3,XMODEM_DATA_SIZE);
            // Acknowledge packet
            uart_poll_tx_byte(XMODEM_ACK);
            // Set flag to indicate that first packet has been correctly received
            first_ack_sent = TRUE;
            // Next packet
            xmodem_packet_number++;
            // Reset retry count
            retry_count = XMODEM_MAX_RETRIES;
            break;

        case XMODEM_RECEIVED_EOT:           
            // Acknowledge EOT and make sure sender has received ACK
            XMODEM_EOT_STATE:
            while(--retry_count)
            {
                uart_poll_tx_byte(XMODEM_ACK);
                tmr_poll_start(TMR_POLL_MS_TO_START_VAL(XMODEM_TIMEOUT_MS));
                while(!tmr_poll_has_exipred())
                {
                    if(uart_poll_rx_byte(&data))
                        if(data == XMODEM_EOT)
                        {
                            // Unfortunate, but neccesary use of the "goto" keyword
                            goto XMODEM_EOT_STATE;
                        }
                }
                // File successfully transferred
                return TRUE;
            }
            // File not successfully transferred
            return FALSE;

        case XMODEM_ERR_DUPLICATE_PACKET_NUMBER:
            // Acknowledge packet
            uart_poll_tx_byte(XMODEM_ACK);
            break;

        case XMODEM_ERR_RECEIVED_NOTHING:
            // Fall through...
        case XMODEM_ERR_RECEIVE_TIMEOUT:
            // Fall through...
        case XMODEM_ERR_INCORRECT_HEADER:
            // Fall through...
        case XMODEM_ERR_INCORRECT_PACKET_NUMBER:
            // Fall through...
        case XMODEM_ERR_INCORRECT_CRC:
            // Fall through...
        default:
            if(first_ack_sent)
            {
                // Send NAK
                uart_poll_tx_byte(XMODEM_NAK);
            }
            break;
        }        
    }

    // File not successfully transferred
    return FALSE;
}