API Reference

Header files

• include/xymodem.h

File include/xymodem.h

Structures and Types

Functions

Macros

Structures and Types Documentation

struct xmodem_data_sink_t

The abstraction representing where data received by XMODEM is delivered.

Variables:

• void * ctx
  User-defined context passed to write().

• xymodem_write_fn_t write
  Deliver received payload bytes to the application.
  Note:

The XMODEM protocol cannot distinguish the payload from trailing padding. The padding is also delivered through this function.

struct xmodem_data_source_t

The abstraction representing the source of data to be sent via XMODEM.

Variables:

• void * ctx
  User-defined context passed to read().

• xymodem_read_fn_t read
  Read the next chunk of payload to transmit.

enum xymodem_block_size_t

Block size as defined by the X/YMODEM protocol.

enum xymodem_block_size_t {
    XYMODEM_BLOCK_SIZE_MIXED = 0,
    XYMODEM_BLOCK_SIZE_128 = 128,
    XYMODEM_BLOCK_SIZE_1024 = 1024
};

enum xymodem_check_type_t

Verification types as defined by the X/YMODEM protocol.

enum xymodem_check_type_t {
    XYMODEM_CHECK_AUTO = 0,
    XYMODEM_CHECK_SUM8,
    XYMODEM_CHECK_CRC16
};

typedef xymodem_read_fn_t

Read data from a source, such as a file or a simple array. The protocol layer obtains the data to be sent through this function.

typedef esp_err_t(* xymodem_read_fn_t) (void *ctx, void *buf, size_t len, size_t *read_len);

Parameters:

• ctx User-defined context.
• buf Buffer to store read data.
• len Requested length of data to read.
• read_len Actual length of data read.

Returns:

ESP_OK if the data was successfully read. Returning an error will abort the X/YMODEM transfer.

Note:

This function attempts to read exactly len bytes, but may return fewer bytes if the end of the source is reached. A short read (read_len < len) is only allowed when no further data is available. read_len must not exceed len

struct xymodem_recv_config_t

Receiver configuration.

Variables:

• uint32_t can_interval_ms
  Max interval between two CAN bytes when recognizing peer cancel. Must be > 0.

• uint8_t cancel_can_count
  Number of CAN bytes to send when aborting. Must be >= 2.

• xymodem_check_type_t check_type
  Checksum or CRC mode to request during handshake.

• uint32_t max_retry_cnt
  Maximum number of extra retries after the first attempt.

• uint32_t packet_timeout_ms
  Wait for a packet before sending NAK. Must be > 0.

• uint32_t purge_idle_timeout_ms
  RX idle time required to finish a purge. Set based on the physical link rate.

struct xymodem_send_config_t

Sender configuration.

Variables:

• xymodem_block_size_t block_size
  Packet payload size to use when sending.

• uint32_t can_interval_ms
  Max interval between two CAN bytes when recognizing peer cancel. Must be > 0.

• uint8_t cancel_can_count
  Number of CAN bytes to send when aborting. Must be >= 2.

• uint32_t max_retry_cnt
  Maximum number of extra retries after the first attempt.

• uint32_t purge_idle_timeout_ms
  RX idle time required to finish a purge. Set based on the physical link rate.

• uint32_t response_timeout_ms
  Wait for handshake or ACK/NAK. Must be > 0. Set several times longer than the receiver packet timeout.

struct xymodem_transport_t

The abstraction of the low-level communication channel used by X/YMODEM protocol layer.

Variables:

• void * ctx
  User-defined context passed to recv()_ and_send().

• esp_err_t(* recv
  Receive data through some interface, such as a serial port.
  Parameters:

• ctx User-defined context.
• buf Buffer to store received data.
• len Requested length of data to receive.
• recv_len Actual length of data received.
• timeout_ms Timeout in milliseconds. 0 means non-blocking.

Returns:

• ESP_OK if the requested amount of data is received in full, or if the timeout expires.
• others if an error occurs during the transfer. Timeout is NOT considered as an error.

Note:

This function attempts to receive the full requested amount within the timeout period. If the timeout is reached, return whatever data has been received. Returning early with a short read before the timeout is not allowed.

• esp_err_t(* send
  Send data through some interface, such as a serial port.
  Parameters:

• ctx User-defined context.
• buf Buffer to send.
• len Length of data to send.

Returns:

• ESP_OK if all data was successfully sent or queued for transmission.
• others if an error occurs during the transfer.

typedef xymodem_write_fn_t

Write data to a destination, such as a file or a simple array. The data received by the protocol layer is passed to the upper-layer application through this function.

typedef esp_err_t(* xymodem_write_fn_t) (void *ctx, const void *buf, size_t len);

Parameters:

• ctx User-defined context.
• buf Buffer containing the data to write.
• len Length of data to write.

Returns:

ESP_OK if all data was successfully written. Returning an error will abort the X/YMODEM transfer.

Note:

This function can also process the data on the fly, without necessarily storing it anywhere.

Functions Documentation

function xmodem_recv

Receive data using the XMODEM protocol.

esp_err_t xmodem_recv (
    const xymodem_transport_t *transport,
    const xymodem_recv_config_t *config,
    const xmodem_data_sink_t *sink
) 

This function performs a complete XMODEM reception using the provided transport and data sink, and blocks until the transmission completes, fails, or is cancelled.

Parameters:

• transport Transport interface used for sending and receiving protocol data.
• config XMODEM receiver configuration.
• sink Data sink that receives the transmitted payload.

Returns:

• ESP_OK: Reception completed successfully.
• ESP_ERR_INVALID_ARG: One or more arguments or configuration values are invalid.
• ESP_ERR_NO_MEM: Not enough memory to complete the reception.
• ESP_ERR_XYMODEM_NO_RESPONSE: The peer did not respond within the configured timeout.
• ESP_ERR_XYMODEM_CANCEL_BY_PEER: The transmission was cancelled by the peer.
• ESP_ERR_XYMODEM_RETRY_EXCEEDED: The maximum number of retries was exceeded.
• ESP_ERR_XYMODEM_OUT_OF_SYNC: The received packet sequence is out of sync.
• Other errors returned by the transport or data sink.

function xmodem_recv_buffer

Directly receive data into a buffer using XMODEM.

esp_err_t xmodem_recv_buffer (
    const xymodem_transport_t *transport,
    const xymodem_recv_config_t *config,
    void *buf,
    size_t len,
    size_t *recv_len
) 

Parameters:

• transport The transport layer to use.
• config The receive configuration.
• buf The buffer to receive the data.
• len The length of the buffer.
• recv_len Number of bytes stored in buf. May be NULL.

Note:

XMODEM cannot distinguish payload data from trailing padding, so the last packet may be larger than the remaining buffer space. Bytes from that packet that fit are stored; the rest of the packet is discarded. If another packet arrives after buf is already full, the transfer is aborted.

Returns:

• ESP_OK if the transfer completed. recv_len (when not NULL) is the number of bytes stored inbuf, which is at mostlen.
• ESP_ERR_NO_MEM: buf was filled and the peer sent another packet.
• others if an error occurs (same as xmodem_recv()).recv_len still reports how many bytes were stored before the failure.

function xmodem_send

Send data using the XMODEM protocol.

esp_err_t xmodem_send (
    const xymodem_transport_t *transport,
    const xymodem_send_config_t *config,
    const xmodem_data_source_t *source
) 

This function performs a complete XMODEM transmission using the provided transport and data source, and blocks until the transmission completes, fails, or is cancelled.

Parameters:

• transport Transport interface used for sending and receiving protocol data.
• config XMODEM sender configuration.
• source Data source providing the payload to be transmitted.

Returns:

• ESP_OK: Transmission completed successfully.
• ESP_ERR_INVALID_ARG: One or more arguments or configuration values are invalid.
• ESP_ERR_NO_MEM: Not enough memory to complete the transmission.
• ESP_ERR_XYMODEM_NO_RESPONSE: The peer did not respond within the configured timeout.
• ESP_ERR_XYMODEM_CANCEL_BY_PEER: The transmission was cancelled by the peer.
• ESP_ERR_XYMODEM_RETRY_EXCEEDED: The maximum number of retries was exceeded.
• Other errors returned by the transport or data source.

function xmodem_send_buffer

Directly send the contents of a buffer using XMODEM.

esp_err_t xmodem_send_buffer (
    const xymodem_transport_t *transport,
    const xymodem_send_config_t *config,
    const void *buf,
    size_t len
) 

Parameters:

• transport The transport layer to use.
• config The send configuration.
• buf The buffer to send.
• len The length of the buffer.

Returns:

• ESP_OK if the data was successfully sent.
• others if an error occurs (same as xmodem_send()).

Macros Documentation

define ESP_ERR_XYMODEM_BAD_PACKET

Received data is not a valid packet.

#define ESP_ERR_XYMODEM_BAD_PACKET ( ESP_ERR_XYMODEM_BASE + 3)

define ESP_ERR_XYMODEM_BASE

#define ESP_ERR_XYMODEM_BASE 0x1E000

define ESP_ERR_XYMODEM_CANCEL_BY_PEER

Cancelled by the peer (two consecutive CAN bytes).

#define ESP_ERR_XYMODEM_CANCEL_BY_PEER ( ESP_ERR_XYMODEM_BASE + 1)

define ESP_ERR_XYMODEM_NO_RESPONSE

Peer did not respond within the timeout.

#define ESP_ERR_XYMODEM_NO_RESPONSE ( ESP_ERR_XYMODEM_BASE + 4)

define ESP_ERR_XYMODEM_OUT_OF_SYNC

Packet sequence number is neither expected nor previous.

#define ESP_ERR_XYMODEM_OUT_OF_SYNC ( ESP_ERR_XYMODEM_BASE + 5)

define ESP_ERR_XYMODEM_RETRY_EXCEEDED

Retry limit reached.

#define ESP_ERR_XYMODEM_RETRY_EXCEEDED ( ESP_ERR_XYMODEM_BASE + 2)

define XYMODEM_RECV_CONFIG_DEFAULT

Default XMODEM receiver configuration.

#define XYMODEM_RECV_CONFIG_DEFAULT (
    
) { \
    .check_type = XYMODEM_CHECK_AUTO , \
    .packet_timeout_ms = 3000, \
    .max_retry_cnt = 10, \
    .cancel_can_count = 2, \
    .can_interval_ms = 100, \
    .purge_idle_timeout_ms = 10, \
}

Note:

These defaults are intended for a good-quality link to a modern peer (CRC-16, 1K blocks). For noisy links, slower devices, or legacy implementations, adjust the fields as needed.

define XYMODEM_SEND_CONFIG_DEFAULT

Default XMODEM sender configuration.

#define XYMODEM_SEND_CONFIG_DEFAULT (
    
) { \
    .block_size = XYMODEM_BLOCK_SIZE_MIXED , \
    .response_timeout_ms = 30000, \
    .max_retry_cnt = 10, \
    .cancel_can_count = 2, \
    .can_interval_ms = 100, \
    .purge_idle_timeout_ms = 10, \
}

Note:

These defaults are intended for a good-quality link to a modern peer (CRC-16, 1K blocks). For noisy links, slower devices, or legacy implementations, adjust the fields as needed.