CANopenNode DS301 设备档案深度解读:从对象字典文档到可编译固件

原创2026-10-04 19:03:172,000 阅读
文章标签:嵌入式通信工业制造

CANopenNode DS301 设备档案深度解读:从对象字典文档到可编译固件

本文以 CANopenNode 仓库中由 CANopenEditor 自动生成的 DS301 设备档案 DS301_profile.md 为主体,逐项解析这份"New Product"设备定义所包含的设备信息、波特率支持与完整 CiA 301 对象字典(索引 0x1000–0x1A03),并结合同源生成的 OD.h、OD.c 及 301/ 目录下的模块源码,说明每个对象在协议栈中的真实作用、位定义与持久化机制。读完本文,你将能够读懂任意一份 DS301 对象字典文档,理解 PERSIST_COMM / RAM 存储分组的含义,并掌握从 .xpd 工程文件到可编译固件的完整落地路径。

一、文档定位:一份"设备档案"从何而来

example/DS301_profile.md 的文档头给出了它的身份信息:项目文件为 DS301_profile.xpd,文件版本 1,创建于 2020-11-23,最后修改于 2023-03-17,且由 CANopenEditor v4.1-1-ga49a51a 自动生成。这意味着同一工程会同时产出一组相互对应的文件,它们描述同一个设备:

文件 作用
DS301_profile.xpd CANopenEditor 的工程源文件,所有编辑都在此进行
DS301_profile.md 人类可读的设备档案(即本文主体)
DS301_profile.eds 标准 EDS(Electronic Data Sheet),供主站/配置工具导入
OD.c / OD.h 协议栈 C 代码使用的对象字典定义与数据结构

因此,本文所解析的每一行表格,都能在 DS301_profile.eds 的 [1000]、[1001] 等段,以及 OD.c、OD.h 的 C 结构体中找到一一对应的事实依据——这份文档不是孤立的说明文字,而是整个设备固件的"对象字典蓝图"。

二、设备信息:基础身份与通信能力

文档开头的 Device Information 定义了设备的宏观属性:

项目 值
Vendor Name / Vendor ID (空,待厂商填写)
Product Name New Product
Product ID (空)
Granularity 8
RPDO count 4
TPDO count 4
LSS Slave True
LSS Master False

其中:

  • Granularity = 8:表示 OD 对象的数据粒度按 8 bit 对齐(即字节粒度),这也是 DS301_profile.eds 中 Granularity=8 的来源;
  • 4×RPDO / 4×TPDO:对应 OD.h 中的 OD_CNT_RPDO 4 与 OD_CNT_TPDO 4,也决定了对象字典中 0x1400–0x1403、0x1600–0x1603、0x1800–0x1803、0x1A00–0x1A03 各出现 4 组;
  • LSS Slave = True:设备可作为 LSS 从站,允许通过 305/CO_LSSslave.c 协议动态配置节点 ID 与波特率,这一点在 main_blank.c 的 CO_LSSinit() 调用中得到了印证。

支持的波特率

波特率 支持
10 kBit/s ✓
20 kBit/s ✓
50 kBit/s ✓
125 kBit/s ✓
250 kBit/s ✓
500 kBit/s ✓
800 kBit/s ✓
1000 kBit/s ✓
auto(自动检测) ✗

这 8 种波特率的勾选状态与 DS301_profile.eds 中的 BaudRate_10=1 ... BaudRate_1000=1 一一对应;auto 未勾选,说明该设备不支持自动波特率检测,上电时必须由配置工具或 LSS 服务显式指定波特率。

三、对象字典的组织方式:Storage Group 与对象类型

在深入具体条目之前,先理解 OD.h 暴露出的两个关键分组,这也是本档案中每个对象都带有的 Storage Group 标签的含义:

  • PERSIST_COMM(持久化通信参数):编译后落入 OD_PERSIST_COMM_t 结构体(OD.h),可被存储模块整体写入非易失存储器;
  • RAM(运行期易失数据):落入 OD_RAM_t 结构体(OD.h),掉电即失,无需持久化。

每个条目的 Object Type 分三种:

  • VAR:单值对象;
  • ARRAY:同类型子索引数组(如 0x1003 错误记录、0x1016 心跳消费表);
  • RECORD:异构子索引组合(如 0x1018 Identity、0x1400 RPDO 通信参数)。

表格中的 SDO / PDO / SRDO 列表示该对象对三种访问途径的开放程度:ro 只读、rw 可读写、t 表示可被 PDO 传输、tr 表示可被 PDO 传输并响应 RTR,no 表示不参与该项访问。

四、CiA 301 通信对象详解(0x1000–0x1019)

0x1000 – Device type(设备类型)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / SDO: ro,PDO: no,SRDO: no
Default Value 0x00000000
  • bit 16–31:附加信息(Additional information);
  • bit 0–15:设备子协议号(Device profile number),本例为 0,表示纯通用 CiA 301 设备、未绑定特定子协议。

0x1001 – Error register(错误寄存器)

属性 值
Object Type / Storage Group VAR / RAM
Data Type / 访问 UNSIGNED8 / SDO: ro,PDO: t,SRDO: no
Default Value 0x00

错误寄存器是紧急报文的"状态字",各 bit 语义:bit 7 厂商特定、bit 6 保留(恒 0)、bit 5 设备子协议特定、bit 4 通信错误(溢出/错误状态)、bit 3 温度、bit 2 电压、bit 1 电流、bit 0 通用错误。它由 301/CO_Emergency.c 的 CO_errorReport() 维护,并可通过 PDO 映射(t)实时上报。

0x1003 – Pre-defined error field(预定义错误记录)

属性 值
Object Type / Storage Group ARRAY / RAM
子索引数量 0x00–0x10,共 17 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Number of errors UNSIGNED8 rw no no —
0x01–0x10 Standard error field UNSIGNED32 ro no no —
  • Sub 0 存放当前实际错误数,写入 0 可清空错误历史;
  • Sub 1 及以上每个错误项:bit 16–31 为厂商附加信息,bit 0–15 为 Emergency 对象中传输的错误码(EMC)。

0x1005 – COB-ID SYNC message(SYNC 报文 COB-ID)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / rw / no / no
Default Value 0x00000080
  • bit 31:恒为 0;
  • bit 30:置 1 时本设备生产 SYNC 对象(SYNC 生产者);
  • bit 11–29:恒为 0;
  • bit 0–10:11 位 CAN-ID(默认 0x080,即 SYNC 的标准 COB-ID)。

对应 301/CO_SYNC.c 模块,其默认 COB-ID 0x80 是全总线共享的。

0x1006 – Communication cycle period(通信周期)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / rw / no / no
Default Value 0

SYNC 发送周期,单位 µs(0 = 禁用发送)。这是 SYNC 生产者规划同步周期的依据。

0x1007 – Synchronous window length(同步窗口长度)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / rw / no / no
Default Value 0

同步窗口长度,单位 µs(0 = 不使用)。所有同步型 PDO 必须在该时间窗口内完成传输,超出窗口的同步 PDO 应被丢弃。

0x1010 – Store parameters(参数存储)

属性 值
Object Type / Storage Group ARRAY / RAM
子索引数量 0x00–0x04,共 5 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 0x04
0x01 Save all parameters UNSIGNED32 rw no no 0x00000001
0x02 Save communication parameters UNSIGNED32 rw no no 0x00000001
0x03 Save application parameters UNSIGNED32 rw no no 0x00000001
0x04 Save manufacturer defined parameters UNSIGNED32 rw no no 0x00000001

Sub 1 及以上各子索引的读取结果反映存储能力:bit 1 = 设备可自主保存参数,bit 0 = 设备可按命令保存参数。向对应子索引**写入 0x65766173('s','a','v','e' 从 LSB 到 MSB)**即可触发存储。这正是 storage/CO_storage.h 中描述的标准 CiA 301 存储机制,具体实现在 storage/CO_storage.c 中挂接到 OD 扩展上执行。

0x1011 – Restore default parameters(恢复默认参数)

属性 值
Object Type / Storage Group ARRAY / RAM
子索引数量 0x00–0x04,共 5 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 0x04
0x01 Restore all default parameters UNSIGNED32 rw no no 0x00000001
0x02 Restore communication default parameters UNSIGNED32 rw no no 0x00000001
0x03 Restore application default parameters UNSIGNED32 rw no no 0x00000001
0x04 Restore manufacturer defined default parameters UNSIGNED32 rw no no 0x00000001

Sub 1 及以上:bit 0 = 设备可恢复默认参数。向对应子索引**写入 0x64616F6C('l','o','a','d' 从 LSB 到 MSB)**即可恢复相应类别参数的出厂默认值。

0x1012 – COB-ID time stamp object(时间戳对象 COB-ID)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / rw / no / no
Default Value 0x00000100
  • bit 31:置 1 时本设备消费 TIME 报文;
  • bit 30:置 1 时本设备生产 TIME 报文;
  • bit 11–29:恒 0;
  • bit 0–10:11 位 CAN-ID(默认 0x100)。

对应 301/CO_TIME.c 模块,默认 COB-ID 0x100 是 TIME 对象的标准地址。

0x1014 – COB-ID EMCY(紧急报文 COB-ID)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED32 / rw / no / no
Default Value $NODEID+0x80
  • bit 31:置 1 表示 EMCY 不存在/无效;
  • bit 11–30:恒 0;
  • bit 0–10:11 位 CAN-ID。

$NODEID 是 CANopenEditor 中的节点 ID 占位符,最终值在固件初始化时写入。默认 EMCY 地址 = 节点 ID + 0x80,由 301/CO_Emergency.c 的紧急对象生产者使用。

0x1015 – Inhibit time EMCY(EMCY 禁止时间)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED16 / rw / no / no
Default Value 0

EMCY 报文的禁止发送间隔,单位为 100 µs 的倍数;0 表示不启用禁止时间,用于限制紧急报文的发送频率。

0x1016 – Consumer heartbeat time(心跳消费表)

属性 值
Object Type / Storage Group ARRAY / PERSIST_COMM
子索引数量 0x00–0x08,共 9 项(最高子索引 0x08)
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 0x08
0x01–0x08 Consumer heartbeat time UNSIGNED32 rw no no 0x00000000

每个子索引的 32 位值含义:

  • bit 24–31:恒 0;
  • bit 16–23:被监视节点的 Node ID(0 或大于 127 时该子项未使用);
  • bit 0–15:心跳时间,单位 ms(0 表示该子项未使用),应大于对应生产者心跳时间。

该表由 301/CO_HBconsumer.c 消费,超时未收到心跳即上报通信错误;表容量 8 与 OD.h 的 OD_CNT_ARR_1016 8 一致。

0x1017 – Producer heartbeat time(心跳生产时间)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED16 / rw / no / no
Default Value 0

心跳生产周期,单位 ms(0 = 禁止发送)。由 301/CO_NMT_Heartbeat.c 驱动,main_blank.c 中 FIRST_HB_TIME 500 则是首次心跳的 500 ms 预热参数。

0x1018 – Identity(身份对象)

属性 值
Object Type / Storage Group RECORD / PERSIST_COMM
子索引数量 0x00–0x04,共 5 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 0x04
0x01 Vendor-ID UNSIGNED32 ro no no 0x00000000
0x02 Product code UNSIGNED32 ro no no 0x00000000
0x03 Revision number UNSIGNED32 ro no no 0x00000000
0x04 Serial number UNSIGNED32 ro no no 0x00000000
  • Vendor-ID 由 CiA 统一分配;Product code 与 Serial number 厂商自定义;
  • Revision number:bit 16–31 为主版本(CANopen 行为已改变),bit 0–15 为次版本(CANopen 行为未改变)。

Identity 是 LSS 服务的寻址依据——main_blank.c 正是从 OD_PERSIST_COMM.x1018_identity 读出这四个字段构造 LSS 地址。

0x1019 – Synchronous counter overflow value(SYNC 计数器溢出值)

属性 值
Object Type / Storage Group VAR / PERSIST_COMM
Data Type / 访问 UNSIGNED8 / rw / no / no
Default Value 0
  • 0:SYNC 报文以 0 数据长度发送;
  • 1:保留;
  • 2–240:SYNC 报文携带 1 字节计数器,计数器在该值处回绕;
  • 241–255:保留。

五、SDO 参数(0x1200 / 0x1280)

0x1200 – SDO server parameter(SDO 服务器参数)

属性 值
Object Type / Storage Group RECORD / RAM
子索引数量 0x00–0x02,共 3 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 2
0x01 COB-ID client to server (rx) UNSIGNED32 ro t no $NODEID+0x600
0x02 COB-ID server to client (tx) UNSIGNED32 ro t no $NODEID+0x580

Sub 1/2 的 bit 11–31 恒 0,bit 0–10 为 11 位 CAN-ID。SDO 服务器收发 COB-ID 默认分别为节点 ID + 0x600 / 0x580,且本例中两个子索引均为只读(ro),同时标记 t 允许作为 PDO 数据被映射。默认地址的计算逻辑体现在 301/CO_SDOserver.c 的初始化过程中。

0x1280 – SDO client parameter(SDO 客户端参数)

属性 值
Object Type / Storage Group RECORD / PERSIST_COMM
子索引数量 0x00–0x03,共 4 项
Sub 名称 数据类型 SDO PDO SRDO 默认值
0x00 Highest sub-index supported UNSIGNED8 ro no no 0x03
0x01 COB-ID client to server (tx) UNSIGNED32 rw tr no 0x80000000
0x02 COB-ID server to client (rx) UNSIGNED32 rw tr no 0x80000000
0x03 Node-ID of the SDO server UNSIGNED8 rw no no 0x01
  • Sub 1/2:bit 31 置 1 表示该 SDO 不存在/无效;bit 30 置 1 表示值被动态分配;bit 11–29 恒 0;bit 0–10 为 11 位 CAN-ID。默认 0x80000000 即"SDO 客户端未启用";
  • Sub 3:目标 SDO 服务器的节点 ID,取值 0x01–0x7F。

六、PDO 通信与映射参数(0x1400–0x1A03)

0x1400–0x1403:RPDO 通信参数(4 组)

每组均为 RECORD / PERSIST_COMM,结构完全相同,仅 COB-ID 默认值不同:

子索引 名称 数据类型 访问 0x1400 0x1401 0x1402 0x1403
0x00 Highest sub-index supported UNSIGNED8 ro 0x05 0x05 0x05 0x05
0x01 COB-ID used by RPDO UNSIGNED32 rw $NODEID+0x80000200 $NODEID+0x80000300 $NODEID+0x80000400 $NODEID+0x80000500
0x02 Transmission type UNSIGNED8 rw 254 254 254 254
0x05 Event timer UNSIGNED16 rw 0 0 0 0
  • COB-ID:bit 31 置 1 表示该 PDO 不存在/无效;bit 11–30 恒 0;bit 0–10 为 11 位 CAN-ID。默认值中的 0x8000xxxx 表明 bit 31 已置位(PDO 默认无效,需要主站通过 SDO 写入真实 COB-ID 激活);
  • Transmission type(RPDO):
    • 0–240:同步,在接收到下一个 SYNC 对象后处理;
    • 241–253:未使用;
    • 254:事件驱动(厂商特定);
    • 255:事件驱动(设备子协议/应用子协议特定);
  • Event timer:单位 ms,用于接收截止时间监视(deadline monitoring),0 = 禁用。

0x1600–0x1603:RPDO 映射参数(4 组)

每组均为 RECORD / PERSIST_COMM,可映射最多 8 个应用对象:

Sub 名称 数据类型 访问 默认值
0x00 Number of mapped application objects in PDO UNSIGNED8 rw 0
0x01–0x08 Application object 1–8 UNSIGNED32 rw 0x00000000
  • Sub 0:映射对象数量。0 = 映射禁用;1 = 仅 sub 0x01 有效;2–8 = sub 0x01 至 0x02–0x08 有效;
  • Sub 1–8 每个映射项:bit 16–31 = 对象索引(index),bit 8–15 = 子索引(sub-index),bit 0–7 = 数据长度(bit 数)。

0x1800–0x1803:TPDO 通信参数(4 组)

每组均为 RECORD / PERSIST_COMM,TPDO 比 RPDO 多了 Inhibit time 和 SYNC start value 两个子索引:

子索引 名称 数据类型 访问 0x1800 0x1801 0x1802 0x1803
0x00 Highest sub-index supported UNSIGNED8 ro 0x06 0x06 0x06 0x06
0x01 COB-ID used by TPDO UNSIGNED32 rw $NODEID+0xC0000180 $NODEID+0xC0000280 $NODEID+0xC0000380 $NODEID+0xC0000480
0x02 Transmission type UNSIGNED8 rw 254 254 254 254
0x03 Inhibit time UNSIGNED16 rw 0 0 0 0
0x05 Event timer UNSIGNED16 rw 0 0 0 0
0x06 SYNC start value UNSIGNED8 rw 0 0 0 0
  • COB-ID:bit 31 = PDO 不存在/无效;bit 30 = 禁止对该 PDO 使用 RTR;bit 11–29 恒 0;bit 0–10 为 11 位 CAN-ID。默认 0xC000xxxx 中 bit 31 与 bit 30 同时置位,即"默认无效且不允许远程请求";
  • Transmission type(TPDO):
    • 0:同步(非周期);
    • 1–240:同步(周期,每第 1–240 个 SYNC 发送一次);
    • 241–253:未使用;
    • 254:事件驱动(厂商特定);
    • 255:事件驱动(设备/应用子协议特定);
  • Inhibit time:当传输类型为 254/255 时生效,单位 100 µs 的倍数(0 = 禁用),限制 TPDO 最小发送间隔;
  • Event timer:当传输类型为 254/255 时生效,单位 ms(0 = 禁用),周期触发发送;
  • SYNC start value:0 = 不处理 SYNC 计数器;1–240 = 计数器等于该值的 SYNC 视为第一个 SYNC。

传输类型的分段校验在 301/CO_PDO.c 中可见:协议栈拒绝写入 241–253 之间的非法值,并根据"传输类型 ≤ 240"判定同步属性;301/CO_PDO.c 则展示了 TPDO 初始化时读取传输类型并将非法值回退为 254(事件驱动)的处理逻辑。

0x1A00–0x1A03:TPDO 映射参数(4 组)

每组结构与 0x1600 系列完全相同(RECORD / PERSIST_COMM,Sub 0 为映射数量,Sub 1–8 为应用对象映射项,每项按 index / sub-index / bit 长度编码),默认全部为 0(映射禁用)。

至此,4 组 RPDO + 4 组 TPDO 的通信参数(0x1400/0x1800 系列)与映射参数(0x1600/0x1A00 系列)共同构成完整的 PDO 通道配置,实际收发由 301/CO_PDO.c 的 CO_process_RPDO() / CO_process_TPDO() 在 main_blank.c 的定时任务中驱动。

七、从档案到固件:生成文件与工程集成

数据初始化与常量表

OD.c 完整实现了本文档中每个默认值:OD_PERSIST_COMM 结构体逐字段写入 0x1000/0x1005/0x1006/0x1012/0x1014/0x1016/0x1017/0x1018/0x1280/0x1400–0x1403/0x1600–0x1603/0x1800–0x1803/0x1A00–0x1A03 的初值,OD_RAM 写入 0x1001/0x1010/0x1011/0x1200 的初值;随后 OD.c 会为每个对象生成 OD_obj_var_t / OD_obj_array_t 常量表(含访问属性、数据类型等元数据),并通过 OD.h 的 OD_ENTRY_Hxxxx 宏暴露给协议栈各模块使用。

编译工程

example/Makefile 展示了最小编译集:由 CO_driver_blank.c(空驱动)、CO_storageBlank.c(空存储)、OD.c(本档案生成物)、main_blank.c 以及 301/ 目录下的 CO_ODinterface、CO_NMT_Heartbeat、CO_HBconsumer、CO_Emergency、CO_SDOserver、CO_TIME、CO_SYNC、CO_PDO、303/ 的 CO_LEDs、305/ 的 CO_LSSslave、storage/ 的 CO_storage 与根目录 CANopen.c 组成。在 example 目录执行 make 即可生成 canopennode_blank 可执行文件。

参数持久化与存储分组

档案中标注 PERSIST_COMM 的对象之所以能持久化,是因为 main_blank.c 将 OD_PERSIST_COMM 整体注册为一条存储记录(subIndexOD = 2 对应 0x1010 的"保存通信参数"子索引),并与 0x1010/0x1011 两个 OD 条目关联初始化存储模块;0x1010/0x1011 的 save/load 签名机制则定义在 storage/CO_storage.h。这样,主站通过 SDO 向 0x1010 写入 0x65766173 即可把整个 PERSIST_COMM 分组落盘,向 0x1011 写入 0x64616F6C 即可恢复默认。

初始化流程

main_blank.c 展示了本档案对象的消费顺序:CO_CANopenInit() 使用 activeNodeId(默认 10,可由 LSS 从站改写)初始化 NMT/EM/SDO/SYNC/HB 等通信对象,CO_CANopenInitPDO() 再依据 0x1400–0x1A03 的通信与映射参数初始化全部 PDO 通道,CO_LSSinit() 则利用 0x1018 Identity 与待定节点 ID/波特率启动 LSS 从站服务。若对象字典参数非法,初始化会返回 CO_ERROR_OD_PARAMETERS 并通过 errInfo 指出具体的对象索引。

八、实践要点小结

  1. 读档案即读固件:DS301_profile.md 与 DS301_profile.eds、OD.c 同源生成,所有默认值与位定义三处一致,可直接对照核查;
  2. **NODEID是占位符∗∗:所有COB−ID默认值中的‘NODEID 是占位符**:所有 COB-ID 默认值中的 `NODEID在固件运行期由节点 ID(如 <a href="https://link.gitcode.com/i/4715c7f26b26373460099399aedcbc02" target="_blank">main_blank.c</a> 中的pendingNodeId`)代入,因此同一份档案适用于 1–127 任意节点;
  3. PDO 默认不激活:0x1400/0x1800 的 COB-ID 默认 bit 31 置位(0x8xxxxxxx / 0xCxxxxxxx),主站必须通过 SDO 写入合法 COB-ID 并配置 0x1600/0x1A00 映射后才能建立 PDO 通信;
  4. 传输类型分段是关键:同步(0–240)、非法(241–253)、事件驱动(254–255)三段语义不同,协议栈会在 301/CO_PDO.c 中强制校验,配置时避免写入 241–253 区间;
  5. 持久化只覆盖 PERSIST_COMM:0x1010 'save' 只能保存 PERSIST_COMM 分组(通信参数),运行期的 RAM 分组(错误寄存器、SDO 服务器地址等)不参与持久化,符合 CiA 301 的设计意图。
登录后查看全文
CANopenNode