Skip to content

Console

The Console takes typed commands to run the PLC, force tags, ask why something happened, and record what you did. You can type at it in three places.

  • The Simulator console in ClickNick.
  • The Console in the VS Code debugger.
  • pyrung live in a terminal, covered below.

Type help to print the list below. All three take these commands, with these differences:

  • ClickNick and pyrung live chain commands with ; and stop at the first error. VS Code sends the whole line as one command.
  • ClickNick doesn't support autoreload, record or replay yet.
  • In ClickNick, send reload on its own. ClickNick writes the program to the Simulator (a RUN Time Edit in RUN) and carries forces and links to the new program.
  • ClickNick refuses commands while it writes a program.

Command reference

execution:
  autoreload [off]
  continue
  mode [run|stop]                                       (PLC RUN/STOP mode)
  pause
  reload
  run <N | duration> | run until <expression> within <N | duration>
  speed [N|max]                                         (1 = real time; 0 or max = unpaced)
  step [N]
  stop                                                  (cancels a running analysis)

data:
  bounds [clear]                                        (runtime constraint log)
  clear_forces
  force <tag> <value>
  get <tag> [tag2 ...]
  link <feedback> <[~]enable[:trigger]> key=value ...   (bench wiring)
  links [bench on|off | enable <tag> | disable <tag>]
  monitor <tag>
  patch <tag> <value>
  restore <tag>                                         (drop a bench change)
  unforce <tag>
  unlink <tag>                                          (cut on the bench)
  unmonitor <tag>

analysis:
  check [RULE_OR_CATEGORY ...]

  dataview <text | i: | p: | t: | upstream:tag>
  downstream <tag>
  upstream <tag>
  structures

  cause <tag>[@scan|:value]
  effect <tag>[@scan|:value]
  recovers <tag>
  why <tag> [tag2 ...]
  how <expression>[, <expression>...] [avoid <expression>[, <expression>...]]  (runs planner)

  simplified [tag]

capture:
  assert <tag> == <value>
  harness <install|remove|status>                       needs physical+link=
  record <action> | record stop | record save [file]
  replay <filepath> [--harness current|recorded|off]

other:
  help

Values, forces, patches, and bounds

get Button Counter        # read one or more current values
force Button true          # persistent override, held across scans
unforce Button             # remove a force
clear_forces               # remove all forces
patch Button true          # one-shot input, consumed after one scan
bounds                     # review runtime min/max/choices violations
bounds clear               # clear the accumulated violation log

Stepping and running

step                       # advance one scan
step 5                     # advance 5 scans
run 100                    # run 100 scans
run 500ms                  # run for 500ms of sim time
run 2 s                    # run for 2 seconds (split unit ok)
continue                   # run continuously (background)
pause                      # stop a running continue

step and run process breakpoints and logpoints during execution. If a breakpoint fires, the command stops early and reports it. Duration parsing accepts ms, s, m, min, h, and d, including compact compound durations such as 1h30min.

run until Done within 500          # stop on the first scan that ends with Done on
run until Count >= 10 within 2 s   # a Watch expression, given at most 2 s
run until State == HELD within 50  # a choice label stands for its value

run until runs whole scans until its condition holds. It runs no scan if the condition already holds. Write the condition as you would in a Watch. Past the limit, run until fails with an error that names the condition and how many scans it ran. A replay stops at that line.

The within limit is required. Give it room, because the scan count to a step in a sequence can change when the program does.

mode and speed set the PLC mode and the pacing. Each prints the current setting when given no argument.

mode stop                  # put the PLC in STOP
mode run                   # back to RUN
speed 2                    # run Continue at twice real time
speed max                  # unpaced (same as speed 0)

Why, cause, effect, and how

These four answer "what happened" and "how do I make it happen". The Cause & Effect and Diagnosis guides cover the same questions from Python.

cause Light                # why did Light last change?
cause Light@5              # why did Light change at scan 5?
cause Light:true           # how could Light reach true? (projected)
effect Button              # what did Button's last change cause?
effect Button:true         # what would happen if Button became true?
recovers Light             # can Light return to its resting value?
why Light Button           # explain current values without scan history
how Running                # find a verified input-change sequence
how State == HELD avoid State == FAULTED
how Burner avoid ProdMode, MaintFault

cause and effect read the scan history. @scan picks a scan and :value asks about a projected change instead of a past one. why needs no history, so it works on a fresh session.

how takes one or more comma-separated targets that must all hold at the end of the path. The optional avoid clause lists conditions the path must never pass through. Each is avoided on its own. The planner prints progress as it works.

how holds the Console's state lock while it runs. Cancel it from another terminal with pyrung live stop, since a stop typed in the same Console cannot preempt its own request. cancel works as well as stop from pyrung live.

Program inspection

check                      # run every static ladder check
check COIL TAG             # select rules or categories
structures                 # list UDTs and named arrays

DataView queries

dataview Motor             # tags containing "Motor"
dataview i:                # all input tags
dataview p:Motor           # pivots containing "Motor"
dataview upstream:Light    # upstream dependencies of Light
dataview downstream:Button # downstream effects of Button
upstream Light             # shorthand for dataview upstream:Light
downstream Button          # shorthand for dataview downstream:Button

The query language supports role prefixes (i: inputs, p: pivots, t: terminals, x: isolated) and slice prefixes (upstream:, downstream:). Multiple tokens are applied left to right.

Simplified form

simplified                 # show all terminals' simplified Boolean forms
simplified MotorOut        # show one terminal, resolved to inputs

Monitors

monitor Button             # watch Button for value changes
unmonitor Button           # stop watching

Session capture

Record console commands into a file that replay and pytest can run. ClickNick doesn't support record or replay yet.

record start_machine       # begin recording action "start_machine"
patch Start true
run until Running within 2 s
assert Running == true
record save                # stop, and write start_machine.rec next to the program

record save writes <action>.rec in the program's folder. Give it a file name to write somewhere else, as in record save tests/start.rec. In record save and replay, a relative path starts at the program's folder. record stop ends the recording and prints it without saving it. A record save after that saves it.

record save replaces a file that is already there, and says so. If the file is in git, git still has the old version.

A recording is a text file with one command per line, under a header of # lines:

# action: start_machine
# program: logic.py
# program sha256: 5f2c0e...
# pyrung: 0.17.0
# scan time: 0.01 s
# harness: on
patch Start true
run until Running within 2 s
assert Running == true

The program line names the program file, relative to the recording's folder. Replay reads the scan time and harness lines. The other lines are there for a person reading the file.

replay start_machine.rec                      # the harness as it was recorded
replay start_machine.rec --harness current    # the current program's harness
replay start_machine.rec --harness recorded   # the harness inputs the file holds
replay start_machine.rec --harness off        # no harness

Replay runs each command in order. It stops at a breakpoint, or at the first command that fails, and reports that line. Without --harness, a recording made with the harness off replays with no harness. Any other recording replays with the current program's harness. current skips the harness inputs in the file. recorded removes the program's harness and applies the inputs from the file.

Replaying a recording made with the harness off removes the session's harness. The harness stays off after the replay. Add --harness current to keep it.

A PLC that hasn't run a scan yet takes the recording's scan time. A PLC that has already scanned keeps its own scan time, and replay prints a note.

Checks

assert Light == true       # fails unless Light is on
assert Temp == 72.5        # a Real within one part in a million passes
assert State == HELD       # a choice label stands for its value

assert compares one tag with one value. A failed assert is an error that reports the value it found. A replay stops at that line. A tag the program doesn't have is an error too. So is a word that isn't one of the tag's choice labels.

assert reads the values at the end of the last full scan, as get does. After a next into the middle of a scan, assert doesn't see what that scan's rungs have written so far.

Autoharness

If your program uses Physical annotations with physical= and link= declarations, the adapter installs the autoharness automatically at launch. A banner appears in the Console:

Harness: 3 feedback loop(s) (2 delay, 1 ramp); `harness status` for details

A force still wins over the harness. Force a feedback tag to hold it whatever the harness computes.

harness status             # show couplings, pending patches, active state
harness remove             # disable the harness for this session
harness install            # re-install after removal

Bench links change the feedback wiring for this session without editing the program. You can add a link, replace one the program declares, or cut one to simulate a failed sensor or a stuck contactor. They take the same keys as a link in a nickname comment. Tags may be names or CLICK addresses:

link X002 Y001 on_delay=2s off_delay=500ms     # Y001 drives X002 after 2 s, drops 500 ms after
link DF5 Y003 ramp_on=0.8 ramp_off=-0.05       # analog feedback
link Sorted State:2 on_delay=1s                # value trigger
unlink X002        # cut the program's link (X002 is a free input), or remove a bench link
restore X002       # drop the bench change (back to what the program declares)
links              # list program and bench links
links bench off    # set every bench change aside (`links bench on` brings them back)
links disable X002 # set one aside (`links enable X002` brings it back)

A link added while its enable is already on starts its on-delay from zero, so the feedback follows only after the on-delay.

Bench links live in the debug session, not the runner, so reload keeps them. A recording captures the link verbs, and replay runs them only with --harness current.

pyrung live

Attach to a running debug session from another terminal or process.

When the DAP adapter launches, it starts a TCP server on localhost and writes the port to a session file. The session name defaults to the program filename stem (logic.py → logic). In VS Code, you can set it in the launch configuration instead:

{
  "type": "pyrung",
  "request": "launch",
  "program": "${file}",
  "session": "my_session"
}

CLI usage

pyrung live                                # list active sessions
pyrung live step 5                         # works when only one session is active
pyrung live -s my_session step 5           # explicit session when multiple are running
pyrung live "force Button true; step 5; cause Light"  # chain commands with ;
pyrung live -h                             # show all available commands

Commands chained with ; run in order over one connection and halt on the first error. The exit code is 0 on success and 1 on error.

Python library

from pyrung.live import send_command, list_sessions

sessions = list_sessions()          # ["logic", "pump_test"]
ok, text = send_command("logic", "step 5")
print(text)                         # "Stepped 5 scan(s), now at scan 10"

Pair commissioning

One person drives VS Code (breakpoints, Data View, Graph View). Another person runs pyrung live from a terminal. Both work on the same PLC state. The live client can do everything the Console can, including forces, patches, causal queries and recording. Stepping from either side advances the same scan counter.

Reload

reload re-executes the program file and keeps PLC state. Tags, memory, timer accumulators, counter values and forces all carry over. History clears. This is the same experience as downloading a new program to a running PLC.

reload                         # from the Console
pyrung live reload             # from another terminal

Scan ID and timestamp continue from where they were. Debug registrations (breakpoints, monitors) are cleared since rung indices may have shifted.

A reload keeps the PLC mode, so a reload in STOP stays in STOP. A reload sent while continue runs pauses it first.

Forces and bench links follow the tag name. A reload names each force and bench link whose tag moved to another CLICK address, and each one it dropped:

The force on A moved from C1 to C5.
Dropped the force on B because B is not in the new program.

autoreload does the same on every file save. See Auto-reload for how it watches.

Tag type changes

If a tag changes type between reloads (e.g. Bool('X') becomes Int('X')), the old value is dropped and the tag gets its new default, with a warning.

New tags added to the program get their defaults. Removed tags become harmless orphans in state.

Reload errors

If the program file has a syntax error or the runner can't be discovered, the reload aborts and the old runner stays active. Fix the file and reload again.