Spec2Control

LLM-workflow to translate control narratives into IEC 61131-3 function block diagrams (FBDs).

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Configure Azure OpenAI (create .env file)
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
# ... (see USAGE_GUIDE.md for complete setup)

# 3. Start backend (Terminal 1)
./start-backend.sh   # Linux/Mac
start-backend.bat    # Windows

# 4. Run processing (Terminal 2)
./process.sh --list                                      # See available narratives
./process.sh --narrative ammonium-nitrates --chapters 2  # Process single chapter

Documentation

• USAGE_GUIDE.md - Quick start guide with examples
• Spec2Control-Screencast.mp4: screencast with a test run (2:17 min)
• LLM workflows: Context Generation + FBD Generation
• PlantUML activity diagrams for LLM worfklows: Context Generation UML + FBD Generation UML

Features

• Converts natural language control narratives to PLCOpen TC6 XML
• Multi-step LLM prompt chain for structured FBD generation:
• Auto-layout engine with IEC 61131-3 semantic awareness
• OpenPLC compatible output
• Configurable via YAML or command-line arguments

Experiment Data

• experiment_results.xlsx: contains statistics about the FBDs and metrics from a test run
• _evaluation-script-output: contains the output of automated scripts that compared the LLM output with the baseline

Project Structure

├── data/
│   ├── control-narratives/      # Input: Process descriptions
│   ├── BASIC_LIB/               # Function block specifications
│   ├── prompt-sets/             # LLM prompt chains
│   ├── fbd-baseline/            # Manually reviewed FBDs
│   ├── fbd-GPT5-generated/      # FBDs generated by GPT-5 
│   ├── fbd-llm-output/          # Default output folder for new runs
│   ├── prompts-sets/            # LLM prompt chains to generate context and to generate FBDs
│   └── process_config.yaml      # Configuration file
├── src/
│   ├── spec2control_cli.py      # Main CLI tool
│   ├── spec2control_backend.py  # FastAPI backend
│   └── export_openplc.py        # PLCOpen XML generator
├── start-backend.sh/.bat        # Backend startup scripts
└── process.sh/.bat              # CLI wrapper scripts

Working with OpenPLC

After processing control narratives, Spec2Control generates PLCOpen TC6 XML files that can be opened in OpenPLC Editor.

Installing OpenPLC Editor

1. Download OpenPLC Editor:

   • Visit: https://autonomylogic.com/download/
   • Select "OpenPLC Editor" for your operating system (Windows/Linux/Mac)
   • Download and install the application

2. Alternative - Build from Source:

   git clone https://github.com/thiagoralves/OpenPLC_Editor.git
   cd OpenPLC_Editor
   # Follow build instructions in repository README
   

Opening Generated PLCOpen XML Files

Spec2Control generates a complete PLCOpen project that can be opened directly in OpenPLC Editor:

Step 1: Locate Output Folder

After processing, outputs are in data/fbd-llm-output/:

data/fbd-llm-output/
└── ammonium-nitrates_1003_143022/    # ← Open this folder in OpenPLC
    ├── plc.xml                        # Combined project file
    ├── chapter_2/
    │   ├── Section2.xml               # Individual chapter XML
    │   └── 2_control_logic.txt        # Textual FBD notation
    └── chapter_3/
        ├── Section3.xml
        └── 2_control_logic.txt

Step 2: Open in OpenPLC Editor

1. Launch OpenPLC Editor
2. Go to File → Open Project
3. Navigate to the output folder (e.g., data/fbd-llm-output/ammonium-nitrates_1003_143022/)
4. Select the folder itself (not the plc.xml file)
5. OpenPLC will load the entire project structure

Step 3: View Function Block Diagrams

• The left panel shows the project tree with all POUs (Program Organization Units)
• Each processed chapter appears as Section2, Section3, etc.
• Double-click any section to view its Function Block Diagram
• The auto-layout positions blocks according to IEC 61131-3 semantics

Understanding the Generated Structure

Project Components:

• Project Name: Matches the narrative name (e.g., ammonium-nitrates)
• Applications: One per chapter (e.g., Section2, Section3)
• POUs: Function Block Diagrams for each control section
• Variables: Input/output variables and internal signals
• Function Blocks: Standard IEC 61131-3 blocks from BASIC_LIB

File Formats:

• plc.xml - Complete PLCOpen TC6 XML project (combined)
• SectionN.xml - Individual chapter exports
• 2_control_logic.txt - Textual notation (for debugging)

Tips for Using Generated PLCOpen Projects

1. Verify Layout: Auto-layout positions blocks semantically; you can manually adjust if needed
2. Check Connections: All data connections and parameter assignments are pre-configured
3. Review Variables: Output variables are in the project's variable table
4. Export Options: OpenPLC Editor can export to various PLC formats
5. Simulation: Use OpenPLC Runtime to simulate the generated logic

Troubleshooting OpenPLC Import

"Cannot open project" error:

• Ensure you selected the folder, not the XML file
• Check that plc.xml exists in the selected folder
• Verify OpenPLC Editor version supports PLCOpen TC6 XML v2.01

"Invalid XML structure" error:

• Check 2_control_logic.txt for parsing issues in textual notation
• Review prompt_chain_log.md to see LLM generation steps
• Validate function block types exist in BASIC_LIB specifications

Missing function blocks:

• Standard IEC 61131-3 blocks (OR, AND, TON, etc.) are built-in
• Custom blocks from BASIC_LIB should be included in the XML
• Check data/BASIC_LIB/specification/ for block definitions

License

See LICENSE file for details.