# MechBase PLC — Ladder Logic Interpreter v2
PLC ladder logic interpreter for the Technic Mechatronics set, targeting ESP32.
## Instructions
### Contacts (Input Logic)
| Symbol | Name | Description |
|--------|------|-------------|
| `--\| \|---` | **NO** | Normally Open — passes when TRUE |
| `--\|/\|---` | **NC** | Normally Closed — passes when FALSE |
| `--\|P\|---` | Rising Edge | Single-scan TRUE→FALSE transition |
| `--\|N\|---` | Falling Edge | Single-scan FALSE→TRUE transition |
| `T0.DN` | Timer Done | Timer has reached preset |
| `T0.TT` | Timer Timing | Timer is currently running |
| `T0.EN` | Timer Enable | Timer rung has power flow |
### Outputs
| Symbol | Name | Description |
|--------|------|-------------|
| `--( )--` | **OTE** | Output Energize — follows input power |
| `--(L)--` | **OTL** | Output Latch — SET, stays ON once set |
| `--(U)--` | **OTU** | Output Unlatch — RESET, clears latched output |
| `--(TON)--` | TON | Timer On-Delay |
| `--(TOF)--` | TOF | Timer Off-Delay |
| `--(TP)--` | TP | Timer Pulse |
### Timer Status Bits (All 3 types)
| Bit | Meaning |
|-----|---------|
| **EN** | Enable — controlling rung has power flow |
| **TT** | Timing — timer is currently counting |
| **DN** | Done — timer has reached preset |
### Network Structure
- **Input branches** — parallel paths (OR logic). Any branch passing = power flows.
- **Output branches** — executed when power flows from input side.
- **Series elements** — contacts in one branch (AND logic). All must pass.
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ ESP32 Firmware (C++) │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Ladder Interpreter │ │
│ │ │ │
│ │ For each scan: │ │
│ │ 1. Read digital inputs (GPIO) │ │
│ │ 2. Evaluate networks rung-by-rung │ │
│ │ a. Input branches (OR) │ │
│ │ b. Output branches (OTE/OTL/OTU/Timers) │ │
│ │ 3. Update timers (TON/TOF/TP) │ │
│ │ 4. Write physical outputs (GPIO) │ │
│ └───────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Web UI (served from ESP32) │ │
│ │ — Visual ladder editor │ │
│ │ — I/O monitoring │ │
│ │ — Program download │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## GPIO Map (ESP32)
| Pin | Function |
|-----|----------|
| GPIO 27 | Digital Input 0 |
| GPIO 26 | Digital Input 1 |
| GPIO 33 | Digital Input 2 |
| GPIO 35 | Digital Input 3 |
| GPIO 34 | Digital Input 4 |
| GPIO 25 | Digital Output 0 |
| GPIO 32 | Digital Output 1 |
| GPIO 4 | Digital Output 2 |
| GPIO 15 | Digital Output 3 |
## Files
| Path | Purpose |
|------|---------|
| `src/ladder_interpreter.h` | C++ header — all types, enums, structs |
| `src/ladder_interpreter.cpp` | C++ implementation — evaluation, I/O, timers |
| `tests/ladder_test.py` | Python test harness (runs on Pi for testing) |
| `templates/motor_control.json` | Motor interlock template |
## Testing
```bash
cd ~/projects/mechbase-plc
python3 tests/ladder_test.py
```
10 tests covering: NO/NC, OTE, OTL/OTU, parallel branching, series contacts, TON/TOF/TP with all status bits, start/stop latching, motor interlock.