# project_config.md
_Last updated: 2025-07-30_

## Goal  
Create a modular and automated flow for generating, structuring, and compiling PLC projects from raw input data to final ACD output, with cross-platform development capabilities.

## Tech Stack  
- **Language**: Python 3.12 (Linux), Python 3.11+ (Windows compatibility)
- **Development Environment**: Native Linux virtual environment (WSL2/Ubuntu)
- **Core Libraries**: pandas, openpyxl, numpy, xml.etree.ElementTree, pathlib  
- **Web Framework**: Flask, Werkzeug, Jinja2 (for web application)
- **Compilation Tools**: Logix Designer SDK (Windows-only, via hybrid approach)
- **Platform Support**: Linux development, Windows compilation (hybrid workflow)
- **Environment Management**: Native Linux venv, cross-platform compatibility

## PLC GENERATION Flow (Hybrid Linux/Windows)
1. **PLC Data Generator** *(Linux)*
   - Parses raw network/device data and descriptor sheets.  
   - Outputs: structured descriptor-IP file with calculated columns.

2. **Routines Generator** *(Linux)*
   - Uses enriched descriptors to generate tags and logic routines.  
   - Outputs: SafetyProgram and MainProgram L5X files.

3. **IO Tree Configuration Generator** *(Linux)*
   - Builds IO tree and module hierarchy.  
   - Embeds generated programs and creates complete project structure.
   - Outputs: Complete `.L5X` project file ready for compilation.

4. **L5X2ACD Compiler** *(Windows via Hybrid)*
   - **Linux Phase**: Generates Windows batch file with proper paths
   - **Windows Phase**: Invokes Logix Designer SDK via generated batch file  
   - Outputs: `.ACD` compiled project ready for deployment

## Patterns  
- One module per phase of generation.  
- snake_case naming convention.  
- Pure functions, no implicit side-effects.  
- Config and file paths externalized in YAML/ENV files.

## Constraints  
- **Linux Development**: Phases 1-3 run natively on Linux subsystem (WSL2/Ubuntu)
- **Windows Compilation**: Phase 4 requires Windows environment for Logix Designer SDK
- **Hybrid Workflow**: Seamless file sharing via WSL mounts (`/mnt/c/`)
- **No Studio 5000 UI**: SDK-only compilation flow via automated batch files
- **Intermediate Artifacts**: Reusable L5X files between Linux generation and Windows compilation  
- **Offline Operation**: Works offline after initial SDK setup on Windows
- **Firmware Compatibility**: Compatible with v33 and later firmware
- **Single Command**: Complete workflow executable with one Linux terminal command

## Changelog  
- 2025-01-22: Linux subsystem migration analysis completed - hybrid approach recommended.
- 2025-07-23: Synced structure with project UI: 4-phase PLC generator flow.
- 2025-07-30: **Linux migration completed successfully** - Full hybrid workflow operational with native Linux virtual environment, streamlined codebase, and one-command generation pipeline.

## Current Operational Commands

### Linux Development Environment
```bash
# Activate native Linux virtual environment
source venv/bin/activate

# Complete PLC generation workflow (Excel → L5X)
python "Routines Generator/complete_workflow.py" \
  --excel-file "PLC Data Generator/data/IO Assignment_MTN6_MCM01_COMPLETE_UL1_UL3.xlsm" \
  --project-name MTN6_MCM01_UL1_UL3

# Web application (optional)
python plc_web_app.py
```

### Windows Compilation (when needed)
```batch
# Run generated batch file for ACD compilation
L5X2ACD Compiler\compile_project.bat
```

## Project Types and Architecture

### **Supported MCM Project Types**
The system supports multiple MCM (Material Control Module) project configurations:

1. **MCM01 Projects** *(Unit Line Configuration)*
   - **Example**: `MTN6_MCM01_UL1_UL3` 
   - **Zones**: Unit Line based (UL1_1 to UL1_13, UL2_1 to UL2_10, UL3_1 to UL3_9)
   - **Applications**: Unit-based sorting and material handling
   - **Safety Logic**: Zone-based E-stop interlocks with unit line progression

2. **MCM04 Projects** *(Feeder Line Configuration)*
   - **Example**: `MTN6_MCM04_CHUTE_LOAD`
   - **Zones**: Feeder Line based (FL1014, FL1018, FL1022, FL1026, FL1034, FL1038, FL3012, FL3016, FL3020, FL3024)
   - **Applications**: Feeder conveyor systems with multiple discharge points
   - **Safety Logic**: Feeder-specific E-stop and zone control

3. **MCM05 Projects** *(Future/Custom Configuration)*
   - **Status**: Data file present, configuration to be defined
   - **Applications**: Custom material control configurations

### **Module Type Architecture**
The system automatically detects and configures multiple hardware module types:

**Communication Modules:**
- **APF/VFD**: Allen-Bradley PowerFlex drives with Ethernet/IP communication
- **M12DR**: IO-Link master modules with 16-channel M12 connectivity
- **Hub (FIOH)**: Turck Hub modules for distributed IO via IO-Link

**Local IO Modules:**
- **IB16**: 16-point digital input modules (local chassis slot-based)
- **OB16E**: 16-point digital output modules (local chassis slot-based) 
- **IB16S**: 16-point safety input modules (local chassis slot-based)

**Specialized Modules:**
- **ZMX**: Banner ZMX sensor/beacon modules
- **Extendo**: Extendo conveyor control modules
- **DPM**: Device Parameter Manager modules
- **TL70**: Banner TL70 Pro beacon modules with IO-Link
- **LPE**: Light Position Encoder modules
- **PMM**: Position Monitoring Modules
- **Festo Solenoids**: Pneumatic control via IO-Link

### **Data Flow Architecture**

**Phase 1: Data Processing** *(PLC Data Generator)*
```
Input:  Excel files with NETWORK and DESC sheets
├── Signal Classification: I/O/IOLink/SPARE categorization
├── Device Type Detection: APF/M12DR/Hub/IB16/OB16E/IB16S identification  
├── IO Path Mapping: Automatic path generation based on device types
└── Output: DESC_IP_MERGED.xlsx with safety sheets (RST/STO/EPC/ZONES)
```

**Phase 2: Logic Generation** *(Routines Generator)*
```
Input:  DESC_IP_MERGED.xlsx with safety device data
├── Safety Program: R010_INPUTS, R012_RESETS, R020_ESTOPS, R030_ZONES
├── Main Program: MainRoutine, R000_SAFETY_TAG_MAP, R100_ESTOP_CHECK
├── Controller Tags: 146 tags (Standard BOOL, Safety BOOL, DCS, Module UDT)
└── Output: SafetyProgram_Generated.L5X, MainProgram_Generated.L5X
```

**Phase 3: IO Tree Assembly** *(IO Tree Configuration Generator)*
```
Input:  DESC_IP_MERGED.xlsx + Generated L5X programs
├── Controller Build: L83ES controller with proper firmware settings
├── Module Generation: Device-specific boilerplate configurations
├── Program Integration: Embed SafetyProgram and MainProgram 
├── Tag Integration: Controller-level tag definitions
└── Output: Complete project L5X (1-4MB) ready for compilation
```

**Phase 4: Compilation** *(Hybrid Linux→Windows)*
```
Input:  Complete project L5X file
├── Linux Phase: Generate Windows batch file with proper paths
├── Windows Phase: Logix Designer SDK compilation (l5x_to_acd.py)
└── Output: Compiled ACD project ready for PLC deployment
```

### **Zone Configuration System**
Projects use zone-based safety logic with hierarchical E-stop control:

**MCM01 Zone Structure:**
```python
ZONES = [
    {"name": "MCM01", "start": "", "stop": "", "interlock": ""},           # Master MCM
    {"name": "ZONE 01-01", "start": "UL1_1", "stop": "UL1_13", "interlock": ""},
    {"name": "ZONE 01-02", "start": "UL2_1", "stop": "UL2_10", "interlock": "ZONE 01-01"},
    {"name": "ZONE 01-03", "start": "UL3_1", "stop": "UL3_9", "interlock": "ZONE 01-01"}
]
```

**MCM04 Zone Structure:**
```python
ZONES = [
    {"name": "MCM04", "start": "", "stop": "", "interlock": ""},          # Master MCM
    {"name": "FL1014", "start": "FL1014_2_VFD1", "stop": "FL1014_4_EX1", "interlock": ""},
    {"name": "FL1018", "start": "FL1018_2_VFD1", "stop": "FL1018_4_EX1", "interlock": ""},
    # ... additional feeder lines
]
```

### **File Integration Architecture**
```
Project Root/
├── PLC Data Generator/           # Phase 1: Excel data processing
│   ├── data/                    # Input Excel files by project type
│   ├── IO-To-Path.xlsx         # Device type to IO path mapping rules
│   └── DESC_IP_MERGED.xlsx     # Generated merged data with safety sheets
├── Routines Generator/          # Phase 2: Logic generation  
│   ├── SafetyProgram_Generated.L5X    # Safety routines and logic
│   ├── MainProgram_Generated.L5X      # Main program with controller tags
│   └── SafetyTagMapping.txt           # Safety tag cross-reference
├── IO Tree Configuration Generator/   # Phase 3: Complete project assembly
│   ├── models/                 # Device-specific boilerplate generators
│   ├── boilerplate/           # Template L5X files for each module type
│   └── generated_projects/    # Final complete L5X projects
└── L5X2ACD Compiler/           # Phase 4: Windows compilation
    ├── l5x_to_acd.py          # Logix Designer SDK compilation script
    └── compile_project.bat    # Auto-generated Windows batch file
```

## Architecture Summary
- **Development**: 100% Linux-native with WSL2/Ubuntu
- **Project Types**: MCM01/MCM04/MCM05 with distinct zone configurations  
- **Module Support**: 12+ hardware module types with automatic detection
- **Safety Integration**: Zone-based E-stop logic with hierarchical interlocks
- **Tag Generation**: Automatic controller tag creation (Standard/Safety/DCS/UDT)
- **Dependencies**: All Python packages installed in native Linux venv  
- **Generation**: Complete L5X project generation on Linux
- **Compilation**: Hybrid handoff to Windows via automated batch files
- **File Sharing**: Seamless via WSL mounts for cross-platform access
- **Performance**: Fast Linux development with maintained Windows SDK compatibility