402 lines
12 KiB
Markdown
402 lines
12 KiB
Markdown
# 🚂 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
|