plc-format-converter 2.0.1

Modern ACD ↔ L5X conversion library with industrial-grade validation and motion control support

PLC Format Converter - a python library

Modern ACD ↔ L5X conversion library with industrial-grade validation and motion control support

Convert between Rockwell Automation's PLC file formats with comprehensive validation, motion control detection, and safety system support.

✨ Key Features

• 🔄 Bidirectional Conversion - ACD ↔ L5X with data integrity
• 🏭 Industrial-Grade Validation - Multi-tier validation framework
• ⚡ Motion Control Support - MAOC, MAPC, MAAT instruction detection
• 🛡️ Safety System Support - GuardLogix safety instruction validation
• 🎯 Type-Safe - Built with Pydantic for robust data models
• 📊 Comprehensive Reporting - Detailed validation reports
• 🌐 Cross-Platform - Works on Windows, Linux, macOS
• 📦 Easy Installation - Available via pip

🚀 Quick Start

Installation

# Install the library
pip install plc-format-converter

# Install with optional dependencies
pip install plc-format-converter[all]  # All features
pip install plc-format-converter[acd-tools]  # ACD support only  
pip install plc-format-converter[l5x]  # Enhanced L5X support

Basic Usage

from plc_format_converter import ACDHandler, L5XHandler, PLCValidator

# Convert ACD to L5X
acd_handler = ACDHandler()
l5x_handler = L5XHandler()

# Load ACD project
project = acd_handler.load("MyProject.ACD")
print(f"Loaded: {project.name} ({project.controller.processor_type})")

# Validate before conversion
validator = PLCValidator()
result = validator.validate_project(project)
print(f"Validation: {'✅ PASS' if result.is_valid else '❌ FAIL'}")

# Save as L5X
l5x_handler.save(project, "MyProject.L5X")
print("✅ Conversion completed!")

📚 Documentation

Format Handlers

ACD Handler - Automation Control Database

from plc_format_converter.formats import ACDHandler

handler = ACDHandler()

# Check capabilities
caps = handler.get_capabilities()
print(f"Motion Control: {caps['features']['motion_control']}")
print(f"Safety Systems: {caps['features']['safety_systems']}")

# Load ACD file
project = handler.load("Industrial_System.ACD")

# Access project components
for program in project.programs:
    print(f"Program: {program.name}")
    for routine in program.routines:
        print(f"  Routine: {routine.name} ({routine.type.value})")

L5X Handler - Logix Designer Export Format

from plc_format_converter.formats import L5XHandler

handler = L5XHandler()

# Load L5X file
project = handler.load("Production_Line.L5X")

# Analyze structured text for motion instructions
for program in project.programs:
    for routine in program.routines:
        if routine.type.value == "ST" and routine.structured_text:
            if "MAOC" in routine.structured_text:
                print(f"🎯 Motion instruction found in {routine.name}")

# Save with modifications (full round-trip support)
handler.save(project, "Modified_Production_Line.L5X")

Validation Framework

from plc_format_converter.utils import PLCValidator

validator = PLCValidator()

# Configure validation options
validation_options = {
    'capabilities': True,      # Controller capability validation
    'data_integrity': True,    # Data consistency checks  
    'instructions': True       # Motion/safety instruction validation
}

# Run comprehensive validation
result = validator.validate_project(project, validation_options)

# Analyze results
print(f"Status: {'✅ PASS' if result.is_valid else '❌ FAIL'}")
print(f"Issues: {len(result.issues)}")

# Show detailed issues
for error in result.get_errors():
    print(f"❌ {error.category}: {error.message}")
    if error.recommendation:
        print(f"   💡 {error.recommendation}")

# Generate detailed report
report = validator.generate_validation_report(result)
with open("validation_report.txt", "w") as f:
    f.write(report)

Supported Controllers

Controller	Programs	Tags	Motion	Safety	I/O Modules
ControlLogix	1,000	250,000	✅	❌	128
CompactLogix	100	32,000	✅	❌	30
GuardLogix	1,000	250,000	✅	✅	128

🔧 Advanced Usage

Custom Validation Rules

from plc_format_converter.utils import PLCValidator, ValidationIssue, ValidationSeverity

class CustomValidator(PLCValidator):
    def validate_naming_conventions(self, project, result):
        """Custom naming convention validation"""
        for program in project.programs:
            if not program.name.startswith("PGM_"):
                result.add_issue(ValidationIssue(
                    severity=ValidationSeverity.WARNING,
                    category="naming_convention", 
                    message=f"Program {program.name} doesn't follow PGM_ convention",
                    component=f"Program.{program.name}",
                    recommendation="Use PGM_ prefix for all programs"
                ))

validator = CustomValidator()
result = validator.validate_project(project)

Batch Processing

from pathlib import Path

def batch_convert_l5x_files(input_dir: str, output_dir: str):
    """Convert multiple L5X files with validation"""
    handler = L5XHandler()
    validator = PLCValidator()
    
    for l5x_file in Path(input_dir).glob("*.L5X"):
        try:
            # Load and validate
            project = handler.load(l5x_file)
            result = validator.validate_project(project)
            
            # Save processed file
            output_file = Path(output_dir) / f"validated_{l5x_file.name}"
            handler.save(project, output_file)
            
            print(f"✅ {l5x_file.name}: {len(result.issues)} issues")
            
        except Exception as e:
            print(f"❌ {l5x_file.name}: {e}")

# Process all files in directory
batch_convert_l5x_files("input_projects/", "validated_projects/")

🛠️ Development

Setting Up Development Environment

# Clone repository
git clone https://github.com/plc-gpt/plc-format-converter.git
cd plc-format-converter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting and formatting
ruff check src/
ruff format src/
black src/

Project Structure

plc-format-converter/
├── src/plc_format_converter/
│   ├── __init__.py              # Package initialization
│   ├── core/
│   │   ├── models.py            # Core data models (Pydantic)
│   │   └── converter.py         # Main converter logic
│   ├── formats/
│   │   ├── __init__.py
│   │   ├── acd_handler.py       # ACD format handler
│   │   └── l5x_handler.py       # L5X format handler
│   └── utils/
│       ├── __init__.py
│       └── validation.py        # Validation framework
├── tests/                       # Comprehensive test suite
├── docs/                        # Documentation
├── pyproject.toml              # Package configuration
└── README.md                   # This file

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=plc_format_converter

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m "not slow"    # Skip slow tests

📖 API Reference

Core Models

All data models are built with Pydantic for type safety:

from plc_format_converter.core.models import (
    PLCProject,          # Root project container
    PLCController,       # Controller configuration  
    PLCProgram,          # Program container
    PLCRoutine,          # Individual routines
    PLCTag,              # Tag definitions
    PLCDevice,           # I/O devices
    DataType,            # PLC data types enum
    RoutineType,         # Routine types enum  
)

# Create a new project
project = PLCProject(
    name="MyProject",
    controller=PLCController(
        name="MainController", 
        processor_type="ControlLogix"
    )
)

Error Handling

from plc_format_converter.core.models import (
    ConversionError,     # General conversion errors
    FormatError,         # Format-specific errors  
    ValidationError      # Validation errors
)

try:
    project = handler.load("corrupted_file.L5X")
except FormatError as e:
    print(f"Format error: {e}")
except ConversionError as e:
    print(f"Conversion error: {e}")

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: pytest
5. Submit a pull request

Code Quality

This project uses:

• Ruff for linting and formatting
• Black for code formatting
• MyPy for static type checking
• Pytest for testing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Rockwell Automation for PLC file format specifications
• acd-tools library for ACD parsing capabilities
• l5x library for L5X processing
• The industrial automation community for feedback and contributions

📊 Project Status

• ✅ Stable: Core format conversion functionality
• ✅ Stable: Validation framework
• ✅ Stable: Motion control instruction detection
• ✅ Beta: Safety system validation
• 🚧 Development: Advanced analytics and reporting
• 📋 Planned: Real-time monitoring capabilities

🔗 Related Projects

• PLC-GPT - AI-powered PLC programming assistant
• Studio 5000 Integration - Windows COM automation
• Format Compatibility Checker - Legacy validation tools

---

For the latest updates and detailed documentation, visit our documentation site.