外观
EtherCAT API
2025-09-17
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 及以上版本废弃。
