Zeugwerk Framework Quickstart Tutorial

A complete TwinCAT 3 PLC project that implements the Zeugwerk Framework Quickstart Tutorial. It is the canonical reference for how a Zeugwerk Framework application is structured: one unit, state machine, sequences, and equipment — all wired together the way the framework expects.

This project is also the demo target for Zeugwerk Creator's MCP server, where an AI agent builds this exact application from scratch using MCP tool calls.

A 3D visualization with physics simulation is available as a companion project: Tutorial-Quickstart-Visualization.

What the machine does

The Quickstart unit implements a pick-and-place cycle:

1. A conveyor moves a cube from the left side of the machine to the right
2. A horizontal axis (TransportX) positions over the cube; a pneumatic cylinder (CylinderY) lowers; a magnet picks up the cube
3. The axis transports the cube back to the left; the cylinder lowers; the magnet releases; the cycle repeats

Equipment

Name	Purpose	Framework type
TransportX	Horizontal axis	ZEquipment.AxisPlcOpenMc
CylinderY	Pneumatic actuator	ZEquipment.ActuatorDigital
MagnetOn	Magnet	ZEquipment.DigitalOutput
LimitSwitchLeft	Cube presence at left	ZEquipment.DigitalInput
LimitSwitchRight	Cube presence at right	ZEquipment.DigitalInput
ConveyorOn	Conveyor	ZEquipment.DigitalOutput
CylinderYIsDown	Cylinder at bottom position	ZEquipment.DigitalInput
CylinderYIsUp	Cylinder at top position	ZEquipment.DigitalInput
CylinderYMoveDown	Cylinder down command	ZEquipment.DigitalOutput
CylinderYMoveUp	Cylinder up command	ZEquipment.DigitalOutput

State machine

The unit follows the Zeugwerk Framework standard state machine (similar to PackML):

• Boot: initializes the unit and transitions to Idle
• GoHome: switches off the magnet, runs the conveyor until a cube is at the left limit switch, lifts the cylinder, homes the axis to 0 mm
• Automatic: runs the pick-and-place cycle continuously; supports Halt (exits after completing the current iteration) and Stop (exits immediately and requires re-homing)
• FaultReaction: handles errors

Prerequisites

• TwinCAT 3.1 (Build 4024 or newer)
• Zeugwerk DevKit (includes the Framework libraries and Creator)
• Twinpack to restore the Zeugwerk Framework libraries

Getting started

1. Clone the repository
2. Open Zeugwerk Quickstart.sln in TwinCAT XAE (Visual Studio)
3. Right-click References in the PLC project, open the Twinpack Catalog, and click Restore All to download and install the Zeugwerk Framework libraries
4. Activate the Zeugwerk Framework trial license under SYSTEM > License > Manage Licenses
5. Activate the configuration on a TwinCAT runtime, download, and run

To explore the machine interactively without hardware, open the companion 3D Visualization alongside the running PLC.

Full step-by-step setup instructions are in the Quickstart Tutorial.

Project structure

ZApp/
├── ZModuleProgram.TcPOU        # Main PROGRAM: calls App and Quickstart unit
├── ZGlobal.TcGVL               # Global Com (published data) and persistent Data
├── App/                        # Application FB (EXTENDS ZApplication.Application)
│   └── _States/                # Application-level sequences: Boot, Running, BootFault
└── Unit/Quickstart/
    ├── QuickstartUnit.TcPOU    # Unit FB (EXTENDS ZApplication.Unit)
    ├── _Equipment/             # Equipment instances (axis, cylinder, I/O, magnet)
    ├── _States/                # Unit sequences: Automatic, Stop, GoHome, FaultReaction
    └── _Com/                   # COM data types for external clients (HMI, visualization)

Framework libraries used

Library	Purpose
ZApplication	Application, Unit, Sequence, StateMachine base types
ZEquipment	Axis, actuator, digital I/O equipment FBs
ZCore	Interfaces, container patterns, strings
ZAux	Timers, logging, utilities

Links

• Quickstart Tutorial guide
• Zeugwerk Framework documentation
• Twinpack package manager
• 3D Visualization companion project
• Zeugwerk Creator MCP demo
• Zeugwerk website