|
| 1 | +# SmartSpin2k - ESP32 Smart Trainer Firmware |
| 2 | + |
| 3 | +SmartSpin2k is an ESP32-based DIY smart trainer project that converts any spin bike into a connected fitness device compatible with Zwift, TrainerRoad, and other training apps. The firmware controls stepper motor resistance, handles BLE communication, serves a web interface, and manages sensor data. |
| 4 | + |
| 5 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Bootstrap Environment |
| 10 | +Install required tools and dependencies: |
| 11 | +- `sudo apt-get update && sudo apt-get install -y build-essential git python3 python3-pip` |
| 12 | +- `pip install platformio pre-commit` |
| 13 | +- `pre-commit install --hook-type pre-push` |
| 14 | + |
| 15 | +### Build the Firmware |
| 16 | +- **CRITICAL**: Build takes 15-45 minutes depending on network connectivity. NEVER CANCEL. Set timeout to 60+ minutes. |
| 17 | +- `pio run --environment release` -- builds ESP32 firmware. NEVER CANCEL: Build takes 15-45 minutes on first run due to platform/toolchain downloads. |
| 18 | +- `pio run --target buildfs` -- builds filesystem. Takes 2-5 minutes. |
| 19 | +- **Network Issues**: If platform downloads fail with HTTPClientError, this is due to firewall/network restrictions. The build cannot proceed without internet access to download ESP32 toolchain. |
| 20 | + |
| 21 | +### Testing |
| 22 | +- **CRITICAL**: Native tests take 5-15 minutes. NEVER CANCEL. Set timeout to 30+ minutes. |
| 23 | +- `pio test --environment native` -- runs unit tests using Unity framework. NEVER CANCEL: Takes 5-15 minutes on first run. |
| 24 | +- Tests validate sensor data parsing, power calculations, BLE communication, and stepper motor control. |
| 25 | +- **Network Issues**: Native platform download may fail with HTTPClientError due to firewall restrictions. |
| 26 | + |
| 27 | +### Code Quality and Validation |
| 28 | +- `pre-commit run --all-files` -- runs license header insertion. Takes 1-2 minutes. |
| 29 | +- `pio check -e debug` -- runs cppcheck static analysis on debug environment. Takes 2-5 minutes. **Network Issues**: May fail with HTTPClientError due to platform download restrictions. |
| 30 | +- Python build scripts (always work): |
| 31 | + - `python git_tag_macro.py` -- generates firmware version from git tags |
| 32 | + - `python build_date_macro.py` -- generates build timestamp |
| 33 | + - `python cert_updater.py` -- updates SSL certificates (may fail with network issues) |
| 34 | + |
| 35 | +### Run the Application |
| 36 | +- **Build First**: Always complete the bootstrap and build steps before attempting to run. |
| 37 | +- The application runs on ESP32 hardware - cannot be executed in the sandbox environment. |
| 38 | +- Web interface available at device IP on port 80 when running on hardware. |
| 39 | +- BLE services broadcast as "SmartSpin2k" when running on hardware. |
| 40 | + |
| 41 | +## Validation |
| 42 | + |
| 43 | +### Manual Testing Scenarios |
| 44 | +After making code changes, always validate: |
| 45 | +1. **Build Validation**: Ensure `pio run --environment release` completes successfully. |
| 46 | +2. **Test Validation**: Ensure `pio test --environment native` passes all Unity tests. |
| 47 | +3. **Code Quality**: Run `pre-commit run --all-files` and fix any license header issues. |
| 48 | +4. **BLE Service Changes**: When modifying BLE services, verify characteristic UUIDs match the CustomCharacteristic.md specification. |
| 49 | +5. **Power Calculations**: When changing power table or ERG mode code, run tests in test_pt_lookup_*.cpp files. |
| 50 | +6. **Sensor Data**: When modifying sensor parsing, validate with tests in test_*Data.cpp files. |
| 51 | + |
| 52 | +### Critical Areas to Test |
| 53 | +- **Power Table**: Always validate power lookup and resistance calculations after changes to Power_Table.cpp or PowerTable_Helpers.cpp |
| 54 | +- **BLE Services**: Test characteristic read/write operations when modifying BLE_*_Service.cpp files |
| 55 | +- **ERG Mode**: Validate resistance control when changing ERG_Mode.cpp |
| 56 | +- **Stepper Control**: Test motor control when modifying stepper-related code in Main.cpp |
| 57 | + |
| 58 | +## Common Tasks |
| 59 | + |
| 60 | +### Repository Structure |
| 61 | +Key directories and their purpose: |
| 62 | +``` |
| 63 | +/src -- Main ESP32 firmware source code |
| 64 | +/lib/SS2K/src -- Core library with sensor parsing and data structures |
| 65 | +/include -- Header files and configuration |
| 66 | +/test -- Unity unit tests for native environment |
| 67 | +/data -- Web interface HTML/CSS files |
| 68 | +/Hardware -- 3D printing files and PCB designs |
| 69 | +/.github/workflows -- CI/CD pipeline definitions |
| 70 | +``` |
| 71 | + |
| 72 | +### Important Files |
| 73 | +- `platformio.ini` -- Build configuration for ESP32 and native environments |
| 74 | +- `include/settings.h` -- Hardware pin definitions and configuration constants |
| 75 | +- `CustomCharacteristic.md` -- BLE characteristic specification and usage |
| 76 | +- `src/Main.cpp` -- Main firmware entry point and setup |
| 77 | +- `lib/SS2K/src/sensors/` -- Sensor data parsing classes |
| 78 | + |
| 79 | +### Build Dependencies |
| 80 | +External libraries loaded automatically by PlatformIO: |
| 81 | +- NimBLE-ESP32 for Bluetooth Low Energy |
| 82 | +- TMCStepper for stepper motor control |
| 83 | +- FastAccelStepper for smooth motor movement |
| 84 | +- ArduinoJson for configuration and web API |
| 85 | +- ArduinoWebsockets for real-time web communication |
| 86 | + |
| 87 | +### Configuration |
| 88 | +- Default device name: "SmartSpin2k" |
| 89 | +- Default WiFi password: "password" |
| 90 | +- Web interface served on port 80 |
| 91 | +- BLE service UUID: "77776277-7877-7774-4466-896665500000" |
| 92 | +- Over-the-air update URL: configured in settings.h |
| 93 | + |
| 94 | +### Hardware Compatibility |
| 95 | +- ESP32 DevKit v1 board (primary target) |
| 96 | +- TMC2209 stepper motor driver |
| 97 | +- Custom PCB designs in Hardware/ directory |
| 98 | +- Support for multiple bike mount configurations |
| 99 | + |
| 100 | +### Known Issues and Limitations |
| 101 | +- **Network Connectivity**: Platform and toolchain downloads may fail due to firewall restrictions. All build commands (`pio run`, `pio test`, `pio check`) require internet access on first run. |
| 102 | +- **SSL Certificates**: cert_updater.py may fail to fetch current certificates due to network restrictions |
| 103 | +- **Hardware Testing**: Cannot test actual motor control or BLE communication without physical hardware |
| 104 | +- **Build Times**: Initial builds require internet access and take 15-45 minutes due to large platform downloads |
| 105 | + |
| 106 | +### Troubleshooting Common Issues |
| 107 | +- **HTTPClientError during build**: This indicates network/firewall restrictions preventing platform downloads. No workaround available in restricted environments. |
| 108 | +- **Platform not found**: Run `pio platform install espressif32` to manually install the ESP32 platform (requires internet). |
| 109 | +- **Test failures**: Ensure you're running tests in native environment: `pio test -e native` |
| 110 | +- **SSL certificate warnings**: Update certificates with `python cert_updater.py` or manually update `include/cert.h` |
| 111 | +- **Build flag errors**: The Python scripts in build_flags must execute successfully. Test them individually if build fails. |
| 112 | + |
| 113 | +### Environment Verification |
| 114 | +Before working on the project, verify your environment: |
| 115 | +```bash |
| 116 | +# Check tools are installed |
| 117 | +which python3 pio pre-commit |
| 118 | +# Verify project configuration |
| 119 | +pio project config |
| 120 | +# Test build scripts |
| 121 | +python git_tag_macro.py && python build_date_macro.py |
| 122 | +``` |
| 123 | + |
| 124 | +### Debugging Tips |
| 125 | +- Use `pio device monitor` to view serial output when connected to ESP32 hardware |
| 126 | +- Check `include/cert.h` if experiencing SSL errors during firmware updates |
| 127 | +- Monitor memory usage with DEBUG_STACK enabled in settings.h |
| 128 | +- BLE debugging available through web interface at `/develop.html` |
| 129 | + |
| 130 | +Always run `pre-commit run --all-files` before completing changes to ensure code meets project standards. |
0 commit comments