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

目錄1. 軟硬件版本 31.1. 控制硬件 31.2. 控制軟件 32. 基本概念和介紹 33. 編輯自定義事件 54. 導出自定義事件 75. 基于系統庫文件Tc3_Eventlogger二次開發的配套應用庫文件EventloggerApplication.lib 95.1. 通用事件處理的對象接口/功能塊：I_EventLoggerHanding、FB_EventloggerHandlingBase/Extend 115.2. 過濾事件功能塊FB_EventFilter 135.3. 跨PLC監聽功能塊FB_EventListner 145.4. 導出日志功能塊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. 過濾器設置 226.12. 導出CSV功能 246.13. 導出設置功能塊FB_TcEventCsvExportSettings 246.14. 方法FB_TcEventLogger.ExportLoggedEvents 247. 模擬現場Demo：TwinCATEventloggerApplicationExmaple 268. 常見問題 29

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

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

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

完成保存之后，在其路徑下的TMC文件，就可以以現有項的方式通過路徑添加到其他的項目里去了：在PLC項目下的ExternalTypes文件夾右鍵pin，在輸入助手里將對應的枚舉體和結構體都導入即可：

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

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

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

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

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

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

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

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

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

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

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

S_OK。如果報警已經處于

Raised

狀態，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

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

S_OK。如果報警不處于

Raised

狀態，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

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

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

S_OK。如果確認狀態不是

WaitConfirmation，則返回

ADS_E_INVALIDSTATE。否則返回

HRESULT

作為錯誤碼。代碼樣例：

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

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

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

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