# Twinworks PLC Scan Simulator

> Structured Text, ladder or state machine + input timeline → scan-by-scan outputs, timers and trace. Run a small PLC program in a simulated scan cycle: an IEC 61131-3 style Structured Text subset, a ladder diagram in text form or a state machine. Inputs change on a timeline; every scan reads inputs, executes the program and writes outputs. You get the output and state timeline, TON/TOF/TP timers and CTU/CTD counters per standard behaviour, the generated Structured Text and a timing diagram. Simulation only, no real PLC I/O.

Part of usefulweb.site (https://usefulweb.site/). Part of [Twinworks](https://twinworks.usefulweb.site/) (ownerApp: twinworks). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://twinworksplcsimulator.usefulweb.site/ (interactive tool at https://twinworksplcsimulator.usefulweb.site/tool)
- JSON API: POST https://twinworksplcsimulator.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://twinworksplcsimulator.usefulweb.site/api/v1/tool)
- OpenAPI: https://twinworksplcsimulator.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://twinworksplcsimulator.usefulweb.site/mcp - tool `twinworks_plc_simulator`

## Inputs
- language (select): Language
- program (textarea): Program - Structured Text: VAR_INPUT / VAR_OUTPUT / VAR blocks (BOOL, INT, DINT, REAL, TIME, TON, TOF, TP, CTU, CTD, CTUD, R_TRIG, F_TRIG, SR, RS), IF/ELSIF/ELSE, CASE, FOR, WHILE, REPEAT, := assignments, PLC_TIME. Ladder: one rung per line, "(Start | Motor) & !Stop -> Motor", outputs Name, !Name, S Name, R Name, TON T1 PT=T#5s, CTU C1 PV=3 R=Reset; POS(x)/NEG(x) edge contacts. State machine: input/output/var lines, "state Name [initial]", entry/do/exit statements, "transition A -> B when GUARD", StateTime.
- timeline (textarea): Input timeline - One line per time: time then Name=value pairs, e.g. "0 Start=0", "250ms Start=1", "2s Stop=TRUE". Times in ms unless s/m/h or T#… is given. Inputs keep their value until changed.
- cycleMs (integer): Scan cycle time
- durationMs (integer): Duration
- watch (text): Extra variables to trace (optional) - Comma-separated, e.g. T1.ET, Count. Inputs, outputs, timer Q and counter CV are always traced.

## Method
- Own parser for a Structured Text subset (no eval): declarations, expressions with IEC precedence, IF/ELSIF/ELSE, CASE with ranges, FOR/WHILE/REPEAT with EXIT, function block calls with := inputs and => outputs. Types are checked before running; only widening conversions are implicit (INT → DINT → REAL), INT/DINT wrap at 16/32 bits like a PLC.
- Ladder rungs and state machines compile to the same program representation and run in the same interpreter; the generated Structured Text is shown so you can see exactly what runs. Each rung is evaluated once per scan, top to bottom, so a coil written in a later rung is seen by earlier rungs only in the next scan.
- Scan cycle: at k × cycle time the input image is taken from the timeline, the program executes once, and the output image is recorded. Timers use the scan start time: TON switches on at the first scan where IN has been TRUE for at least PT; TOF holds Q for PT after IN falls; TP gives a non-retriggerable pulse of length PT. CTU/CTD count rising edges of CU/CD between scans (pulses shorter than a scan are missed, as on a real PLC).
- State machines become a CASE over State: at most one transition per scan, checked in the listed order; exit action, transition action, then entry action of the new state. StateTime is the time since the state was entered.
- Sandbox: a watchdog stops a scan after 200,000 instructions, loops after 100,000 iterations, a run after 500,000 scans.

## Limits
- Teaching and design aid only: a subset of IEC 61131-3 implemented from public descriptions, simulated in virtual time. It is not a certified runtime and never connects to real inputs or outputs; never use it to validate safety functions.