Your first program
Getting started ends with a scaffold. This page takes the next step: one small, real program, built end to end in about twenty minutes. It is a single-pump sump (a lift station’s wet well):
- the pump starts when the level reaches
StartLevel(60 %) and stops when it falls toStopLevel(20 %); - once started it runs for at least
MinRun(30 s), so a quick pump-down does not short-cycle the motor — aTON; - every start is counted — an
R_TRIGfeeding aCTU.
You will declare the tags, write the Structured Text, write acceptance tests that pin the 30 s down in virtual time, run it and drive it over HTTP, and build the controller binary.
You need naut on your PATH (Getting started, step
1). Steps 5 and 6 also use curl and jq.
1. Scaffold
Section titled “1. Scaffold”naut new sump --template minimalcd sump created sump/ — a manifest project, no Go required
next steps: cd sump naut run # scan loop + dashboard + tag API on http://localhost:8080 naut test # acceptance tests, in virtual time naut build # emit ./sump — a self-contained controller binary
open the folder in VS Code with the "nautilus IEC 61131-3" extension for diagnostics, the graphical editors, and live values in program.st.You will replace the three files that matter:
nautilus.yaml, program.st and sump_test.yaml.
2. Declare the tags
Section titled “2. Declare the tags”Replace nautilus.yaml with:
name: sump
server: addr: "localhost:8080"
tasks: - program: program.st scan: 100ms
tags: - { name: LevelPct, role: input, type: REAL, init: 0.0, unit: "%", desc: Sump level } - { name: StartLevel, role: setpoint, type: REAL, init: 60.0, unit: "%", desc: Pump starts at or above } - { name: StopLevel, role: setpoint, type: REAL, init: 20.0, unit: "%", desc: Pump stops at or below } - { name: MinRun, role: setpoint, type: TIME, init: T#30s, desc: Shortest run once started } - { name: PumpRun, role: output, type: BOOL, desc: Pump run command } - { name: PumpStarts, role: output, type: INT, desc: Starts since power-up }
driver: type: memoryThe role says who writes a tag:
| role | written by | here |
|---|---|---|
input | the field driver, before every scan | LevelPct, the level transmitter |
setpoint | an operator (HMI or POST /api/tags); exists from scan one with its init: | the two levels and MinRun |
output | the program; handed to the driver after every scan | PumpRun, PumpStarts |
Every program sees these tags without declaring them. driver: memory is a
loopback with no hardware behind it, so nothing will move LevelPct until
you do — in a test with given:, on a running controller with a force.
unit: and desc: show up in the dashboard and in test failures. More on
roles, and the one rule that bites (a tag is read before anything wrote
it), in The tag model.
3. Write the logic
Section titled “3. Write the logic”Replace program.st with:
PROGRAM SumpVAR run : BOOL; (* the pump's state, kept across scans *) minTimer : TON; (* how long the pump has been running, up to MinRun *) started : R_TRIG; (* TRUE for one scan when the pump starts *) starts : CTU; (* counts those scans *)END_VAR
IF LevelPct >= StartLevel THEN run := TRUE;ELSIF LevelPct <= StopLevel AND minTimer.Q THEN run := FALSE;END_IF;
minTimer(IN := run, PT := MinRun);started(CLK := run);starts(CU := started.Q, R := FALSE, PV := 32767);
PumpRun := run;PumpStarts := starts.CV;END_PROGRAMrunis a local, so it keeps its value from one scan to the next: between the two levels the pump stays as it was.minTimeris an on-delay. ItsQturns TRUE oncerunhas been TRUE forMinRun, and only then may the stop level stop the pump.startedis TRUE for exactly one scan whenrungoes TRUE, andstartscounts it. (CTUcounts rising edges ofCUon its own, soCU := runwould count the same; theR_TRIGmakes the start a pulse you can name and reuse.)- The logic works on
runand copies it toPumpRunat the end, so it never reads an output before writing it.
Check it compiles against the manifest:
naut check .naut check: 1 file(s), 0 with errorsEvery block and operator is in the language reference; the ST syntax is in Structured Text.
4. Write the acceptance tests
Section titled “4. Write the acceptance tests”Replace sump_test.yaml with:
tests: - name: pump starts at the start level given: { LevelPct: 65.0 } scans: 1 expect: { PumpRun: true, PumpStarts: 1 }
- name: a quick pump-down still runs the full MinRun steps: - given: { LevelPct: 65.0 } scans: 1 expect: { PumpRun: true } - given: { LevelPct: 15.0 } # below StopLevel almost at once advance: 29.5s expect: { PumpRun: true } # MinRun (T#30s) holds it on - advance: 1s expect: { PumpRun: false } # ... and now it may stop
- name: MinRun is a setpoint, so a longer one needs no program change given: { MinRun: T#2m } steps: - given: { LevelPct: 65.0 } scans: 1 - given: { LevelPct: 15.0 } advance: 119.5s expect: { PumpRun: true, MinRun: T#2m } - advance: 1s expect: { PumpRun: false }
- name: between the levels the pump keeps its state; each start counts once steps: - given: { LevelPct: 65.0 } advance: 31s expect: { PumpRun: true, PumpStarts: 1 } # one start, not one per scan - given: { LevelPct: 40.0 } # pumping down: keeps running advance: 10s expect: { PumpRun: true } - given: { LevelPct: 15.0 } scans: 1 expect: { PumpRun: false } - given: { LevelPct: 40.0 } # filling up: stays off advance: 10s expect: { PumpRun: false } - given: { LevelPct: 65.0 } scans: 1 expect: { PumpRun: true, PumpStarts: 2 }How to read it:
- The fixture is
nautilus.yaml: every test starts from the manifest’s tags,init:values and 100 ms scan. Nothing is restated. given:sets tags before the step runs. Arole: inputtag arrives through the driver at the top of the next scan, as the field would deliver it; a setpoint is written directly. ATIMEtag takes an IEC literal,T#2m, ingiven:andexpect:alike.scans: 1runs one scan.advance: 29.5sruns 29.5 s of virtual time: the clock theTONcounts on moves exactly that far, in well under a millisecond of real time. That is what lets a test say “still on 29.5 s after the level dropped, off a second later” and mean it.expect:is checked at the end of the step.
Run them:
naut testsump_test.yaml ok pump starts at the start level ok a quick pump-down still runs the full MinRun ok MinRun is a setpoint, so a longer one needs no program change ok between the levels the pump keeps its state; each start counts once
4 tests, 4 passed, 0 failedBreak it on purpose
Section titled “Break it on purpose”A test is worth what it catches. In program.st, delete AND minTimer.Q
from the ELSIF line, so the stop level stops the pump at once, and run
naut test again:
sump_test.yaml ok pump starts at the start level FAIL a quick pump-down still runs the full MinRun sump_test.yaml:14 — step 2 (line 12), t=29.6s PumpRun = false, want true (expectation failed)
PumpRun — Pump run command 0.1s 4.3s 8.5s 12.7s 16.9s 21.1s 25.3s 29.6s true false false false false false false false FAIL MinRun is a setpoint, so a longer one needs no program change sump_test.yaml:25 — step 2 (line 23), t=1m59.6s PumpRun = false, want true (expectation failed)
PumpRun — Pump run command 0.1s 17.1s 34.2s 51.3s 1m8.3s 1m25.4s 1m42.5s 1m59.6s true false false false false false false false
MinRun — Shortest run once started 0.1s 17.1s 34.2s 51.3s 1m8.3s 1m25.4s 1m42.5s 1m59.6s T#2m T#2m T#2m T#2m T#2m T#2m T#2m T#2m ok between the levels the pump keeps its state; each start counts once
4 tests, 2 passed, 2 failedThe failure names the line of the expectation, the virtual time, and what
PumpRun actually did: on at the first scan, off by the next sample. The
second failure also shows the MinRun the test set, so you can see the
pump stopped with a two-minute minimum in force. Put
AND minTimer.Q back and the suite passes again. naut test exits
non-zero on a failure, which is what the scaffolded CI gates on. Every
step key, matcher and the force: step are in
Testing.
5. Run it
Section titled “5. Run it”naut runnautilus · sump — dashboard + tag API on http://localhost:8080 — Ctrl+C to stopOpen http://localhost:8080 for the live dashboard, or leave it running and use a second terminal for the rest of this step. Read the tags:
curl -s localhost:8080/api/state | jq -c .tags{"LevelPct":0,"MinRun":30000,"PumpRun":false,"PumpStarts":0,"StartLevel":60,"StopLevel":20}A TIME reads back as milliseconds: MinRun is 30000.
6. Drive it with forces
Section titled “6. Drive it with forces”LevelPct is an input, so it belongs to the driver, and a write to it is
refused:
curl -s -X POST localhost:8080/api/tags -d '{"name":"LevelPct","value":65}'tag LevelPct is a driver-owned input: its value is the field's, so a write is refused — force it (POST /api/forces) to hold a value during bring-up, or write the setpoint or command tag the logic reads insteadA force holds a tag at a value, against the driver, until you remove it. Fill the sump:
curl -s -X POST localhost:8080/api/forces -d '{"name":"LevelPct","value":65}'{"forces":[{"name":"LevelPct","value":65,"sinceMs":1793686399858}]}The reply is the force table (sinceMs is when the force was set, so
yours will differ). The program sees the forced value from its next scan,
a tenth of a second later. Read the tags:
curl -s localhost:8080/api/state | jq -c .tags{"LevelPct":65,"MinRun":30000,"PumpRun":true,"PumpStarts":1,"StartLevel":60,"StopLevel":20}The pump started and the start was counted. Now drop the level below
StopLevel straight away and look at the timer, which is a program local:
curl -s -X POST localhost:8080/api/forces -d '{"name":"LevelPct","value":15}'curl -s localhost:8080/api/state | jq -c '.tags.PumpRun, .locals.minTimer'{"forces":[{"name":"LevelPct","value":15,"sinceMs":1793686403871}]}true{"ET":3900,"IN":true,"PT":30000,"Q":false}Still running, with 3.9 s of the 30 s used (yours will differ: it is
however long you took between the two forces). Wait out the rest of
MinRun and read it again:
curl -s localhost:8080/api/state | jq -c .tags{"LevelPct":15,"MinRun":30000,"PumpRun":false,"PumpStarts":1,"StartLevel":60,"StopLevel":20}Setpoints, unlike inputs, take a plain write. Lower the start level and
lengthen the minimum run (a TIME write takes an IEC literal, or a number
of milliseconds), then remove the force so the level goes back to what the
driver says (the loopback’s 0):
curl -s -X POST localhost:8080/api/tags -d '{"name":"StartLevel","value":50}'curl -s -X POST localhost:8080/api/tags -d '{"name":"MinRun","value":"T#1m"}'curl -s -X DELETE localhost:8080/api/forces/LevelPctcurl -s localhost:8080/api/state | jq -c .tags{"forces":[]}{"LevelPct":0,"MinRun":60000,"PumpRun":false,"PumpStarts":1,"StartLevel":50,"StopLevel":20}MinRun reads back as 60000, the milliseconds of T#1m.
A successful write answers 204 No Content, so it prints nothing. Forces
are not retained: a restart comes up with none. Stop the controller with
Ctrl+C. The whole force API, the VS Code side of it and the lifetime rules
are in Forcing.
7. Build it
Section titled “7. Build it”naut buildbuilt sump — a self-contained controller (run it like any binary; NAUTILUS_ADDR/NAUTILUS_TOKEN apply) — no git history embedded (no commits yet)./sump is the whole controller: the program, the manifest and the
dashboard in one binary, with no naut and no toolchain needed where it
runs. Start it with ./sump and it serves the same API on
localhost:8080; the tests are left out of it. “No git history embedded”
goes away once the project has a commit (naut new made it a git
repository); see Program history.
Where next
Section titled “Where next”- Put real I/O behind
LevelPctandPumpRun: pointdriver:at the bus (Modbus, EtherNet/IP). The program and the tests do not change. - Add a high-level alarm on
LevelPct: Alarms. - Ship it: Deployment.
nautilus is free and open source (Apache 2.0), built by Joy Automation. For implementation or support on your site, see Joy Automation services. Privacy.