POU to Markdown Converter

A modular Python tool that converts Beckhoff TwinCAT 3 .TcPOU files into Mermaid diagrams embedded in Markdown (.md) documents.

Features

• Class Diagrams (classDiagram): Automatically extracts IEC 61131-3 declarations (PROGRAM, FUNCTION_BLOCK, FUNCTION) with variable sections (VAR_INPUT, VAR_OUTPUT, VAR_IN_OUT, VAR), types, and initial values.
• Continuous Function Chart (CFC): Reconstructs the signal flow graph (flowchart LR) from <CFC> XML structures, resolving pins, operators, function blocks, program calls, and wiring.
• Function Block Diagram (FBD): Recursively parses <NWL> trees, resolving nested calls, pass-through assignments, and negated inputs.
• Ladder Diagram (LD): Automatically detects LD view mode, formatting contacts (┤├), coils (( )), and jump labels (▶ Label).
• Structured Text (ST): Embeds the original IEC 61131-3 source code in an iecst code block alongside the declaration class diagram.
• Minimal Runtime Dependencies: Uses only the Python standard library on Python 3.11+; Python 3.10 installs tomli for TOML configuration support.

Architecture

pou2md/
├── __init__.py
├── __main__.py          # CLI entry point
├── converter.py         # Main conversion orchestrator
├── model/
│   ├── declaration.py   # PouDeclaration, VarGroup, Variable dataclasses
│   └── flow_graph.py    # FlowNode, FlowEdge, NetworkDiagram, FlowGraph dataclasses
├── parser/
│   ├── declaration.py   # IEC 61131-3 CDATA declaration parser
│   ├── nwl_parser.py    # Network List parser (FBD & LD)
│   ├── cfc_parser.py    # Continuous Function Chart parser
│   └── st_parser.py     # Structured Text parser
├── renderer/
│   ├── class_diagram.py # Mermaid classDiagram generator
│   └── flowchart.py     # Mermaid flowchart LR generator
└── writer/
    └── markdown.py      # Markdown document generator

Installation & CLI Setup

Install the package using pip (editable mode is recommended during development):

# Editable install (recommended)
pip install -e .

# Or standard install
pip install .

Once installed, the CLI tool can be executed from any terminal or directory using pou2md (or via Python's -m switch):

# Global CLI command
pou2md [input] [options]

# Standard Python module syntax
python -m pou2md [input] [options]

CLI Reference

Command Syntax

pou2md [input] [-o OUTPUT] [-r] [-u] [--single-folder] [--copy-folder-structure] [--exclude PATTERN] [--dry-run] [--clean] [--stdout] [-w] [--curve {step,stepAfter,linear,basis,none}] [--no-bifurcate] [--repeat-inputs]

Options & Arguments

Output Resolution Rules

The destination path depends on the input type and flags provided:

When both individual and unified output are requested with -o path/to/file.md, the unified document uses that exact path and individual files are written to its parent directory.

Continuous Watching (-w)

Use -w to perform an initial conversion and then keep the process running while watching for added, modified, or removed .TcPOU files. The watcher polls the input path, debounces editor save operations, and releases its lock file when stopped with Ctrl+C.

# Watch a directory and update individual generated files
pou2md MyPlcProject/ -r -w -o docs/generated/

# Watch a directory and rebuild one unified document
pou2md MyPlcProject/ -r -u -w -o docs/complete_system_manual.md

# Watch one file and print each generated document to stdout
pou2md POUs/FB_Motor.TcPOU -w

For directory input, specify -o/--output or --stdout, just as with a one-time conversion. When a source file is removed, its generated individual Markdown file is removed as well; unified output files are rebuilt instead.

Output mode combinations are:

The default polling interval is one second, followed by a 250 ms save debounce. This is normally suitable for mapped drives and SMB shares, but network latency can make detection slower and a temporarily unavailable share is skipped until the next poll. The watcher uses an atomic lock-file claim, so two processes started for the same target cannot both watch it; the second process exits with an error. Different output targets intentionally use separate locks.

Parsing errors are reported to stderr and do not terminate the watcher. This allows editors to save an incomplete XML document temporarily: the watcher waits and retries that file after the next change. The same behavior applies to an incomplete file present when the watcher starts.

Generated Markdown is written through a temporary sibling file and atomically replaced into place, preventing readers from seeing partially written output. Use --exclude to ignore backup or generated sources, for example:

pou2md MyPlcProject/ -r -w -o docs/ --exclude "Backup/*" --exclude "*_old.TcPOU"

Use --verbose for diagnostic status logging or --quiet to suppress normal status messages while retaining errors. Watcher timing can be tuned with --poll-interval, --debounce-delay, --retry-count, and --retry-delay.

Dry runs, cleanup, and manifests

Use --dry-run to inspect the output plan without creating files:

pou2md MyPlcProject/ -r --copy-folder-structure --dry-run -o docs/

When writing to an output directory, the converter maintains .pou2md-manifest.json containing the generated Markdown paths. --clean removes only stale paths recorded in that manifest; it never scans for or deletes untracked files:

pou2md MyPlcProject/ -r --clean -o docs/

Use JSON logs for automation:

pou2md MyPlcProject/ -r -w -o docs/ --log-format json

Project configuration

Arguments can be saved in a committed pou2md.toml file:

input = "POUs"
output = "docs"
recursive = true
unified = true
copy_folder_structure = true
exclude = ["Backup/*"]

Run it with:

pou2md --config pou2md.toml

Built-in defaults are overridden by the TOML file, and explicit command-line arguments override the TOML values.

Use pou2md --version when reporting issues so the exact installed converter version is known. Invalid XML errors include the source filename and XML location, while the watcher preserves the last valid output.

Practical CLI Recipes

1. Quick Inspection & Terminal Piping

Inspect generated Markdown or pipe directly into tools like bat, glow, or clipboard utilities:

# Print POU markdown directly to stdout
pou2md POUs/FB_Motor.TcPOU --stdout

# Pipe output to a markdown viewer (bat, glow, etc.)
pou2md POUs/FB_Motor.TcPOU --stdout | bat -l md

# Copy markdown directly to clipboard (Windows PowerShell)
pou2md POUs/FB_Motor.TcPOU --stdout | Set-Clipboard

2. Single File Conversion

Convert an individual POU into a specific output directory or custom filename:

# Save to an output directory (produces output/FB_Motor.md)
pou2md POUs/FB_Motor.TcPOU -o output/

# Save to a specific custom filename
pou2md POUs/FB_Motor.TcPOU -o docs/motor_controller.md

3. Batch Directory Conversion

Convert all .TcPOU files located directly inside a folder:

pou2md POUs/ -o docs/pous/

4. Recursive Project Conversion (-r)

Recursively scan complete TwinCAT PLC project structures. The converter flattens nested folder hierarchies into distinct, clash-free filenames:

pou2md MyPlcProject/ -r -o docs/generated/

Example name mapping:

• MyPlcProject/Motion/Axes/FB_Axis.TcPOU → docs/generated/Motion--Axes--FB_Axis.md
• MyPlcProject/Diagnostics/FB_Logger.TcPOU → docs/generated/Diagnostics--FB_Logger.md

5. Unified Single-Document Generation (-u)

Merge your entire PLC library or project into a single Markdown document. Perfect for single-page project wikis, Obsidian vaults, or MkDocs:

# Save as default unified.md in target directory
pou2md MyPlcProject/ -r -u -o docs/

# Save with a custom documentation filename
pou2md MyPlcProject/ -r -u -o docs/complete_system_manual.md

# Stream the entire unified manual to stdout for downstream processing
pou2md MyPlcProject/ -r -u --stdout > complete_system_manual.md

Diagram Layout & Styling Customization

pou2md provides dedicated flags to fine-tune the look and layout of Mermaid flowcharts to match industrial PLC schematics:

Wire Routing (--curve)

Select how signal connection lines are interpolated:

# Default: Orthogonal right angles entering nodes horizontally (industrial CAD style)
pou2md POUs/FB_Controller.TcPOU -o docs/ --curve step

# Smooth cubic splines (fluid curves)
pou2md POUs/FB_Controller.TcPOU -o docs/ --curve basis

# Direct point-to-point straight lines
pou2md POUs/FB_Controller.TcPOU -o docs/ --curve linear

# Standard Mermaid default curve interpolation
pou2md POUs/FB_Controller.TcPOU -o docs/ --curve none

Output Bifurcation Junctions (--no-bifurcate)

When an output pin connects to multiple downstream blocks:

• Default (Bifurcation enabled): Splits wires using a clean junction dot ((( ))), preventing duplicate pin labels and visual clutter.
• --no-bifurcate: Draws separate, independent wires directly from the output pin to every target node.

# Disable bifurcation junctions
pou2md POUs/FB_Controller.TcPOU -o docs/ --no-bifurcate

CFC Input Variable Duplication (--repeat-inputs)

In large Continuous Function Charts (CFC), multiple blocks often share common inputs (e.g. bEnable or stConfig):

• Default (False): Creates a single node for each input variable and connects it across the diagram.
• --repeat-inputs: Creates an input variable block next to each block pin it feeds, eliminating long feedback loops and wires crossing through the middle of the sheet.

pou2md POUs/CFC_PlantControl.TcPOU -o docs/ --repeat-inputs

CI / CD & Automation Integration

GitHub Actions Workflow Example

Automatically generate up-to-date Markdown diagrams whenever PLC files are pushed:

name: Generate PLC Documentation
on: [push, pull_request]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install converter
        run: pip install .
      - name: Build documentation
        run: pou2md src/ -r -u -o docs/plc_architecture.md
      - name: Upload documentation artifact
        uses: actions/upload-artifact@v4
        with:
          name: plc-docs
          path: docs/plc_architecture.md

Shell Automation Scripts

PowerShell (Windows):

# Convert all POU subdirectories into separate documentation folders
Get-ChildItem -Directory "src/PLC/*" | ForEach-Object {
    pou2md $_.FullName -r -o "docs/$($_.Name)"
}

Bash (Linux / macOS):

# Compile documentation for each PLC subsystem
for dir in src/PLC/*/; do
  name=$(basename "$dir")
  pou2md "$dir" -r -u -o "docs/${name}.md"
done

Exit Codes

For CI/CD scripts and automated tools, the CLI returns standard status codes:

• 0: Execution completed successfully.
• 1: Error encountered (e.g. input path does not exist, or directory input without -o / --stdout).

Running Tests

Run the test suite using Python's standard unittest module:

python -m unittest tests/test_converter.py -v

Disclaimer & AI Disclosure

License

This project is licensed under the MIT License.