Initialisation depot

2026-02-10 12:12:11 +01:00
commit c3176e8d79
818 changed files with 52573 additions and 0 deletions
--- a/ESP32/DCC-Bench/README.md
+++ b/ESP32/DCC-Bench/README.md
@@ -0,0 +1,401 @@
+# 🚂 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