Skip to content

Tutorials

Follow the tutorial sequence from basic editing through runtime and deployment workflows.

For goal-based ordering, open Learning Paths.

Guided Tutorial Path

Docs category: docs/public/examples/tutorials.md

This is the primary onboarding path for learning truST in VS Code.

You will move from simple ST syntax to runtime interaction and unit testing, while intentionally using one VS Code feature per tutorial.

One-Time Setup

  1. Open repository root in VS Code:
code /path/to/trust-platform
  1. Install extension if needed:
code --install-extension trust-platform.trust-lsp

For contributors working on truST itself, one test compiles every tutorial: cargo test -p trust-runtime tutorial_examples_parse_typecheck_and_compile. You do not need Rust to follow the tutorials.

How To Work Through This Path

For each tutorial:

  1. Open the file.
  2. Read the "VS Code Feature Spotlight" first.
  3. Follow the guided interaction steps.
  4. Complete the challenge.
  5. Trigger one pitfall intentionally, then fix it.

01_hello_counter.st

VS Code Feature Spotlight

  • Diagnostics + squiggles
  • Hover tooltips
  • Semantic syntax highlighting

Guided Steps

  1. Open 01_hello_counter.st.
  2. Hover Count, Increment, and Enable to inspect inferred types.
  3. Intentionally remove one semicolon and confirm a red diagnostic.
  4. Restore the semicolon and confirm diagnostics clear.

Challenge

  • Add MaxCount : INT := 100; and wrap Count to 0 when Count > MaxCount.

Common Pitfalls

  • Missing semicolon after assignment.
  • Using = instead of := for assignment.
  • Forgetting END_IF.

02_blinker.st

VS Code Feature Spotlight

  • Completion for standard FBs (TON)
  • Snippet insertion and parameter hints

Guided Steps

  1. Open 02_blinker.st.
  2. Create a temporary line and type TO then trigger completion (Ctrl+Space).
  3. Select TON and inspect inserted call shape.
  4. Hover timer fields (IN, PT, Q) to inspect semantics.

Challenge

  • Change period from T#250ms to T#500ms and document expected behavior change.

Common Pitfalls

  • Writing 250ms instead of typed literal T#250ms.
  • Forgetting to keep timer call active each cycle.

03_traffic_light.st

VS Code Feature Spotlight

  • Go to definition on program variables and timer types
  • Document outline (Ctrl+Shift+O)

Guided Steps

  1. Open 03_traffic_light.st.
  2. Place the cursor on PhasePeriod or TON and press F12 (or Ctrl+Click).
  3. Open outline (Ctrl+Shift+O) and jump to the TrafficLight program.

Challenge

  • Add a maintenance phase value and transition into it from a new condition.

Common Pitfalls

  • Missing integer phase value in CASE handling.
  • Leaving one phase without explicit red, yellow, and green outputs.

04_tank_level.st

VS Code Feature Spotlight

  • Inlay hints
  • Format Document (Shift+Alt+F)

Guided Steps

  1. Open 04_tank_level.st.
  2. Run Format Document and inspect spacing/alignment changes.
  3. Enable inlay hints if disabled and review call-site parameter names.

Challenge

  • Tighten threshold band to reduce output oscillation.

Common Pitfalls

  • Type mismatch between INT sensor and REAL threshold math.
  • Missing END_IF in nested conditions.

05_motor_starter.st

VS Code Feature Spotlight

  • Find All References (Shift+F12)

Guided Steps

  1. Open 05_motor_starter.st.
  2. Run Find All References on MotorRun.
  3. Verify all latching/unlatching writes are visible in one place.

Challenge

  • Add FaultReset behavior requiring explicit reset after overload.

Common Pitfalls

  • Accidental combinational loop in latch logic.
  • Forgetting stop/overload precedence.

06_recipe_manager.st

VS Code Feature Spotlight

  • Code folding for CASE branches

Guided Steps

  1. Open 06_recipe_manager.st.
  2. Fold all CASE branches and expand one-by-one while tracing outputs.
  3. Confirm each branch assigns all required outputs.

Challenge

  • Add one new recipe ID with full parameter mapping.

Common Pitfalls

  • Missing default/else behavior.
  • Partially assigned outputs in one branch.

07_pid_loop.st

VS Code Feature Spotlight

  • Rename Symbol (F2)

Guided Steps

  1. Open 07_pid_loop.st.
  2. Rename one control variable (for example ControlOutput -> CommandOutput) with F2.
  3. Review rename preview before applying.

Challenge

  • Add clamping limits to output and anti-windup condition.

Common Pitfalls

  • Renaming to reserved keyword.
  • Breaking semantic meaning by unclear variable names.

08_conveyor_system.st

VS Code Feature Spotlight

  • Signature help during FB calls (Ctrl+Shift+Space)

Guided Steps

  1. Open 08_conveyor_system.st.
  2. Place cursor inside a call argument list and trigger signature help.
  3. Validate parameter ordering and intent.

Challenge

  • Add a jam-reset input that clears jam latch under safe conditions.

Common Pitfalls

  • Passing wrong parameter order in positional calls.
  • Missing safety condition around restart.

09_simulation_coupling/

VS Code Feature Spotlight

  • Live Values first-use walkthrough

Guided Steps

  1. Open 09_simulation_coupling/src/main.st.
  2. In the truST view, press Start: the Simulator runs the program and Live Values opens.
  3. In Live Values, write %IW0 under Inputs below the threshold (for example 300) and observe the alarm output.
  4. Write %IW0 above the threshold (for example 600) and observe the alarm change.

Challenge

  • Add second alarm level (warning/critical) with two thresholds.

Common Pitfalls

  • Writing wrong address type (%Q instead of %I).
  • Not pressing Start before writing values.

10_unit_testing_101/

VS Code Feature Spotlight

  • Test Explorer + CodeLens run actions

Guided Steps

  1. Open 10_unit_testing_101/src/tests.st.
  2. Use CodeLens Run Test above each test.
  3. Open Testing sidebar (beaker icon) and run all discovered tests.
  4. Inspect pass/fail indicators and test output details.

Challenge

  • Add one failing assertion intentionally, run tests, then fix it (red-green cycle).

Common Pitfalls

  • Writing tests in PROGRAM instead of TEST_PROGRAM/TEST_FUNCTION_BLOCK.
  • Forgetting deterministic setup per test case.

11_unit_testing_102/

VS Code Feature Spotlight

  • Test Explorer triage + focused reruns

Guided Steps

  1. Open 11_unit_testing_102/src/tests.st.
  2. Run all tests from Testing sidebar.
  3. Break one expected value intentionally.
  4. Re-run failed test only from sidebar.
  5. Restore fix and verify green state.

Challenge

  • Extend mock I/O test matrix with one new operating-band scenario.

Common Pitfalls

  • Testing hardware-mapped PROGRAM directly instead of FB logic.
  • Carrying test state between scenarios.

12_hmi_pid_process_dashboard/

VS Code Feature Spotlight

  • Live Values write/force on mapped %IX inputs
  • Runtime build/run against a multi-file project with VAR_CONFIG mapping

Guided Steps

  1. Open 12_hmi_pid_process_dashboard/README.md.
  2. Build and run the tutorial project.
  3. Toggle %IX0.0 / %IX0.1 / %IX0.2 / %IX0.3 to drive start/stop/spike/bypass scenarios.
  4. Verify setpoint, deviation, and alarm values update in Live Values.
  5. Read the %QX outputs with trust-runtime ctl --project ./12_hmi_pid_process_dashboard io-read.

Challenge

  • Add a low-flow alarm while the pump runs and map it to %QX0.5.

Common Pitfalls

  • Writing an input address that is not mapped in src/config.st.
  • Forgetting to release a forced input after a scenario check.

Advanced Operations Tutorials (13-23)

After finishing Tutorials 01-12, continue with these production-oriented walkthroughs. Each guide is intentionally detailed and explains both what to do and why it matters.

  1. 13_project_bootstrap_zero_to_first_app/README.md
  2. start from an empty folder and build a first runnable PLC project.
  3. 14_deploy_and_rollback/README.md
  4. practice versioned deployment and controlled rollback.
  5. 15_multi_plc_discovery_mesh/README.md
  6. run two runtimes, verify discovery/pairing, and enable mesh sharing.
  7. 16_secure_remote_access/README.md
  8. configure TCP control with auth token, pairing, and minimal firewall exposure.
  9. 17_io_backends_and_multi_driver/README.md
  10. configure loopback, simulated, gpio, modbus-tcp, mqtt, and composed io.drivers.
  11. 18_simulation_toml_fault_injection/README.md
  12. use deterministic simulation.toml couplings/disturbances/fault events.
  13. 19_safety_commissioning/README.md
  14. verify safe-state outputs, watchdog/fault policy, and restart recovery.
  15. 21_ci_cd_project_pipeline/README.md
  16. implement CI gates with machine-readable reports and stable exit codes.
  17. 22_neovim_zed_workflow/README.md
  18. run a complete non-VS-Code workflow with Neovim/Zed plus terminal gates.
  19. 23_observability_historian_prometheus/README.md
    • enable historian + Prometheus telemetry and verify runtime observability contracts.
  20. 24_hmi_alarms/README.md
    • declare alarms with the Alarm library and operate them in the HMI's runtime display: priorities, acknowledge, shelve, first out on a trip, equipment alarms, own detection.

Suggested sequence for operations engineers:

  1. 13_project_bootstrap_zero_to_first_app/README.md
  2. 17_io_backends_and_multi_driver/README.md
  3. 18_simulation_toml_fault_injection/README.md
  4. 19_safety_commissioning/README.md
  5. 14_deploy_and_rollback/README.md
  6. 16_secure_remote_access/README.md
  7. 15_multi_plc_discovery_mesh/README.md
  8. 21_ci_cd_project_pipeline/README.md
  9. 22_neovim_zed_workflow/README.md
  10. 23_observability_historian_prometheus/README.md
  11. 24_hmi_alarms/README.md

Communication Protocol Examples (Grouped)

For protocol-first commissioning, use:

  • ../communication/README.md
  • includes dedicated subfolders for:
    • modbus_tcp
    • mqtt
    • opcua
    • ethercat
    • ethercat_field_validated_es
    • gpio
    • multi_driver
  • each subfolder includes a runnable minimal project and step-by-step flow.

Transport gating reminders:

  • EtherCAT hardware transport is gated by ethercat-wire and unix-only for non-mock adapters.
  • OPC UA wire server is gated by opcua-wire.

Validation Coverage

Current regression coverage verifies:

  • parse, type-check and compile of the tutorial sources into program images,
  • deterministic runtime behavior for selected scenarios,
  • no unexpected LSP diagnostics on tutorial files.