Desktop firmware updater for KB1 MIDI controller. Flash firmware via USB with automatic battery calibration preservation.
- Firmware Flashing - Update KB1 firmware via USB
- NVS Preservation - Automatically backs up and restores battery calibration
- GitHub Integration - Auto-download latest firmware releases
- Local Files - Drag & drop custom .bin files
- Serial Monitor - View device boot logs and debug output
This tool requires Chrome, Edge, or Opera on desktop (Windows, macOS, Linux).
- Web Serial API support required
- HTTPS or localhost required
- Mobile browsers not supported
# Install dependencies
npm install
# Run development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview- Open the tool in Chrome/Edge/Opera
- Connect KB1 via USB-C cable
- Select firmware source:
- Click a GitHub release to auto-download
- Or drag/drop a local
.binfile
- Grant USB permission when prompted
- Wait for flash to complete (automatic NVS backup/restore)
- Device restarts automatically
kb1-flash/
├── src/
│ ├── main.ts # Entry point, UI logic
│ ├── flasher.ts # Firmware flashing (esptool-js wrapper)
│ ├── github.ts # GitHub releases API
│ ├── serial-monitor.ts # Serial port reader
│ ├── types.ts # TypeScript definitions
│ └── style.css # KB1 brand styles
├── index.html # Main UI
├── package.json # Dependencies
├── vite.config.ts # Build configuration
└── tsconfig.json # TypeScript config
- Vite - Build tool
- TypeScript - Type safety
- esptool-js - ESP32 flashing library
- Web Serial API - USB communication
- GitHub API - Release fetching
Expects combined firmware binary with:
- Bootloader @ 0x0
- Partition table @ 0x8000
- NVS partition @ 0x9000 (preserved)
- Firmware @ 0x10000
The tool automatically preserves the NVS partition (0x9000, 20KB) which contains:
- Battery percentage
- Active time counters (BLE on/off, sleep, discharge)
- Calibration timestamp
- User settings
This ensures battery calibration survives firmware updates.
# Build
npm run build
# Deploy dist/ folder to GitHub Pages
# Configure base in vite.config.ts if using subdirectory- Build for production
- Upload
dist/to web server - Ensure HTTPS (required for Web Serial API)
- Point DNS to server
View real-time output from KB1:
- Boot messages
- Firmware version
- Debug logs
- Error messages
Useful for troubleshooting flash issues or verifying successful update.
- Use Chrome, Edge, or Opera on desktop
- Ensure you're on HTTPS or localhost
- Mobile browsers don't support Web Serial API
- Make sure KB1 is connected via USB
- Try different USB cable
- Check USB port is working
- On macOS: Grant permission in System Preferences
- Ensure release has .bin file
- Check GitHub release assets
- Try uploading local .bin file instead
- Don't disconnect USB during flash
- Try different USB port
- Ensure battery has charge
- Check serial monitor for errors
MIT License - See LICENSE file