TwinCAT Community Libraries Reference

Version: 2026.01 | TwinCAT: 3.1 Build 4024.65+ / 4026+

Overview

整合 Beckhoff USA Community 與 Loupe Team 的開源函式庫，提供 TwinCAT 3 機台開發的完整框架參考：

庫名稱	組織	用途	架構層級
SPT-Libraries	Beckhoff USA	PackML 機台控制框架	Layer 3
AAG_TwinSAFE_XML	Beckhoff USA	TwinSAFE 安全邏輯 XML 產生器	Layer 1
CSVFileLib	Loupe Team	CSV 配方/設定檔格式概念	Layer 4
Omniverse_Beckhoff_Bridge	Loupe Team	Omniverse/Isaac Sim ADS 橋接	Layer 6

Architecture Layers

code

[Layer 6] Omniverse / Isaac Sim 4.5
          └── Omniverse_Beckhoff_Bridge_Extension (ADS ↔ USD 橋接)

[Layer 5] ADS Interface / 外部 UI
          └── GVL 結構：軸狀態、安全狀態、配方、測試結果

[Layer 4] Config / Recipe / TestCase
          └── CSVFileLib 概念 (VariableName, Value, Description)

[Layer 3] SPT-Libraries 機台框架
          └── Machine / Unit / PackML 狀態機

[Layer 2] TwinCAT PLC / Motion 核心
          └── Task_AxisCtrl (1ms) + Task_SafetyMon (4ms)

[Layer 1] TwinSAFE 專案
          └── AAG_TwinSAFE_XML → EL6900 / EL1904 / EL2904

[Layer 0] 現場硬體 / 電控箱
          └── C6030, EtherCAT, HIWIN E1, GL-V 光柵, EMG

1. SPT-Libraries (機台框架)

GitHub: https://github.com/Beckhoff-USA-Community/SPT-Libraries

核心功能

•PackML 狀態機：Idle → Starting → Execute → Complete → Stopping
•UnitModeManager：Automatic / Manual / Maintenance 模式切換
•Machine/Unit/Module 架構：標準化機台控制結構

版本對應

SPT 版本	TwinCAT 版本	PackML 版本
V3.x	3.1.4024.x	V2
V4.0+	3.1.4026+	V3

基本使用

iecst

VAR
    fbStateMachine : FB_PML_StateMachine;
    eCommand       : E_PMLCommand;
    eState         : E_PMLState;
END_VAR

fbStateMachine(eMode := eMode, eCommand := eCommand);
eState := fbStateMachine.eState;

CASE eState OF
    E_PMLState.Idle:     // 等待 Start 命令
    E_PMLState.Starting: // 啟動流程
    E_PMLState.Execute:  // 執行運動
    E_PMLState.Complete: // 完成
END_CASE;

與安全系統整合

iecst

bMachineSafeOK := bSafe_ESTOP = FALSE
              AND bSafe_LightCurtain = FALSE
              AND bSafe_EnableDrives = TRUE;

IF NOT bMachineSafeOK THEN
    eCommand := E_PMLCommand.Abort;
END_IF

2. AAG_TwinSAFE_XML (安全系統)

GitHub: https://github.com/Beckhoff-USA-Community/AAG_TwinSAFE_XML

功能

Excel + VBA 工具，使用 3×3 Grid 視覺化設計 Sensor → Actor 映射，自動產生 TwinSAFE XML。

設計流程

•

Excel Grid 設計：

code

           | Actor1 (K1) | Actor2 (K2) |
-----------+-------------+-------------+
Sensor1    |     ✓       |     ✓       |  EMG_Button
Sensor2    |             |     ✓       |  LightCurtain

•
產生 XML：點擊 VBA 按鈕
•
匯入 TwinCAT：
- •TwinSAFE Editor → Import XML
- •對應 S-Addr：EL6900=1, EL1904=2, EL2904=3
- •編譯 → Download 到 EL6900

典型配置

Sensor	I/O	Actor	I/O
EMG_Button	EL1904 CH1	K1_MainEMG	EL2904 O1
LightCurtain	EL1904 CH4	K2_AxisEMG	EL2904 O2

3. CSVFileLib (配方管理概念)

GitHub: https://github.com/loupeteam/CSVFileLib

注意

此庫原生為 B&R Automation Runtime，無法直接在 TwinCAT 編譯。應使用其「設計理念」，以 Tc2_Utilities 實作類似功能。

CSV 格式

csv

//Variable Name, Value, Optional Description
stConfigMotion.Accel_mm_s2,  5000,  直線加速度
stConfigMotion.MaxVel_mm_s, 10000,  最高速度
stTestCase[1].Mode,         3,      相對運動
stTestCase[1].Travel_mm,    800,    等速段長度

TwinCAT 實作

iecst

TYPE ST_MotorParam :
STRUCT
    AxisID          : INT;
    AxisName        : STRING(20);
    MaxSpeed_mps    : LREAL;
    Accel_mps2      : LREAL;
    HomeOffset_mm   : LREAL;
    PosLimitPos_mm  : LREAL;
    PosLimitNeg_mm  : LREAL;
END_STRUCT
END_TYPE

// 從 CSV 載入
aFields := F_CSV_SplitLine(sLine);
stMotorParam[i].MaxSpeed_mps := STRING_TO_LREAL(aFields[3]);

應用場景

•運動參數配方：速度、加速度、位置極限
•測試案例定義：測試模式、起始位置、觸發條件
•安全 I/O 設定表：通道名稱、功能映射

4. Omniverse_Beckhoff_Bridge (數位孿生)

GitHub: https://github.com/loupeteam/Omniverse_Beckhoff_Bridge_Extension

功能

NVIDIA Omniverse Extension，使用 pyads 建立 ADS 通訊，將 PLC 變數映射到 USD 場景。

連線設定

python

import pyads

plc = pyads.Connection("192.168.1.60.1.1", 851, "192.168.1.60")
plc.open()

# 讀取軸位置
pos_x1 = plc.read_by_name("gvlAxis.stAxisX1.fActualPos_mm", pyads.PLCTYPE_LREAL)

# 更新 USD 場景
prim.GetAttribute("xformOp:translate").Set(Gf.Vec3d(pos_x1, 0, 0))

ADS Symbol 映射

code

gvlAxis.stAxisX1.fActualPos_mm  →  /World/LinearStage/X1.position
gvlAxis.stAxisX2.fActualPos_mm  →  /World/LinearStage/X2.position
gvlSafe.bSafe_ESTOP             →  /World/Indicators/EStopLight.emissive

Isaac Sim 整合

•開啟 Isaac Sim 4.5
•Extensions → 啟用 loupe.simulation.beckhoff_bridge
•設定 AMS NetId 與 IP
•定義 Symbol → USD 屬性映射

Integration Example: 雙軸高速滑台

系統架構

code

┌─────────────────────────────────────────────────────┐
│                    Isaac Sim 4.5                    │
│  ┌─────────────────────────────────────────────┐   │
│  │     Omniverse_Beckhoff_Bridge_Extension     │   │
│  └─────────────────────┬───────────────────────┘   │
└────────────────────────┼───────────────────────────┘
                         │ ADS
┌────────────────────────┼───────────────────────────┐
│                 C6030 IPC                          │
│  ┌─────────────────────┴───────────────────────┐   │
│  │              TwinCAT Runtime                │   │
│  │  ┌─────────────┐  ┌─────────────────────┐   │   │
│  │  │ SPT-Machine │  │    TwinSAFE (FSoE)  │   │   │
│  │  │  PackML SM  │  │  AAG XML → EL6900   │   │   │
│  │  └──────┬──────┘  └──────────┬──────────┘   │   │
│  │         │                    │              │   │
│  │  ┌──────┴────────────────────┴──────────┐   │   │
│  │  │         Motion Control (CSP)         │   │   │
│  │  │   CSV Config → Axis Parameters       │   │   │
│  │  └──────────────────┬───────────────────┘   │   │
│  └─────────────────────┼───────────────────────┘   │
└────────────────────────┼───────────────────────────┘
                         │ EtherCAT
┌────────────────────────┼───────────────────────────┐
│  HIWIN E1 #1  │  HIWIN E1 #2  │  EL1904  │  EL2904 │
└───────────────┴───────────────┴──────────┴─────────┘

實作順序

•Layer 1：用 AAG_TwinSAFE_XML 產生安全邏輯 XML
•Layer 2：建立最小 PLC 專案（單軸 CSP + 軟體限位）
•Layer 3：導入 SPT-Libraries 作為機台層
•Layer 4：加入 CSV Config / TestCase 概念
•Layer 6：導入 Omniverse_Beckhoff_Bridge + Isaac Sim

GitHub Sources

•SPT-Libraries: https://github.com/Beckhoff-USA-Community/SPT-Libraries
•AAG_TwinSAFE_XML: https://github.com/Beckhoff-USA-Community/AAG_TwinSAFE_XML
•CSVFileLib: https://github.com/loupeteam/CSVFileLib
•Omniverse_Beckhoff_Bridge: https://github.com/loupeteam/Omniverse_Beckhoff_Bridge_Extension

Available References

詳細參考資料位於 references/ 目錄：

檔案	內容
`spt-libraries.md`	SPT 框架詳細說明、程式碼範例
`aag-twinsafe-xml.md`	TwinSAFE XML 工具使用流程
`csvfilelib.md`	CSV 配方格式與 TwinCAT 實作
`omniverse-beckhoff-bridge.md`	Omniverse ADS 橋接設定
`framework-integration.md`	四個框架整合分析（原始文件）

Quick Reference

SPT 狀態機狀態

狀態	說明
Idle	等待命令
Starting	啟動中
Execute	執行中
Complete	完成
Stopping	停止中
Aborting	中止中

CSV 格式範例

csv

AxisID,AxisName,MaxSpeed_mps,Accel_mps2,HomeOffset_mm
1,X_Master,10.0,50.0,0.0
2,X_Slave,10.0,50.0,0.0

ADS 讀取範例

python

import pyads
plc = pyads.Connection("192.168.1.60.1.1", 851)
plc.open()
pos = plc.read_by_name("gvlAxis.stAxisX1.fActualPos_mm", pyads.PLCTYPE_LREAL)