Skip to content

Commit 4921a89

Browse files
doudardoudar
committed
Merge branch 'develop' into copilot/fix-573
2 parents ad1878a + 37d51c0 commit 4921a89

File tree

3 files changed

+231
-0
lines changed

3 files changed

+231
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
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.

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: "Copilot Setup Steps"
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
paths:
7+
- .github/workflows/copilot-setup-steps.yml
8+
pull_request:
9+
paths:
10+
- .github/workflows/copilot-setup-steps.yml
11+
12+
jobs:
13+
# IMPORTANT: Job name must be exactly this.
14+
copilot-setup-steps:
15+
# You can upgrade to a larger Ubuntu runner label later if needed (e.g. ubuntu-4-core)
16+
runs-on: ubuntu-latest
17+
timeout-minutes: 40
18+
19+
# Minimize permissions; Copilot will get its own token later.
20+
permissions:
21+
contents: read
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v5
26+
with:
27+
# fetch-depth overridden internally for Copilot anyway; keep explicit for normal runs
28+
fetch-depth: 0
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v6
32+
with:
33+
python-version: '3.x'
34+
35+
- name: Cache PlatformIO core and packages
36+
uses: actions/cache@v4
37+
with:
38+
path: |
39+
~/.platformio
40+
key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini', 'dependencies.lock') }}
41+
restore-keys: |
42+
pio-${{ runner.os }}-
43+
44+
- name: Install PlatformIO Core
45+
run: |
46+
python -m pip install --upgrade pip
47+
pip install --upgrade platformio
48+
49+
- name: Show PlatformIO info
50+
run: |
51+
platformio --version
52+
platformio system info
53+
54+
- name: Pre-download native test dependencies
55+
run: |
56+
platformio pkg install -e native || echo "Native env install attempted"
57+
58+
- name: Pre-download ESP32 toolchains and libraries (release env)
59+
run: |
60+
# Only install packages (faster + ensures offline availability later)
61+
platformio pkg install -e release
62+
63+
- name: Warm build cache (lightweight compile) for release env
64+
run: |
65+
# A full build ensures toolchains, frameworks, and libs are all present
66+
# If this becomes too slow, you can remove this step and rely on pkg install only.
67+
platformio run -e release || exit 0
68+
69+
- name: Warm build cache for native env (tests)
70+
run: |
71+
platformio run -e native || exit 0
72+
73+
- name: Validate native tests (non-blocking)
74+
run: |
75+
set +e
76+
platformio test -e native
77+
# Do not fail setup if tests fail; Copilot will handle fixes.
78+
exit 0
79+
80+
- name: Summarize cached packages
81+
run: |
82+
du -sh ~/.platformio/packages/* || true
83+
du -sh ~/.platformio/platforms/* || true
84+
85+
- name: Guidance for future adjustments
86+
shell: bash
87+
run: |
88+
echo "Setup steps completed. You can:"
89+
echo " - Upgrade runner: change runs-on to ubuntu-4-core if builds are slow." \
90+
"\n - Enable LFS: add 'with: lfs: true' to checkout step if using Git LFS." \
91+
"\n - Trim steps: remove warm build steps if time exceeds limits." \
92+
"\n - Add more pkg installs for other environments if created later."

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313

1414
### Hardware
1515

16+
17+
## [25.9.8]
18+
19+
### Added
20+
21+
### Changed
22+
23+
### Hardware
24+
1625
## [25.8.26]
1726

1827
### Added

0 commit comments

Comments
 (0)