EtherCAT 从站调试里大量报错、主站识别不到、PDO 映射错乱，根源大多出在 ESI XML 文件写错，按照规范流程配合工具，30 分钟就可以完成一份能用的 ESI XML 基础版本。ESI XML 本质就是从站的设备描述文件，对应硬件里 SII 信息接口，主站 TwinCAT 这类软件靠这份 XML 读取厂商 ID、设备型号、PDO、同步管理器参数；很多人上手直接手写 XML，大小写、标签、数据长度、厂商编号随便填，最后出现解析失败、周期性通讯报错、DC 同步异常，这套方案优先用模板 + 工具校验，先搭基础结构、填准关键参数，再逐步增加 PDO 和对象字典，避开高频踩坑点，先保证文件能被主站正常加载识别，再做功能调试。
一、ESI XML 基础概念与文件结构清单
- 全称：EtherCAT Slave Information，后缀 xml/esi，遵循 ETG.2000 标准
- 根节点：
，严格区分大小写，写错直接解析失败 - 核心子节点顺序：Vendor 厂商信息 → Product 产品定义 → Descriptions 设备描述 → Mailbox 邮箱配置 → SyncManager 同步管理器 → PDO 映射列表
- 对应硬件：ESI XML 内容必须和 ESC 芯片 EEPROM 里 SII 数据、固件对象字典三者保持一致，三者不一致是最常见大坑
| 节点 | 填写重点 | 高频错误 |
|---|---|---|
| Vendor | 填写 ETG 官方分配的 Vendor ID，不能随便自编 | 厂商 ID 重复、十六进制格式写错 |
| Product | 产品码、版本号，和 SII 内一致 | 版本号和固件不匹配，升级固件后 ESI 没同步更新 |
| SyncManager | 邮箱 SM、过程数据 SM，方向、长度 | SM 区域重叠、长度设置和 PDO 总和对不上 |
| PDO | RxPDO 主站下发、TxPDO 从站上送，子条目索引、子索引、位宽 | 索引写错、总长度不匹配、输入输出方向搞反 |
二、30 分钟 ESI XML 制作简易步骤
- 准备模板与校验工具：找一份同类型成熟 ESI 模板，准备 XML 校验工具、TwinCAT、ETG 官方 xsd 校验文件，不要从零手写
- 修改 Vendor 和 Product 信息：填入正式分配的厂商 ID、产品编号、名称、版本，和 EEPROM SII 内容保持统一
- 配置 Mailbox 邮箱参数：CoE 邮箱常用 SM0、SM1，设置缓冲区大小，支持 CoE 协议
- 配置 SyncManager 过程数据通道：SM2 用于 RxPDO，SM3 用于 TxPDO，核对每个 SM 的起始地址、长度、方向
- 编写 PDO 条目：逐个添加对象字典索引、子索引、数据类型，累加校验总长度，保证和 SM 长度匹配
- 语法校验：先用 xsd 校验 XML 格式，检查标签闭合、大小写、特殊字符
- 导入主站测试：放到 TwinCAT ESI 目录，清除缓存，重新扫描设备，看是否正常识别、无红色报错
三、ESI XML 开发高频避坑点（上篇重点）
- XML 大小写与标签坑
- Vendor ID 随意填写
- SII、ESI、对象字典三方不一致
- SyncManager 缓冲区重叠、长度不匹配
- 缓存没清，修改 ESI 后不生效
- PDO 方向搞反
ESI 标准节点严格区分大小写，
Vendor ID 必须向 ETG 申请分配，自己随便写 ID，多设备组网时容易 ID 冲突，一致性测试直接不通过。
EEPROM 里烧录的 SII 信息、ESI XML、固件内 OD 字典三者参数必须统一，经常出现改了固件 PDO，ESI 文件忘记同步更新，通讯间歇性报错。
SM 缓冲区地址不能重叠，PDO 所有条目的总字节长度，必须等于对应 SyncManager 配置长度，多一个 bit、少一个 bit 都会导致周期通讯报错。
TwinCAT 会缓存 ESI 信息，修改 XML 之后，直接扫描不会加载新文件，必须删除 ESICache 缓存文件，重启 TwinCAT 配置模式。
RxPDO 是主站发给从站（Output），TxPDO 是从站发给主站（Input），方向写反，数据收发完全错乱，调试很难定位。
四、上篇内容边界说明
本篇只覆盖 ESI XML 基础结构、语法校验、厂商、SM、PDO 基础配置和基础识别类问题；DC 同步、分布式时钟、安全协议、模块化设备、CoE 初始化命令、一致性 CTT 测试等进阶内容放在下篇。
【相关 FAQ】
问题 1：EtherCAT 从站开发里，ESI XML 的作用是什么？
回答 1：EtherCAT 从站开发中 ESI XML 是从站标准化描述文件，给 TwinCAT 等 EtherCAT 主站提供厂商、型号、同步管理器、PDO 映射、对象字典信息，主站依靠 ESI XML 完成从站识别和通讯配置，没有或者写错 ESI XML，主站会识别为未知从站或者通讯报错。
问题 2：制作 ESI XML 时，为什么 SII、ESI XML、对象字典必须保持一致？
回答 2：EtherCAT 从站开发中 ESI XML 是 SII 的软件镜像，对象字典是固件实际运行的数据定义，三者参数不一致时，主站读到的描述和从站实际能力不匹配，会出现 PDO 映射失败、周期性丢包、随机断连，也是 ESI XML 调试最耗时的坑。
问题 3：修改完 ESI XML 导入 TwinCAT，但是主站识别没有变化是什么原因？
回答 3：EtherCAT 从站开发调试 ESI XML 时，TwinCAT 会自动生成 ESI 缓存，修改 ESI XML 之后没有删除缓存，软件依旧读取旧配置；需要删除 ESICache 缓存文件，重启 TwinCAT 配置模式，再重新扫描从站。
问题 4：手写 ESI XML 和用工具生成 ESI XML 哪个更适合新手？
回答 4：EtherCAT 从站开发新手做 ESI XML 优先用成熟模板 + 工具生成，手写很容易出现标签、大小写、PDO 长度、SM 参数错误；工具生成后再微调参数，校验成本更低，更容易在 30 分钟内完成可用版本。
问题 5：ESI XML 校验通过，导入 TwinCAT 依然报 PDO 错误，优先查什么？
回答 5：EtherCAT 从站开发 ESI XML 语法校验通过只代表 XML 格式合法，优先核对 SyncManager 长度、PDO 条目总长度、PDO 输入输出方向，再核对和 EEPROM SII、固件 OD 字典是否匹配。
【参考资料】
[2026-11-10]（EtherCAT 从站开发避坑指南：30 分钟搞定 ESI XML (上)）ZLG 致远电子
[2026-11-11]（EtherCAT 从站开发避坑指南：30 分钟搞定 ESI XML (下)）ZLG 致远电子
[2025-05-26]（ETG.2000 ESI 规范与 XML Schema 文档）EtherCAT 技术协会
[2025-03-12]（ETG.2200 EtherCAT 从站实现指南）EtherCAT 技术协会
[2024-09-02]（EtherCAT 一致性测试指南 ESI 校验部分）EtherCAT 技术协会
【免责声明】
本文仅为 EtherCAT 从站 ESI XML 开发科普避坑参考，不替代 ETG 官方 ETG.2000、ETG.2200 标准文档以及一致性测试；ESI XML 最终能否通过 ETG 一致性测试、适配不同主站，取决于完整参数配置、固件、硬件 ESC、SII 烧录配合，实操前请核对官方标准，项目商用前务必完成 CTT 一致性测试。