Welcome to pyfcstm (Python Finite Control State Machine Framework)

Overview

pyfcstm (Python Finite Control State Machine Framework) is a powerful Python framework for parsing the FCSTM (Finite Control State Machine) Domain-Specific Language (DSL) and generating executable code in multiple target languages. It specializes in modeling Hierarchical State Machines (Harel Statecharts) with a flexible Jinja2-based template system.

Key Features

• Expressive DSL Syntax: Intuitive domain-specific language for defining states, transitions, events, and lifecycle actions

• Hierarchical State Machines: Full support for nested states with parent-child relationships and aspect-oriented programming

• Multi-Language Code Generation: Template-based rendering system supporting C, C++, Python, and custom target languages

• PlantUML Visualization: Automatic generation of state machine diagrams for documentation

• ANTLR4-Based Parser: Robust grammar parsing with detailed error reporting

• Flexible Event System: Local, chain, and global event scoping for complex state machine coordination

• Lifecycle Actions: Enter, during, and exit actions with before/after aspect support

• Abstract and Reference Actions: Declare abstract functions and reuse actions across states

Use Cases

pyfcstm is ideal for:

• Embedded Systems: Generate efficient state machine code for microcontrollers and IoT devices

• Protocol Implementations: Model communication protocols with complex state transitions

• Game AI: Design character behaviors and game logic with hierarchical state machines

• Workflow Engines: Implement business process workflows with clear state definitions

• Control Systems: Build industrial control logic with safety-critical state management

Quick Start

Installation

pip install pyfcstm

The full installation checklist is in Install pyfcstm.

Fast Path

Create traffic_light.fcstm and follow the complete walkthrough in Quick Start. The shortest command sequence is:

pyfcstm simulate -i traffic_light.fcstm -e "cycle; cycle; current"
pyfcstm inspect -i traffic_light.fcstm --format json -o traffic_light.inspect.json
pyfcstm generate -i traffic_light.fcstm --template python -o generated --clear
pyfcstm plantuml -i traffic_light.fcstm -o traffic_light.puml

Use --template for packaged built-in templates. Use -t/--template-dir only when rendering with a custom template directory.

Architecture

pyfcstm follows a three-stage pipeline:

1. DSL Parsing: ANTLR4-based parser converts DSL text into Abstract Syntax Tree (AST)

2. Model Construction: AST nodes are transformed into a queryable state machine model

3. Code Generation: Jinja2 templates render the model into target language code

The framework provides:

• DSL Layer (pyfcstm.dsl): Grammar definition, parser, and AST nodes

• Model Layer (pyfcstm.model): State machine model classes with validation

• Rendering Engine (pyfcstm.render): Template-based code generation with expression styles

• CLI Tools (pyfcstm.entry): Command-line interface for common operations

Tutorials

Tutorials provide learning paths and first-success walkthroughs. The roadmap is listed first, followed by the concrete tutorial pages so the left navigation can show the whole learning path directly from this home page.

• Tutorial roadmap

• Quick Start

• Write your first FCSTM DSL model

• FCSTM simulation first run

• First inspect report

• First generated runtime

• First diagram

• Your First Bounded Model Check

How-to Guides

How-to guides are task-oriented pages. The roadmap is listed first, followed by concrete tasks so the left navigation exposes the available workflows without an extra click through a category page.

• How-to roadmap

• Install pyfcstm

• CLI workflows

• BMC Task Recipes

• DSL task guide

• Simulation tasks

• Inspect tasks

• Generation tasks

• Visualization tasks

• Template author tasks

• Grammar and editor tasks

Explanations

Explanations describe semantics, architecture, boundaries, and trade-offs. The map page comes first, then the individual explanation topics are listed directly in the global navigation.

• Explanation map

• Architecture explanation

• DSL semantics explanation

• Execution semantics explanation

• How FCSTM Becomes a Bounded Transition System

• Property Objectives, Definedness, and Bounds

• BMC solving, witnesses, and replay boundaries

• Diagnostics explanation

• Template rendering explanation

• Grammar tooling explanation

Reference

Reference pages are for exact facts. The map page is listed first and the generated API documentation remains the last item in this reference area.

• Reference map

• CLI reference

• DSL reference

• Inspect report reference

• Diagnostics code reference

• Simulation reference

• Visualization options reference

• Template configuration reference

• Grammar and editor tooling reference

• Built-in templates reference

• FBMCQ Language Reference

• BMC CLI and Result Protocol Reference

• API Documentation

Release Notes

• Release Notes

Community and Support

• GitHub Repository: https://github.com/HansBug/pyfcstm

• Issue Tracker: https://github.com/HansBug/pyfcstm/issues

• PyPI Package: https://pypi.org/project/pyfcstm/

License

pyfcstm is released under the Apache License 2.0. See the LICENSE file for details.