> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
$schema: https://holocron.so/frontmatter.json
title: Examples
description: Run every shipped example (.st, .il, .sfc, .ld, .fbd, .xml) and see which IEC features each one covers.
icon: lucide:folder-open
---

<Aside full>
  <Tip>
    Run from the repository root with **`cargo run -p rbcpp_cli --`** while developing, or use a built **`rbcpp`** binary if you have one installed.
  </Tip>
</Aside>

The **`examples/`** directory is the fastest way to see what RoboC++ supports today. Files use **`.st`**, **`.il`**, **`.sfc`**, **`.ld`**, **`.fbd`**, or **`.xml`** extensions. Each example is a small IEC project you can **`check`**, **`run`**, or **`build-c`** (programs only for C) without extra setup.

Integration tests require every shipped example to pass **`rbcpp check`**, and every **`.xml`** file to pass **`import-plcopen`** as well.

## How to run any example

```bash
# Parse + semantic check only
cargo run -p rbcpp_cli -- check examples/counter.st

# Deterministic scan simulation (add --json for traces)
cargo run -p rbcpp_cli -- run examples/counter.st --cycles 3

# Portable C output (requires a clean check)
cargo run -p rbcpp_cli -- build-c examples/counter.st -o build/counter.c
```

Use **`--program <name>`** when a file defines more than one `PROGRAM`. Use **`--configuration <name>`** for files that declare a `CONFIGURATION` (see [Execution model](/execution-model)).

## Quick reference

| File                        | Language / area  | Primary lesson                                                          |
| --------------------------- | ---------------- | ----------------------------------------------------------------------- |
| `counter.st`                | Structured Text  | First program: variables, `IF`, arithmetic                              |
| `all_data_types.st`         | Types            | Elementary types, typed literals, enums, subranges, repeated array init |
| `control_flow.st`           | Structured Text  | Loops, `CASE`, `MAX`                                                    |
| `functions.st`              | ST + `FUNCTION`  | User functions and calls                                                |
| `function_blocks.st`        | ST + stdlib FBs  | `CTU`, `SR`, `R_TRIG` state                                             |
| `timers.st`                 | ST + stdlib FBs  | `TON`, `TP`, elapsed time                                               |
| `conversions.st`            | ST + stdlib      | BCD, string/real/bool/time conversions                                  |
| `strings_dates.st`          | ST + strings     | `STRING` ops, date/time literals                                        |
| `aggregates.st`             | Types            | Arrays, structs, enums, subranges                                       |
| `st_bit_ops.st`             | ST expressions   | `AND`, `OR`, `XOR`, `NOT` on integers/bools                             |
| `instruction_list.st`       | Instruction List | Accumulator, compare, store (embedded in `.st`)                         |
| `instruction_list.il`       | Instruction List | Same IL body in a standalone `.il` file                                 |
| `instruction_list_calls.st` | IL               | `CAL` / `CALC` on function blocks                                       |
| `instruction_list_jumps.st` | IL               | Labels, `JMP`, conditional jumps                                        |
| `sfc_sequence.st`           | SFC              | Steps, transitions, actions (embedded in `.st`)                         |
| `sequence.sfc`              | SFC              | Textual SFC in a standalone `.sfc` file                                 |
| `sfc_qualifiers.st`         | SFC              | Action qualifiers (`P`, `D`, `L`, timers)                               |
| `configuration.st`          | Configuration    | Tasks, globals, `VAR_ACCESS`, located vars                              |
| `native_ladder.ld`          | Native LD        | `LADDER`/`RUNG` contacts and coils                                      |
| `native_fbd.fbd`            | Native FBD       | `FBD`/`NETWORK` data-flow outputs                                       |
| `plcopen_ld.xml`            | PLCopen LD       | Graphical ladder import, lowering, run                                  |
| `plcopen_fbd.xml`           | PLCopen FBD      | Graphical FBD import and data-flow lowering                             |
| `plcopen_sfc.xml`           | PLCopen SFC      | Graphical SFC import (branches, macro steps)                            |

***

## counter.st

**Best first example.** A single `PROGRAM` increments an integer until a limit is reached, then sets a done flag.

| Construct                 | What you learn                                     |
| ------------------------- | -------------------------------------------------- |
| `VAR` with initial values | Local program variables survive across scan cycles |
| `IF` / `ELSE`             | Conditional assignment                             |
| `INT` arithmetic          | `Count := Count + 1`                               |

Each **`run`** cycle executes the body once. **`Count`** rises from 0 toward **`Limit`** (3); on the cycle where **`Count`** is no longer less than **`Limit`**, **`Done`** becomes `TRUE`.

```bash
cargo run -p rbcpp_cli -- run examples/counter.st --cycles 3
```

See [Getting started](/getting-started) and [Structured Text](/structured-text).

***

## control\_flow\.st

Exercises **Structured Text control flow** and one standard function in one program.

| Construct          | Behavior in the example                    |
| ------------------ | ------------------------------------------ |
| `FOR`              | Sums 1..3 into **`Total`**                 |
| `WHILE`            | Increments **`Total`** until it reaches 8  |
| `REPEAT` / `UNTIL` | Decrements until **`Total`** is 7          |
| `MAX`              | **`Selected`** becomes `MAX(Total, 3)` → 7 |
| `CASE`             | Sets **`Done`** when **`Selected`** is 7   |

Use this file when validating loop diagnostics (`EXIT` placement, zero `BY` steps) and **`CASE`** label rules. See [Structured Text](/structured-text).

```bash
cargo run -p rbcpp_cli -- check examples/control_flow.st
cargo run -p rbcpp_cli -- run examples/control_flow.st --cycles 1
```

***

## functions.st

Defines a user **`FUNCTION Scale`** and a **`PROGRAM`** that calls it with positional and named arguments.

| POU            | Role                                                          |
| -------------- | ------------------------------------------------------------- |
| `Scale`        | Multiplies two `INT` inputs and returns the product           |
| `FunctionDemo` | `B := Scale(A, 3)` then `C := Scale(Input := B, Factor := 2)` |

Demonstrates **function declarations**, **`VAR_INPUT`**, and both call styles. Does not use function blocks, so there is no implicit instance state between cycles.

```bash
cargo run -p rbcpp_cli -- run examples/functions.st --cycles 1
```

***

## function\_blocks.st

Standard **function block instances** keep state between scan cycles.

| FB       | Wired for                                                         |
| -------- | ----------------------------------------------------------------- |
| `CTU`    | Count-up: **`Pulse`** toggles each cycle as clock; preset value 2 |
| `SR`     | Set-dominant latch driven by counter done                         |
| `R_TRIG` | Rising edge on **`Pulse`**                                        |

**`Pulse := NOT Pulse`** flips a bool every scan so the counter sees repeated clock edges. Outputs **`Count`**, **`CountDone`**, **`Latched`**, and **`Rising`** copy FB outputs into plain variables for tracing.

```bash
cargo run -p rbcpp_cli -- run examples/function_blocks.st --cycles 4
```

See [Standard library](/standard-library) and [Execution model](/execution-model) for scan-cycle state.

***

## timers.st

**Timer function blocks** with short time presets (2 ms) so traces are easy to read in tests.

| FB    | Signals                                                                        |
| ----- | ------------------------------------------------------------------------------ |
| `TON` | On-delay: **`Done`** follows **`Delay.Q`**, **`Elapsed`** reads **`Delay.ET`** |
| `TP`  | Pulse: **`PulseActive`** follows **`Pulse.Q`**                                 |

Both timers have **`IN := TRUE`** with **`PT := T#2ms`**. Run multiple cycles to watch **`ET`** and output bits evolve.

```bash
cargo run -p rbcpp_cli -- run examples/timers.st --cycles 5
```

***

## conversions.st

**Type conversion and string parsing** through the standard library in one program.

| Call                                                                  | Purpose               |
| --------------------------------------------------------------------- | --------------------- |
| `STRING_TO_INT`, `STRING_TO_REAL`, `STRING_TO_BOOL`, `STRING_TO_TIME` | Parse literal strings |
| `TRUNC`                                                               | Real toward integer   |
| `INT_TO_BCD` / `BCD_TO_INT` / `WORD_BCD_TO_UINT`                      | BCD paths             |
| `INT_TO_TIME`                                                         | Duration from integer |
| `CONCAT`, `BOOL_TO_STRING`, `INT_TO_STRING`                           | Build a result string |

Good file for **`check`** diagnostics on invalid literals (try breaking a string on purpose). See [Standard library](/standard-library).

```bash
cargo run -p rbcpp_cli -- check examples/conversions.st
```

***

## strings\_dates.st

Focuses on **bounded strings** and **date/time literals**, plus string manipulation.

| Feature                                         | In the example                |
| ----------------------------------------------- | ----------------------------- |
| `STRING[16]`                                    | Fixed-length string variables |
| `DATE`, `TIME_OF_DAY`, `DATE_AND_TIME` literals | `D#`, `TOD#`, `DT#` forms     |
| `LEFT`, `RIGHT`, `CONCAT`, `INSERT`, `FIND`     | Table 29-style string ops     |

Does not exercise every date/time **function** from Table 30; pair with **`conversions.st`** for conversion-heavy paths.

```bash
cargo run -p rbcpp_cli -- run examples/strings_dates.st --cycles 1
```

***

## aggregates.st

**Derived types** and aggregate assignment in Structured Text.

| Type                    | Use                                |
| ----------------------- | ---------------------------------- |
| `Small`                 | Subrange `INT(0..10)`              |
| `Mode`                  | Enumeration `Idle`, `Run`, `Fault` |
| `Pair`                  | Structure with two `Small` fields  |
| `ARRAY [1..3] OF Small` | Array with initializer list        |

The body updates **`Values[2]`**, copies into **`Window.Low`**, assigns **`State`**, compares enum to bool, and sums into **`Total`**. Exercises **whole-array** and **structure field** updates where implemented.

```bash
cargo run -p rbcpp_cli -- check examples/aggregates.st
cargo run -p rbcpp_cli -- run examples/aggregates.st --cycles 1
```

See [Types and variables](/types-and-variables).

***

## st\_bit\_ops.st

**Bitwise and boolean expressions** on `INT` and `BOOL` without function blocks.

* **`Mask`**: combines `15 AND 51` with `1 XOR 3` using `OR`
* **`Inverted`**: `NOT` on integer 15
* **`Flag`**: boolean `AND` / `OR`

Useful when testing **short-circuit** behavior and integer bit ops in ST. See [Structured Text](/structured-text).

```bash
cargo run -p rbcpp_cli -- run examples/st_bit_ops.st --cycles 1
```

***

## instruction\_list.st

Minimal **Instruction List** program using the accumulator model.

| IL           | Effect                                 |
| ------------ | -------------------------------------- |
| `LD` / `ST`  | Load and store through the accumulator |
| `ADD`        | Add into accumulator                   |
| `GT`         | Compare, leave result in accumulator   |
| `AND (expr)` | Parenthesized boolean expression       |

**`C`** receives **`A + B`**; **`Bigger`** is true when that sum exceeds 5; **`Complex`** combines boolean logic.

```bash
cargo run -p rbcpp_cli -- check examples/instruction_list.st
cargo run -p rbcpp_cli -- run examples/instruction_list.st --cycles 2
```

See [IL and SFC](/il-and-sfc).

***

## instruction\_list\_calls.st

IL **function block calls** and conditional return.

| IL                               | Effect                                              |
| -------------------------------- | --------------------------------------------------- |
| `CALC Counter(...)`              | Call `CTU` with named parameters                    |
| `LD Counter.Q` / `LD Counter.CV` | Read FB outputs after call                          |
| `RETC`                           | Return when accumulator is true (skip following IL) |

**`Skipped`** is only assigned if execution continues past **`RETC`**. Run multiple cycles to see **`CTU`** state and **`RETC`** interaction.

```bash
cargo run -p rbcpp_cli -- run examples/instruction_list_calls.st --cycles 3
```

***

## instruction\_list\_jumps.st

IL **labels and jumps** for control flow.

1. If **`Count >= 3`**, jump to **`DoneLabel`** and set **`Done`**
2. Otherwise increment **`Count`** and jump to **`EndLabel`**

Demonstrates **`JMPC`**, unconditional **`JMP`**, and labeled lines. Pair with **`instruction_list.st`** when debugging jump targets.

```bash
cargo run -p rbcpp_cli -- run examples/instruction_list_jumps.st --cycles 5
```

***

## sfc\_sequence.st

Simplest **textual SFC**: one initial step, one transition, one action.

| SFC element              | Role                           |
| ------------------------ | ------------------------------ |
| `INITIAL_STEP Start`     | Entry step                     |
| `STEP Run`               | Active step with bound action  |
| `TRANSITION Go := Ready` | Fires when **`Ready`** is true |
| `ACTION Run`             | Sets **`Done := TRUE`**        |

The runtime uses a **deterministic SFC interpreter** with transition-before-step ordering that matches generated C. See [IL and SFC](/il-and-sfc) for qualifier coverage.

```bash
cargo run -p rbcpp_cli -- run examples/sfc_sequence.st --cycles 3
cargo run -p rbcpp_cli -- sfc-compliance
```

***

## sfc\_qualifiers.st

**SFC action qualifiers** in source form: pulse (`P`), delay (`D`), and limit (`L`) with time operands.

Each action increments a counter (**`PulseCount`**, **`DelayCount`**, **`LimitCount`**) so you can see which steps fired in traces. Qualifiers **`P`**, **`D`**, and **`L`** execute through the SFC action-control paths covered by the compliance suite.

```bash
cargo run -p rbcpp_cli -- run examples/sfc_qualifiers.st --cycles 10
```

***

## configuration.st

Full **configuration / resource / task** layout, not just a bare program.

| Element                            | Purpose                                       |
| ---------------------------------- | --------------------------------------------- |
| `ConfiguredProgram`                | Body increments **`Count`** each time it runs |
| `VAR_GLOBAL PlantOffset`           | Configuration-wide global                     |
| `VAR_CONFIG Tunable AT %MW10`      | Located configurable variable                 |
| `VAR_ACCESS StartAccess AT %MX0.0` | Named access path for external reads/writes   |
| `TASK Fast`                        | 10 ms interval, priority 1                    |
| `PROGRAM Main WITH Fast`           | Schedules the program instance on the task    |

```bash
cargo run -p rbcpp_cli -- run examples/configuration.st --configuration Plant --cycles 2
```

Inject writes through access paths during simulation:

```bash
cargo run -p rbcpp_cli -- run examples/configuration.st --configuration Plant --cycles 2 --access StartAccess=TRUE
cargo run -p rbcpp_cli -- run examples/configuration.st --configuration Plant --cycles 3 --access 1:StartAccess=TRUE
```

Use **`CYCLE:NAME=VALUE`** when the write should land on a specific scan. See [Execution model](/execution-model).

See [Execution model](/execution-model) and [Types and variables](/types-and-variables).

***

## all\_data\_types.st

**Type surface tour.** One program declares nearly every elementary and derived form RoboC++ models in a single place.

| Construct                  | What you learn                                           |
| -------------------------- | -------------------------------------------------------- |
| `TYPE` blocks              | Enums, subranges, array aliases, structures              |
| Typed literals             | `BOOL#`, `SINT#`, `REAL#`, `T#…`, `D#…`, `TOD#…`, `DT#…` |
| Bit strings                | `BYTE`, `WORD`, `DWORD`, `LWORD` with hex literals       |
| `STRING[n]` / `WSTRING[n]` | Fixed-length strings and wide strings                    |
| Repeated array init        | `Samples : Counts := [4(0)]`                             |
| Struct aggregate init      | `(Mode := Enabled, Load := 42, Name := 'joint')`         |

```bash
cargo run -p rbcpp_cli -- check examples/all_data_types.st
cargo run -p rbcpp_cli -- run examples/all_data_types.st --cycles 1
```

***

## instruction\_list.il

Same **Instruction List** accumulator pattern as `instruction_list.st`, but stored in a standalone **`.il`** file. The CLI loader treats **`.st`**, **`.il`**, and **`.sfc`** the same way: parse into a `PROGRAM` POU.

```bash
cargo run -p rbcpp_cli -- run examples/instruction_list.il --cycles 2
```

***

## sequence.sfc

**Textual SFC in a standalone `.sfc` file.** Uses labeled steps, explicit `TRANSITION … FROM … TO … END_TRANSITION`, and named `ACTION` bodies.

```bash
cargo run -p rbcpp_cli -- run examples/sequence.sfc --cycles 3
```

Compare with `sfc_sequence.st`, which embeds SFC inside a `.st` project.

***

## native\_ladder.ld

**Native textual Ladder Diagram** with **`LADDER`**, labeled **`RUNG`** blocks, series contacts, negated contacts, coils, and set coils.

```bash
cargo run -p rbcpp_cli -- run examples/native_ladder.ld --cycles 2
```

See [Native LD and FBD](/native-ld-fbd).

***

## native\_fbd.fbd

**Native textual Function Block Diagram** with **`FBD`**, a **`NETWORK`** block, and ordered **`OUT`** assignments using standard functions.

```bash
cargo run -p rbcpp_cli -- run examples/native_fbd.fbd --cycles 2
```

***

## plcopen\_ld.xml, plcopen\_fbd.xml, plcopen\_sfc.xml

**Graphical POUs** imported from PLCopen XML. Use these to exercise LD power-flow lowering, FBD data-flow lowering, and graphical SFC topology (branches, macro steps, jump targets).

```bash
cargo run -p rbcpp_cli -- import-plcopen examples/plcopen_ld.xml
cargo run -p rbcpp_cli -- check examples/plcopen_fbd.xml
cargo run -p rbcpp_cli -- run examples/plcopen_sfc.xml --cycles 3
```

See [PLCopen](/plcopen) for lowering details and export round-trips.

***

## What to read next

<CardGroup cols={2}>
  <Card title="Architecture" icon="lucide:blocks" href="/architecture">
    How examples flow through each crate.
  </Card>

  <Card title="Structured Text" icon="lucide:braces" href="/structured-text">
    Statement and expression coverage.
  </Card>

  <Card title="IL and SFC" icon="lucide:git-branch" href="/il-and-sfc">
    IL operators and textual SFC.
  </Card>

  <Card title="Native LD and FBD" icon="lucide:layout-grid" href="/native-ld-fbd">
    LADDER/RUNG and FBD/NETWORK syntax.
  </Card>

  <Card title="Standard library" icon="lucide:library" href="/standard-library">
    FBs and functions used in examples.
  </Card>
</CardGroup>


---

*Powered by [holocron.so](https://holocron.so)*