EtherCAT 主站组件是睿擎平台内部集成的高性能 EtherCAT 协议栈，具备简单易用、高性能、高实时性等特点，用户开箱即用，不需要做复杂的配置。

版本变化说明

从站地址变化

在 v1.7.2 及以上版本中，从站地址编号规则发生了变化：

• 旧版本：从站地址从 1 开始编号（1 到 ecat_slavecount()）
• 新版本：从站地址从 0 开始编号（0 到 ecat_slavecount() - 1）

注意：使用时请根据实际使用的版本选择正确的从站地址编号方式。

EtherCAT 主站初始化

rt_err_t ecat_master_init(ec_master_t *master)

初始化主站实例

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	错误码

此函数用于初始化主站组件。

EtherCAT 主站反初始化

rt_err_t ecat_master_deinit(ec_master_t *master)

将主站实例进行反初始化

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	错误码

此函数用于反初始化主站组件，释放上下文资源，通常情况下用不到。

EtherCAT 主站启动

rt_err_t ecat_master_start(ec_master_t *master)

启动 EtherCAT 主站（v1.7.2 及以上版本推荐使用）

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	错误码

此函数用于启动主站上下文，主站启动后会扫描从站并完成从站配置，配置完成后会进入 OP 状态。

获取从站信息

rt_err_t ecat_slave_info(ec_master_t *master, uint16_t slave, ec_slave_info_t *info)

获取指定从站信息

参数	描述
master	主站结构体指针，不能为空
slave	指定从站索引（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
info	从站信息数据指针
返回	描述
rt_err_t	错误码

此函数用于获取对应从站的详细信息

写从站 SDO 数据

int ecat_sdo_write(ec_master_t *master, uint16_t slave, uint16_t index, uint8_t subindex, uint8_t complete_access, void *data, int size, int timeout)

写入从站 SDO 数据

参数	描述
master	主站结构体指针，不能为空
slave	指定从站索引（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引号
subindex	SDO 子索引号
complete_access	是否完全访问
data	数据 buffer 指针
size	数据长度
timeout	超时时间(us)
返回	描述
int	wkc 计数值，大于 0 为成功

此函数用于写对应从站 SDO 数据

读取从站 SDO 数据

int ecat_sdo_read(ec_master_t *master, uint16_t slave, uint16_t index, uint8_t subindex, uint8_t complete_access, void *data, int size, int timeout)

读取从站 SDO 数据

参数	描述
master	主站结构体指针，不能为空
slave	指定从站索引（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引号
subindex	SDO 子索引号
complete_access	是否完全访问
data	数据 buffer 指针
size	数据长度
timeout	超时时间(us)
返回	描述
int	wkc 计数值，大于 0 为成功

此函数用于读取对应从站 SDO 数据

获取从站个数

int ecat_slavecount(ec_master_t *master)

获取当前总线从站个数

参数	描述
master	主站结构体指针，不能为空
返回	描述
int	返回从站个数

此函数用于获取当前总线上从站个数

通过 SDO 写入单个字节到从站

int ecat_sdo_write_u8(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint8_t data,
    int timeout)

通过 SDO（服务数据对象）向指定从站写入一个字节（8 位）数据。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	要写入的字节数据（8 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

通过 SDO 写入 16 位数据到从站

int ecat_sdo_write_u16(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint16_t data,
    int timeout)

通过 SDO（服务数据对象）向指定从站写入 16 位（2 字节）数据。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	要写入的字节数据（16 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

通过 SDO 写入 32 位数据到从站

int ecat_sdo_write_u32(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint32_t data,
    int timeout)

通过 SDO（服务数据对象）向指定从站写入 32 位（4 字节）数据。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	要写入的字节数据（32 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

通过 SDO 从从站读取 8 位数据

int ecat_sdo_read_u8(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint8_t *data,
    int timeout)

通过 SDO（服务数据对象）从指定从站读取一个字节（8 位）数据到提供的缓冲区。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	读取到的数据存储地址（8 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

通过 SDO 从从站读取 16 位数据

int ecat_sdo_read_u16(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint16_t *data,
    int timeout)

通过 SDO（服务数据对象）从指定从站读取两个字节（16 位）数据到提供的缓冲区。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	读取到的数据存储地址（16 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

通过 SDO 从从站读取 32 位数据

int ecat_sdo_read_u32(ec_master_t *master,
    uint16_t slave,
    uint16_t index,
    uint8_t subindex,
    uint32_t *data,
    int timeout)

通过 SDO（服务数据对象）从指定从站读取 4 个字节（32 位）数据到提供的缓冲区。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1，0 代表全部从机）
index	SDO 索引（通常为 16 进制）
subindex	SDO 子索引（通常为 16 进制）
data	读取到的数据存储地址（32 位）
timeout	操作超时时间（us），0 表示默认超时
返回	描述
int	状态：>=0 - 成功<0 - 失败

检查从站当前状态

rt_err_t ecat_check_state(
    ec_master_t *master, uint16_t slave, uint16_t *state, int timeout)

设置指定从站的目标状态，并触发状态机切换请求。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()；v1.7.2 及以上版本：0 到 ecat_slavecount() - 1，0 代表全部从机）
state	当前状态值指
timeout	等待超时时间（us）
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

初始化 EtherCAT 主站服务

int ecat_service_init(void)

初始化 EtherCAT 主站服务的核心组件

参数	描述
返回	描述
int	操作状态：0 - 成功-1 - 失败

从站配置

rt_err_t ecat_slave_config(
    ec_master_t *master, uint16_t slave, ec_slave_config_t *config)

配置 EtherCAT 从站的同步管理器、PDO 映射和 DC 同步参数（v1.7.2 及以上版本新增）

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.2 及以上版本：0 到 ecat_slavecount() - 1）
config	从站配置结构体指针
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

此函数用于配置从站的同步管理器、PDO 映射和 DC 同步参数。

从站配置结构体

typedef struct {
    ec_sync_info_t *sync;                           /**< Sync manager configuration. */
    uint8_t sync_count;                             /**< Number of sync managers. */
    ec_pdo_callback_t pdo_callback;                 /**< PDO process data callback. */
    uint16_t dc_assign_activate;                    /**< dc assign control */
    ec_sync_signal_t dc_sync[EC_SYNC_SIGNAL_COUNT]; /**< DC sync signals. */
} ec_slave_config_t;

PDO 回调函数类型

typedef void (*ec_pdo_callback_t)(uint16_t slave_index, uint8_t *output, uint8_t *input);

此回调函数在处理 PDO 过程数据时被调用，用于自定义数据处理逻辑。

注意：回调函数中的 slave_index 参数在 v1.7.2 及以上版本中是从 0 开始编号的。

DC 同步信号结构体

typedef struct {
    uint32_t cycle_time; /**< Cycle time [ns]. */
    int32_t shift_time;  /**< Shift time [ns]. */
} ec_sync_signal_t;

此结构体用于配置 DC 同步信号的周期时间和偏移时间。

以下为旧版本废弃 API

EtherCAT 主站启动（废弃）

rt_err_t ecat_simple_start(ec_master_t *master)

启动 EtherCAT 主站

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	错误码

此函数用于启动主站上下文，主站启动后会扫描从站并完成从站配置

废弃提示：v1.7.2 及以上版本废弃，建议使用 ecat_master_start 替代。

停止 EtherCAT 主站（废弃）

rt_err_t ecat_simple_stop(ec_master_t *master)

停止 EtherCAT 主站

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	错误码

此函数用于停止主站，如果主站当前已经运行在 OP 模式将退出过程数据同步循环，重新回到 INIT 状态

废弃提示：v1.7.2 及以上版本废弃。

DC 同步时钟配置（废弃）

void ecat_dc_config(ec_master_t *master, uint16_t slave, uint8_t act, uint32_t cycle_time, int32_t cycle_shift)

DC 同步时钟配置

参数	描述
master	主站结构体指针，不能为空
slave	提供 DC 时钟的从站编号，0 为主站
act	是否激活 DC 时钟同步
cycle_time	DC 同步周期时间，单位为 ns
cycle_shift	DC 同步平移时间，单位为 ns
返回	描述
void

此函数用于配置 DC 同步参数

废弃提示：v1.7.2 及以上版本废弃。使用 ecat_slave_config 替代。

扩展 DC 同步时钟配置（废弃）

void ecat_dc_config_ex(ec_master_t *master, uint16_t slave, uint8_t act, uint32_t cycle_time0, uint32_t cycle_time1, int32_t cycle_shift)

扩展 DC 同步时钟配置，在需要使用 DC1 同步时使用

参数	描述
master	主站结构体指针，不能为空
slave	提供 DC 时钟的从站编号，0 为主站
act	是否激活 DC 时钟同步
cycle_time0	DC0 同步周期时间，单位为 ns
cycle_time1	DC1 同步周期时间，单位为 ns
cycle_shift	DC 同步平移时间，单位为 ns
返回	描述
void

此函数用于配置 DC 同步参数

废弃提示：v1.7.2 及以上版本废弃。使用 ecat_slave_config 替代。

设置从站目标状态（废弃）

rt_err_t ecat_write_state(ec_master_t *master, 
                          uint16_t slave, 
                          uint16_t state)

设置指定从站的目标状态，并触发状态机切换请求。

参数	描述
master	主站结构体指针，不能为空
slave	目标从站地址（v1.7.1 及以下版本：1 到 ecat_slavecount()）
state	目标状态值
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

初始化 EtherCAT 主站配置（废弃）

rt_err_t ecat_config_init(ec_master_t *master, uint8_t usetable)

执行 EtherCAT 主站的配置初始化过程

参数	描述
master	主站结构体指针，不能为空
usetable	配置模式选择:0 - 自动配置模式（扫描实际拓扑）1 - 使用预定义配置表
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

配置过程数据映射（废弃）

rt_err_t ecat_config_map_group(ec_master_t *master, void *map, uint8_t group)

配置 EtherCAT 过程数据对象（PDO）的映射关系

参数	描述
master	主站结构体指针，不能为空
map	过程数据缓冲区指针
group	逻辑地址空间组号（通常为 0 表示默认组）
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

发送输出过程数据（废弃）

rt_err_t ecat_send_processdata_group(ec_master_t *master, uint8_t group);

向 EtherCAT 总线发送指定组的输出过程数据（Output PDO）

参数	描述
master	主站结构体指针，不能为空
group	逻辑地址空间组号（通常为 0 表示默认组）
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

接收输入过程数据（废弃）

rt_err_t ecat_receive_processdata_group(
    ec_master_t *master, 
    uint8_t group, 
    int timeout)

接收并处理指定组的输入过程数据（Input PDO）

参数	描述
master	主站结构体指针，不能为空
group	逻辑地址空间组号（通常为 0 表示默认组）
timeout	接收超时时间(us)
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

启动定时器（废弃）

rt_err_t ecat_timer_start(struct ecat_timer *t, uint32_t timeout_us)

启动一个针对 EtherCAT 实时控制的定时器

参数	描述
t	预初始化的定时器结构体指针
timeout_us	定时器超时时间（微秒）
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_EINVAL - 失败

废弃提示：v1.7.2 及以上版本废弃。

检查定时器是否超时（废弃）

rt_bool_t ecat_timer_is_expired(struct ecat_timer *t)

参数	描述
t	已启动的定时器结构体指针
返回	描述
rt_bool_t	RT_TRUE - 定时器已超时RT_FALSE - 定时器运行中或未启动

废弃提示：v1.7.2 及以上版本废弃。

初始化同步时钟（废弃）

rt_err_t ecat_hwtimer_start(ec_master_t *master)

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。

DC 时钟同步（废弃）

rt_err_t ecat_sync_dc(ec_master_t *master)

参数	描述
master	主站结构体指针，不能为空
返回	描述
rt_err_t	操作状态：RT_EOK - 成功-RT_ERROR - 失败

废弃提示：v1.7.2 及以上版本废弃。