Skip to content

Commit 556e545

Browse files
jctoledojctoledo
committed
adds release script
1 parent 0c2eef6 commit 556e545

4 files changed

Lines changed: 384 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ dist/
4343
*.csv
4444
*.dat
4545
telemetry_*.bin
46+
blackbox-v*.bin
4647

4748
# Credentials (NEVER commit these!)
4849
secrets.toml

‎RELEASE.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Release Process
2+
3+
Quick guide for creating Blackbox releases.
4+
5+
## Prerequisites
6+
7+
Install required tools:
8+
```bash
9+
# Install espflash if not already installed
10+
cargo install espflash
11+
12+
# Install GitHub CLI (optional, for command-line releases)
13+
# Ubuntu/Debian:
14+
sudo apt install gh
15+
# macOS:
16+
brew install gh
17+
18+
# Authenticate with GitHub
19+
gh auth login
20+
```
21+
22+
## Release Steps
23+
24+
### 1. Build the Release Binary
25+
26+
```bash
27+
# Run the release script
28+
./scripts/release.sh v0.0.1
29+
```
30+
31+
This will:
32+
- Build optimized firmware
33+
- Generate flashable `.bin` file with bootloader
34+
- Show binary size
35+
- Print next steps
36+
37+
### 2. Test the Binary (Recommended)
38+
39+
```bash
40+
# Flash to your ESP32-C3 for testing
41+
espflash write-bin 0x0 sensors/blackbox/blackbox-v0.0.1.bin
42+
43+
# Or monitor while flashing
44+
espflash write-bin 0x0 sensors/blackbox/blackbox-v0.0.1.bin --monitor
45+
```
46+
47+
Verify:
48+
- ✅ Device boots and shows LED sequence
49+
- ✅ WiFi AP "Blackbox" appears
50+
- ✅ Dashboard loads at 192.168.4.1
51+
- ✅ Telemetry updates at ~20Hz
52+
- ✅ Settings save correctly
53+
54+
### 3. Commit and Push
55+
56+
```bash
57+
# Add the release script and notes
58+
git add scripts/release.sh release-notes.md RELEASE.md
59+
60+
# Commit
61+
git commit -m "Add release tooling for v0.0.1"
62+
63+
# Push to PR branch
64+
git push origin ap_enabled
65+
```
66+
67+
### 4. Merge PR on GitHub
68+
69+
Go to your PR and click "Merge pull request"
70+
71+
### 5. Create Git Tag
72+
73+
```bash
74+
# Switch to main and pull
75+
git checkout main
76+
git pull origin main
77+
78+
# Create annotated tag
79+
git tag -a v0.0.1 -m "Release v0.0.1 - Access Point Mode + Mobile Dashboard"
80+
81+
# Push tag
82+
git push origin v0.0.1
83+
```
84+
85+
### 6. Create GitHub Release
86+
87+
**Option A: Using GitHub CLI (Recommended)**
88+
```bash
89+
gh release create v0.0.1 \
90+
--title "v0.0.1 - Access Point Mode + Mobile Dashboard" \
91+
--notes-file release-notes.md \
92+
sensors/blackbox/blackbox-v0.0.1.bin
93+
```
94+
95+
**Option B: Using GitHub Web UI**
96+
1. Go to https://github.com/jctoledo/blackbox/releases/new
97+
2. Choose tag: `v0.0.1`
98+
3. Title: `v0.0.1 - Access Point Mode + Mobile Dashboard`
99+
4. Description: Copy from `release-notes.md`
100+
5. Attach file: `sensors/blackbox/blackbox-v0.0.1.bin`
101+
6. Click "Publish release"
102+
103+
### 7. Verify Release
104+
105+
Check that:
106+
- ✅ Release appears at https://github.com/jctoledo/blackbox/releases
107+
- ✅ Binary is downloadable
108+
- ✅ Release notes are formatted correctly
109+
- ✅ Tag is visible in repository
110+
111+
## Release Checklist
112+
113+
Before releasing:
114+
- [ ] All tests pass (`cargo test`)
115+
- [ ] No clippy warnings (`cargo clippy -- -D warnings`)
116+
- [ ] Code is formatted (`cargo fmt`)
117+
- [ ] CI checks pass on GitHub
118+
- [ ] Binary tested on actual hardware
119+
- [ ] Dashboard loads and works
120+
- [ ] Settings persist correctly
121+
- [ ] Documentation is up to date
122+
- [ ] CHANGELOG.md updated (if exists)
123+
124+
## Version Numbering
125+
126+
We use [Semantic Versioning](https://semver.org/):
127+
- `v0.0.x` - Pre-release, experimental
128+
- `v0.x.0` - Minor feature additions
129+
- `v1.0.0` - First stable release
130+
- `vX.Y.Z` - Major.Minor.Patch
131+
132+
Examples:
133+
- `v0.0.1` - First pre-release
134+
- `v0.0.2` - Bug fixes
135+
- `v0.1.0` - New features added
136+
- `v1.0.0` - Production-ready
137+
138+
## Troubleshooting
139+
140+
**Binary too large:**
141+
```bash
142+
# Check size
143+
ls -lh sensors/blackbox/blackbox-v*.bin
144+
145+
# ESP32-C3 has 4MB flash, binary should be < 2MB
146+
```
147+
148+
**espflash not found:**
149+
```bash
150+
cargo install espflash --force
151+
```
152+
153+
**gh command not found:**
154+
Install GitHub CLI or use the web UI instead.
155+
156+
**Permission denied on release.sh:**
157+
```bash
158+
chmod +x scripts/release.sh
159+
```
160+
161+
## Next Release
162+
163+
For the next release, just increment the version:
164+
```bash
165+
./scripts/release.sh v0.0.2
166+
# ... follow the same steps
167+
```

‎release-notes.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Blackbox v0.0.1 - First Release 🚀
2+
3+
ESP32-C3 vehicle telemetry system with built-in mobile dashboard and dual WiFi modes.
4+
5+
## 🎯 Major Features
6+
7+
### Built-in Mobile Dashboard
8+
- Mobile-optimized web interface running directly on ESP32
9+
- Real-time telemetry display at ~20 Hz via HTTP polling
10+
- G-meter with enhanced trail visualization and glow effects
11+
- Live speed display with car speedometer-like smoothing
12+
- Mode detection visualization (6 states including combined modes)
13+
- Session timer and GPS coordinates
14+
- CSV data recording and export
15+
- **Live settings configuration** with validation
16+
17+
**Usage:** Connect phone to `Blackbox` WiFi → Open browser to `http://192.168.4.1`
18+
19+
### Dual WiFi Operating Modes
20+
21+
**Access Point Mode (Default)**
22+
- ESP32 creates its own WiFi network - no router required
23+
- Perfect for track days, autocross, mobile use
24+
- Fixed IP: `192.168.4.1:80`
25+
- SSID: `Blackbox` / Password: `blackbox123`
26+
27+
**Station Mode**
28+
- ESP32 connects to your existing WiFi network
29+
- UDP telemetry streaming (20 Hz) to laptop
30+
- MQTT status messages
31+
- For data logging and multi-client scenarios
32+
33+
### Enhanced Mode Detection
34+
- **6 driving states:** IDLE, ACCEL, BRAKE, CORNER, ACCEL+CORNER, BRAKE+CORNER
35+
- Combined states using bitflags (e.g., trail braking = BRAKE+CORNER)
36+
- Independent component detection with hysteresis
37+
- Tuned for street driving (lowered acceleration threshold to 0.10g)
38+
- **177 comprehensive unit tests**
39+
40+
## 🔧 Hardware Requirements
41+
42+
- **ESP32-C3** microcontroller
43+
- **WT901** 9-axis IMU (UART, 200Hz)
44+
- **NEO-6M** GPS module (UART, 5Hz)
45+
- **WS2812** RGB LED (status indicator)
46+
47+
## 📥 Installation
48+
49+
### Flash the Firmware
50+
51+
**Method 1: Using espflash (recommended)**
52+
```bash
53+
espflash write-bin 0x0 blackbox-v0.0.1.bin
54+
```
55+
56+
**Method 2: Using ESP Web Flasher**
57+
1. Go to https://espressif.github.io/esptool-js/
58+
2. Connect ESP32-C3 via USB
59+
3. Select `blackbox-v0.0.1.bin`
60+
4. Flash offset: `0x0`
61+
5. Click "Program"
62+
63+
### First Boot
64+
1. Power on ESP32 - LED shows boot sequence (see README for codes)
65+
2. **AP Mode (default):** Connect phone to WiFi network "Blackbox" (password: `blackbox123`)
66+
3. Open browser to `http://192.168.4.1`
67+
4. View live telemetry!
68+
69+
### Switch to Station Mode
70+
To use UDP streaming and MQTT (requires rebuild):
71+
```bash
72+
export WIFI_MODE="station"
73+
export WIFI_SSID="YourNetwork"
74+
export WIFI_PASSWORD="YourPassword"
75+
export MQTT_BROKER="mqtt://192.168.1.100:1883"
76+
export UDP_SERVER="192.168.1.100:9000"
77+
cargo build --release
78+
# Then flash the new binary
79+
```
80+
81+
## 📊 Dashboard Features
82+
83+
- **G-meter:** Real-time visualization with gradient trail, tick marks, enhanced glow
84+
- **Max G tracking:** L/R/Accel/Brake peak values
85+
- **Speed display:** EMA-filtered for smoothness (like car speedometer)
86+
- **Mode indicator:** Visual icons for each driving state
87+
- **Settings:** Adjust all 8 mode detection thresholds live
88+
- **Recording:** Capture session data and export to CSV
89+
90+
## 🎨 Technical Highlights
91+
92+
- 7-state Extended Kalman Filter for sensor fusion
93+
- Zero-velocity updates (ZUPT) prevent drift when stopped
94+
- Gravity-compensated accelerations
95+
- GPS warmup with local coordinate mapping
96+
- HTTP polling architecture (replaced WebSocket to fix thread blocking)
97+
- Binary telemetry protocol (67 bytes, 20Hz)
98+
- Configurable mode detection thresholds
99+
100+
## 📝 Binary Protocol
101+
102+
Mode byte changed to bitflags:
103+
- `0` = IDLE
104+
- `1` = ACCEL
105+
- `2` = BRAKE
106+
- `4` = CORNER
107+
- `5` = ACCEL+CORNER (trail throttle)
108+
- `6` = BRAKE+CORNER (trail braking)
109+
110+
## 🐛 Known Issues
111+
112+
None reported yet! This is the first release.
113+
114+
## 📚 Documentation
115+
116+
- [README](https://github.com/jctoledo/blackbox/blob/main/README.md) - Full setup guide
117+
- [CLAUDE.md](https://github.com/jctoledo/blackbox/blob/main/CLAUDE.md) - Architecture details
118+
- [Hardware Setup](https://github.com/jctoledo/blackbox/blob/main/sensors/blackbox/README.md) - Pin assignments
119+
120+
## 🙏 Credits
121+
122+
Built with:
123+
- Rust ESP-IDF framework
124+
- ESP32-C3 RISC-V chip
125+
- motorsport-telemetry library
126+
127+
---
128+
129+
**Full Changelog:** https://github.com/jctoledo/blackbox/compare/...v0.0.1

‎scripts/release.sh‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
#!/bin/bash
2+
set -e
3+
4+
VERSION=$1
5+
6+
if [ -z "$VERSION" ]; then
7+
echo "Usage: ./scripts/release.sh v0.0.1"
8+
exit 1
9+
fi
10+
11+
# Validate version format
12+
if [[ ! $VERSION =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
13+
echo "Error: Version must be in format vX.Y.Z (e.g., v0.0.1)"
14+
exit 1
15+
fi
16+
17+
echo "======================================"
18+
echo "Building Blackbox Release $VERSION"
19+
echo "======================================"
20+
echo ""
21+
22+
# Navigate to firmware directory
23+
cd sensors/blackbox
24+
25+
# Build optimized firmware
26+
echo "📦 Building optimized firmware..."
27+
cargo build --release
28+
29+
if [ $? -ne 0 ]; then
30+
echo "❌ Build failed!"
31+
exit 1
32+
fi
33+
34+
echo "✅ Build successful!"
35+
echo ""
36+
37+
# Generate flashable binary with bootloader
38+
echo "🔨 Generating flashable binary (with bootloader)..."
39+
cargo espflash save-image \
40+
--chip esp32c3 \
41+
--release \
42+
--merge \
43+
"blackbox-${VERSION}.bin"
44+
45+
if [ $? -ne 0 ]; then
46+
echo "❌ Binary generation failed!"
47+
exit 1
48+
fi
49+
50+
echo "✅ Binary created: sensors/blackbox/blackbox-${VERSION}.bin"
51+
echo ""
52+
53+
# Get binary size
54+
BIN_SIZE=$(ls -lh "blackbox-${VERSION}.bin" | awk '{print $5}')
55+
echo "📊 Binary size: $BIN_SIZE"
56+
echo ""
57+
58+
echo "======================================"
59+
echo "Release build complete!"
60+
echo "======================================"
61+
echo ""
62+
echo "Binary location: sensors/blackbox/blackbox-${VERSION}.bin"
63+
echo ""
64+
echo "Next steps:"
65+
echo "1. Test the binary:"
66+
echo " espflash write-bin 0x0 sensors/blackbox/blackbox-${VERSION}.bin"
67+
echo ""
68+
echo "2. Commit any remaining changes:"
69+
echo " git add ."
70+
echo " git commit -m 'Prepare release ${VERSION}'"
71+
echo " git push origin ap_enabled"
72+
echo ""
73+
echo "3. Merge your PR on GitHub"
74+
echo ""
75+
echo "4. Create and push the tag:"
76+
echo " git checkout main"
77+
echo " git pull origin main"
78+
echo " git tag -a ${VERSION} -m 'Release ${VERSION} - Access Point Mode + Mobile Dashboard'"
79+
echo " git push origin ${VERSION}"
80+
echo ""
81+
echo "5. Create GitHub release with binary:"
82+
echo " gh release create ${VERSION} \\"
83+
echo " --title '${VERSION} - Access Point Mode + Mobile Dashboard' \\"
84+
echo " --notes-file release-notes.md \\"
85+
echo " sensors/blackbox/blackbox-${VERSION}.bin"
86+
echo ""
87+
echo "Or use the web UI: https://github.com/jctoledo/blackbox/releases/new?tag=${VERSION}"

0 commit comments

Comments
 (0)