TwinCAT3 Eventlogger詳解與使用方法

第頁TwinCAT3Eventlogger詳解與使用方法TwinCAT3Eventlogger詳解與使用方法作者：余洋職務(wù)：技術(shù)支持工程師公司：BECKHOFF中國郵箱：yang.yu@日期：2024-4-2摘要：Eventlogger一直是TwinCAT當(dāng)中處理報警的對象，它可以很好地幫主用戶記錄、監(jiān)控自定義的報警事件。不過老版本的Eventlogger缺乏詳細(xì)地使用文檔，且需要通過XML文件編輯事件，一定程度上，不算特別方便。4026之后，TwinCAT3Eventlogger將會全面代替TwinCATEventlogger，他有著易于編輯，高靈活性和高自由度的特點。本文檔將對TwinCAT3Eventlogger進(jìn)行詳解并介紹它的使用方法（PLC實現(xiàn)）。由于TwinCAT3Eventlogger與傳統(tǒng)的功能塊大相徑庭，因此提供了一個基于原始庫二次開發(fā)的應(yīng)用庫文件以方便熟悉傳統(tǒng)功能塊的用戶使用。（注：如章節(jié)6閱讀起來比較困難，可以忽略）附件：序號文件名備注1.TwinCATEventloggerApplicationExmaple例程2.EventloggerApplication庫文件歷史版本：免責(zé)聲明：我們已對本文檔描述的內(nèi)容做測試。但是差錯在所難免，無法保證絕對正確并完全滿足您的使用需求。本文檔的內(nèi)容可能隨時更新，如有改動，恕不事先通知，也歡迎您提出改進(jìn)建議。參考信息：

目錄1. 軟硬件版本 31.1. 控制硬件 31.2. 控制軟件 32. 基本概念和介紹 33. 編輯自定義事件 54. 導(dǎo)出自定義事件 75. 基于系統(tǒng)庫文件Tc3_Eventlogger二次開發(fā)的配套應(yīng)用庫文件EventloggerApplication.lib 95.1. 通用事件處理的對象接口/功能塊：I_EventLoggerHanding、FB_EventloggerHandlingBase/Extend 115.2. 過濾事件功能塊FB_EventFilter 135.3. 跨PLC監(jiān)聽功能塊FB_EventListner 145.4. 導(dǎo)出日志功能塊FB_EventExporter 156. 原始庫文件Tc3_Eventlogger 166.1. 報警功能塊FB_TcAlarm 166.2. FB_TcAlarm.CreateEx/Create 166.3. FB_TcAlarm.Raise 186.4. FB_TcAlarm.Clear 186.5. FB_TcAlarm.Confirm 196.6. 消息功能塊FB_TcMessage 206.7. .FB_TcMessage.Create/CreateEx 206.8. FB_TcMessage.Send 216.9. 過濾器FB_TcEventFilter 226.10. FB_TcEventFiler.Clear 226.11. 過濾器設(shè)置 226.12. 導(dǎo)出CSV功能 246.13. 導(dǎo)出設(shè)置功能塊FB_TcEventCsvExportSettings 246.14. 方法FB_TcEventLogger.ExportLoggedEvents 247. 模擬現(xiàn)場Demo：TwinCATEventloggerApplicationExmaple 268. 常見問題 29

軟硬件版本控制硬件測試電腦（Windows11專業(yè)版）控制軟件TwinCAT3（文檔測試版本為v3.1.4024.54）、庫文件Tc3_Eventlogger（庫文件版本為v）、庫文件EventloggerApplication（庫文件版本為v）?；靖拍詈徒榻B與傳統(tǒng)的PLCFunctions不同的是，TwinCAT3Eventlogger可以理解為存在于TwinCAT3當(dāng)中的一個對象。這個對象可以管理，監(jiān)控并記錄所有的TwinCAT事件（系統(tǒng)事件、EtherCAT事件、自定義事件等等）。該文檔是通過PLC中的庫文件Tc3_Eventlogger對它進(jìn)行訪問交互的。它不僅僅可以通過PLC功能塊去實現(xiàn)，還可以通過高級語言如C#、C++中的API去訪問管理，在TwinCATHMI當(dāng)中也有成熟的控件進(jìn)行記錄（詳情見TwinCATHMIEventGird和Line控件的使用方法）： 事件分為兩大類，分別是消息和報警。消息類對應(yīng)的事件等級分別是Verbose和Info；報警類對應(yīng)的事件等級分別是Warning、Error以及Critical。兩種類別的事件處理方式有所不同。消息類只有發(fā)送，而報警類則有升起、清除和確認(rèn)。報警類事件的狀態(tài)切換如圖所示：

編輯自定義事件既然TwinCAT3Eventlogger管理的目標(biāo)是各種事件。TwinCAT本身無疑會有各種事件、比如編譯器報錯，警報等等。除此之外，EtherCAT總線、軸的事件也都包含在內(nèi)。當(dāng)然，更重要的是應(yīng)對各種工藝以及用戶的自定義事件，那么編輯創(chuàng)建自己的事件是才是最重要的關(guān)鍵之一。新版本的TwinCAT3Eventlogger是通過TMC編輯器在TwinCAT運行環(huán)境中創(chuàng)建報警條目的：（1）找到TwinCAT項目中的System——TypeSystem——EventClass，右鍵空白處：（2）下一步是在TMC編輯器里面自定義事件內(nèi)容，首先修改事件名，這個可以根據(jù)自己的想法隨意修改：（3）在此事件中，可以新增各種子事件，默認(rèn)情況會自帶一個，點擊Events可以新增或者刪除事件：（3）在子事件中，可以修改事件名，修改事件等級和顯示的事件內(nèi)容：完成所有的自定義設(shè)置之后，便可關(guān)閉TMC編輯器，選擇TwinCAT中的SaveAll即可。這樣一來，自定義TwinCAT事件的步驟就完成了

注：事件屬性的介紹：GUID：每個事件都?xì)w屬于一個特定的類別，這個類別由一個全局唯一標(biāo)識符（GUID）表示。這有助于在TwinCAT3項目中對不同類型的事件進(jìn)行分類和管理。nEventID：這是每個事件的唯一標(biāo)識符，用于區(qū)分同一類別下的不同事件。它是一個無符號的雙整型數(shù)字，提供足夠的空間來定義大量的事件ID。eSeverity：這定義了事件的嚴(yán)重性級別。在TwinCAT中，不同的嚴(yán)重性級別（如警告、錯誤、重要等）允許用戶根據(jù)報警的重要程度做出相應(yīng)的響應(yīng)。導(dǎo)出自定義事件如果自定義事件無法導(dǎo)出，那它的重復(fù)利用性就很低。TwinCAT3Eventlogger支持將項目中編輯的自定義事件通過TMC文件的方式導(dǎo)出，這樣一來，可以用在其他的項目中。也避免了，庫文件引用上的丟失。導(dǎo)出的流程如下：右鍵TypeSystem新建一個TMC文件（路徑最好選擇默認(rèn)）：

完成保存之后，在其路徑下的TMC文件，就可以以現(xiàn)有項的方式通過路徑添加到其他的項目里去了：在PLC項目下的ExternalTypes文件夾右鍵pin，在輸入助手里將對應(yīng)的枚舉體和結(jié)構(gòu)體都導(dǎo)入即可：

基于系統(tǒng)庫文件Tc3_Eventlogger二次開發(fā)的配套應(yīng)用庫文件EventloggerApplication.lib由于原始庫文件Tc3_Eventlogger當(dāng)中的API是通過功能塊、方法、接口和指針進(jìn)行交互的，如果沒有面向?qū)ο蟮木幊碳记?，使用起來難度比較大。因此，本文檔配套提供了一個基于原始庫二次開發(fā)的應(yīng)用庫文件EventloggerApplication.lib。該庫文件里面有通過輸入輸出引腳處理操作報警，消息事件的接口以及功能塊（I_EventLoggerHanding、FB_EventloggerHandlingBase/Extend9.1)、跨PLC項目監(jiān)聽全局事件的功能塊（FB_EventListner）以及導(dǎo)出日志功能塊FB_EventExporter。方便使用傳統(tǒng)的輸入輸出功能塊編寫程序的工程師使用。該庫以及系統(tǒng)庫對TwinCATEventlogger操作的流程原理如下：

庫文件免責(zé)聲明：使用此版本的庫是免費的?？蛻粲胸?zé)任檢查并決定該庫和提供的功能是否適用于他的特定應(yīng)用。該庫按原樣提供，既不是TwinCAT3的一部分，也不是Beckhoff

Automation直接支持的。使用該庫是客戶自己的風(fēng)險。不保證該庫和與該庫一起提供的源代碼是完整或準(zhǔn)確的。在任何情況下，作者或Beckhoff

Automation對由于使用該庫而引起的錯誤和/或遺漏不負(fù)任何索賠、損害或其他責(zé)任。不能指望對該庫的維護(hù)、支持、增強或修改，以及對該庫或TwinCAT3的更新或與庫的更新兼容性的期望權(quán)。如有反饋或問題，請聯(lián)系yang.yu@。倍福中國或庫文件作者未經(jīng)明確授權(quán)，禁止復(fù)制、分發(fā)和利用此庫或其部分，以及向他人傳達(dá)其內(nèi)容，對其進(jìn)行未經(jīng)授權(quán)的傳播將受到追究賠償責(zé)任。在授予專利、實用新型或設(shè)計的情況下，保留所有權(quán)利。

通用事件處理的對象接口/功能塊：I_EventLoggerHanding、FB_EventloggerHandlingBase/Extend三者都是對事件對象（無所謂Alarm還是Message類型的事件）進(jìn)行處理。FB_EventloggerHandlingBase實現(xiàn)了接口I_EventloggerHandling；而FB_EventloggerExtend則拓展了Base。Base是通過功能塊其下的方法對報警/消息的實例進(jìn)行處理。功能塊本身內(nèi)部不含有調(diào)用方法的代碼。而Extend則在Base的基礎(chǔ)之上，改造成傳統(tǒng)功能塊的格式，通過其輸入引腳對事件進(jìn)行觸發(fā)，清除等操作，功能塊內(nèi)部有全自動的代碼邏輯去實現(xiàn)方法，所以更推薦使用Extend。功能塊的引腳說明在庫文件中都有詳細(xì)的注釋。使用時，必須在功能塊聲明實例化之后輸入處理的Event對象（變量聲明區(qū)樣例代碼：FB_EventloggerHandlingProductionInfo:FB_EventloggerHandlingExtend（TC_Events.MyEvent.Event1））。建議一個功能塊實例僅處理一個事件對象。如果是消息類型的事件，bMessage是必填的輸入引腳；反之如果是報警類型的事件，bAlarm和bClear是必填的輸入引腳。而bConfirm則是根據(jù)屬性P_bEnableConfirmation（見5.2或者第二章報警事件狀態(tài)切換的流程圖）開啟報警確認(rèn)的功能之后填入。在庫版本中，加了一個屬性P_TextPrefix，該屬性可以對源消息進(jìn)行增加內(nèi)容的操作：比如在TMC文件中有一個溫度報警事件，它觸發(fā)時會報錯“TempError”，但如果在項目中，僅僅提示溫度報錯，很難定位到具體的工件或者工位區(qū)域。因此可以通過這個屬性在報錯內(nèi)容的前面加新的內(nèi)容，比如“Channel1：TempError”，通過這個屬性可以靈活地配置或者調(diào)整源事件。同理，在庫版本中，加了一個屬性P_TextSuffix，該屬性可以對消息后綴進(jìn)行增加內(nèi)容的操作，比如“Channel1：TempError（Over5degrees!）”功能塊以及接口的原理流程如下：

FB_EventloggerHandlingBase（只有輸出，需要調(diào)用其下的方法，無法自動處理事件）：FB_EventloggerHandlingExtend（有輸入，有輸出，可以根據(jù)輸入自動處理事件）：（注：bConfirm需要在屬性P_bEnableConfirmation為TRUE的時候才會被啟用）

過濾事件功能塊FB_EventFilter該功能塊可以對事件進(jìn)行過濾，改過濾功能塊暫時并沒有過濾出EtherCAT類型消息的功能，可以通過輸入引腳Option對過濾的事件進(jìn)行篩選（注：該功能塊在5.3/5.4監(jiān)聽或者導(dǎo)出功能塊中會被內(nèi)部引用，所以在項目中無需單獨調(diào)用）：Option中每一位的含義如下：

跨PLC監(jiān)聽功能塊FB_EventListner該功能塊可以對選定的事件或者所有TwinCAT3當(dāng)中產(chǎn)生的事件進(jìn)行監(jiān)聽，不僅限于當(dāng)前PLC。同時也可以監(jiān)聽到高級語言或者TwinCATHMI所發(fā)送的事件，內(nèi)部包含了一個篩選器功能塊（5.1）：監(jiān)聽器的工作原理如下：自定義過濾器：由于庫文件里的過濾器并不包含所有的功能，如果用戶需要自己去編寫新的過濾器功能塊的話，可以先通過Extends拓展FB_EventFilter，如：FB_EventCustomFilter。接著在主程序當(dāng)中調(diào)用監(jiān)聽器的方法Listener.AppendCustomerFilter(FB_EventCustomFilter);即可使用自定義的監(jiān)聽過濾功能。

導(dǎo)出日志功能塊FB_EventExporter該功能塊可以對選定的事件或者所有的事件進(jìn)行導(dǎo)出，內(nèi)部包含了一個原始庫文件Tc3_Eventlogger中的功能塊FB_TcEventlogger和一個篩選器功能塊（5.1）：導(dǎo)出日志功能塊的原理：自定義過濾器：由于庫文件里的過濾器并不包含所有的功能，如果用戶需要自己去編寫新的過濾器功能塊的話，可以先通過Extends拓展FB_EventFilter，如：FB_EventCustomFilter。接著在主程序當(dāng)中調(diào)用監(jiān)聽器的方法Exporter.AppendCustomerFilter(FB_EventCustomFilter);即可使用自定義的導(dǎo)出過濾功能。

原始庫文件Tc3_Eventlogger報警功能塊FB_TcAlarm報警功能是通過庫文件中的功能塊FB_TcAlarm實現(xiàn)的。FB_TcAlarm實例代表了TwinCAT3Eventlogger中處理報警的對象。由于改功能塊拓展了FB_TcEventBase，因此有一些方法是繼承下來的。我們用的更多的則是它獨有的方法：FB_TcAlarm.CreateEx/Create該方法用于在Eventlogger中創(chuàng)建一個報警事件的實例。兩種方法分別通過兩種方式創(chuàng)建報警事件：CreateEx：該方法的第一個輸入引腳就是事件對象。改結(jié)構(gòu)體可以通過PLC的ExternalTypes導(dǎo)入，非常方便。除了創(chuàng)建的事件對象之外，改方法還有兩個輸入變量bWithConfirmation和ipSourceInfo。前者代表該條報警是否啟用確認(rèn)的功能，后者則是一個可選項，指向I_TcSourceInfo類型的接口指針。采用接口指針指向某個事件源是一種更加高級的方式，一般來說，大多數(shù)應(yīng)用都還是基于EventClass、nEventId以及eSeverity三者去進(jìn)行事件的指定。因此，在ipSourceInfo中，填寫0不作消息源關(guān)聯(lián)即可。填寫改接口實現(xiàn)的實例FB_TcSourceInfo可以對已經(jīng)有的事件對象作更改。打個比方：我有一個溫度報警事件，它觸發(fā)時會報錯“TempError”，然后我可以通過這個接口的實現(xiàn)也就是這個功能塊fb_TcSourceInfo的實例，在報錯內(nèi)容的前面加新的內(nèi)容，比如“Channel1：TempError”，通過這個接口可以靈活地配置或者調(diào)整源事件：Create：Create本質(zhì)上與CreateEx是一樣的，只不過將事件分割成三個屬性：EventClass、nEventId以及eSeverity。分別代表了它在TwinCAT3中的GUID、事件ID以及事件等級。這些屬性可以在TMC編輯器里看到。兩種方法中，推薦使用后者。兩者返回值的類型是HRESULT，用來判斷是否報警實例是否創(chuàng)建成功：如果成功創(chuàng)建了新報警，則返回S_OK。如果報警已經(jīng)存在，則返回ERROR_ALREADY_EXISTS。否則返回HRESULT作為錯誤代碼。代碼樣例：

FB_TcAlarm.Raise該方法用于將已經(jīng)創(chuàng)建（Create/CreateEx）的報警實例狀態(tài)切換為Raised：該方法只有一個輸入引腳nTimeStamp，代表升起報警的時間戳。如果想采用當(dāng)前默認(rèn)的系統(tǒng)時間戳，填0即可。當(dāng)然也可以使用外部時間戳。（從January1st,1601(UTC)開始算起）。如果方法調(diào)用成功，返回

S_OK。如果報警已經(jīng)處于

Raised

狀態(tài)，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

作為錯誤碼。代碼樣例：FB_TcAlarm.Clear該方法用于將已經(jīng)創(chuàng)建（Create/CreateEx）的報警實例狀態(tài)切換為NotRaised：該方除了nTimeStamp（詳情見6.3）之外，還有一個ResetConfirmation。表示在清除報警的時候，同時復(fù)位確認(rèn)標(biāo)志位，僅僅只有當(dāng)在事件的實例被創(chuàng)建時，bWithConfirmation被置為TRUE時才有意義。如果方法調(diào)用成功，返回

S_OK。如果報警不處于

Raised

狀態(tài)，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

作為錯誤碼。代碼樣例：FB_TcAlarm.Confirm該方法用于將啟用了確認(rèn)功能的事件實例狀態(tài)從

WaitingForConfirmation（等待確認(rèn)）狀態(tài)切換到Confirmed（已確認(rèn)）狀態(tài)：該方法輸入引腳和Clear一致，這里就不贅述了。如果方法調(diào)用成功，返回

S_OK。如果確認(rèn)狀態(tài)不是

WaitConfirmation，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

作為錯誤碼。代碼樣例：

消息功能塊FB_TcMessage消息功能也是通過庫文件中的功能塊FB_TcMessage實現(xiàn)的。FB_TcMessage實例代表了TwinCAT3Eventlogger中處理消息的對象。由于改功能塊也是拓展了FB_TcEventBase，我們接下來也是對它獨有的方法進(jìn)行講解：.FB_TcMessage.Create/CreateEx該方法用于在Eventlogger中創(chuàng)建一個消息事件的實例。兩種方法分別通過兩種方式創(chuàng)建消息事件：（1） Create：（2） CreateEx：用法詳見4.1，兩者如出一轍。如果方法調(diào)用成功，返回S_OK；否則返回HRESULT作為錯誤碼。代碼樣例：FB_TcMessage.Send該方法用于發(fā)送消息：輸入引腳見6.3。如果方法調(diào)用成功，返回S_OK；否則返回HRESULT作為錯誤碼。代碼樣例：

過濾器FB_TcEventFilter無論是選擇監(jiān)聽的事件，還是選擇導(dǎo)出的事件，過濾器都是非常重要的設(shè)置，通過設(shè)定過濾指定消息源，事件等級等等，可以靈活地篩選事件的實例。過濾器是通過庫文件中的FB_TcEventFliter進(jìn)行設(shè)置的。由于該功能塊的內(nèi)置方法、實現(xiàn)的接口和繼承關(guān)系非常復(fù)雜，我們僅僅解析如何通過代碼來進(jìn)行過濾器的設(shè)置FB_TcEventFiler.Clear該方法可以清除當(dāng)前的過濾器設(shè)置。代碼樣例：過濾器設(shè)置過濾器通過遵循結(jié)構(gòu)化邏輯代碼的浮動接口篩選事件：條件可以通過.AND_OP()和.OR_OP()連接。條件可以通過.NOT_OP()取反。條件可以通過方法篩選，如isAlarm()和isMeassage()、條件可以通過屬性篩選，如EventClass.EqualsTo和Severity：代碼樣例：（先清除舊的設(shè)置，只記錄等級是Critical且事件ID是EventClassID的事件）接收EtherCAT事件的機制與上述類似。方法調(diào)用的入口點是EtherCATDevice()，查詢它是否是從EtherCAT設(shè)備發(fā)送的。往后可以篩選制造商、產(chǎn)品代碼或版本：代碼樣例：（先清除舊的設(shè)置，只記錄產(chǎn)品代碼為1且修訂號為1的EtherCAT設(shè)備的事件）

導(dǎo)出CSV功能自從TwinCATv3.1.4024.17開始，TwinCAT3Eventlogger還加入了導(dǎo)出指定事件的日志功能。該功能是通過導(dǎo)出設(shè)定功能塊FB_TcEventCsvExportSettings和FB_TcEventLogger下的方法ExportLoggedEvents完成的。導(dǎo)出設(shè)置功能塊FB_TcEventCsvExportSettings該功能塊用于篩選導(dǎo)出的事件，有兩個常用的方法；Clear：用于清除先前的過濾設(shè)置AddFliter：用于添加ipEventFliter類型的接口（即FB_TcEventFliter，因為該功能塊可以實現(xiàn)此類型的接口。FB_TcEventFliter使用方法見第六章節(jié)）代碼樣例：方法FB_TcEventLogger.ExportLoggedEvents首先簡單地介紹一些FB_TcEventLogger。該功能塊代表了TwinCAT3Eventlogger本體。它內(nèi)部有一些管理事件實例的方法，如ClearAllAlarms、ConfirmAllAlarms、GetAlarm等。（詳情可以參考/content/1033/tc3_eventlogger/5002818315.html?id=6803183681524141353）導(dǎo)出的動作也是通過其下的方法ExportLoggedEvents完成的：輸入引腳有兩個，第一個是保存文件的路徑和名稱，如'c:\temp\Eventlogger-export.csv'。第二個是I_TcEventExportSettings類型的接口（即8.1FB_TcEventCsvExportSettings，因為該功能塊可以實現(xiàn)此類型的接口）輸出引腳有三個，比較簡單。ExportLoggedEvents代表是否導(dǎo)出成功。bError和hrErrorCode分別表示導(dǎo)出是否有錯誤和錯誤代碼。代碼樣例：

模擬現(xiàn)場Demo：TwinCATEventloggerApplicationExmapleDemo程序模擬了三個事件的檢測和觸發(fā)：程序啟動，上電之后延時10秒發(fā)送消息“ProcessStart！”。同時通過主程序變量bActiveSimulation模擬了一個氣缸升溫的過程，該過程純模擬，用的是TF4100里面的功能塊FB_CTRL_PT1。bActiveSimulation被置為TRUE之后，開始升溫。當(dāng)溫度超過75攝氏度之后，會發(fā)送氣缸溫度過高的報警。并通過FB_EventloggerHandlingCylinderTemp的屬性P_TextPrefix