2022年12月27日【Jiawei_Z】--对于LAN9252和XML文件的深入研究

再次深入的研究LAN9252的XML和SSC Tools之间的关系

2022年12月27日–对于LAN9252和XML文件的深入研究
EtherCAT从站设备描述文件xml详解
项目简单使用64入64出纯数字IO，制作一个由键盘和LED灯组成的EtherCAT从站面板，来跟BECKHOFF的PLC进行通信。LAN9252与MCU之间的通信方式我们选择使用SPI方式。
打开SSC后，File->New，打开新建项目的对话框，这里让我们选择一个项目模板，可以使用默认选项创建，该选项提示我们All settings are available.，这里我们不选则默认模板，而是在点中Custom单选按钮中，下拉出一个EL9800 | 8Bit Digital I/O, 16Bit Analog Input，选中它，下方提示我们
This configuration provides the standard configuration for the new EL9800 EtherCAT Evaluation Kit.
The corresponding device description is located in file “…\esi\SlaveStackCode.xml” (device: EL9800-SPI-PIC24) or will be created by this tool.
此配置为新的EL9800 EtherCAT评估套件提供了标准配置。相应的设备描述位于文件“…\esi\SlaveStackCode.xml”（设备：EL9800-SPI-PIC24）中，或将由该工具创建。

显然这个模板更加适合我们，点击OK进入下一步。

此时界面由左边的树状菜单和右边的内容条目组成，有许多可以配置的选项，包括VendorID和Image等LOGO的设置。如果有兴趣可以对其进行设置，也可以直接进入下一步。

依次点击Tool->Application->Create New，提示需要先保存一下，随便找个路径保存一下本项目。保存成功后，会立刻弹出一个Excel文件（需要预先安装Excel）。
这是一份模板Excel，用来设置EtherCAT的通信数据，我们将使用此Excel进行传输IO的点位设置。根据之前的计划，输入有64个BIT，输出有64个BIT，因此对该Excel的//0x6nnx和//0x7nnx条目进行配置，配置方法如下：

按照上述三张图片的配置，熟练使用Excel的批量拖拽方法，可以快速地填入。不要忘了修改最后一个Maximum number of modules条目，改成3即可。 都修改好以后，导入完成后界面并不会有太大变化，此时需要点击Project->Create new Slave Files进行协议栈文件的创建。

创建完成后整个工程项目如图所示：至此，使用SSC的工作就都完成了。下面的工作是对其生成的XML文件进行微调，并对协议栈文件进行移植。

本章所介绍的知识点大部分来自于SSC内置的一份帮助文档EtherCAT Slave Design Quick Guide.pdf，可以点击下载。我已经代表我们企业申请加入了EtherCAT协会，并注册了VendorID，在EtherCAT协会入会章程中不允许会员在互联网上扩散只有会员才可以下载到的资源，因此SSC的安装包我不方便上传，有需要的小伙伴可以私下交流.

EtherCAT Slave Design Quick Guide.pdf 进一步阅读

细节的梳理
I. Create a basic SSC Tool project
1.1. Download the Slave Stack Code (SSC) and install the EtherCAT Slave Stack Code Tool.
1.2. Start the EtherCAT Slave Stack Code Tool and create a new project [1] .
1.3. Select EL9800 | 8Bit Digital I/O, 16Bit Analog Input

1.4. Set DEVICE_NAME = “MyApplication” (Node Slave Information )

1.5. Save the project in “c:\working\SlaveProject\” (File->Save)

II. Create a new Application
2.6. Create a new application description file (Tool-> Application->Create new)
2.7. Add the following object descriptions to the Excel® file

2.8. Save the Excel file (in the default location)
2.9. Close the import application dialog
2.10. Create the slave files (Project -> “Create new Slave Files”) and close the SSC Tool

III. Create a MPLAB Project
3.11. Create a MPLAB slave project in c:\working\SlaveProject [2] .
3.12. Open “MyApplication.c” and add the following lines to the method ----“void APPL_InputMapping(UINT16* pData)” (line 254)

3.13. Add the following lines to the method -----------“void APPL_OuputMapping(UINT16* pData)” (line 270)

3.14. Add the following lines to the method -----------“void APPL_Application(void)” (line 282)

3.15. Compile and run the slave application [2] .
3.16. Copy the ESI file to the TwinCAT ESI folder (e.g. TwinCAT 2.11 : “c:\Twincat\Io\Ethercat\”)
3.17. Create a TwinCAT configuration [2] .
3.18. Scan slave, update EEPROM of slave, delete slave, re-scan network with new slave

---

接下来再对生成的XML文件深入分析一下；
如图使用XMLNotepad打开上一章STM32与LAN9252构建EtherCAT从站（二）：使用SSC生成EtherCAT协议栈和XML文件生成的XML文件。
可以粗略地观察到整个文档由两个节点组成，Vendor 和 Descriptions。

Vendor下面的id和name来自于EtherCAT会员企业信息，我这里不方便用我们公司的真实信息，暂且用#x1和EtherCAT来替代。
Vendor下面的ImageData16x14节点，存储的是.bmp格式的16色深度的logo文件，可以使用微软画图或者Photoshop等软件制作，制作完成后使用任何16进制查看器（Notepad++和Sublime都有相关插件直接查看任何文件的16进制数据）将数据填入该节点。

Descriptions->Groups->Group节点下方的Type和Name两个节点描述的设备类型的种类和名称，这里根据自己的想法自定义即可。ImageData16x14是设备类型图标，可以直接用上面的数据。
Descriptions->Devices->Device->Physics是以太网口类型，YY表示两个RJ45，一进一出，跟Y相对应的是K，表示EBUS网口，德国倍福的专用端口，不需要修改。
Descriptions->Devices->Device->Type节点下的ProductCode和RevisonNo表示的是硬件编号和版本号，这里取一些有意义的名称，产品迭代升级时不要忘记这里的版本号也应该做相应的升级。TwinCAT通过这两个字段确定XML的唯一性，也就是说你如果两份XML这两个字段一样，放到TwinCAT/IO/EtherCAT文件夹下，只能识别其中一个。
Descriptions->Devices->Device->Name设备名，任意取。
Descriptions->Devices->Device->Info节点存储了一些超时限制的数据，没有特殊情况不需要修改，这里设置好了以后在TwinCAT界面可以看到设备在各种状态切换时的超时限制。
Descriptions->Devices->Device->GroupType与上面Descriptions->Groups->Group->Type相对应。

XML中的字典和IO数据
这部分数据超级复杂，包括字典定义和IO点位描述，但这部分数据已经由SSC创建完成了，SSC通过我们填写的Excel自动生成的，如果没有SSC，这里的数据全都由我们自己填写，将是一件非常恐怖的事情，不仅编写起来工作量非常巨大，而且极易出错。我们这里仅做简单地浏览认识一下。
首先理解一下字典，所谓字典就是对数据结构的描述，XML里面每种数据集合都需要有它的类型定义，有些类型是简单的String，UINT等基本类型，有些类型是由多种基本类型组合而成的复合结构，在字典定义部分都需要对其进行定义。打开Descriptions->Devices->Device->Profile节点，里面有两个子节点DataType和Objects，有点类似C语言中的typedef定义类型和int x定义变量，事实上在SSC生成的协议栈中的SSC-DeviceObjects.h文件也确实与这里的定义一一对应的，感兴趣的朋友可以提前去浏览一下，

我们将会在STM32与LAN9252构建EtherCAT从站（五）：STM32与LAN9252适配做详细介绍。

举个例子，如图所示，在Objects节点下有一个Object名叫Device name, 其index为#x1008，type为STRING(10)，这个STRING(10)就要从上面的DataTypes节点里面找对应的子项了，果然我们会发现一个DataType子节点名叫STRING(10)，它的BitSize定义的是80个bit，应该是个uchar[10]的数组，那么这个字符串内容是什么呢，还记得我们之前在硬件基础信息部分定义的Device Name吗，我们去看看，上面定义的是SSC-Device，数一数正好10个字节。

所以在XML中每一个元素都会有自己的数据结构，每一种数据结构都会在数据字典中定义，如果这之间的关系理得不顺，EtherCAT将无法建立连接，想要手工把这里面的关系搞定真的非常困难，SSC在之前帮我们全都搞定了。

IO点位数据就更加复杂了，在Descriptions->Devices->Device节点下有四个Sm节点，这个表示通道，我们通信时一共有四个通道，除了过程传输数据输出和输入以外，还有两个通道用来控制EtherCAT自身状态的，也是EtherCAT协议中非常重要的MailBox概念，分别叫做MBoxOut和MBoxIn，这里不需要管它，只需要了解过程传输数据Inputs和Outputs两个通道，这两个通道内部的数据又分别指向RxPdo和TxPdo两个节点，这两个节点每个Entry节点都是我们之前在Excel中定义的一个IO点。
SSC通过Excel帮我们完成了一项庞大的工作，在XML中生成了64+64个Entry，如果手工录入，这工作量将会非常恐怖。

综上，XML中数据字典和IO点位我们就粗略的理解到这里了。这其中的还有很多深奥的地方，比如SM通道的size需要16位对齐，Entry节点的bitlen和subindex属性等等。
如果您有兴趣理解透彻，可以去看一下CanOpen协议中关于字典和对象的描述，EtherCAT协议这部分内容完全脱胎于CanOPEN协议。
XML中的EEPROM内容

现在我们来到XML最后一部分内容，EEPROM节点，这个节点数据量非常少，只有两个子节点，ByteSize一般为2048，代表板载的EEPROM芯片容量是2KByte，其实我们一般使用512K的物理容量芯片，防止IO数据定义时数据量增加不够存储。这里插一句题外话，与LAN9252相连的EEPROM芯片尽量使用ATMEL家的24FC512，否则EtherCAT可能会有连接困难的现象。

XML中大部分内容都由SSC帮我们生成，现在到了比较重要的最后14byte数据，也就是ConfigData节点，SSC帮我们构建的XML是按照ET1100芯片生成的，默认为050E03440A0000000000，这里使用的是LAN9252，打开LAN9252芯片手册AN1907-Microchip LAN9252 Migration from Beckhoff ET1100，看到2.3节，手册上让我们改成800E00CC8813F0000000800000，我们先跟着做，手册下面一行提示我们如果想进一步了解含义，需要阅读LAN9252 EEPROM章节。

打开LAN9252 datasheet，在12.8 EEPROM Configurable Registers章节，有如下介绍：

可以看到这14个byte其实是由这张表组成的，上面的截图只是表格的前半部分，下面一页有后半部分，不过最重要的就是这前面第一个字节。看到第一个字节定义了芯片的0140h寄存器，这个寄存器叫做Process Data Interface，点击进入改寄存器的详细描述，如下图所示：

在12.14.24章节，有0140h寄存器的详细描述，可以看到这个寄存器配置为80h即为SPI通信方式，这与我们项目架构相匹配。回忆一下之前手册上让我们将ConfigData节点修改为800E00CC8813F0000000800000这第1个80其实就是指的SPI方式，至于后面这些数据代表什么含义，都可以在LAN9252 datasheet中查找到，如果暂时不理解就不要修改，保持默认就可以了。

至此整个XML文档我们就浏览剖析结束了，这份XML后面会放到TwinCAT安装路径下的/Io/EtherCAT文件夹，然后在TwinCAT中给寻找到的EtherCAT设备烧录，LAN9252将其中关键数据存储到与自己相连的EEPROM中，供自己以后上电时给自己配置各项参数。

花开两朵，各表一枝，XML文件我们暂且放在一边，下面一章，我们将给STM32F103配置一下SPI功能，并与之前SSC生成的协议栈做一下SPI部分的融合。
STM32与LAN9252构建EtherCAT从站（四）：STM32配置SPI
使用STM32CubeMX软件配置MCU外设
我并不打算将本系列文章写成一个关于STM32，尤其是关于STM32、Keil、CubeMX大而全的基础教程，那种每个界面都有截图，每个按钮的点击都要介绍，篇幅拉得太长了。我这里关于这些知识只能用简要地说明一下，具体到每个软件或者技术的详细使用，列为感兴趣，或者追求细节的话，还是建议去搜一些颗粒度更小，更专业的教程。 打开STM32CubeMX，新建一个STM32F103ZExx工程，我们来配置一下与LAN9252通信的外设。

与LAN9252通信，涉及到的外设包括以下几点：
SPI：4线标准SPI，LAN9252支持SQI（6线高速SPI），但我们这里一切从简。标准模式下，SPI时钟频率最高支持30M。LAN9252还有高速SPI模式，时钟频率最高80M，这个自己去研究。

1ms的定时器：命名为ECAT_CheckTimer，协议栈的日常处理，包括看门狗喂狗行为，在定时器中断服务函数中进行，一般配置成1ms。

3个外部中断：包括1个EtherCAT主中断，命名为PDI_Isr；2个时钟同步IRQ，命名为Sync0_Isr,Sync1_Isr，EtherCAT主从通信中如果选择使用分布式时钟功能，这两个中断要配上。

NVIC方面，使用CubeMX配置时注意以下几点：
对于MCU来说，SPI是主站，不需要中断读写，SPI的通信时序是读的同时写，写的同时读，读写不分离，所以没必要配置中断。

3个外部中断，在CubeMX中都配置成初始enable，这样生成的代码友好一点，但到了Keil中，需要把初始化函数中最后一行Enable的语句给注释掉。什么时候Enable中断，什么时候Disable中断，都要由协议栈决定，而不是一上电就打开外部中断，那样非常容易出错，基本连不上。

定时器中断，跟外部中断一样，CubeMX中配置好enable，代码生成后注释掉最后一行Enable，由协议栈来决定打开和关闭定时器中断。

向量表的详细介绍可以参考我的另一篇博客：STM32F4+DP83848以太网通信指南系列（三）：中断向量。一个可行的中断向量表为2bit抢先，2bit响应： a). ECAT_CheckTimer 配置为 1抢先，0响应 b). PDI_Isr 配置为 1抢先，0响应 c). Sync0_Isr,Sync1_Isr 均配置成 2抢先，0响应





Keil5中适配SPI
CubeMX帮我们生成了Keil工程，我们的整个项目的后续开发也将以此套工程代码为蓝本继续下去。首先熟悉一下工程文件树。

这是CubeMX帮我们生成的工程架构，其他都是浮云，中间的Application/User是主战场，我们自己的逻辑一般都在这个Group中，毫无疑问，main.c是主程序；gpio.c,spi.c,tim.c中有各个外设资源初始化的代码；stm32f1xx_it.c中有帮我们生成好的中断服务函数，里面有一些关键函数我们待会儿需要移动到main.c中；stm32f1xx_hal_msp.c中是外设资源与硬件资源的映射配置代码，如果有些外设，比如SPI，使用的是其他GPIO复用，将在这个文件中有所体现。此时点击Keil5中的编译按钮，应该能够顺利编译，无任何报警和错误的。

所谓的EtherCAT协议栈移植，其实就是将上面讲的各个外设资源的接口与EtherCAT协议栈的内部接口进行对接，比如SPI部分，我们需要封装一些简单的SPI操作，命名为协议栈期望的函数名，供协议栈调用；再比如3个外部中断和1个时间中断，我们需要在这4个中断服务函数中调用协议栈暴露给我们的4个不同的函数来适配协议栈。我们这个教程的本章节，将主要介绍SPI的适配，其他适配将留到后面章节介绍。

LAN9252 芯片的SSC模板
之前我们在STM32与LAN9252构建EtherCAT从站（二）：使用SSC生成EtherCAT协议栈和XML文件中，使用SSC生成的EtherCAT从站代码是基于EL9800学习板的，那个学习板上的PHY芯片是ET1100这颗倍福自己的PHY芯片。我们这里使用相对廉价的LAN9252作为从站PHY芯片，LAN9252的一些寄存器设置跟ET1100是有区别的，因此我们到microchip官网下载LAN9252的SSC SDK。

下载回来以后，配合SSC5.11版本（5.12版本太新，跟LAN9252官方SDK兼容性不好），参考microchip的官方文档AN1916，生成的代码如下：

跟之前SSC生成的标准协议栈有所区别的是图片中第1，第2个文件由el9800.c,el9800.h变成了9525_HW.c,9252_HW.h；另外在LAN9252的SSC SDK中有一个SPI的工程文件，里面有SPI驱动的两个文件SPIDriver.c,SPIDriver.h，如果生成协议栈时没有add进去，这里手动复制一下；此外最后三个文件，STM32_EtherCAT_Slave开头的，是根据SSC中配置IO时的Excel文件生成的，其中STM32_EtherCAT_SlaveObjects.h是最有价值的，跟XML文件是一一对应的。 将这些文件全都copy到STM32工程的一个目录中，比如新建一个EtherCAT目录。 在KEIL的工程结构中新建2个Group，比如命名为EtherCAT，和Porting，按照图示，引入以下文件：

https://www.hexcode.cn/article/5e3eed1535616641b2daef9a

https://www.hexcode.cn/article/5e3eed9035616641b2daef9b