01-03-01 倍福桥接服务¶
1. 创建潘多拉TwinCAT桥接服务¶
在 TwinCAT 3 中使用结构化文本（ST）编程调用 KXGEM 库，实现 SECS/GEM 的功能接口调用，整个开发过程完全在 PLC 代码中完成。首先，需在潘多拉盒子中至少配置一个TwinCAT桥接服务容器，并将其指向对应的TwinCAT PLC。该容器服务作为 TwinCAT PLC 通过 ST 编程调用 SECS/GEM API 的实际实现，配置完成后无需对潘多拉盒子程序再做任何修改。TwinCAT 运行环境支持 Windows 7/8/9/10/11 及 WinCE。
以下是基于潘多拉客户端界面添加并配置桥接服务的具体操作：
1.1 删除所有已经创建的容器对象实例¶
ℹ️ 取决于当前潘多拉盒子的授权许可证，通常一个潘多拉盒子只允许创建一个容器对象，相应的创建一个SECS/GEM实例对象。如果你使用的潘多拉盒子需要同时映射多个硬件模块（PLC控制器）到各自独立的SECS/GEM实例，请联系sales@kxware.com安装支持多实例的SECS/GEM许可证。
1.2 添加TwinCAT SECS/GEM 桥接服务容器¶
在左侧空白处右键菜单中选择创建新的连接（容器）
1.3 修改桥接容器配置¶
编辑容器配置，修改ADS访问端口号，以及PLC IPV4地址（注意：此处填写的不是TwinCAT PLC的AMS NetID地址，而是和潘多拉LAN1或LAN2口连接的）。 依次点击“保存”按钮，“开始”按钮启动TwinCAT SECS/GEM Brdige桥接容器。
2. TwinCAT PLC安装KxADSRouter服务程序¶
由于倍福官方暂时尚未发布Linux平台上ADS路由服务程序，为了能够让潘多拉盒子上的TwinCAT SECS/GEM服务程序能顺利铜鼓“ADS”通信协议访问倍福TwinCAT PLC（包括Win7/8/9/10/11 和 WinCE）中的内部变量，我们需要提前在倍福TwinCAT PLC上安装开机自启动的KXADSRouter服务程序。
2.1 WinNT平台安装KxAdsRouter操作步骤¶
下载WinNT平台下运行的KxAdsRouter程序 （适用于Win7/8/9/10/11操作系统）
https://project.kxware.com/attachments/download/3640/KXAdsRouter_NT_1.3.0.26105.zip解压缩文件
.zip文件解压缩到 C:\TwinCAT\GEM\ 目录创建Windows开机自启动
在Windows Startup开始菜单中创建快捷方式指向 C:\TwinCAT\GEM\Kxware.AdsRouter.exe
2.2 WinNT平台安装KxAdsRouter操作步骤¶
下载WinCE平台下运行的KxAdsRouter程序
https://project.kxware.com/attachments/download/3639/KXAdsRouter_CE_1.3.0.26105.zip文件上传PLC
访问 ftp://{PLC_IP_Address}
将解压缩的KxAdsRouter文件夹复制到PLC FTP文件夹下
WinCE远程桌面操作
点击下面链接下载WinCE远程桌面工具
https://project.kxware.com/attachments/download/3641/CERHOST.exe登录WinCE远程桌面，打开StartMan菜单，
新建ads srv开机自启动项目
输入启动文件路径
\Hard Disk\FTP\KXAdsRouter_CE_1.3.0.26105\Kxware.AdsRouter.exe
保存，重启WinCE PLC
3. TwinCAT集成KXGEM ST库¶
3.1 下载安装KXGEM ST库¶
准备工作：下载TwinCAT 3 SECS/GEM PLC库文件，点击下方链接下载：
https://project.kxware.com/attachments/download/3595/KXGEM_1.1.0.26141.compiled-library.zip
打开TwinCAT 3软件，新建PLC项目。在PLC项目References栏目上鼠标右键点击Add Library。
在Add Library窗口上点击Advanced按钮
点击 Library Repository.. 按钮
点击 Install按钮，选择 KXGEM.compiled-library 库文件，点击Open按钮
点击Close关闭按钮，返回上一级对话框，Company选择 Kxware Information Technology删选PLC Lib文件，选择 KXware SECS/GEM，点击OK按钮。
库文件添加完成后，在PLC项目References列表中可以找到KXware SECS/GEM PLC库。
3.2 PLC创建SECS/GEM全局操作对象¶
SECS/GEM各个方法被封装在FB_GEM功能块中，用户通过定义全局的FB_GEM对象对GEM的各个接口进行访问操作。默认FB_GEM全局变量名为 FA.GEM，如需要修改该名字，需要同时修改上位机TwinCAT.GEM.exe.config配置文件。
创建名字为FA的全局变量区，并创建 FB_GEM类型的全局变量命名为 GEM。
4. FB_GEM功能块的API列表¶
4.1 InitializeFromPlc¶
从PLC上传入GEM初始化参数，并完成设备SECS/GEM服务程序的初始化操作。初始化操作包括：SECS/GEM网络连接参数；SV,DV,EC注册，Event注册，Alarm注册，Remote Command注册，Terminal注册等。初始化内容采用.INI文件格式，以下是Sample示例项目中的INI文件模板。
https://project.kxware.com/attachments/3598
- 因为受到PLC Stack容量大小的默认限制，传送的STRING总长度不能超过32KB。
- 当FA.GEM.InitializationState 处于NotInitialized 状态下，PLC 才可以调用InitializeFromPlc或InitializeFromFile方法进行初始化
- 通过读取FA.GEM.InitializationState是否等于InitializationSucc判断TwinCAT.GEM.exe是否完成GEM初始化操作。
设备基本信息设定：
- MDLN ：设备类型名
- SOFTREV：设备 软件版本号
- EqpSerialNum ： 设备序列号
- EqpModel : 设备型号
- Manufacturer：设备制造商
[Equipmment] ;MDLN,equipment model ;SOFTREV, software version num MDLN=DemoMachine SOFTREV=1.0.2 EqpSerialNum=0001 EqpModel=UVMachine Manufacturer=Beckhoff Gmbh
设备SECS通信设定：
- HSMS ： 采用SEMI E37 HSMS 高速Ethernet网络通信方式
- Passive：设备是TCP服务端，工厂Host作为客户端连接设备
- Active: 工厂主机是TCP服务端，设备主动连接工厂主机
- Device ID： 设备编号，通常 0或 32767
- Port No： 指定TCP监听端口号，默认5000
为了提升数据采集速度，通常工厂会要求设备提供2个或2个以上的TCP监听端口，通常第一个端口（默认5000）既作为数据采集端口也作为远程控制端口，其余端口只作为数据采集端口，不允许作为远程控制端口。
[Connection] ;ECS connection type, SECS connection mode, Device ID, IP Address, TCP Port No ;SECS connection type: SECS-I (Serial Port), HSMS (Ethernet, default) ;SECS connection mode: Active (Host is TCP server), Passive (Local PLC is TCP server, default) ;Device ID: 0 (default) ~ 32767 ;IP Address: In Active mode, host PC IP. In Passive, local PLC listening IP, 0.0.0.0 means listen at every local IP address ;TCP Port No: In Active mode, host PC listenning Port No. In Passive mode, local PLC listenning Port No. Default: 5000 CONN1=HSMS,Passive,0,0.0.0.0,5000 CONN2=HSMS,Passive,0,0.0.0.0,5001 CONN3=HSMS,Passive,0,0.0.0.0,5002
设备Variable定义：
按照SEMI E30 GEM标准，Variable分为三类：
- SV（Status Variable）：只和时间相关的状态变量
- DV（Data Variable）：只和事件相关的数据变量
- EC（Equipment Constant）：工厂可以远程读写的设备常量
INI文件对TwinCAT变量如何映射GEM Variable做了定义，如果PLC Variable Name这个字段填写PLC符号变量名称，在GEM初始化完成后，上位机TwinCAT.GEM.exe程序会自动 定期（20ms）通过ADS抓取该PLC变量值并更新到GEM Variable中。如果INI文件中没有对PLC Variable Name进行指定，则需要PLC代码调用SetValue方法对指定的Variable进行赋值操作。
INI文件中如果Persistent变量为True，且PLC Variable Name不为空的情况，当GEM初始化成功完成后，上位机TwinCAT.GEM.exe会自动将上一次掉电存储的Variable Value写回到PLC变量中。类似的当工厂原车能够修改EC变量值，同样也会触发新的Variable Value写回到PLC变量。
[Variables] ;Variable ID, GEM Variable Name, PLC Variable Name, Variable Type, Persistent(False/True), Variable Value Type, Unit, MinValue, MaxValue, DefaultValue, Description ;Variable Type: SV(Status Variable), DV(Data Variable), EC(Equipment Constant) ;Variable Value Type: L/B/BOOLEAN/A/I1/I2/I4/I8/U1/U2/U4/U8/F4/F8 CHA.Temperature=1001,SV,MAIN.CHA.Temperature,False,F8,C,0,100,25,Chamber heater temperature reading CHA.Pressure=1002,SV,MAIN.CHA.Pressure,False,F8,mBar,0,1020,750,Chamber vac pressure reading CHA.StepNo=1003,SV,MAIN.CHA.RecipeStep,False,I2,,0,1000,0,Chamber current recipe step number CHA.RecipeName=1004,SV,MAIN.CHA.RecipeName,False,A,,,,,Chamber recipe name CHA.OverTempThreshold=1005,EC,MAIN.CHA.OverTempThreshold,True,F8,C,0,1000,100,Over temperature alarm threshold CHA.OverPressThreshold=1006,EC,MAIN.CHA.OverPressThreshold,True,F8,mBar,0,2000,760,Over pressure alarm threshold CHB.Temperature=2001,SV,MAIN.CHB.Temperature,False,F8,C,0,100,25,Chamber heater temperature reading CHB.Pressure=2002,SV,MAIN.CHB.Pressure,False,F8,mBar,0,1020,750,Chamber vac pressure reading CHB.StepNo=2003,SV,MAIN.CHB.RecipeStep,False,I2,,0,1000,0,Chamber current recipe step number CHB.RecipeName=2004,SV,MAIN.CHB.RecipeName,False,A,,,,,Chamber recipe name CHB.OverTempThreshold=2005,EC,MAIN.CHB.OverTempThreshold,True,F8,C,0,1000,100,Over temperature alarm threshold CHB.OverPressThreshold=2006,EC,MAIN.CHB.OverPressThreshold,True,F8,mBar,0,2000,760,Over pressure alarm threshold StepNo=3001,DV,,False,I2,,0,1000,0,Chamber current recipe step numberStepNo=3001,DV,,False,I2,,0,100000,0,Chamber current recipe step number RecipeName=3002,DV,,False,A,,,,,Chamber recipe name ChamberName=3003,DV,,False,A,,,,,Chamber name Temperature=3004,DV,,False,F8,C,0,1000,100,Over temperature alarm threshold Pressure=3005,DV,,False,F8,mBar,0,2000,760,Over pressure alarm threshold
设备Event定义：
Associated Variable Names: 指定事件关联的Variable名称，如果关联多个Variable Names彼此间以‘|’符号进行分隔。PLC代码调用TriggerEvent方法触发Event事件，并传入关联的Variable Names和Variable Values。
按照SEMI E30 GEM标准，每个Alarm需要指定Alarm_SET事件和Alarm_CLEAR事件。因此，如果设备定义了N个Alarm，此处需要额外定义 2*N个Event事件。
[Events] ;Event ID, Event Name, Description, Associated Variable Names RecipeStarted=1001,Triggered when recipe starts,RecipeName|ChamberName RecipeCompleted=1002,Triggered when recipe succ completes,RecipeName|ChamberName RecipeStopped=1003,Triggered when recipe is stopped,RecipeName|ChamberName RecipeStepStarted=1010,Triggered when recipe step starts,RecipeName|ChamberName|StepNo RecipeStepComplete=1011,Triggered when recipe step succ completes,RecipeName|ChamberName|StepNo RecipeStepStopped=1012,Triggered when recipe step is stopped,RecipeName|ChamberName|StepNo ;Following SEMI standard, each alarm should associate with two events CHA.OverTempAlarm_SET=2001,CHA.OverTempAlarm SET event,ChamberName|Temperature CHA.OverTempAlarm_CLEAR=2002,CHA.OverTempAlarm CLEAR event,ChamberName|Temperature CHA.OverPressAlarm_SET=2003,CHA.OverPress SET event,ChamberName|Pressure CHA.OverPressAlarm_CLEAR=2004,CHA.OverPress CLEAR event,ChamberName|Pressure CHB.OverTempAlarm_SET=3001,CHB.OverTempAlarm SET event,ChamberName|Temperature CHB.OverTempAlarm_CLEAR=3002,CHB.OverTempAlarm CLEAR event,ChamberName|Temperature CHB.OverPressAlarm_SET=3003,CHB.OverPress SET event,ChamberName|Pressure CHB.OverPressAlarm_CLEAR=3004,CHB.OverPress CLEAR event,ChamberName|Pressure
设备Alarm定义：
Alarm Code：报警代码，如果不确定当前报警指定哪一个报警代码，默认使用0 NotUsed
0 = Not used,
1 = Personal safety,
2 = Equipment safety,
3 = Parameter control warning,
4 = Parameter control error,
5 = Irrecoverable error,
6 = Equipment status warning,
7 = Attention flags,
8 = Data integrity,
8+ = Other categories
PLC代码调用AlarmSET和AlarmCLEAR方法分别对指定的Alarm进行置位和复位操作。
按照SEMI E30 GEM标准，每个Alarm需要指定Alarm_SET事件和Alarm_CLEAR事件名称。因此，在定义Alarm之前需提前定义Alarm关联的Event。
按照SEMI E30 GEM标准，当某个Alarm已经处于Active状态下，PLC代码再次对该Alarm调用AlarmSET操作，不会再次触发S5F1消息发送工厂。
[Alarms] ;Alarm ID, Alarm Name, Alarm Text, Alarm Code, SetEventName, ClearEventName, Description ;Alarm Code: 0 = Not used, 1 = Personal safety, 2 = Equipment safety, 3 = Parameter control warning, 4 = Parameter control error, 5 = Irrecoverable error, 6 = Equipment status warning, 7 = Attention flags, 8 = Data integrity, >8 = Other categories CHA.OverTempAlarm=101,CHA over temperature alarm,2,CHA.OverTempAlarm_SET,CHA.OverTempAlarm_CLEAR,Chamber A over temperaure alarm CHA.OverPressAlarm=102,CHA over pressure alarm,2,CHA.OverPressAlarm_SET,CHA.OverPressAlarm_CLEAR,Chamber A over pressure alarm CHB.OverTempAlarm=201,CHB over temperature alarm,2,CHB.OverTempAlarm_SET,CHB.OverTempAlarm_CLEAR,Chamber B over temperaure alarm CHB.OverPressAlarm=202,CHB over pressure alarm,2,CHB.OverPressAlarm_SET,CHB.OverPressAlarm_CLEAR,Chamber B over pressure alarm
设备Remote Command定义：
Remote Command Name: 远程指令名称，SEMI常见的远程指令有：PP-SELECT, START, STOP, ABORT。 通常工厂通过S2F41消息传递远程指令名，以及远程指令参数。
- Trigger Symbol Name: 指定PLC收到远程指令的标识变量，该变量必须为BOOL类型，当上位机TwinCAT.GEM.exe收到来自工厂主机的远程指令后，会将该变量写为True并维持至少2个PLC扫描周期，然后将该变量写为False，确保PLC能接收到远程指令到达通知。
- P1~P10 Symbol Name: 这10个参数都是STRING类型，可以为空不指定，当设备收到的远程指令包括一个或多个参数时，上位机将按照参数次序分别将参数值转换为STRING值依次写入到P1~P10这10个指定的变量中。
只有当设备处于Online Remote和Communicating状态下，PLC才能接收并处理来自工厂主机的远程操作指令。
[RemoteCommands] ;Remote command name, Trigger symbol name,P1 symbol name,P2 symbol name,P3 symbol name,P4 symbol name,P5 symbol name,P6 symbol name,P7 symbol name,P8 symbol name,P9 symbol name,P10 symbol name RCMD1=PP-SELECT,HandleRemoteCommand.RemoteCommandArrival,HandleRemoteCommand.RemoteCommandName,HandleRemoteCommand.P1,HandleRemoteCommand.P2,,,,,,,, RCMD2=START,HandleRemoteCommand.RemoteCommandArrival,HandleRemoteCommand.RemoteCommandName,HandleRemoteCommand.P1,HandleRemoteCommand.P2,,,,,,,, RCMD3=STOP,HandleRemoteCommand.RemoteCommandArrival,HandleRemoteCommand.RemoteCommandName,HandleRemoteCommand.P1,HandleRemoteCommand.P2,,,,,,,,
设备Terminal Message定义：
Terminal ID: 指定PLC所在终端的编号，例如：0，1，2等
- PLC variable to indicate a new message arrival：指定PLC变量用户接收新的终端消息到达通知，该变量必须为BOOL类型 +Variable of received terminal message content : 指定接收到来自工厂的终端消息在PLC上的存储变量名，该变量必须为STRING类型
[TerminalRequest] ;Terminal ID,PLC variable to indicate a new message arrival, variable of received terminal message content TID=0,Main.TerminalMessageReceivedFlag,Main.ReceivedTerminalMessage
4.2 AlarmSET¶
调用该方法通知工厂指定报警被触发，当指定Alarm处于Enable状态情况下，PLC上调用该方法会触发TwinCAT.exe发送S5F1消息通知工厂。
PLC示例代码：
FA.GEM.AlarmSET('CHA.OverTemp', 'Over temperature alarm', 'ChamberName|Temperature', 'CHA|123.45');
4.3 AlarmCLEAR¶
调用该方法通知工厂指定报警已被清除（复位），当指定Alarm处于Enable状态情况下，PLC上调用该方法会触发TwinCAT.exe发送S5F1消息通知工厂。
PLC示例代码：
FA.GEM.AlarmCLEAR('CHA.OverTemp', 'Over temperature alarm', 'ChamberName|Temperature', 'CHA|25.1');
4.4 EnableAllAlarms¶
启用机台定义的所有Alarms，机台恢复向工厂上报报警信息。
PLC示例代码：
FA.GEM.EnableAllAlarms();
4.5 DisableAllAlarms¶
禁用机台定义的所有Alarms，机台不再向工厂上报报警信息。
PLC示例代码：
FA.GEM.DisableAllAlarms();
4.6 EnableAllEvents¶
启用机台定义的所有Events，机台恢复向工厂上报事件信息。
PLC示例代码：
FA.GEM.EnableAllEvents();
4.7 DisableAllEvents¶
禁用机台定义的所有Events，机台不再向工厂上报事件信息。
PLC示例代码：
FA.GEM.DisableAllEvents();
4.8 GEMEnable¶
启用SECS/GEM通信，机台恢复与工厂主机的通信。
PLC示例代码：
FA.GEM.GEMEnable();
4.9 GEMDisable¶
禁用SECS/GEM通信，机台和工厂主机的通信被关闭。
PLC示例代码：
FA.GEM.GEMDisable();
4.10 Offline¶
切换设备SECS/GEM Control state到 Offline（离线）状态，在该状态下设备和工厂不再进行数据通信。
PLC示例代码：
FA.GEM.Offline();
4.11 OnlineLocal¶
切换设备SECS/GEM Control state到 OnlineLocal（本地在线）状态，在该状态下设备和工厂可以进行数据通信，工厂可以从设备抓取数据，接收事件和报警，但是不能对设备进行远程操作。
PLC示例代码：
FA.GEM.OnlineLocal();
4.12 OnlineRemote¶
切换设备SECS/GEM Control state到 OnlineRemote（远程在线）状态，在该状态下设备和工厂可以进行数据通信，工厂不仅可以从设备抓取数据，接收事件和报警，并且可以对设备进行远程操作。
PLC示例代码：
FA.GEM.OnlineRemote();
4.13 GetProcessState¶
获取当前设备运行的状态，返回的枚举值定义见下面表格：
| Name | Type | Value | Comment |
|---|---|---|---|
| NotInitialized | INT | 0 | Equipment is in Not Initialized state. |
| Initializing | INT | 1 | Equipment is in Initializing state. |
| Idle | INT | 2 | Equipment is in Idle state. |
| Setup | INT | 3 | Equipment is in Setup state. |
| Ready | INT | 4 | Equipment is in Ready state. |
| Executing | INT | 5 | Equipment is in recipe processing state. |
| Paused | INT | 6 | Equipment is in processing paused state. |
| Aborting | INT | 7 | Equipment is in operation aborting state. |
4.14 SetProcessState¶
State : enumProcessState （枚举定义见上面表格）
PLC调用该接口通知工厂设备运行状态发生改变。
PLC示例代码：
当设备切换到Executing状态是调用以下代码：
FA.GEM.SetProcessState(enumProcessState.Executing);
4.15 PurgeSpooledMessage¶
当Spooling功能启用，并且设备和工厂断线后暂存一定数量的消息，当设备恢复和工厂主机通信后，PLC调用该方法将暂存的消息丢弃操作。
PLC示例代码：
FA.GEM.PurgeSpooledMessage();
4.16 SetValue¶
PLC调用该方法对指定的Variable进行赋值操作，该操作针对SV，DV，EC三类Variable均有效。
注意：
A、 当SECS/GEM初始化的时候如果某个Variable已经指定了对应的PLC变量符号名，TwinCAT.exe程序会主动通过ADS通信获取PLC变量值并更新对应的GEM Variable Value。
B、 为了便于PLC上对不同数据类型的SetValue操作，所有传入的Value值需转换为STRING类型传入。
PLC示例代码：
(*PLC更新CHA的温度变量值*)
FA.GEM.SetValue('CHA.Temperature', '56.78');
4.17 TerminalRequest¶
PLC调用该方法将传入的Message字符串通过Terminal Request的SECS消息发送给工厂主机。
PLC示例代码：
(*PLC发送Hello, world! 消息给工厂主机*)
FA.GEM.TerminalRequest('Hello, world!');
4.18 TriggerEvent¶
PLC调用该方法触发指定的Event消息，当Event消息处于启用状态时，TwinCAT.GEM.exe通过S6F11消息将事件通知给工厂主机。
PLC示例代码：
(*PLC触发RecipeStarted事件，通知工厂 CHA 工艺程序 ABC.rcp 开始执行*)
FA.GEM.TriggerEvent('RecipeStarted', 'RecipeName|ChamberName', 'ABC.rcp|CHA‘));
5. SECS/GEM代码集成代码编写¶
SECS/GEM代码集成完全基于TwinCAT ST编程完成，以下链接是基于PLC ST库进行SECS/GEM开发的示例项目文件：
https://project.kxware.com/attachments/download/3597/PlcSample.zip
