# 🚂 Locomotive Test Bench

A comprehensive testing platform for model/scale locomotives using **ESP32-2432S028R** (ESP32 with ILI9341 touchscreen) and motor driver circuits. This system supports both **DC Analog** and **DCC Digital** control modes with an intuitive touchscreen interface.

## ✨ Features

### Control Modes
- **DC Analog Mode**: Traditional PWM-based speed control with bidirectional operation
- **DCC Digital Mode**: Full DCC protocol support for digital model locomotives
  - 128-step speed control
  - Function control (F0-F28 capable)
  - Short and long address support (1-10239)

### Track Configuration
- **2-Rail Mode**: Standard two-rail DC/DCC operation
- **3-Rail Mode**: Center rail configuration with relay switching

### Touchscreen Interface
- **320x240 ILI9341 TFT Display** with resistive touch
- Power ON/OFF control with visual indicators
- Mode switching (DCC/Analog) with automatic power-off safety
- Interactive speed slider (0-100%)
- Direction control (Forward/Reverse)
- Rail configuration selector (2-rail/3-rail)
- Real-time status display
- Persistent settings (saved to ESP32 NVS)

### Safety Features
- **Automatic power-off** when switching between DCC and Analog modes
- Emergency stop via power button
- Configuration persistence across reboots

## 🔧 Hardware Requirements

### Main Components
- **ESP32-2432S028R Module** (ESP32 with built-in ILI9341 touchscreen)
- **Motor Driver** (LM18200, L298N, or similar)
- **DCC Booster Circuit** (for DCC mode)
- **Relay Module** (5V single-channel for 2-rail/3-rail switching)
- **Power Supply**: Suitable for your locomotive scale (typically 12-18V)
- Model locomotive (DC or DCC compatible)

### ESP32-2432S028R Module Specifications
- **MCU**: ESP32-WROOM-32
- **Display**: 2.8" ILI9341 TFT (320x240)
- **Touch**: XPT2046 Resistive Touch Controller
- **Built-in**: USB-C, MicroSD slot, RGB LED

### Pin Connections

See **[WIRING_ESP32-2432S028R.md](WIRING_ESP32-2432S028R.md)** for complete wiring diagrams and connection details.

#### Quick Pin Reference
| Function | ESP32 GPIO | Connected To |
|----------|-----------|--------------|
| PWM/DCC_A | 18 | LM18200 PWM Input (dual purpose) |
| DIR/DCC_B | 19 | LM18200 DIR Input (dual purpose) |
| Motor Brake | 23 | LM18200 Brake Input |
| Relay Control | 4 | Relay Module Signal |
| TFT/Touch | 2,12-15,21,22 | Built-in (no wiring needed) |

## 📦 Software Setup

### Prerequisites
- [Visual Studio Code](https://code.visualstudio.com/)
- [PlatformIO IDE Extension](https://platformio.org/install/ide?install=vscode)

### Installation Steps

1. **Clone or download this project**
   ```bash
   git clone <repository-url>
   cd DCC-Bench
   ```

2. **Open in VS Code**
   - Open VS Code
   - File → Open Folder → Select `DCC-Bench` folder

3. **Install Dependencies**
   - PlatformIO will automatically download required libraries:
     - TFT_eSPI (Display driver)
     - XPT2046_Touchscreen (Touch controller)
     - ArduinoJson (Configuration)
     - DCCpp (DCC protocol)

4. **Build the project**
   ```bash
   pio run
   ```

5. **Upload to ESP32-2432S028R**
   ```bash
   pio run --target upload
   ```

6. **Monitor Serial Output** (optional)
   ```bash
   pio device monitor
   ```
   - Default baud rate: 115200

## 🎮 Usage

### First Power-On

1. **Connect USB-C cable** to ESP32-2432S028R
2. **Display initializes** - you should see the touchscreen UI
3. **Default state**: 
   - Power: OFF
   - Mode: DC Analog
   - Rails: 2-Rail
   - Speed: 0%

### Basic Operation

#### Power Control
- Tap **[POWER]** button to toggle power ON/OFF
- Green = ON, Red = OFF
- Power must be ON for motor/DCC output

#### Mode Selection
- Tap **[MODE]** button to switch between DCC and DC Analog
- **⚠️ IMPORTANT**: Power automatically turns OFF when changing modes
- Cyan = DCC mode, Yellow = DC Analog mode

#### Rail Configuration
- Tap **[RAILS]** button to switch between 2-Rail and 3-Rail
- Relay activates in 3-Rail mode
- Can be changed while power is on

#### Speed Control
- Use the **horizontal slider** to adjust speed (0-100%)
- Drag the white knob or tap anywhere on the slider
- Real-time speed updates to motor/DCC controller

#### Direction Control
- Tap **[DIR]** button to toggle Forward/Reverse
- FWD = Forward, REV = Reverse
- Changes immediately if power is on

### Status Bar
The bottom status bar shows:
- Current power state
- Active mode (DCC/DC)
- Rail configuration (2-Rail/3-Rail)
- DCC address (if in DCC mode)
- Current speed and direction

## ⚙️ Configuration

### Settings Persistence
All settings are automatically saved to ESP32's Non-Volatile Storage (NVS):
- Power state
- Mode selection (DCC/Analog)
- Rail configuration (2-rail/3-rail)
- Speed value
- Direction
- DCC address
- DCC functions

Settings persist across power cycles and reboots.

### DCC Address Configuration
To change the DCC locomotive address:
1. Edit `src/main.cpp` or add a UI element
2. Default address is **3** (configurable in code)
3. Supports addresses 1-10239 (short and long addresses)

### Touch Calibration
If touch response is inaccurate, adjust calibration in `include/TouchscreenUI.h`:
```cpp
#define TS_MIN_X 200    // Adjust if needed
#define TS_MAX_X 3700   // Adjust if needed
#define TS_MIN_Y 200    // Adjust if needed
#define TS_MAX_Y 3750   // Adjust if needed
```

## 📝 Pin Customization

To change pin assignments, edit these files:

### Motor Controller Pins
Edit `include/MotorController.h`:
```cpp
#define MOTOR_PWM_PIN 18      // PWM speed control
#define MOTOR_DIR_PIN 19      // Direction control
#define MOTOR_BRAKE_PIN 23    // Brake control
```

### DCC Output Pins
Edit `include/DCCGenerator.h`:
```cpp
#define DCC_PIN_A 17    // DCC Signal A
#define DCC_PIN_B 16    // DCC Signal B (inverted)
```

### Relay Control Pin
Edit `include/RelayController.h`:
```cpp
#define RELAY_PIN 4    // 2-rail/3-rail relay control
```

## 📚 API Documentation

This project includes comprehensive API documentation using Doxygen.

### Generate Documentation

```bash
# Install Doxygen (if not already installed)
# Ubuntu/Debian: sudo apt-get install doxygen graphviz
# macOS: brew install doxygen graphviz

# Generate documentation
./generate_docs.sh

# View documentation
xdg-open doc/html/index.html  # Linux
open doc/html/index.html      # macOS
```

The documentation includes:
- Detailed class descriptions
- Function/method documentation
- Parameter and return value descriptions
- Code examples and usage notes
- Cross-referenced source code

See `doc/README.md` for more information.

## Project Structure

```
LocomotiveTestBench/
├── platformio.ini          # PlatformIO configuration
├── Doxyfile               # Doxygen configuration for API docs
├── generate_docs.sh       # Script to generate documentation
├── README.md              # This file
├── doc/                   # Generated API documentation
│   └── html/             # HTML documentation (generated)
├── data/                  # Filesystem (uploaded to LittleFS)
│   ├── index.html        # Main web interface
│   ├── css/
│   │   ├── bootstrap.min.css  # Bootstrap CSS (local)
│   │   └── style.css     # Custom styles
│   └── js/
## 📂 Project Structure

```
DCC-Bench/
├── platformio.ini        # PlatformIO configuration (ESP32-2432S028R)
├── README.md            # This file
├── ESP32-2432S028R_MIGRATION.md  # Migration details
├── WIRING_ESP32-2432S028R.md     # Wiring guide
├── include/             # Header files
│   ├── Config.h         # Configuration management (NVS)
│   ├── MotorController.h # DC motor control
│   ├── DCCGenerator.h   # DCC signal generation
│   ├── RelayController.h # 2-rail/3-rail relay control
│   └── TouchscreenUI.h  # Touchscreen interface
└── src/                 # Source files
    ├── main.cpp         # Main application
    ├── Config.cpp       # Configuration implementation
    ├── MotorController.cpp # Motor control implementation
    ├── DCCGenerator.cpp # DCC implementation
    ├── RelayController.cpp # Relay control implementation
    └── TouchscreenUI.cpp # UI implementation
```

## 🔧 Troubleshooting

### Display Issues
- **Blank screen**: Check USB power connection, verify 5V supply
- **Touch not responding**: Adjust touch calibration values in `TouchscreenUI.h`
- **Inverted display**: Change rotation in `TouchscreenUI::begin()`
- **Wrong colors**: Verify ILI9341 driver configuration in `platformio.ini`

### Motor Not Running (DC Mode)
- Verify mode is set to "DC Analog" (yellow button)
- Check power is ON (green button)
- Verify motor controller connections
- Check pin assignments match your wiring
- Use serial monitor to verify commands

### DCC Not Working
- Verify mode is set to "DCC" (cyan button)
- Check power is ON
- Verify DCC booster is connected and powered
- Check DCC signal with oscilloscope (GPIO 17, 16)
- Verify DCC address matches your locomotive
- Check locomotive is DCC-compatible
- Verify correct address is programmed in locomotive

### Upload Failed
- Check USB cable connection
- Try different USB port
- Press BOOT button on ESP32 during upload
- Check correct board selected in platformio.ini

## Technical Details

### DCC Protocol Implementation
- NMRA DCC Standard compliant
- 128-step speed control
- Function groups support (F0-F12 currently implemented)
- Configurable preamble (14 bits)
- Error detection with XOR checksum

### PWM Specifications (DC Mode)
- Frequency: 20 kHz
- Resolution: 8-bit (0-255)
- Duty cycle: 0-100% (mapped from speed)

### WiFi Specifications
- AP Mode: 802.11 b/g/n
- Client Mode: Auto-reconnect enabled
- Default reconnect interval: 30 seconds

## Safety Notes

⚠️ **Important Safety Information**
- Always disconnect power before wiring changes
- Use appropriate fuses for your scale
- Never exceed voltage ratings of your locomotives
- LM18200 requires adequate heat sinking
- Test with low voltage before full power
- Emergency stop should be easily accessible

## Future Enhancements

Potential features for future versions:
- [ ] PWM frequency adjustment
- [ ] Current monitoring and overload protection
- [ ] Multiple locomotive support
- [ ] Consist/multi-unit control
- [ ] Extended DCC functions (F13-F28)
- [ ] MQTT integration
- [ ] Locomotive profile storage
- [ ] Mobile app

## License

This project is provided as-is for educational and hobbyist purposes.

## Credits


### Relay Not Switching
- Check relay module power (5V and GND)
- Verify GPIO 4 connection to relay signal pin
- Listen for relay click when toggling 2-rail/3-rail
- Test relay with multimeter (continuity test)

### Settings Not Saving
- Check serial monitor for NVS errors
- Try factory reset (clear NVS partition)
- Verify ESP32 flash has NVS partition

### Serial Monitor Shows Errors
- Check all #include statements resolved
- Verify all libraries installed via PlatformIO
- Check for pin conflicts
- Review error messages for specific issues

## 📋 Technical Specifications

### Software
- **Platform**: PlatformIO with Arduino framework
- **Libraries**:
  - TFT_eSPI (Display driver)
  - XPT2046_Touchscreen (Touch controller)
  - ArduinoJson (Configuration)
  - DCCpp (DCC protocol from Locoduino)
- **Storage**: ESP32 NVS (Non-Volatile Storage)

### Hardware Limits
- **PWM Frequency**: 20kHz (motor control)
- **DCC Timing**: NMRA standard compliant
- **Touch**: Resistive (pressure-sensitive)
- **Display**: 320x240 pixels, 65K colors

## 🤝 Support & Contributing

For issues, questions, or contributions:
- Check serial monitor output for debugging (115200 baud)
- Verify hardware connections match pin assignments
- Review **[WIRING_ESP32-2432S028R.md](WIRING_ESP32-2432S028R.md)**
- Check **[ESP32-2432S028R_MIGRATION.md](ESP32-2432S028R_MIGRATION.md)** for migration details
- Test with known-good locomotive

## 📄 License

This project is open source. Check repository for license details.

---

**Version**: 2.0 (ESP32-2432S028R Edition)  
**Last Updated**: December 2025  
**Compatible Hardware**: ESP32-2432S028R (ESP32 with ILI9341 touchscreen)  
**Framework**: Arduino for ESP32 via PlatformIO