File syn_ymodem.h¶

FileList > proto > syn_ymodem.h

YMODEM / XMODEM-1K Serial File Transfer Receiver Protocol. More...

#include "../common/syn_defs.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_YMODEM_Receiver YMODEM Receiver Context.

Public Types¶

Type	Name
enum	SYN_YMODEM_Event YMODEM Event Types passed to callback.
typedef int(*	SYN_YMODEM_EventCallback Application callback for YMODEM transfer events.
typedef int(*	SYN_YMODEM_GetChar Read a byte from the serial link (UART RX).
typedef void(*	SYN_YMODEM_PutChar Write a byte to the serial link (UART TX).
enum	SYN_YMODEM_Status YMODEM Session Status Codes.

Public Functions¶

Type	Name
SYN_YMODEM_Status	syn_ymodem_receive (SYN_YMODEM_Receiver * rx) Execute a YMODEM receive session.
void	syn_ymodem_receiver_init (SYN_YMODEM_Receiver * rx, SYN_YMODEM_PutChar putchar_fn, SYN_YMODEM_GetChar getchar_fn, SYN_YMODEM_EventCallback event_fn, void * ctx) Initialize a YMODEM receiver instance.

Macros¶

Type	Name
define	SYN_YMODEM_ACK `0x06U`
define	SYN_YMODEM_CAN `0x18U`
define	SYN_YMODEM_CRC `0x43U`
define	SYN_YMODEM_EOT `0x04U`
define	SYN_YMODEM_MAX_BLOCK_SIZE `1024U`
define	SYN_YMODEM_MAX_FILENAME `64U`
define	SYN_YMODEM_MAX_RETRIES `10U`
define	SYN_YMODEM_NAK `0x15U`
define	SYN_YMODEM_SOH `0x01U`
define	SYN_YMODEM_STX `0x02U`

Detailed Description¶

Implements a lightweight, zero-allocation YMODEM (and XMODEM-1K compatible) batch file transfer receiver state machine for microcontroller bootloaders. Supports Block 0 metadata (filename, file size parsing), 1024-byte (STX) and 128-byte (SOH) blocks, CRC-16/XMODEM error checking, and cancellation.

** **

SYN_YMODEM_Receiver rx;
syn_ymodem_receiver_init(&rx, my_putchar, my_getchar, my_event_cb, user_ctx);
SYN_YMODEM_Status status = syn_ymodem_receive(&rx);

Public Types Documentation¶

enum SYN_YMODEM_Event¶

YMODEM Event Types passed to callback.

enum SYN_YMODEM_Event {
    SYN_YMODEM_EVENT_FILE_START = 0,
    SYN_YMODEM_EVENT_DATA = 1,
    SYN_YMODEM_EVENT_FILE_END = 2,
    SYN_YMODEM_EVENT_SESSION_END = 3
};

typedef SYN_YMODEM_EventCallback¶

Application callback for YMODEM transfer events.

typedef int(* SYN_YMODEM_EventCallback) (SYN_YMODEM_Event event, const uint8_t *data, size_t len, void *ctx);

Parameters:

event Event type.
data Payload buffer (filename for FILE_START, block payload for DATA).
len Payload size in bytes.
ctx User context.

Returns:

0 on success, non-zero to cancel transfer.

typedef SYN_YMODEM_GetChar¶

Read a byte from the serial link (UART RX).

typedef int(* SYN_YMODEM_GetChar) (uint32_t timeout_ms, void *ctx);

Parameters:

timeout_ms Read timeout in milliseconds.
ctx User context.

Returns:

Byte value (0-255) on success, or negative value (<0) on timeout/error.

typedef SYN_YMODEM_PutChar¶

Write a byte to the serial link (UART TX).

typedef void(* SYN_YMODEM_PutChar) (uint8_t byte, void *ctx);

Parameters:

byte Data byte to send.
ctx User context.

enum SYN_YMODEM_Status¶

YMODEM Session Status Codes.

enum SYN_YMODEM_Status {
    SYN_YMODEM_OK = 0,
    SYN_YMODEM_ERR_TIMEOUT = -1,
    SYN_YMODEM_ERR_CRC = -2,
    SYN_YMODEM_ERR_CANCEL = -3,
    SYN_YMODEM_ERR_SEQUENCE = -4,
    SYN_YMODEM_ERR_OVERFLOW = -5,
    SYN_YMODEM_ERR_PARAM = -6
};

Public Functions Documentation¶

function syn_ymodem_receive¶

Execute a YMODEM receive session.

SYN_YMODEM_Status syn_ymodem_receive (
    SYN_YMODEM_Receiver * rx
)

Runs the YMODEM handshake, processes Block 0 header, accepts data packets, verifies CRCs, and invokes event callbacks until all files in the batch are transferred or an unrecoverable error occurs.

Parameters:

rx Receiver context.

Returns:

SYN_YMODEM_OK on successful session completion, or error code (<0).

function syn_ymodem_receiver_init¶

Initialize a YMODEM receiver instance.

void syn_ymodem_receiver_init (
    SYN_YMODEM_Receiver * rx,
    SYN_YMODEM_PutChar putchar_fn,
    SYN_YMODEM_GetChar getchar_fn,
    SYN_YMODEM_EventCallback event_fn,
    void * ctx
)

Parameters:

rx Receiver context.
putchar_fn Serial TX function.
getchar_fn Serial RX function with timeout.
event_fn Event callback handler.
ctx User context pointer.

Macro Definition Documentation¶

define SYN_YMODEM_ACK¶

#define SYN_YMODEM_ACK `0x06U`

Acknowledge

define SYN_YMODEM_CAN¶

#define SYN_YMODEM_CAN `0x18U`

Cancel transmission

define SYN_YMODEM_CRC¶

#define SYN_YMODEM_CRC `0x43U`

ASCII 'C' to request CRC-16 mode

define SYN_YMODEM_EOT¶

#define SYN_YMODEM_EOT `0x04U`

End of transmission

define SYN_YMODEM_MAX_BLOCK_SIZE¶

#define SYN_YMODEM_MAX_BLOCK_SIZE `1024U`

Maximum packet block size (1024 B STX)

define SYN_YMODEM_MAX_FILENAME¶

#define SYN_YMODEM_MAX_FILENAME `64U`

Maximum filename string buffer size

define SYN_YMODEM_MAX_RETRIES¶

#define SYN_YMODEM_MAX_RETRIES `10U`

Maximum packet NAK retry attempts

define SYN_YMODEM_NAK¶

#define SYN_YMODEM_NAK `0x15U`

Negative acknowledge

define SYN_YMODEM_SOH¶

#define SYN_YMODEM_SOH `0x01U`

Start of 128-byte data block

define SYN_YMODEM_STX¶

#define SYN_YMODEM_STX `0x02U`

Start of 1024-byte data block

The documentation for this class was generated from the following file src/syntropic/proto/syn_ymodem.h