Welcome to pyfcstm (Python Finite Control State Machine Framework)

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

Basic Usage

1. Define a State Machine in DSL

Create a file 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. Generate Code

pyfcstm generate -i traffic_light.fcstm -t templates/c/ -o output/

3. Visualize with PlantUML

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

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

Best Practice

API Documentation

Community and Support

License

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