Lely dcf-tools 与 master.yml 配置教程：从 EDS 生成可用的主站 DCF

在这里插入图片描述

@[toc]

适用版本：原生 Lely CANopen 2.4.0 dcfgen。本文使用上游 master/options/<slave> 结构，不适用于 ROS 2 或其他 downstream 项目自定义的 defaults/nodes YAML 格式。

本文解决什么问题

Lely 主站通常不是直接读取从机 EDS 后运行，而是先在开发机上通过 dcfgen 合并主站策略、从机 EDS 和 PDO/SDO 配置，生成 master.dcf 以及按需生成的 concise DCF 二进制文件。

本文给出一条可复现的配置路径：

  1. 在 Ubuntu 开发机安装与目标 Lely 源码匹配的 dcf-tools；
  2. 准备从机 EDS 和 master.yml；
  3. 逐项理解 options、master 和从机 section；
  4. 生成并检查 master.dcf；
  5. 使用一份完整的 demo.yml 作为字段字典，其中非必需字段全部保留为注释。

本文示例环境：

1
2
3
4
5
6
7
开发机：Ubuntu 20.04
Lely 源码：/home/embedsky/share/lely-imx8p/lely-core
Lely C/C++ 版本：2.4.0
目标架构：AArch64 / i.MX8P
目标板 CAN：can1，1000 kbit/s
从机：Node-ID 1，CANopenNode demo OD
主站：Node-ID 127

1. 先理解生成链路

1
2
3
4
5
6
7
8
9
flowchart LR
    A[从机 EDS/DCF] --> C[dcfgen]
    B[master.yml] --> C
    C --> D[master.dcf]
    C --> E[master.bin 可选]
    C --> F[slave-name.bin 可选]
    D --> G[Lely 主站运行时]
    E --> G
    F --> G

三类文件的职责不同：

文件 生成条件 用途
master.dcf 始终生成 主站运行时设备描述、NMT 策略、PDO 和远端对象配置
master.bin 主站自身存在 concise SDO 数据时 主站对象的简明 DCF 数据
<slave-name>.bin 对从机产生配置期 SDO 下载时 NMT boot/configuration 阶段写入从机

关键结论：master.yml 不只是静态描述。只要 heartbeat、PDO、error behavior 或 sdo 等配置与 EDS 默认值不同，就可能生成从机 .bin，并在自动 boot 时修改设备。

2. 安装与源码版本匹配的 dcf-tools

2.1 固定源码版本

不要在生成环境中无条件 git pull。先记录当前 Lely commit：

1
2
3
4
5
6
7
8
export WORK_ROOT=/home/embedsky/share/lely-imx8p
export LELY_SRC=${WORK_ROOT}/lely-core
export TESTER_ROOT=${WORK_ROOT}/canopen-slave-tester

cd "$LELY_SRC"
git status --short
git rev-parse HEAD
git describe --always --dirty

建议让目标板上的 Lely C/C++ 库与开发机上的 dcf-tools 来自同一 commit，至少应保存完整 SHA 以便复现。

2.2 创建独立 Python 环境

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
sudo apt update
sudo apt install -y \
    python3 \
    python3-venv \
    python3-pip \
    python3-setuptools \
    python3-wheel

mkdir -p "$TESTER_ROOT"
python3 -m venv "$TESTER_ROOT/.venv-dcf-tools"
source "$TESTER_ROOT/.venv-dcf-tools/bin/activate"

python -m pip install --upgrade pip wheel setuptools
python -m pip install \
    'PyYAML==6.0.3' \
    'empy==4.2.1' \
    'setuptools==75.3.2' \
    wheel
python -m pip install --no-deps "$LELY_SRC/python/dcf-tools"

这里安装的是开发机工具，不是 AArch64 运行库。目标板可以继续使用 --disable-python --disable-cython 构建；目标板不需要 Python、pip 或 dcf-tools。

2.3 验证命令来源

1
2
3
4
5
6
7
8
command -v dcfchk
command -v dcfgen
command -v dcf2dev
python -m pip show dcf-tools

dcfchk --help
dcfgen --help
dcf2dev --help

三个命令都应来自项目 venv。dcfgen --help 至少应包含 -d、-r、-S 和 -v。

3. 准备目录和输入文件

推荐目录：

1
2
3
4
5
6
7
8
9
10
${TESTER_ROOT}/config/
├── project.eds
├── master.yml
├── demo.yml
└── generated/
    ├── project.dcfgen.eds
    ├── master.dcf
    ├── master.bin
    ├── mcu_node_1.bin
    └── SHA256SUMS

.bin 是否生成由配置内容决定，不应在脚本中假定它始终存在。

3.1 原始 EDS 与兼容副本

原始 EDS 应保留为证据文件，不直接修改。若 dcfchk 或 dcfgen 对某些厂商字段、identity 一致性或旧格式存在兼容问题，应生成一份专用副本，例如：

1
2
project.eds                       # 原始文件，只读保存
generated/project.dcfgen.eds      # 供 dcf-tools 使用的规范化副本

当前工程曾遇到两类问题：

  • DeviceInfo.NG_Slave 不被当前工具识别；
  • DeviceInfo.RevisionNumber 与 0x1018:03 不一致。

处理原则是只规范化副本，并在每次生成前校验原始 EDS 的 SHA256。

4. master.yml 的顶层结构

原生 Lely 2.4.0 识别三类顶层 section：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
options:
  # 可选的全局默认值

master:
  # 必须存在的主站 section

mcu_node_1:
  # 一个从机 section

another_node:
  # 另一个从机 section

.comment_or_template:
  # 以点开头的顶层 section 会被忽略

规则如下：

  1. master section 必须存在；
  2. options 可选；
  3. 其余非点开头的顶层名称都被当作从机；
  4. 从机 section 名决定生成文件名，例如 mcu_node_1.bin；
  5. Node-ID 为 255 的从机会被忽略并产生警告；
  6. 不要使用 ROS 2/downstream 风格的 defaults: 和 nodes:，原生工具会把它们误当成从机。

5. YAML 写法规则

5.1 布尔值不要加引号

1
boot: false

错误写法：

1
boot: "false"

当前源码通过 Python bool() 转换配置值，非空字符串会被当成 true。

5.2 数字和键的写法

1
2
3
4
5
vendor_id: 0x00000000

rpdo:
  1:
    cob_id: 0x201

十六进制整数和 PDO 编号键均不要加引号。cob_id: auto 是工具识别的特殊字符串。

5.3 区分 dcf 与 dcf_path

  • dcf：dcfgen 在生成阶段加载的 EDS/DCF 输入路径；
  • dcf_path：目标运行环境中 concise DCF 文件的路径前缀。

dcf 的相对路径按运行 dcfgen 时的当前目录解析，不会自动按 YAML 所在目录解析。因此应固定在 config/ 目录执行生成命令。

6. 从最小配置开始

一份能够描述一个主站和一个从机的最小工程配置如下：

1
2
3
4
5
6
7
master:
  node_id: 127
  baudrate: 1000

mcu_node_1:
  dcf: "generated/project.dcfgen.eds"
  node_id: 1

这份配置可用于理解字段，但不能直接代表“安全的手工测试策略”。Lely 的部分 NMT 默认值会自动启动或 boot 从机。测试程序需要显式控制 NMT/SDO/PDO 时，应继续配置第 8 节中的手工控制策略。

7. 配置 options：建立全局默认值

options 全部为可选项：

字段 类型 默认值 作用
dcf_path string "" 目标系统上生成 .bin 的运行时路径前缀
heartbeat_multiplier float 3.0 heartbeat producer 周期到 consumer timeout 的倍数
retry_factor int 3 NMT boot retry factor，进入对象 0x1F81 高位字段

示例：

1
2
3
4
options:
  dcf_path: "/opt/Ultra/Debug/canopen-slave-tester/config"
  heartbeat_multiplier: 3.0
  retry_factor: 3

cob_id = 0x680 是工具内部的自动分配游标，不是 YAML 可配置字段。

8. 配置 master：主站身份、通信和 NMT 策略

8.1 主站字段总览

字段 默认值 单位/对象 说明
node_id 255 Node-ID 主站节点号；工程中应显式设置
baudrate 1000 kbit/s CAN bit rate
vendor_id 0 0x1018:01 Vendor-ID
product_code 0 0x1018:02 Product code
revision_number 0 0x1018:03 Revision number
serial_number 0 0x1018:04 Serial number
sync_period 0 0x1006, μs 周期 SYNC；0 禁用
sync_window 0 0x1007, μs SYNC window；0 禁用
sync_overflow 0 0x1019 SYNC counter overflow；0 禁用
time_cob_id 0x100 0x1012 TIME COB-ID
emcy_inhibit_time 0 0x1015, 100 μs EMCY 抑制时间
heartbeat_multiplier 继承 options 倍数 主站监控从机时的 timeout 倍数
heartbeat_consumer true 0x1016 为已配置从机生成 heartbeat consumer
heartbeat_producer 0 0x1017, ms 主站 heartbeat producer 周期
error_behavior {1: 0} 0x1029 主站错误行为
nmt_inhibit_time 0 0x102A, 100 μs NMT 命令最小间隔
start true 0x1F80 bit2 主站是否自动进入 Operational
start_nodes true 0x1F80 bit3 是否自动启动从机
start_all_nodes false 0x1F80 bit1 是否广播启动全部节点
reset_all_nodes false 0x1F80 bit4 mandatory 从机失败时 reset all
stop_all_nodes false 0x1F80 bit6 mandatory 从机失败时 stop all
boot_time 0 0x1F89, ms mandatory 从机 boot timeout

8.2 手工测试场景的 NMT 策略

当测试程序要逐条执行 NMT、SDO 和 PDO 用例时，不应让主站在启动阶段抢先改变节点状态：

1
2
3
4
5
6
7
8
9
master:
  node_id: 127
  baudrate: 1000

  start: false
  start_nodes: false
  start_all_nodes: false
  reset_all_nodes: false
  stop_all_nodes: false

对应的 0x1F80 计算如下：

1
2
3
4
5
6
初值 bit0 = 1
start_all_nodes=true  -> bit1
start=false           -> bit2
start_nodes=false     -> bit3
reset_all_nodes=true  -> bit4
stop_all_nodes=true   -> bit6

上述配置应得到：

1
0x1F80 = 0x0000000D

8.3 自动化生产系统的策略

只有在主站负责整个网络的自动启动、身份校验和配置下发时，才启用：

1
2
3
4
5
master:
  start: true
  start_nodes: true
  heartbeat_consumer: true
  boot_time: 5000

这类配置必须与从机 boot/mandatory/reset_communication、identity、heartbeat 周期和 concise DCF 文件部署保持一致。

9. 配置从机 section

9.1 从机字段总览

字段 默认/来源 作用
dcf 必填 生成阶段加载的 EDS/DCF
node_id 255 或 DCF 环境 解析 $NODEID 并决定节点号
dcf_path 继承 options 该节点 concise DCF 的运行时目录
revision_number EDS 期望 0x1018:03
serial_number EDS 期望 0x1018:04
time_cob_id EDS 0x1012 期望配置的 TIME COB-ID
heartbeat_multiplier 继承 options 该从机 heartbeat timeout 倍数
heartbeat_consumer false 是否让从机监控主站 heartbeat
heartbeat_producer EDS 0x1017 从机 heartbeat producer 周期，ms
retry_factor 继承 options NMT boot retry factor
guard_time EDS 0x100C Node guarding 时间，ms
life_time_factor EDS 0x100D Node guarding lifetime factor
error_behavior EDS 0x1029 从机错误行为
rpdo EDS 覆盖从机 RPDO，并生成主站对应 remote mapping
tpdo EDS 覆盖从机 TPDO，并生成主站对应 remote mapping
boot true 是否由主站自动 boot/configure
mandatory false 是否为 mandatory slave
reset_communication true boot 时是否允许 NMT Reset Communication
software_file "" 0x1F58 firmware file
software_version 0 0x1F55 expected version
configuration_file 自动路径 0x1F22 concise DCF 文件
restore_configuration 0 0x1011 restore sub-index
sdo 空列表 追加配置期 SDO 下载

9.2 手工测试场景的从机策略

1
2
3
4
5
6
7
mcu_node_1:
  dcf: "generated/project.dcfgen.eds"
  node_id: 1

  boot: false
  mandatory: false
  reset_communication: false

0x1F81 assignment 的主要位规则：

1
2
3
4
5
6
7
8
9
bit0  = 节点存在
bit2  = boot=true
bit3  = mandatory=true
bit4  = reset_communication=false
bit5  = software_version != 0
bit6  = software_file 非空
bit7  = restore_configuration != 0
bits 8..15  = retry_factor
bits 16..31 = guard_time

9.3 heartbeat 与 node guarding 不要同时启用

当以下三个条件同时成立时，当前源码会报警并清零 guarding：

1
2
3
guard_time != 0
life_time_factor != 0
heartbeat_producer != 0

同一节点应选择 heartbeat 或 node guarding 作为主要错误控制机制，不要同时保持两者活动。

10. 配置 PDO

10.1 RPDO 示例

1
2
3
4
5
6
7
8
9
mcu_node_1:
  rpdo:
    1:
      enabled: true
      cob_id: 0x201
      transmission: 254
      mapping:
        - index: 0x2200
          sub_index: 0

10.2 TPDO 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
mcu_node_1:
  tpdo:
    1:
      enabled: true
      cob_id: 0x181
      transmission: 254
      inhibit_time: 0
      event_timer: 1000
      sync_start: 0
      mapping:
        - index: 0x2100
          sub_index: 0
        - index: 0x2101
          sub_index: 0

字段说明：

字段 说明
enabled 是否启用该 PDO；必须使用未加引号的布尔值
cob_id 显式 COB-ID 或 auto
transmission PDO transmission type
inhibit_time TPDO inhibit time，单位 100 μs
event_timer TPDO event timer，单位 ms
event_deadline 主站 RPDO reception deadline，单位 ms；当前 2.4.0 源码存在已知问题
sync_start TPDO SYNC start value
mapping 映射对象列表，每项包含 index/sub_index

使用限制：

  1. PDO 编号必须已存在于 EDS；
  2. 映射对象必须存在且允许 PDO mapping；
  3. Classic CAN 单个 PDO 总映射不应超过 64 bit；
  4. -r 是 dcfgen 命令行选项，不是 YAML 字段；
  5. 测试 EDS 默认映射时，不要在 YAML 中重复覆盖 PDO，否则会产生配置期 SDO 写入。

11. 配置启动阶段 SDO 下载

1
2
3
4
5
6
7
8
mcu_node_1:
  sdo:
    - index: 0x1017
      sub_index: 0
      value: 1000
    - index: 0x2200
      sub_index: 0
      value: 0x12345678
字段 必填 默认值 作用
index 是 无 OD index
sub_index 否 0 OD sub-index
value 否 0 写入值

dcfgen 会按 EDS 数据类型编码 value。该列表适合持久化启动配置，不适合测试过程中的临时写入，因为它会改变 boot 行为并可能生成 <slave-name>.bin。临时测试值应由测试程序在运行时写入，并在用例结束后清理。

12. 当前工程推荐的 master.yml

下面配置用于“所有协议动作由测试程序显式控制”的场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
options:
  dcf_path: ""
  heartbeat_multiplier: 3.0
  retry_factor: 3

master:
  node_id: 127
  baudrate: 1000

  heartbeat_consumer: false
  heartbeat_producer: 0

  start: false
  start_nodes: false
  start_all_nodes: false
  reset_all_nodes: false
  stop_all_nodes: false
  boot_time: 0

mcu_node_1:
  dcf: "generated/project.dcfgen.eds"
  node_id: 1

  heartbeat_consumer: false
  heartbeat_producer: 0

  boot: false
  mandatory: false
  reset_communication: false

生成时 -v 输出不应出现非预期的从机 SDO 写请求。

13. 完整 demo.yml：全部字段与注释

下面模板保留了原生 Lely 2.4.0 dcfgen 支持的全部配置字段。只有项目建立主从关系所需的基线字段处于启用状态；其余字段全部以注释形式保留，并在相邻注释中说明作用、单位和风险。

这是一份字段模板，不是生产参数清单。取消注释前应核对 EDS 默认值、节点能力、CAN-ID 冲突、运行时文件路径和自动 boot 的副作用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
# Lely dcfgen 2.4.0 完整配置模板。
#
# 使用方法：
#   1. 将本文件保存为 config/demo.yml。
#   2. 将从机 EDS/DCF 放到 config/generated/project.dcfgen.eds。
#   3. 进入 config 目录执行：
#        dcfgen -r -v -d generated demo.yml
#
# 下方只启用了建立当前工程主从关系所需的基线字段。其他字段均为
# 可选配置，保留为注释。取消注释前必须确认取值、单位、EDS 支持情况
# 以及对自动启动和配置下发的影响。

# -----------------------------------------------------------------------------
# 全局默认值，可被 master 或任意从机 section 继承。
# 整个 options section 均为可选；使用工具默认值时可以完全省略。
# -----------------------------------------------------------------------------
# options:
#   # 目标系统上 concise DCF 文件的运行时目录前缀。
#   # 该字段不是输入 EDS 路径，也不会相对于本 YAML 文件自动解析。
#   dcf_path: "/opt/canopen/config"
#
#   # heartbeat consumer timeout 的默认倍率。
#   # 例如 producer 周期为 1000 ms，倍率为 3.0，则超时为 3000 ms。
#   heartbeat_multiplier: 3.0
#
#   # NMT boot 重试因子，写入对象 0x1F81 的高字节字段。
#   retry_factor: 3

# -----------------------------------------------------------------------------
# 主站 section。section 名称必须是 master。
# -----------------------------------------------------------------------------
master:
  # 当前工程必配：主站 CANopen Node-ID。
  # 通常使用 1..127；本工程约定主站使用 127。
  node_id: 127

  # 当前工程必配：CAN bit rate，单位 kbit/s。
  # 必须与 Linux CAN 接口和总线上全部节点一致。
  baudrate: 1000

  # 主站 identity 对象 0x1018。没有正式分配值时保持默认 0。
  # vendor_id: 0x00000000       # 0x1018:01，供应商 ID。
  # product_code: 0x00000000    # 0x1018:02，产品代码。
  # revision_number: 0x00000000 # 0x1018:03，修订版本。
  # serial_number: 0x00000000   # 0x1018:04，序列号。

  # SYNC producer 配置。
  # sync_period: 0              # 0x1006，单位 us；0 表示不周期发送 SYNC。
  # sync_window: 0              # 0x1007，单位 us；0 表示不启用 SYNC window。
  # sync_overflow: 0            # 0x1019；0 表示 SYNC 不携带 counter byte。

  # TIME 与 EMCY 通信参数。
  # time_cob_id: 0x00000100     # 0x1012，TIME 默认 CAN-ID 为 0x100。
  # emcy_inhibit_time: 0        # 0x1015，单位 100 us。

  # 主站 heartbeat 行为。
  # heartbeat_multiplier: 3.0   # 覆盖 options.heartbeat_multiplier。
  # heartbeat_consumer: true    # 为配置的从机生成主站 0x1016 consumer 条目。
  # heartbeat_producer: 1000    # 主站 0x1017，单位 ms；0 表示禁用。

  # 主站错误行为对象 0x1029，map key 为子索引/错误类别。
  # error_behavior:
  #   1: 0x00

  # 连续 NMT 命令之间的最小间隔。
  # nmt_inhibit_time: 0         # 0x102A，单位 100 us。

  # NMT 启动策略。工具默认 start=true、start_nodes=true。
  # 显式协议测试时，可取消下面五项注释并保持 false，避免主站自动改变状态。
  # start: false                # false：主站不自动进入 Operational。
  # start_nodes: false          # false：主站不自动启动已配置从机。
  # start_all_nodes: false      # true：广播 NMT Start 到全部节点。
  # reset_all_nodes: false      # true：mandatory 从机失败时 reset all。
  # stop_all_nodes: false       # true：mandatory 从机失败时 stop all。

  # mandatory 从机的 boot 超时。
  # boot_time: 0                # 0x1F89，单位 ms；0 表示不设置超时。

# -----------------------------------------------------------------------------
# 从机 section。除 options、master 和点号开头 section 外，其他顶层名称
# 都会被当作从机。section 名同时决定 concise DCF 文件名，例如
# mcu_node_1.bin。
# -----------------------------------------------------------------------------
mcu_node_1:
  # 必配：dcfgen 在生成阶段读取的 EDS/DCF。
  # 相对路径按执行 dcfgen 时的当前工作目录解析，不按本文件目录解析。
  dcf: "generated/project.dcfgen.eds"

  # 当前工程必配：从机 Node-ID，同时用于解析 EDS 中的 $NODEID 表达式。
  node_id: 1

  # 当前从机 concise DCF 的运行时目录，覆盖 options.dcf_path。
  # dcf_path: "/opt/canopen/config"

  # 从机 identity 期望值。启用后应与 EDS、设备和 boot 校验策略一致。
  # revision_number: 0x00010000 # 期望 0x1018:03。
  # serial_number: 0x00000001   # 期望 0x1018:04。

  # 从机 TIME COB-ID。Lely 2.4.0 源码相关路径存在属性名不一致问题，
  # 未完成本地修复和回归测试前不要启用。
  # time_cob_id: 0x00000100

  # heartbeat 监督与生产。
  # heartbeat_multiplier: 3.0   # 当前从机 heartbeat timeout 倍率。
  # heartbeat_consumer: false   # true：配置从机监控主站 heartbeat。
  # heartbeat_producer: 1000    # 写从机 0x1017，单位 ms。

  # 当前从机 NMT boot 重试因子，覆盖 options.retry_factor。
  # retry_factor: 3

  # Node guarding。不要与同一节点的非零 heartbeat_producer 同时启用。
  # guard_time: 0               # 从机 0x100C，单位 ms。
  # life_time_factor: 0         # 从机 0x100D；超时=guard_time*factor。

  # 从机错误行为对象 0x1029。与 EDS 默认值不同会产生配置期 SDO 写入，
  # 并可能生成 mcu_node_1.bin。
  # error_behavior:
  #   1: 0x00

  # RPDO 覆盖。PDO 编号必须已存在于 EDS，映射对象必须允许 PDO mapping。
  # rpdo:
  #   1:
  #     enabled: true            # 清除 invalid bit，启用该 RPDO。
  #     cob_id: 0x00000201       # 可写 auto 或显式 11-bit CAN-ID。
  #     transmission: 254        # 0..240 同步；254/255 事件驱动。
  #     event_deadline: 0        # 单位 ms；2.4.0 有已知源码问题，暂勿启用。
  #     mapping:
  #       - index: 0x2200        # 当前示例 EDS 中的 control_value。
  #         sub_index: 0

  # TPDO 覆盖。Classic CAN 单个 PDO 的总映射长度不得超过 64 bit。
  # tpdo:
  #   1:
  #     enabled: true            # 清除 invalid bit，启用该 TPDO。
  #     cob_id: 0x00000181       # 可写 auto 或显式 11-bit CAN-ID。
  #     transmission: 254        # 0..240 同步；254/255 事件驱动。
  #     inhibit_time: 0          # 单位 100 us。
  #     event_timer: 1000        # 单位 ms；0 表示禁用周期 event timer。
  #     sync_start: 0            # 首次发送对应的 SYNC counter 值。
  #     mapping:
  #       - index: 0x2100        # 当前示例 EDS 中的 status_value。
  #         sub_index: 0
  #       - index: 0x2101        # 当前示例 EDS 中的 counter_value。
  #         sub_index: 0

  # NMT boot 与 assignment 策略。工具默认 boot=true、mandatory=false、
  # reset_communication=true。显式协议测试时可取消注释并使用下列值。
  # boot: false                  # false：不自动 boot/configure 当前从机。
  # mandatory: false             # true：从机失败会影响主站启动/错误策略。
  # reset_communication: false   # false：禁止自动 NMT Reset Communication。

  # NMT boot 使用的固件和配置管理对象。
  # software_file: "firmware.bin"                # 0x1F58，固件路径。
  # software_version: 0x00000000                 # 0x1F55，期望固件版本。
  # configuration_file: "/opt/canopen/config/mcu_node_1.bin"
  #                                               # 0x1F22，concise DCF 路径。
  #                                               # 2.4.0 有已知解析问题，
  #                                               # 优先使用自动推导路径。
  # restore_configuration: 0                     # 0x1011 子索引；0 表示不恢复。

  # 配置期附加 SDO 下载。工具按 EDS 数据类型编码 value。
  # 启用后可能生成 mcu_node_1.bin 并在 boot 时修改从机，
  # 因此不要在这里放临时测试值。
  # sdo:
  #   - index: 0x1017
  #     sub_index: 0
  #     value: 1000
  #   - index: 0x2200
  #     sub_index: 0
  #     value: 0x12345678

# 增加从机时，复制一个新的顶层 section 并使用唯一名称。
# mcu_node_2:
#   dcf: "generated/another_device.eds"
#   node_id: 2

14. 生成 DCF

在 config/ 目录运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
cd "$TESTER_ROOT/config"
source "$TESTER_ROOT/.venv-dcf-tools/bin/activate"

mkdir -p generated
rm -f generated/master.dcf \
      generated/master.bin \
      generated/mcu_node_1.bin \
      generated/SHA256SUMS

dcfchk -n 1 -p generated/project.dcfgen.eds

dcfgen \
    -r \
    -v \
    -d generated \
    master.yml

dcfchk -n 127 generated/master.dcf

参数含义：

参数 作用
-d generated 指定输出目录
-r 在主站 DCF 中生成 remote PDO 对象和参数映射
-v 打印生成的配置期 SDO 请求
-S lint 失败时继续；正式生成不建议使用

15. 生成后检查

15.1 文件完整性

1
2
3
4
5
cd "$TESTER_ROOT/config/generated"
sha256sum master.dcf project.dcfgen.eds > SHA256SUMS
[ ! -f master.bin ] || sha256sum master.bin >> SHA256SUMS
[ ! -f mcu_node_1.bin ] || sha256sum mcu_node_1.bin >> SHA256SUMS
sha256sum -c SHA256SUMS

15.2 语义检查

手工测试配置至少应确认：

1
2
3
4
5
6
7
主站 Node-ID = 127
Baudrate = 1000 kbit/s
0x1F80 = 0x0000000D
节点 1 不自动 boot
节点 1 不是 mandatory
节点 1 不自动执行 Reset Communication
remote PDO 映射存在

15.3 检查意外的 .bin

若生成了 mcu_node_1.bin，先查看 dcfgen -v 输出，重点检查：

  • heartbeat producer/consumer；
  • PDO 通信参数和 mapping；
  • node guarding；
  • error behavior；
  • sdo 列表；
  • identity、software/configuration 管理字段。

任何与 EDS 默认值不同的配置都可能被转换为启动阶段 SDO 下载。

16. Lely 2.4.0 源码注意事项

以下字段在当前源码中存在实现风险，模板中已保持注释：

16.1 configuration_file

当前解析代码会把 configuration_file 的值写入与预期不一致的属性。建议使用自动生成的 <dcf_path>/<section-name>.bin 路径；确需自定义时，应先修复源码并增加生成结果测试。

16.2 event_deadline

当前处理 RPDO event_deadline 的代码引用了错误的变量。仅启用该字段可能导致异常或错误编码。启用前应修复源码，并验证对象 0x140x:05 的 verbose SDO 和 concise DCF 内容。

16.3 从机 time_cob_id

当前源码在相关路径中出现 time_cob_id 与 time_cobid 两种属性名。建议保持 EDS 中 0x1012 的默认值，除非已完成本地修复和回归测试。

16.4 不支持的常见 downstream 字段

以下字段不是原生 Lely 2.4.0 dcfgen schema：

1
2
3
4
5
6
7
8
boot_timeout
sdo_timeout_ms
defaults
nodes
driver
package
namespace
enable_lazy_load

不要直接从 ROS 2 或第三方文档复制这些字段到原生 master.yml。

17. 常见问题

17.1 dcfgen: command not found

1
2
source "$TESTER_ROOT/.venv-dcf-tools/bin/activate"
command -v dcfgen

17.2 调用了错误版本

1
2
type -a dcfgen
python -m pip show dcf-tools

确认命令和 Python package 都来自项目 venv。

17.3 找不到 EDS

原因通常是从错误目录执行。固定从 config/ 目录运行：

1
2
cd "$TESTER_ROOT/config"
dcfgen -r -v -d generated master.yml

17.4 RevisionNumber 不一致

使兼容副本的 DeviceInfo.RevisionNumber 与 0x1018:03 一致，同时保留原始 EDS 和转换记录。

17.5 主站自动启动或复位从机

检查并显式设置：

1
2
3
4
5
6
7
8
master:
  start: false
  start_nodes: false

mcu_node_1:
  boot: false
  mandatory: false
  reset_communication: false

17.6 false 仍被当成 true

确认没有使用 quoted boolean：

1
2
boot: false       # 正确
# boot: "false"   # 错误

18. 推荐维护流程

EDS 或 YAML 变化时：

1
2
3
4
5
6
7
8
校验原始 EDS SHA256
  -> 生成兼容 EDS
  -> dcfchk 从机
  -> dcfgen -r -v
  -> dcfchk 主站
  -> 检查 0x1F80/0x1F81/PDO/verbose SDO
  -> 生成 SHA256SUMS
  -> 提交 YAML、生成物和版本记录

Lely commit 变化时：

1
2
3
4
5
6
重建或重装 dcf-tools venv
  -> 比较 dcfgen/cli.py、master.dcf.em、setup.py
  -> 重新生成 DCF
  -> 比较 verbose SDO 和生成物语义
  -> 重跑主从功能测试
  -> 再更新项目基线

19. 参考资料

源码位置：

1
2
3
4
python/dcf-tools/setup.py
python/dcf-tools/dcfgen/cli.py
python/dcf-tools/dcfgen/data/master.dcf.em
python/dcf-tools/Makefile.am

官方文档：