KB1 Config is the official browser-based configuration and control application for the PocketMidi KB1 MIDI controller. This release delivers a complete, wireless configuration environment with real-time performance control—configure keyboard modes, lever behavior, touch sensitivity, scales, power management, and control 12 performance sliders (with FX/MIX mode for Polyend Tracker integration) directly from your browser over Bluetooth Low Energy. No drivers, no apps to install.
Latest Features v1.2.5: Chord Mode (15 chord types, strum patterns with looping and swing), Dual-mode performance sliders
IMPORTANT: Before connecting to the web app, you must enable Bluetooth on your KB1 device.
How to Enable Bluetooth:
- Cross-lever gesture: Push both levers toward each other (left lever → right, right lever → left) and hold for 3 seconds
- Watch for progressive LED feedback:
- Octave arrow LEDs turn ON immediately (gesture detected)
- Pink + blue LEDs pulse with increasing speed as you hold
- All LEDs turn OFF = activation complete, release levers
- Repeat the same gesture anytime to toggle Bluetooth on/off
Note: The gesture is automatically cancelled if any keyboard key is pressed, preventing accidental triggers during performance.
Note: The web app cannot detect your device unless Bluetooth is enabled on the hardware.
Want to explore the interface without hardware? Enable Evaluation Mode to interact with all settings using simulated device data—perfect for learning the interface, testing configurations, or exploring community presets before purchasing.
To Enable: Click the KB1 Configurator title (top-center) 5 times rapidly. A modal will appear to toggle the mode on/off.
What Works: All interface features, settings adjustments, preset management, and community preset browsing work normally with mock data.
What Doesn't: No Bluetooth hardware communication (requires real KB1 hardware).
Browser Connection:
- Ensure Bluetooth is enabled on your KB1 hardware (see above)
- Click the CONNECTED / DISCONNECTED status in the top-right navigation bar
- Select your KB1 device from the browser's Bluetooth pairing dialog
- Once connected, the status will turn blue and display "CONNECTED"
- Click Load from Device to fetch current settings from your hardware
First Time Users: A helpful overlay will explain the connection process on your first visit.
Disconnected State: When disconnected, all controls are shown but grayed out. Click any control to see a prompt to connect.
IMPORTANT: If you see a gray battery icon with a ? symbol, your device needs calibration.
Why? Fresh firmware cannot measure battery voltage—it estimates by tracking usage. Without calibration, it doesn't know if your battery is at 100% or 20%.
How to Calibrate:
- Connect USB cable to your KB1
- Charge for ONE continuous 5.5+ hour session
- Do NOT unplug during this time!
- Battery meter will automatically show accurate percentage
- The 5 hour charge MUST be continuous in ONE session
- If you unplug before 5 hours, the timer resets to ZERO
- Partial charges do NOT accumulate (3hrs + 2.5hrs ≠ calibrated)
- This is intentional to ensure accurate baseline
- Only needs to happen ONCE - future USB connections just pause discharge
Until Calibrated: The battery meter shows "Needs Calibration" and battery percentage is unreliable. Complete a full charge cycle before trusting battery estimates.
After Calibration: The meter provides accurate runtime estimates (±10%) based on measured power consumption.
Scale Mode — Play quantized notes based on selected scale type:
- Choose from multiple scale types (Chromatic, Major, Minor, Pentatonic, Blues, etc.)
- Set root note (C, C#, D, etc.)
- Toggle between Mapped Mode (spaced keys repeat) and Efficient Mode (dense, all keys used)
Chord Mode — Play full chords with each key press:
- Choose chord type: Major, Minor, Diminished, Augmented, Sus2, Sus4, Power, Major7, Minor7, Dominant7
- Toggle between Chord Mode (all notes together) and Strum Mode (cascaded notes)
- Adjust velocity spread (0-100%) for dynamic chord voicing
- Set strum speed (5-100ms) for cascading notes
Configure the first lever for continuous control:
- CC Number: Choose MIDI CC from Polyend map with descriptions
- CC Range: Set min/max values (0-127)
- Step Size: Quantize movement to steps
- Function Mode: Uni/Bi-directional, Momentary, Toggle
- Value Mode: Jump, Hook, Pickup, Latch
- Interpolation: Onset/offset timing (0-5000ms) and curve type (Linear, S-Curve, Logarithmic)
Configure the first push button:
- CC Number: Choose MIDI CC with descriptions
- CC Range: Set min/max values
- Function Mode: Trigger, Momentary, Toggle
- Interpolation: Onset/offset timing and curves
Configure the second lever for continuous control:
- CC Number: Choose MIDI CC from Polyend map with descriptions
- CC Range: Set min/max values (0-127)
- Step Size: Quantize movement to steps
- Function Mode: Uni/Bi-directional, Momentary, Toggle
- Value Mode: Jump, Hook, Pickup, Latch
- Interpolation: Onset/offset timing (0-5000ms) and curve type (Linear, S-Curve, Logarithmic)
Configure the second push button:
- CC Number: Choose MIDI CC with descriptions
- CC Range: Set min/max values
- Function Mode: Trigger, Momentary, Toggle
- Interpolation: Onset/offset timing and curves
Configure the capacitive touch sensor:
- CC Number: Choose MIDI CC
- CC Range: Set output range
- Function Mode: Trigger, Momentary
- Threshold: Adjust touch sensitivity (0-65535, default: 24000, lower = more sensitive)
The Preset Manager offers two storage systems for different use cases:
Community Tab (Work + Share):
- Your Working Presets: Save unlimited presets to browser localStorage
- Perfect for experimenting and iterating on configurations
- Persists between sessions (until browser cache cleared)
- Create, rename, export, import, and delete presets
- Quick actions: + New, Import, Export
- Browse Shared: Load community presets shared by other users
- Discover configurations from the community
- Load to try instantly, save to your working presets to keep
Archive Tab (Cold Storage):
- Stored on Device: 8 preset slots in device flash memory
- Survive browser resets and cache clears
- Permanently stored on device hardware
- Perfect for your final, go-to configurations
- Load, Save, and Delete for each slot
Workflow: Experiment in Working Presets → Refine → Archive your favorites to device → Share exceptional ones with the community
Power Management — Customize sleep and timeout intervals:
Sleep Behavior:
-
Without Web App Connection:
- After Light Sleep timeout (default: 5 min idle) → device enters light sleep with pulsing LEDs
- 90 seconds of LED pulsing (fixed warning period)
- Then device enters deep sleep (lowest power)
- Only touch sensor can wake from deep sleep
-
With Web App Connected:
- While web app is actively connected and sending keepalive pings, sleep timers are continuously reset
- BLE Timeout setting controls how long since last ping before allowing sleep to proceed
- This keeps device awake while you're actively configuring settings
- Once sleep is entered, Bluetooth radio turns off and only touch sensor can wake the device
- Reopening web app after sleep requires touching the sensor first to wake the device
Settings:
- Light Sleep: Time until pulsing LEDs begin (3-10 minutes, default: 5 min)
- BLE Timeout: Keepalive reprieve while web app is connected (5-20 minutes, default: 10 min)
Note: Deep sleep automatically occurs 90 seconds after light sleep begins (fixed LED warning period).
Actions:
- Load from Device: Fetch current settings from KB1 hardware
- Reset to Defaults: Restore factory default settings
- Save to Device: Apply changes to RAM and automatically save to flash memory
The SLIDERS tab provides 12 customizable performance sliders for real-time MIDI CC control with dual mode support:
Control Modes:
The slider interface now supports two distinct control modes, selectable via the FX|MIX toggle button in the header:
-
FX Mode (Performance Effects):
- CC 51-62: Traditional performance effects control
- Full bipolar/unipolar support
- All linking and ganging features enabled
- 4 groups of 3 sliders with color coding
-
MIX Mode (Master Mixer — requires firmware v1.1.2+):
- Global Mixer (Sliders 1-4):
- Delay Send (CC 79) — Orange
- Reverb Send (CC 80) — Orange
- Dry Level (CC 81) — Orange
- Line Level (CC 82) — Orange
- Independent operation (no ganging)
- Track Mixer (Sliders 5-12):
- Track 1-8 Volumes (CC 71-78)
- Color coded: Red (1-2), Green (3-4), Cyan (5-6), Violet (7-8)
- Link buttons available for grouping tracks
- Unipolar mode enforced (0-127 range matches Polyend Tracker specs)
- Mode persists across sessions
- Global Mixer (Sliders 1-4):
Setup Mode (Portrait or Desktop):
- Mode Toggle: Tap FX|MIX button to switch between control modes
- Color Selection: Tap color swatch or drag vertical picker to choose from 12 colors (FX mode only — MIX mode uses fixed colors)
- Momentary/Latched Toggle: Tap "M" or "L" button for spring-back or hold behavior
- Bipolar/Unipolar Toggle: Tap "BI" or "UNI" button to switch modes (disabled in MIX mode)
- Link Sliders: Drag across "link" icons between sliders to gang them (conditional visibility in MIX mode)
- CC Assignment: Each slider mapped per mode (51-62 in FX, 71-82 in MIX)
Live Mode (Mobile - Landscape Fullscreen):
- Enter: Rotate device to landscape (iOS shows rotation animation)
- Fullscreen: Sliders fill the entire screen for performance
- Control: Drag sliders vertically to send MIDI CC in real-time
- Exit: Swipe horizontally >100px, then rotate back to portrait (iOS prompts with rotation animation)
- Momentary: Release touch on momentary sliders springs back to 0 with smooth animation
Slider Features:
- Color Coded: 12 rainbow colors for visual organization
- Gang Control: Linked sliders move together and share settings
- Visual Feedback: Colored fill shows current value with minimum visible height
- Bipolar Mode: Center line divider, both positive/negative fill from center
- Unipolar Mode: Bottom-up fill, 0-100% range
Desktop Use:
- All features work with mouse on desktop
- Setup and live modes available simultaneously
- Click and drag sliders for control
Recommended iOS Browser:
For the best experience on iOS devices, we recommend using vBrowser to access the KB1 web configurator. vBrowser provides reliable Web Bluetooth support and accurate touch handling for all 12 performance sliders.
V Browser Setup (iOS):
- Download V Browser from the App Store
- Go to iOS Settings > V Browser > Bluetooth and toggle ON
- Open V Browser and navigate to the KB1 Configurator URL
- If you see a "Bluetooth Required" prompt, tap OK — this is V Browser requesting iOS permission
The KB1 system offers ~10²⁷ total unique configurations (approximately 1 octillion possible combinations). When focusing on the most commonly adjusted parameters—CC numbers, min/max values, function modes, and interpolation curves—there are still ~10¹⁰ to 10¹² practical combinations (10-100 billion distinct configurations).
Storage & Sharing:
- Unlimited working presets in browser for experimentation
- 8 archive slots on device for permanent storage
- Community sharing for discovering and contributing configurations
The system is extraordinarily flexible for any performance or production workflow.
- Wireless Configuration - Full device setup via Web Bluetooth (no drivers, no apps)
- Real-time Control - 12 performance sliders with MIDI CC output
- Flexible Presets - Unlimited browser storage + 8 device archive slots
- Community Sharing - Browse and load presets from other users
- Evaluation Mode - Test interface without hardware (click logo 5x)
- Keyboard Modes - Scale and Chord modes with extensive customization
- Physical Controls - Configure 2 levers, 2 push buttons, and touch sensor
- Power Management - Customize sleep timeouts and Bluetooth keep-alive
- MIDI Mapping - Polyend CC map with descriptions for all controls
- KB1 Theme - Custom dark UI with light/dark theme toggle
- Responsive Design - Mobile-first, scales to desktop
- Live Mode - Fullscreen landscape sliders for performance
- Connection Modals - First-time intro and contextual connection prompts
- Visual Feedback - Real-time parameter updates and unsaved change indicators
- Vue 3 with Composition API
- TypeScript for type safety
- Vite for fast development and optimized builds
- Web Bluetooth API for device communication
- GitHub Actions for automated deployment
src/
├── App.vue # Main app with tab navigation & connection management
├── main.ts # Application entry point
├── constants.ts # App-wide constants
├── ble/
│ ├── bleClient.ts # Web Bluetooth transport layer
│ └── kb1Protocol.ts # KB1 device protocol encoding/decoding
├── pages/
│ ├── MobileScales.vue # SETTINGS tab (scales, system, presets)
│ ├── MobileControls.vue # CONTROLS tab (levers, touch sensor)
│ └── MobileSliders.vue # SLIDERS tab (12 performance sliders)
├── components/
│ ├── AccordionSection.vue # Expandable accordion container
│ ├── AnimatedBLEIcon.vue # Bluetooth icon with breathing animation
│ ├── CCMappingCard.vue # CC configuration card
│ ├── ConnectionStatus.vue # Connection status indicator
│ ├── ContextualConnectionModal.vue # "Connect to use" modal
│ ├── FirstTimeOverlay.vue # First-time user intro
│ ├── LeverSettings.vue # Lever configuration component
│ ├── LeverPushSettings.vue # Lever push configuration
│ ├── TouchSettings.vue # Touch sensor settings
│ ├── ScaleSettings.vue # Scale configuration
│ ├── SystemSettings.vue # Power/timeout settings
│ ├── PresetManager.vue # Preset save/load/manage
│ ├── PerformanceSliders.vue # 12-slider performance interface
│ ├── NotePickerControl.vue # Note selection dropdown
│ └── ValueControl.vue # Numeric value input
├── composables/
│ └── useDeviceState.ts # Central device state management
├── services/
│ └── midiBle.ts # BLE MIDI real-time control
├── state/
│ ├── presets.ts # Complete device preset storage
│ └── sliderPresets.ts # Slider configuration storage
├── data/
│ └── ccMap.ts # Polyend CC map with descriptions
└── styles/
├── slider.css # Slider component styles
└── themes/
└── kb1.css # KB1 theme variables & global styles
The KB1 system offers ~10²⁷ total unique configurations (approximately 1 octillion possible combinations). When focusing on the most commonly adjusted parameters—CC numbers, min/max values, function modes, and interpolation curves—there are still ~10¹⁰ to 10¹² practical combinations (10-100 billion distinct configurations).
Storage & Sharing:
- Unlimited working presets in browser for experimentation and refinement
- 8 archive slots on device flash for permanent, reliable storage
- Community preset sharing via GitHub for discovering and contributing configurations
The system is extraordinarily flexible for any performance or production workflow, from live electronic music to studio production.
- Node.js 18+ and npm
- A browser with Web Bluetooth support (Chrome, Edge, Opera)
- HTTPS connection (required for Web Bluetooth API)
- KB1 hardware device (or enable Evaluation Mode for UI testing)
- Clone the repository:
git clone https://github.com/PocketMidi/KB1-config.git
cd KB1-config- Install dependencies:
npm install- Run development server:
npm run dev-
Optional - Evaluation Mode: To test the UI without hardware, open the app and click the KB1 logo (top-left) 5 times rapidly.
-
Open your browser to
http://localhost:5173(or the URL shown in terminal)
Note: For Web Bluetooth to work in development, you may need to:
- Use
localhost(works over HTTP) - Or set up HTTPS for your dev server
- Or use Chrome flags for testing:
chrome://flags/#unsafely-treat-insecure-origin-as-secure
npm run buildThe built files will be in the dist/ directory, ready for deployment.
npm run previewThe app includes a DEV_MODE flag for testing the UI without a physical KB1 device:
To toggle:
- Edit
src/composables/useDeviceState.tsline 17:
To test the interface without KB1 hardware:
- Open the app in your browser
- Click the KB1 logo (top-left corner) 5 times rapidly
- A modal will appear - toggle Evaluation Mode on
When Evaluation Mode is enabled:
- App auto-connects with simulated device "KB1 (Evaluation Mode)"
- All settings and controls are populated with default mock data
- Changes are logged to console but not sent to hardware
- Perfect for exploring the UI, testing configurations, and browsing community presets
Note: Evaluation Mode state persists in browser localStorage and can be toggled on/off anytime via the logo clicks.
The BLE communication layer is fully implemented with the KB1 firmware protocol:
BLE Configuration (src/ble/bleClient.ts):
- Service UUID:
f22b99e8-81ab-4e46-abff-79a74a1f2ff3 - Direct characteristic access for all settings (Lever, LeverPush, Touch, Scale, System)
- MIDI characteristic:
eb58b31b-d963-4c7d-9a11-e8aabec2fe32 - Keep-alive characteristic maintains connection (60s interval, 10min firmware grace period)
Protocol Encoding (src/ble/kb1Protocol.ts):
- Binary encoding/decoding for all settings (little-endian int32)
- Settings read/written directly to BLE characteristics
- Validation and default value creation
- Type-safe interfaces for all device settings
Web Bluetooth API is supported in:
- ✅ Chrome/Chromium 56+
- ✅ Edge 79+
- ✅ Opera 43+
- ✅ vBrowser (iOS) - Recommended Web Bluetooth browser for iOS devices
- ❌ Firefox (requires flag)
- ❌ Safari (not supported)
iOS Users: Safari does not support Web Bluetooth. We recommend using vBrowser for the best Web Bluetooth experience on iOS devices. vBrowser provides reliable connectivity and accurate touch control for all 12 performance sliders.
For the best experience on desktop/Android, use Chrome, Edge, or Opera.
The Web Bluetooth API requires a secure context (HTTPS) except for localhost. When deploying:
- GitHub Pages provides HTTPS automatically
- Use a service with HTTPS support
- Or set up SSL certificates for your domain
This repository includes a GitHub Actions workflow that automatically deploys to GitHub Pages when you push to the main branch.
To enable:
- Go to your repository Settings → Pages
- Set Source to "GitHub Actions"
- Push to the
mainbranch - The site will be available at
https://pocketmidi.github.io/KB1-config/
Build the project and deploy the dist/ folder to any static hosting service that supports HTTPS.
Contributions are welcome! Please feel free to submit issues or pull requests.
See the LICENSE file for details.
Built with Vue 3, Vite, and the Web Bluetooth API to provide a seamless wireless configuration experience for the PocketMidi KB1 device.