# LM18200 Dual-Mode Operation

## System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    ESP32-2432S028R Module                   │
│                                                             │
│  ┌──────────────┐  ┌────────────┐  ┌──────────────────┐   │
│  │ Touchscreen  │  │  DCC       │  │  Motor           │   │
│  │ UI Control   │→→│ Generator  │  │  Controller      │   │
│  └──────────────┘  └────────────┘  └──────────────────┘   │
│                           │                │               │
│                           ▼                ▼               │
│                    GPIO 18 (PWM/DCC_A)                     │
│                    GPIO 19 (DIR/DCC_B)                     │
│                    GPIO 23 (BRAKE)                         │
│                    GPIO 35 (ADC - ACK Detect)              │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    LM18200      │
                    │   H-Bridge      │
                    │                 │
                    │  Universal      │
                    │  DC/DCC Driver  │
                    └─────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Current Sense   │
                    │   0.1Ω 1W       │
                    └─────────────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
                ▼                         ▼
          Track Rail 1             Track Rail 2
                │                         │
                └────── LOCOMOTIVE ───────┘
```

## Mode Comparison

### DC Analog Mode
```
GPIO 18 ──→ PWM Signal (20kHz, 0-100% duty) ──→ LM18200 ──→ Variable Voltage
GPIO 19 ──→ Direction (HIGH/LOW)             ──→ LM18200 ──→ Polarity
GPIO 23 ──→ Brake (active when needed)       ──→ LM18200 ──→ Both outputs LOW

Result: Traditional DC motor control with variable speed
```

### DCC Digital Mode
```
GPIO 18 ──→ DCC Signal A (58μs/100μs pulses) ──→ LM18200 ──→ Track +
GPIO 19 ──→ DCC Signal B (inverted A)        ──→ LM18200 ──→ Track -
GPIO 23 ──→ Brake (emergency stop)           ──→ LM18200 ──→ Both outputs LOW

Result: NMRA DCC digital control with 128 speed steps + functions
```

### Programming Track Mode (DCC Service Mode)
```
GPIO 18 ──→ Service Mode Packets (22-bit preamble) ──→ LM18200 ──→ Track +
GPIO 19 ──→ Inverted service packets              ──→ LM18200 ──→ Track -
                                                         │
                                                         ▼
                                              Current Sense (0.1Ω)
                                                         │
                                                         ▼
                                              Voltage Divider
                                                         │
                                                         ▼
GPIO 35 ◄──────────────── ADC reads ACK pulse (60mA = 6mV across 0.1Ω)

Result: Decoder programming with ACK verification
```

## Signal Characteristics

### DC Mode Signals
```
GPIO 18 (PWM):
  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
  ▔▔▔▔▔▔▔▔▔▔ (20kHz square wave, variable duty cycle)

GPIO 19 (Direction):
  ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ (Forward: HIGH)
  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ (Reverse: LOW)
```

### DCC Mode Signals
```
GPIO 18 (DCC Signal A):
  ▔▁▔▁▔▁▔▁▔▁▔▁▔▁▔▁        ← '1' bits (58μs per half)
  ▔▔▁▁▔▔▁▁▔▔▁▁▔▔▁▁        ← '0' bits (100μs per half)

GPIO 19 (DCC Signal B):
  ▁▔▁▔▁▔▁▔▁▔▁▔▁▔▁▔        ← Inverted from Signal A
  ▁▁▔▔▁▁▔▔▁▁▔▔▁▁▔▔
```

### Programming Track ACK
```
Current Draw During Programming:

Normal: ───────────────────────────── (baseline ~10-20mA)

ACK:    ────────┏━━━━━━┓─────────────  (60mA spike for 6ms)
                ↑      ↑
              Valid  End
            Command  ACK

ADC Reading (GPIO 35):
        ─────────┏━━━━━┓──────────────  (voltage spike detected)
```

## LM18200 Pin Configuration

```
┌────────────────────────────────┐
│         LM18200 H-Bridge        │
├────────────────────────────────┤
│                                │
│ PWM  (Pin 3)  ← GPIO 18        │  } Dual purpose:
│ DIR  (Pin 5)  ← GPIO 19        │  } DC: PWM+Direction
│ BRAKE(Pin 4)  ← GPIO 23        │  } DCC: Signal A+B
│                                │
│ VCC  (Pin 1)  ← 5V Logic       │
│ GND  (Pin 2)  ← GND            │
│                                │
│ VS   (Pin 10) ← 12-18V Track   │
│                                │
│ OUT1 (Pin 8)  → Rail 1 ────┐   │
│ OUT2 (Pin 9)  → Rail 2 ────┤   │
└────────────────────────────┼───┘
                             │
                      ┌──────┴──────┐
                      │ 0.1Ω Sense  │
                      └──────┬──────┘
                             │
                         To Track
```

## Current Flow and ACK Detection

### Programming Track Current Sensing

```
                    LM18200 OUT1
                         │
                         ▼
                    ┌─────────┐
                    │ 0.1Ω 1W │  ← Sense Resistor
                    └─────────┘
                         │
                    ┌────┴────┐
                    │         │
                   1kΩ       To Track Rail 1
                    │
              GPIO 35 (ADC)
                    │
                  10kΩ
                    │
                   GND ──── Track Rail 2 ──── LM18200 OUT2


Voltage Calculation:
- Decoder ACK = 60mA
- Voltage across 0.1Ω = I × R = 0.06A × 0.1Ω = 6mV
- Voltage divider (1kΩ/10kΩ): V_adc = 6mV × (10/(1+10)) ≈ 5.45mV
- ESP32 ADC: 12-bit (0-4095) for 0-3.3V
- Expected ADC value: (5.45mV / 3300mV) × 4095 ≈ 6-7 counts

Note: In practice, use higher resistance for better ADC reading,
or amplify signal with op-amp for more reliable detection.
```

## Why This Works for Programming

### Traditional DCC System
- **Main Track**: 3-5A continuous, many locomotives
- **Programming Track**: 250mA max, one decoder at a time
- **Separation Required**: Different boosters to prevent overcurrent

### DCC-Bench Approach
- **Single Track**: Only one locomotive under test
- **Low Current**: Programming current well within LM18200 limits
- **No Isolation Needed**: Same track for operation and programming
- **Mode Selection**: Software-controlled (touchscreen UI)

### LM18200 Specifications
- **Continuous Current**: 3A (plenty for single loco)
- **Peak Current**: 6A (handles inrush)
- **Current Limit**: Built-in thermal protection
- **Perfect for**: Small test bench with one locomotive

## Safety Features

### Hardware Protection
1. **LM18200 thermal shutdown**: 165°C junction temperature
2. **Current limiting**: Automatic under-voltage lockout
3. **Brake function**: Forces outputs LOW (GPIO 23)
4. **Optional fuse**: 250mA on track output for extra safety

### Software Safety
1. **Power-off on mode change**: Prevents accidental high current
2. **CV range validation**: Only CV 1-1024 allowed
3. **Address validation**: 1-10239 range check
4. **Write verification**: Confirms successful programming
5. **Timeout handling**: Aborts if no ACK after retries

## Limitations and Considerations

### Current Implementation ✅
- Sends NMRA-compliant programming packets
- Proper timing and packet structure
- Retry logic for reliability
- Basic ACK detection framework

### With Hardware Addition 📋
- Full ACK detection with current sensing
- Verified programming success
- Reliable decoder communication
- Professional-grade test bench

### Not Supported ⚠️
- **Operations Mode Programming**: Requires main track operation
- **RailCom**: Needs additional hardware and timing
- **Multiple Locomotives**: Bench designed for single loco testing
- **High Current Ops**: Not a layout controller (test bench only)

## Advantages Summary

✅ **Simplicity**: One driver for everything
✅ **Cost**: No separate programming booster
✅ **Reliability**: LM18200 proven design
✅ **Flexibility**: Easy mode switching
✅ **Safety**: Built-in protection
✅ **Completeness**: Full NMRA compliance
✅ **Practicality**: Perfect for test bench use

This design leverages the fact that a test bench only ever has ONE locomotive,
eliminating the need for separate main track and programming track boosters!