File syn_ethercat.h

FileList > proto > syn_ethercat.h

Go to the source code of this file

EtherCAT (IEEE 802.3 EtherType 0x88A4) Bare-Metal Protocol Stack. More...

• #include "../common/syn_defs.h"
• #include "../pt/syn_pt.h"
• #include "syn_canopen.h"
• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>
• #include "../sched/syn_task.h"

Classes

Type	Name
struct	SYN_EcatCoEHeader CoE (CANoverEtherCAT) Mailbox Header.
struct	SYN_EcatDatagram EtherCAT Datagram Header (10 bytes header + 2 bytes WKC = 12 bytes overhead)
struct	SYN_EcatDatagramResult Parsed datagram item from frame iteration.
struct	SYN_EcatFMMUConfig EtherCAT FMMU Configuration.
struct	SYN_EcatHeader Raw EtherCAT Header (2 bytes)
struct	SYN_EcatMaster EtherCAT Master Instance Context (Zero-Heap).
struct	SYN_EcatNode EtherCAT Node Descriptor.
struct	SYN_EcatSMConfig EtherCAT SyncManager Configuration.
struct	SYN_EcatSlaveInfo EtherCAT Slave Information Entry.

Public Types

Type	Name
enum	SYN_EcatCmd
enum	SYN_EcatCoEType
enum	SYN_EcatState

Public Functions

Type	Name
size_t	syn_ecat_build_datagram_frame (uint8_t * buf, size_t buf_len, const SYN_EcatDatagram * datagram, const uint8_t * data, uint16_t data_len) Build an EtherCAT Frame containing one or more datagrams.
size_t	syn_ecat_coe_encode_sdo_download (uint8_t * buf, size_t buf_len, uint16_t index, uint8_t subindex, const void * data, size_t data_len) Encode a CoE SDO Download (Write) request into a mailbox buffer.
size_t	syn_ecat_coe_encode_sdo_upload (uint8_t * buf, size_t buf_len, uint16_t index, uint8_t subindex) Encode a CoE SDO Upload (Read) request into a mailbox buffer.
SYN_Status	syn_ecat_decode_coe_sdo_response (SYN_EcatMaster * m, size_t rx_len, void * out_data, size_t max_len, size_t * out_len) Decode SDO Upload response payload from rx_buf.
SYN_Status	syn_ecat_decode_cyclic (SYN_EcatMaster * m, size_t rx_len) Parse LRW cyclic process exchange response from rx_buf and copy inputs to input_image.
SYN_Status	syn_ecat_decode_read_al_status (SYN_EcatMaster * m, size_t rx_len, SYN_EcatState * state, uint16_t * status_code) Decode Application Layer (AL) Status and Status Code from response.
SYN_Status	syn_ecat_decode_read_reg (SYN_EcatMaster * m, size_t rx_len, void * out_data, uint16_t len) Decode FPRD response datagram for register read.
SYN_Status	syn_ecat_decode_read_sii (SYN_EcatMaster * m, size_t rx_len, uint32_t * out_val) Decode 32-bit word from SII EEPROM read response.
uint8_t	syn_ecat_decode_scan_bus (SYN_EcatMaster * m, size_t rx_len) Decode slave count from scan_bus response frame in rx_buf.
size_t	syn_ecat_encode_assign_addr (SYN_EcatMaster * m, uint16_t position, uint16_t station_addr) Encode Auto-Increment Write (APWR) to assign station address.
size_t	syn_ecat_encode_coe_sdo_read (SYN_EcatMaster * m, uint16_t station_addr, uint16_t index, uint8_t subindex) Encode a complete Mailbox-wrapped CoE SDO Upload request frame into tx_buf.
size_t	syn_ecat_encode_coe_sdo_write (SYN_EcatMaster * m, uint16_t station_addr, uint16_t index, uint8_t subindex, const void * data, size_t data_len) Encode a complete Mailbox-wrapped CoE SDO Download request frame into tx_buf.
size_t	syn_ecat_encode_cyclic (SYN_EcatMaster * m) Encode LRW (Logical Read Write) cyclic process exchange frame into tx_buf.
size_t	syn_ecat_encode_dc_configure (SYN_EcatMaster * m, uint16_t station_addr, uint32_t sync0_cycle_ns, int32_t sync0_shift_ns) Encode FPWR to configure DC SYNC0 cycle time and shift for a slave.
size_t	syn_ecat_encode_dc_read_system_time (SYN_EcatMaster * m) Encode Auto-Increment Read Multiple Write (ARMW) for DC System Time propagation.
size_t	syn_ecat_encode_read_al_status (SYN_EcatMaster * m, uint16_t station_addr) Encode Configured Read (FPRD) to read slave Application Layer (AL) Status.
size_t	syn_ecat_encode_read_reg (SYN_EcatMaster * m, uint16_t station_addr, uint16_t reg_addr, uint16_t len) Encode FPRD to read register reg_addr from slavestation_addr .
size_t	syn_ecat_encode_read_sii (SYN_EcatMaster * m, uint16_t station_addr, uint16_t word_offset) Encode Configured Read (FPRD) to read SII EEPROM word.
size_t	syn_ecat_encode_scan_bus (SYN_EcatMaster * m) Encode Broadcast Read (BRD) to scan bus slave count into master tx_buf.
size_t	syn_ecat_encode_set_al_control (SYN_EcatMaster * m, uint16_t station_addr, SYN_EcatState state) Encode Configured Write (FPWR) to set slave Application Layer (AL) Control register.
size_t	syn_ecat_encode_write_fmmu (SYN_EcatMaster * m, uint16_t station_addr, uint8_t fmmu_index, const SYN_EcatFMMUConfig * cfg) Encode Configured Write (FPWR) to configure an FMMU register block.
size_t	syn_ecat_encode_write_reg (SYN_EcatMaster * m, uint16_t station_addr, uint16_t reg_addr, const void * data, uint16_t len) Encode FPWR to write register reg_addr to slavestation_addr .
size_t	syn_ecat_encode_write_sm (SYN_EcatMaster * m, uint16_t station_addr, uint8_t sm_index, const SYN_EcatSMConfig * cfg) Encode Configured Write (FPWR) to configure a SyncManager register block.
size_t	syn_ecat_frame_add_datagram (uint8_t * buf, size_t buf_size, SYN_EcatCmd cmd, uint8_t idx, uint32_t addr, const uint8_t * data, uint16_t data_len, bool circ) Add a datagram payload to an in-progress EtherCAT frame.
void	syn_ecat_frame_begin (uint8_t * buf, size_t buf_size) Initialize an EtherCAT frame buffer header.
size_t	syn_ecat_frame_finalize (uint8_t * buf) Finalize EtherCAT frame header length field.
bool	syn_ecat_frame_parse_next (const uint8_t * frame, size_t frame_len, size_t * offset, SYN_EcatDatagramResult * out) Parse the next datagram from an EtherCAT frame buffer.
void	syn_ecat_init (SYN_EcatNode * node, uint16_t station_addr, SYN_CANOpenNode * od) Initialize an EtherCAT Node instance.
SYN_PT_Status	syn_ecat_master_cyclic_task (SYN_PT * pt, SYN_EcatMaster * m) Protothread Task: Execute single cyclic process exchange cycle.
SYN_PT_Status	syn_ecat_master_discover_pdo_mapping_task (SYN_PT * pt, SYN_EcatMaster * m, uint16_t station_addr, uint16_t * out_rx_bytes, uint16_t * out_tx_bytes) Protothread Task: Read CoE Object Dictionary 0x1C12/0x1C13 to calculate slave Rx/Tx PDO byte lengths.
SYN_Status	syn_ecat_master_init (SYN_EcatMaster * m, uint8_t * tx_buf, uint16_t tx_buf_size, uint8_t * rx_buf, uint16_t rx_buf_size, uint8_t * output_image, uint16_t output_size, uint8_t * input_image, uint16_t input_size) Initialize EtherCAT Master instance context.
bool	syn_ecat_master_pop_tx_frame (SYN_EcatMaster * m, const uint8_t ** out_frame, size_t * out_len) Pop pending transmit frame for Ethernet PHY driver.
SYN_PT_Status	syn_ecat_master_read_sii_task (SYN_PT * pt, SYN_EcatMaster * m, uint16_t station_addr, uint16_t word_offset, uint32_t * out_data) Protothread Task: Read 32-bit word from slave SII EEPROM via hardware status polling.
SYN_PT_Status	syn_ecat_master_scan_task (SYN_PT * pt, SYN_EcatMaster * m) Protothread Task: Scan EtherCAT bus and assign station addresses.
SYN_PT_Status	syn_ecat_master_sdo_read_task (SYN_PT * pt, SYN_EcatMaster * m, uint16_t station_addr, uint16_t index, uint8_t subindex, void * out_data, size_t max_len, size_t * out_len) Protothread Task: CoE SDO read from slave Object Dictionary with SM1 polling.
SYN_Status	syn_ecat_master_set_rx_frame (SYN_EcatMaster * m, const uint8_t * frame, size_t len) Feed received Ethernet frame into Master context.
SYN_PT_Status	syn_ecat_master_transition_task (SYN_PT * pt, SYN_EcatMaster * m, SYN_EcatState target_state) Protothread Task: Drive EtherCAT slaves through state transition.
SYN_Status	syn_ecat_parse_frame (SYN_EcatNode * node, const uint8_t * frame, size_t len, uint16_t * wkc) Parse and process a received raw EtherCAT frame.
SYN_Status	syn_ecat_set_state (SYN_EcatNode * node, SYN_EcatState new_state) Request an EtherCAT State Machine (ESM) state transition.
void	syn_ecat_update (SYN_EcatNode * node) Run ESM state machine step.

Macros

Type	Name
define	SYN_ECAT_MAX_SLAVES 16U
define	SYN_ESC_REG_AL_CONTROL 0x0120U
define	SYN_ESC_REG_AL_STATUS 0x0130U
define	SYN_ESC_REG_AL_STATUS_CODE 0x0134U
define	SYN_ESC_REG_DC_SYNC0_CYCLE 0x09A0U
define	SYN_ESC_REG_DC_SYSTEM_OFFSET 0x0920U
define	SYN_ESC_REG_DC_SYSTEM_TIME 0x0900U
define	SYN_ESC_REG_FMMU0 0x0600U
define	SYN_ESC_REG_PDI_CONTROL 0x0140U
define	SYN_ESC_REG_SII_EEPROM_CTRL 0x0502U
define	SYN_ESC_REG_SM0 0x0800U
define	SYN_ESC_REG_STATION_ADDR 0x0010U
define	SYN_ESC_REG_STATION_ALIAS 0x0012U
define	SYN_ESC_REG_TYPE 0x0000U
define	SYN_ETHERCAT_ETHERTYPE 0x88A4 EtherCAT IEEE 802.3 Ethernet Frame Type.
define	SYN_ETHERCAT_TYPE_DATAGRAM 1 EtherCAT Header Type (1 = EtherCAT Datagrams)

Detailed Description

Implements EtherCAT Frame packing, Datagram commands (APRD, APWR, APRW, FPRD, FPWR, FPRW, BRD, BWR, LRD, LWR, LRW), Working Counter (WKC) accounting, EtherCAT State Machine (ESM: INIT, PREOP, BOOT, SAFEOP, OP), and CoE (CAN application protocol over EtherCAT) Mailbox SDO & PDO handling.

Designed for zero heap allocation and direct L2 raw Ethernet frame processing.

Public Types Documentation

enum SYN_EcatCmd

enum SYN_EcatCmd {
    SYN_ECAT_CMD_NOP = 0,
    SYN_ECAT_CMD_APRD = 1,
    SYN_ECAT_CMD_APWR = 2,
    SYN_ECAT_CMD_APRW = 3,
    SYN_ECAT_CMD_FPRD = 4,
    SYN_ECAT_CMD_FPWR = 5,
    SYN_ECAT_CMD_FPRW = 6,
    SYN_ECAT_CMD_BRD = 7,
    SYN_ECAT_CMD_BWR = 8,
    SYN_ECAT_CMD_BRW = 9,
    SYN_ECAT_CMD_LRD = 10,
    SYN_ECAT_CMD_LWR = 11,
    SYN_ECAT_CMD_LRW = 12,
    SYN_ECAT_CMD_ARMW = 13,
    SYN_ECAT_CMD_FRMW = 14
};

EtherCAT Datagram Commands Enum.

---

enum SYN_EcatCoEType

enum SYN_EcatCoEType {
    SYN_ECAT_COE_TYPE_EMERGENCY = 1,
    SYN_ECAT_COE_TYPE_SDO_REQ = 2,
    SYN_ECAT_COE_TYPE_SDO_RESP = 3,
    SYN_ECAT_COE_TYPE_RXPDO = 4,
    SYN_ECAT_COE_TYPE_TXPDO = 5,
    SYN_ECAT_COE_TYPE_SDO_INFO = 6
};

CAN Application Protocol over EtherCAT (CoE) Service Types.

---

enum SYN_EcatState

enum SYN_EcatState {
    SYN_ECAT_STATE_NONE = 0x00,
    SYN_ECAT_STATE_INIT = 0x01,
    SYN_ECAT_STATE_PREOP = 0x02,
    SYN_ECAT_STATE_BOOT = 0x03,
    SYN_ECAT_STATE_SAFEOP = 0x04,
    SYN_ECAT_STATE_OP = 0x08
};

EtherCAT State Machine (ESM) States.

---

Public Functions Documentation

function syn_ecat_build_datagram_frame

Build an EtherCAT Frame containing one or more datagrams.

size_t syn_ecat_build_datagram_frame (
    uint8_t * buf,
    size_t buf_len,
    const SYN_EcatDatagram * datagram,
    const uint8_t * data,
    uint16_t data_len
) 

Parameters:

• buf Output frame buffer (must include Ethernet header space if needed).
• buf_len Capacity of output buffer.
• datagram Datagram header descriptor.
• data Payload bytes to write into datagram.
• data_len Payload length.

Returns:

Total EtherCAT frame length in bytes, or 0 on error.

---

function syn_ecat_coe_encode_sdo_download

Encode a CoE SDO Download (Write) request into a mailbox buffer.

size_t syn_ecat_coe_encode_sdo_download (
    uint8_t * buf,
    size_t buf_len,
    uint16_t index,
    uint8_t subindex,
    const void * data,
    size_t data_len
) 

Parameters:

• buf Output buffer.
• buf_len Capacity of output buffer.
• index Object Dictionary Index (0x0000 - 0xFFFF).
• subindex Subindex (0x00 - 0xFF).
• data Data bytes to write.
• data_len Data length (1-4 bytes for expedited SDO).

Returns:

Encoded CoE Mailbox packet length in bytes, or 0 on error.

---

function syn_ecat_coe_encode_sdo_upload

Encode a CoE SDO Upload (Read) request into a mailbox buffer.

size_t syn_ecat_coe_encode_sdo_upload (
    uint8_t * buf,
    size_t buf_len,
    uint16_t index,
    uint8_t subindex
) 

Parameters:

• buf Output buffer.
• buf_len Capacity of output buffer.
• index Object Dictionary Index (0x0000 - 0xFFFF).
• subindex Subindex (0x00 - 0xFF).

Returns:

Encoded CoE Mailbox packet length in bytes, or 0 on error.

---

function syn_ecat_decode_coe_sdo_response

Decode SDO Upload response payload from rx_buf.

SYN_Status syn_ecat_decode_coe_sdo_response (
    SYN_EcatMaster * m,
    size_t rx_len,
    void * out_data,
    size_t max_len,
    size_t * out_len
) 

Parameters:

• m Pointer to master handle.
• rx_len Received frame length.
• out_data Output destination buffer.
• max_len Maximum output buffer capacity.
• out_len Pointer to receive read byte count.

Returns:

SYN_OK on success.

---

function syn_ecat_decode_cyclic

Parse LRW cyclic process exchange response from rx_buf and copy inputs to input_image.

SYN_Status syn_ecat_decode_cyclic (
    SYN_EcatMaster * m,
    size_t rx_len
) 

Parameters:

• m Pointer to master handle.
• rx_len Received frame byte length.

Returns:

SYN_OK if WKC >= wkc_expected, SYN_ERROR on WKC mismatch or parsing error.

---

function syn_ecat_decode_read_al_status

Decode Application Layer (AL) Status and Status Code from response.

SYN_Status syn_ecat_decode_read_al_status (
    SYN_EcatMaster * m,
    size_t rx_len,
    SYN_EcatState * state,
    uint16_t * status_code
) 

Parameters:

• m Pointer to master handle.
• rx_len Received frame length.
• state [out] Output location for current ESM state.
• status_code [out] Output location for AL status error code.

Returns:

SYN_OK on success.

---

function syn_ecat_decode_read_reg

Decode FPRD response datagram for register read.

SYN_Status syn_ecat_decode_read_reg (
    SYN_EcatMaster * m,
    size_t rx_len,
    void * out_data,
    uint16_t len
) 

Parameters:

• m Pointer to master handle.
• rx_len Received Ethernet frame length.
• out_data Destination buffer for register data.
• len Expected byte length.

Returns:

SYN_OK on success, error code otherwise.

---

function syn_ecat_decode_read_sii

Decode 32-bit word from SII EEPROM read response.

SYN_Status syn_ecat_decode_read_sii (
    SYN_EcatMaster * m,
    size_t rx_len,
    uint32_t * out_val
) 

Parameters:

• m Pointer to master handle.
• rx_len Received frame length.
• out_val Pointer to receive parsed 32-bit SII value.

Returns:

SYN_OK on success.

---

function syn_ecat_decode_scan_bus

Decode slave count from scan_bus response frame in rx_buf.

uint8_t syn_ecat_decode_scan_bus (
    SYN_EcatMaster * m,
    size_t rx_len
) 

Parameters:

• m Pointer to master handle.
• rx_len Received frame byte length.

Returns:

Discovered slave count.

---

function syn_ecat_encode_assign_addr

Encode Auto-Increment Write (APWR) to assign station address.

size_t syn_ecat_encode_assign_addr (
    SYN_EcatMaster * m,
    uint16_t position,
    uint16_t station_addr
) 

Parameters:

• m Pointer to master handle.
• position Ring position index (0..slave_count-1).
• station_addr Configured station address to set (e.g. 0x1001).

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_coe_sdo_read

Encode a complete Mailbox-wrapped CoE SDO Upload request frame into tx_buf.

size_t syn_ecat_encode_coe_sdo_read (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t index,
    uint8_t subindex
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• index Object Dictionary Index.
• subindex Subindex.

Returns:

Transmit frame byte length, or 0 on error.

---

function syn_ecat_encode_coe_sdo_write

Encode a complete Mailbox-wrapped CoE SDO Download request frame into tx_buf.

size_t syn_ecat_encode_coe_sdo_write (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t index,
    uint8_t subindex,
    const void * data,
    size_t data_len
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• index Object Dictionary Index.
• subindex Subindex.
• data Pointer to payload bytes (<=4 bytes for expedited SDO).
• data_len Payload byte length.

Returns:

Transmit frame byte length, or 0 on error.

---

function syn_ecat_encode_cyclic

Encode LRW (Logical Read Write) cyclic process exchange frame into tx_buf.

size_t syn_ecat_encode_cyclic (
    SYN_EcatMaster * m
) 

Parameters:

• m Pointer to master handle.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_dc_configure

Encode FPWR to configure DC SYNC0 cycle time and shift for a slave.

size_t syn_ecat_encode_dc_configure (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint32_t sync0_cycle_ns,
    int32_t sync0_shift_ns
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• sync0_cycle_ns SYNC0 cycle time in nanoseconds.
• sync0_shift_ns SYNC0 shift time in nanoseconds.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_dc_read_system_time

Encode Auto-Increment Read Multiple Write (ARMW) for DC System Time propagation.

size_t syn_ecat_encode_dc_read_system_time (
    SYN_EcatMaster * m
) 

Parameters:

• m Pointer to master handle.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_read_al_status

Encode Configured Read (FPRD) to read slave Application Layer (AL) Status.

size_t syn_ecat_encode_read_al_status (
    SYN_EcatMaster * m,
    uint16_t station_addr
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_read_reg

Encode FPRD to read register reg_addr from slavestation_addr .

size_t syn_ecat_encode_read_reg (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t reg_addr,
    uint16_t len
) 

Parameters:

• m Pointer to master handle.
• station_addr Configured station address of slave.
• reg_addr Register address to read.
• len Number of bytes to read.

Returns:

Encoded Ethernet frame length.

---

function syn_ecat_encode_read_sii

Encode Configured Read (FPRD) to read SII EEPROM word.

size_t syn_ecat_encode_read_sii (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t word_offset
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• word_offset SII EEPROM word offset.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_scan_bus

Encode Broadcast Read (BRD) to scan bus slave count into master tx_buf.

size_t syn_ecat_encode_scan_bus (
    SYN_EcatMaster * m
) 

Parameters:

• m Pointer to master handle.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_set_al_control

Encode Configured Write (FPWR) to set slave Application Layer (AL) Control register.

size_t syn_ecat_encode_set_al_control (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    SYN_EcatState state
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• state Requested ESM State (INIT, PREOP, SAFEOP, OP).

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_write_fmmu

Encode Configured Write (FPWR) to configure an FMMU register block.

size_t syn_ecat_encode_write_fmmu (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint8_t fmmu_index,
    const SYN_EcatFMMUConfig * cfg
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• fmmu_index FMMU index (0..3).
• cfg Pointer to FMMU configuration settings.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_encode_write_reg

Encode FPWR to write register reg_addr to slavestation_addr .

size_t syn_ecat_encode_write_reg (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t reg_addr,
    const void * data,
    uint16_t len
) 

Parameters:

• m Pointer to master handle.
• station_addr Configured station address of slave.
• reg_addr Register address to write.
• data Pointer to data bytes to write.
• len Number of bytes to write.

Returns:

Encoded Ethernet frame length.

---

function syn_ecat_encode_write_sm

Encode Configured Write (FPWR) to configure a SyncManager register block.

size_t syn_ecat_encode_write_sm (
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint8_t sm_index,
    const SYN_EcatSMConfig * cfg
) 

Parameters:

• m Pointer to master handle.
• station_addr Target slave station address.
• sm_index SyncManager index (0..3).
• cfg Pointer to SyncManager configuration settings.

Returns:

Transmit frame length in bytes, or 0 on error.

---

function syn_ecat_frame_add_datagram

Add a datagram payload to an in-progress EtherCAT frame.

size_t syn_ecat_frame_add_datagram (
    uint8_t * buf,
    size_t buf_size,
    SYN_EcatCmd cmd,
    uint8_t idx,
    uint32_t addr,
    const uint8_t * data,
    uint16_t data_len,
    bool circ
) 

Parameters:

• buf Target output buffer.
• buf_size Total capacity of output buffer.
• cmd Datagram command type.
• idx Datagram index.
• addr 32-bit address field.
• data Payload data bytes (or NULL if data_len is 0).
• data_len Payload data length in bytes.
• circ True if circulating datagram flag set.

Returns:

Output byte offset after added datagram, or 0 on error / insufficient space.

---

function syn_ecat_frame_begin

Initialize an EtherCAT frame buffer header.

void syn_ecat_frame_begin (
    uint8_t * buf,
    size_t buf_size
) 

Parameters:

• buf Target output buffer.
• buf_size Total capacity of output buffer.

---

function syn_ecat_frame_finalize

Finalize EtherCAT frame header length field.

size_t syn_ecat_frame_finalize (
    uint8_t * buf
) 

Parameters:

• buf Target output buffer.

Returns:

Total frame size in bytes (including 2-byte EtherCAT header).

---

function syn_ecat_frame_parse_next

Parse the next datagram from an EtherCAT frame buffer.

bool syn_ecat_frame_parse_next (
    const uint8_t * frame,
    size_t frame_len,
    size_t * offset,
    SYN_EcatDatagramResult * out
) 

Parameters:

• frame Pointer to raw EtherCAT frame bytes (starts with 2-byte EtherCAT header).
• frame_len Total byte length of frame buffer.
• offset In/out byte offset into frame buffer. Set *offset = 2 to start.
• out [out] Result struct to receive parsed datagram details.

Returns:

true if datagram parsed successfully, false if no more datagrams or malformed.

---

function syn_ecat_init

Initialize an EtherCAT Node instance.

void syn_ecat_init (
    SYN_EcatNode * node,
    uint16_t station_addr,
    SYN_CANOpenNode * od
) 

Parameters:

• node EtherCAT node instance.
• station_addr Configured station address.
• od Optional CANopen Object Dictionary binding for CoE.

---

function syn_ecat_master_cyclic_task

Protothread Task: Execute single cyclic process exchange cycle.

SYN_PT_Status syn_ecat_master_cyclic_task (
    SYN_PT * pt,
    SYN_EcatMaster * m
) 

Parameters:

• pt Protothread state handle.
• m Pointer to master handle.

Returns:

PT_WAITING if waiting for frames, PT_ENDED when cycle complete.

---

function syn_ecat_master_discover_pdo_mapping_task

Protothread Task: Read CoE Object Dictionary 0x1C12/0x1C13 to calculate slave Rx/Tx PDO byte lengths.

SYN_PT_Status syn_ecat_master_discover_pdo_mapping_task (
    SYN_PT * pt,
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t * out_rx_bytes,
    uint16_t * out_tx_bytes
) 

Parameters:

• pt Protothread context pointer.
• m Pointer to master handle.
• station_addr Configured station address of slave.
• out_rx_bytes Destination pointer for Rx PDO byte size.
• out_tx_bytes Destination pointer for Tx PDO byte size.

Returns:

PT_WAITING if waiting, PT_ENDED when complete.

---

function syn_ecat_master_init

Initialize EtherCAT Master instance context.

SYN_Status syn_ecat_master_init (
    SYN_EcatMaster * m,
    uint8_t * tx_buf,
    uint16_t tx_buf_size,
    uint8_t * rx_buf,
    uint16_t rx_buf_size,
    uint8_t * output_image,
    uint16_t output_size,
    uint8_t * input_image,
    uint16_t input_size
) 

Parameters:

• m Pointer to master handle.
• tx_buf Pointer to static transmit frame buffer.
• tx_buf_size Capacity of transmit frame buffer.
• rx_buf Pointer to static receive frame buffer.
• rx_buf_size Capacity of receive frame buffer.
• output_image Output process image buffer pointer.
• output_size Output process image byte size.
• input_image Input process image buffer pointer.
• input_size Input process image byte size.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if parameters null/invalid.

---

function syn_ecat_master_pop_tx_frame

Pop pending transmit frame for Ethernet PHY driver.

bool syn_ecat_master_pop_tx_frame (
    SYN_EcatMaster * m,
    const uint8_t ** out_frame,
    size_t * out_len
) 

Parameters:

• m Pointer to master handle.
• out_frame [out] Pointer to receive frame location.
• out_len [out] Pointer to receive frame length.

Returns:

true if frame was popped, false if no frame pending.

---

function syn_ecat_master_read_sii_task

Protothread Task: Read 32-bit word from slave SII EEPROM via hardware status polling.

SYN_PT_Status syn_ecat_master_read_sii_task (
    SYN_PT * pt,
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t word_offset,
    uint32_t * out_data
) 

Parameters:

• pt Protothread context pointer.
• m Pointer to master handle.
• station_addr Configured station address of slave.
• word_offset 16-bit word offset in SII EEPROM.
• out_data Destination pointer for 32-bit word.

Returns:

PT_WAITING if waiting, PT_ENDED when complete.

---

function syn_ecat_master_scan_task

Protothread Task: Scan EtherCAT bus and assign station addresses.

SYN_PT_Status syn_ecat_master_scan_task (
    SYN_PT * pt,
    SYN_EcatMaster * m
) 

Parameters:

• pt Protothread state handle.
• m Pointer to master handle.

Returns:

PT_WAITING if waiting for frames, PT_ENDED when scan complete.

---

function syn_ecat_master_sdo_read_task

Protothread Task: CoE SDO read from slave Object Dictionary with SM1 polling.

SYN_PT_Status syn_ecat_master_sdo_read_task (
    SYN_PT * pt,
    SYN_EcatMaster * m,
    uint16_t station_addr,
    uint16_t index,
    uint8_t subindex,
    void * out_data,
    size_t max_len,
    size_t * out_len
) 

Parameters:

• pt Protothread context pointer.
• m Pointer to master handle.
• station_addr Configured station address of slave.
• index 16-bit Object Dictionary index.
• subindex 8-bit sub-index.
• out_data Destination buffer for SDO payload.
• max_len Capacity of destination buffer.
• out_len Destination pointer for actual payload length.

Returns:

PT_WAITING if waiting, PT_ENDED when complete.

---

function syn_ecat_master_set_rx_frame

Feed received Ethernet frame into Master context.

SYN_Status syn_ecat_master_set_rx_frame (
    SYN_EcatMaster * m,
    const uint8_t * frame,
    size_t len
) 

Parameters:

• m Pointer to master handle.
• frame Pointer to raw frame payload bytes.
• len Frame length in bytes.

Returns:

SYN_OK on success.

---

function syn_ecat_master_transition_task

Protothread Task: Drive EtherCAT slaves through state transition.

SYN_PT_Status syn_ecat_master_transition_task (
    SYN_PT * pt,
    SYN_EcatMaster * m,
    SYN_EcatState target_state
) 

Parameters:

• pt Protothread state handle.
• m Pointer to master handle.
• target_state Target ESM state (INIT, PREOP, SAFEOP, OP).

Returns:

PT_WAITING if waiting for frames, PT_ENDED when transition complete.

---

function syn_ecat_parse_frame

Parse and process a received raw EtherCAT frame.

SYN_Status syn_ecat_parse_frame (
    SYN_EcatNode * node,
    const uint8_t * frame,
    size_t len,
    uint16_t * wkc
) 

Parameters:

• node EtherCAT node instance.
• frame Raw received frame bytes (after Ethernet header).
• len Frame length in bytes.
• wkc [out] Extracted Working Counter sum.

Returns:

SYN_OK on successful parsing and WKC validation.

---

function syn_ecat_set_state

Request an EtherCAT State Machine (ESM) state transition.

SYN_Status syn_ecat_set_state (
    SYN_EcatNode * node,
    SYN_EcatState new_state
) 

Parameters:

• node EtherCAT node instance.
• new_state Requested state (INIT, PREOP, BOOT, SAFEOP, OP).

Returns:

SYN_OK if state transition request is valid.

---

function syn_ecat_update

Run ESM state machine step.

void syn_ecat_update (
    SYN_EcatNode * node
) 

Parameters:

• node EtherCAT node instance.

---

Macro Definition Documentation

define SYN_ECAT_MAX_SLAVES

#define SYN_ECAT_MAX_SLAVES `16U`

Maximum connected EtherCAT slaves supported

---

define SYN_ESC_REG_AL_CONTROL

#define SYN_ESC_REG_AL_CONTROL `0x0120U`

Application Layer Control

---

define SYN_ESC_REG_AL_STATUS

#define SYN_ESC_REG_AL_STATUS `0x0130U`

Application Layer Status

---

define SYN_ESC_REG_AL_STATUS_CODE

#define SYN_ESC_REG_AL_STATUS_CODE `0x0134U`

Application Layer Status Code

---

define SYN_ESC_REG_DC_SYNC0_CYCLE

#define SYN_ESC_REG_DC_SYNC0_CYCLE `0x09A0U`

DC SYNC0 Cycle Time

---

define SYN_ESC_REG_DC_SYSTEM_OFFSET

#define SYN_ESC_REG_DC_SYSTEM_OFFSET `0x0920U`

DC System Time Offset

---

define SYN_ESC_REG_DC_SYSTEM_TIME

#define SYN_ESC_REG_DC_SYSTEM_TIME `0x0900U`

DC System Time (64-bit)

---

define SYN_ESC_REG_FMMU0

#define SYN_ESC_REG_FMMU0 `0x0600U`

FMMU 0 Base (16 bytes per FMMU)

---

define SYN_ESC_REG_PDI_CONTROL

#define SYN_ESC_REG_PDI_CONTROL `0x0140U`

Process Data Interface Control

---

define SYN_ESC_REG_SII_EEPROM_CTRL

#define SYN_ESC_REG_SII_EEPROM_CTRL `0x0502U`

SII EEPROM Control/Status

---

define SYN_ESC_REG_SM0

#define SYN_ESC_REG_SM0 `0x0800U`

SyncManager 0 Base (8 bytes per SM)

---

define SYN_ESC_REG_STATION_ADDR

#define SYN_ESC_REG_STATION_ADDR `0x0010U`

Configured Station Address

---

define SYN_ESC_REG_STATION_ALIAS

#define SYN_ESC_REG_STATION_ALIAS `0x0012U`

Configured Station Alias

---

define SYN_ESC_REG_TYPE

#define SYN_ESC_REG_TYPE `0x0000U`

ESC Type/Build

---

define SYN_ETHERCAT_ETHERTYPE

EtherCAT IEEE 802.3 Ethernet Frame Type.

#define SYN_ETHERCAT_ETHERTYPE `0x88A4`

---

define SYN_ETHERCAT_TYPE_DATAGRAM

EtherCAT Header Type (1 = EtherCAT Datagrams)

#define SYN_ETHERCAT_TYPE_DATAGRAM `1`

---

---

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