Quick Start

This page gives the shortest practical path through pyfcstm: write one FCSTM file, simulate it, inspect the structured model report, generate code from a built-in template, and produce a PlantUML diagram source file.

For deeper explanations, continue to the dedicated tutorials linked from each step. This page intentionally stays small and uses the built-in template entry point --template instead of a repository-local template directory.

1. Write a small state machine

Create traffic_light.fcstm:

def int timer = 0;

state TrafficLight {
    [*] -> Red;

    state Red {
        enter { timer = 0; }
        during { timer = timer + 1; }
    }

    state Yellow {
        enter { timer = 0; }
        during { timer = timer + 1; }
    }

    state Green {
        enter { timer = 0; }
        during { timer = timer + 1; }
    }

    Red -> Green : if [timer >= 30];
    Green -> Yellow : if [timer >= 25];
    Yellow -> Red : if [timer >= 5];
}

2. Simulate the behavior

Run a few cycles without writing Python code:

pyfcstm simulate -i traffic_light.fcstm -e "cycle; cycle; current"

The simulator is useful for checking lifecycle actions and transition timing before generating target-language code. See FCSTM simulation first run for interactive sessions, hot start, batch mode, and execution semantics.

3. Inspect the model

inspect is human-readable by default. Use --format json when you want a structured report with states, transitions, metrics, derived graphs, and diagnostics:

pyfcstm inspect -i traffic_light.fcstm --format json -o traffic_light.inspect.json

The traffic light model is intentionally simple, so diagnostics may be empty. The dedicated First inspect report tutorial shows richer diagnostics, source spans, suggested fixes, and how these messages can guide LLM-assisted repairs.

4. Generate code from a built-in template

Use --template for packaged built-in templates:

pyfcstm generate -i traffic_light.fcstm --template python -o _quick_start_python --clear

The generated directory includes runtime code and generated README files. The full First generated runtime tutorial covers python, c, c_poll, cpp, and cpp_poll.

Use -t/--template-dir only when you are intentionally rendering with a custom template directory.

5. Generate a diagram source

For a stable, versionable diagram source file, use plantuml:

pyfcstm plantuml -i traffic_light.fcstm -o traffic_light.puml

When your environment has a PlantUML renderer available, visualize can render a final png / svg / pdf file directly:

pyfcstm visualize -i traffic_light.fcstm -t svg -o traffic_light.svg --no-open

The full visualization option matrix remains in First diagram.

What to expect

The commands above are intentionally independent from any external PlantUML renderer. A successful quick-start run should look like this in outline:

Current State: TrafficLight.Red
timer = 2
states: 4
transitions: 4
diagnostics: 0
_quick_start_python/machine.py
_quick_start_python/README.md
@startuml

The documentation build also runs quick_start.demo.sh from this directory to keep these examples reproducible. The script is a build-time smoke test rather than the recommended way to read the tutorial; for humans, copy the short commands in the sections above one at a time.