Read the TcForge documentation site for searchable guides.
Reusable TwinCAT 3 function blocks for machine control.
Getting started · Modules · Documentation · Contributing
Foundation under development — local builds and PLC tests are running; production qualification remains open.
See Progress tracker for completed foundation work, remaining architecture gaps, and qualification tasks. Update it as work progresses.
TcForge is a library for Beckhoff PLC applications, with reusable blocks for sequencing, I/O, pneumatics, and alarms. An example application shows how the modules fit together.
| Module | What it covers |
|---|---|
| Common | Shared types, enums, validation helpers, F_Now, FB_DeviceBase (owns the fault ring + header). |
| Sequencing | State machines and sequence steps with an Entry/Execute/Exiting lifecycle, plus permissives. |
| Pneumatics | Actuator control with feedback monitoring. |
| IO | FB_DigitalInput / FB_DigitalOutput / FB_AnalogInput / FB_AnalogOutput — debounce, pulse modes, UNION-based raw terminals, scaling, IIR filter. Process-limit alarms compose externally via FB_AlarmLimit. |
| Alarms | FB_AlarmSimple / FB_AlarmThreshold / FB_AlarmLimit / FB_AlarmDeviation / FB_AlarmRateOfChange — uniform debounce / latch / ack / severity / timestamps surface via FB_AlarmBase + I_Alarm. |
- Method-centric commands. Program methods own command logic; Operator RPC wrappers queue selected commands in a bounded mailbox. The owning cyclic task validates and executes them with fixed operator identity, then applies state and output policy.
- Requester tracking. Accepted commands record source (
PROGorOPERATOR). The application owns program-only source locking. - Shared validation.
F_ValidateRequesterprovides normal source/fault gating; recovery and de-energization commands have explicit device-specific rules. - Permissive system.
FB_Permissivesevaluates mapped conditions and required-mask freshness, reporting throughsts.bOK.
The docs below cover these in detail.
TwinCAT/TcForge.sln: main development workspace: library source, Example, Testing and Simulation in one TwinCAT project.TwinCAT/TcForge.Library.sln: isolated library export.TwinCAT/TcForge.Example.sln: isolated example runtime.TwinCAT/TcForge.Tests.sln: isolated test application.TwinCAT/TcForge.Simulation.sln: isolated simulation runtime.TwinCAT/TcForge/: the reusable library.TwinCAT/TcForgeExample/: the assembly-station application, organized by area; see the example guide.TwinCAT/Testing.plcproj: PLC test project, sharing the reference application source.TwinCAT/Testing/: PLC test suites and fixtures.python/: deterministic plant simulation primitives and test infrastructure; see simulation guide.docs/: design docs.
Within TwinCAT/TcForge/POUs, source is grouped as Base (shared contracts and
mailbox), IO (raw I/O policy and channel blocks), Devices (machine actuators),
Logic (interlocks and sequencing), Alarms, and Utilities. Each feature keeps
its FB, configuration/status structures, enums, and interfaces together. The
TwinCAT project folders mirror the files on disk.
Function-block methods use TwinCAT method folders. Operator RPC contains only
the methods marked TcRpcEnable for OPC UA calls; these submit to the bounded
mailbox. Program Commands and Configuration contain the PLC-facing API, while
Protected, Private, and Internal contain implementation methods. A method's
folder changes its location in the XAE tree, not its ST access modifier or RPC
behavior.
Clone the repository and open the solution in TwinCAT XAE on Windows:
git clone https://github.com/eponce00/TcForge.git
cd TcForgeOpen TwinCAT/TcForge.sln in XAE 3.1.4026.26. Under PLC,
expand TcForge → TcForge Project to edit the reusable blocks. Example, Testing
and Simulation reference [TcForge] directly. Library edits are available to
their next build without exporting, installing or changing the version. The
TcForgeExample project also enables source-library use: Testing and Simulation
reference its block definitions directly. Application code has one owner, with no
separate support library.
python scripts/check_repository.py
powershell.exe -NoProfile -File scripts/build_development.ps1
powershell.exe -NoProfile -File scripts/run_tcunit.ps1 -Development -Target <bench-AMS-Net-ID> -Platform "TwinCAT RT (x64)"The development build does not activate a runtime. The test command replaces the selected bench configuration with the isolated Testing runtime, builds from source, and verifies individual TcUnit results. Example and Simulation are separate PLC applications with separate instances; changes are applied to each application through its own build/login workflow. Simply saving source does not change a running PLC. The combined workspace does not autostart the test/simulation tasks; use the isolated scripts when deploying one application.
scripts/build_twincat.ps1 and run_tcunit.ps1 without -Development retain the
separate exported/installed-artifact qualification workflow. They temporarily
select installed references and restore the source-reference profiles afterward.
See foundation qualification for release evidence.
Read the TcForge documentation site for searchable guides, or browse the Markdown files below. To preview or update the site, see Maintaining this site.
| # | Document | Covers |
|---|---|---|
| 1 | Programming Standards | Naming, organization, FB structure patterns. |
| 2 | Architecture | FB_DeviceBase, unified fault model, device header pattern. |
| 3 | Command Source Control | Requester validation and source locking. |
| 4 | RPC Method Response | Response codes and method inventory. |
| 5 | I/O Binding | Public signal boundaries and application-owned hardware mapping. |
| 6 | Persistent Variables | PERSISTENT vs RETAIN and UPS configuration. |
| 7 | Sequencing | FB_StateMachine, FB_Step, authoring sequences, permissives. |
| 8 | Alarms | FB_AlarmBase, severity model, ack semantics, alarm catalog. |
| 9 | HMI Integration | OPC UA pragmas, cfg/sts exposure, RPC over OPC UA. |
| 10 | Qualification | Build, PLC tests, restart and commissioning gates. |
| 11 | Reference Machine | Owning task, quality, sequencing, shutdown and cyclic integration tests. |
See toolchain.json for the qualification baseline.
See CONTRIBUTING.md for reporting issues, proposing changes, and documenting validation. Include your TwinCAT build and a minimal example when reporting unexpected behavior.
TwinCAT MCP Server connects AI clients to TwinCAT build, deployment, testing, and ADS tools. TcForge can be used independently.
MIT. See LICENSE.
This is an independent project, not affiliated with or endorsed by Beckhoff Automation. The current foundation contracts and acceptance procedure are in Foundation qualification.
Simulation and development references: simulation architecture, SPT review, and using TcForge in a project.