
Bluetooth Low Energy toolkit for electric unicycle wheels: automatic protocol detection, frame reassembly, CRC validation, unit conversion, safe command checking, retries, security handshakes and telemetry/BMS extraction.
Bluetooth Low Energy library for electric unicycle (EUC) wheels, written in Kotlin Multiplatform.
It is plug-and-play: your client app connects and works with three things — BLE devices, EUCData telemetry and commands. The library handles everything else: protocol detection, frame reassembly, CRC validation, unit conversion, safe command encoding, retries, timers and security handshakes.
val client = EucBleClient(context)
client.setConnectionCallback(object : ConnectionCallback() {
override fun onDeviceDiscovered(device: EUCDevice) = client.connect(device)
override fun onConnected() { /* connected */ }
override fun onDisconnected() { /* disconnected */ }
})
client.setDataCallback(object : DataCallback {
override fun onDataReceived(data: EUCData) {
// Metric telemetry: speed, voltage, current, temperature, distances, battery, BMS...
}
})
client.setErrorCallback(object : ErrorCallback {
override fun onError(error: BLEException) { /* handle */ }
})
client.initialize()
client.startScan()
// Commands — discovered, type-checked and state-checked before any byte is written:
client.sendCommand(CommandType.LIGHT_ON)
val descriptors = client.getCommandDescriptors() // names, inputs, valid valuesCallbacks run on background threads; switch to the Android main thread for UI.
First client app: TuxWheel (pre-release, F-Droid planned).
| Module | Artifact | Role |
|---|---|---|
euc-ble-protocols |
io.github.tritbool:euc-ble-protocols |
Synchronous manufacturer engines + shared models. No BLE I/O, no coroutines. JVM, JS, iOS, Linux and macOS targets. |
euc-ble-session |
io.github.tritbool:euc-ble-session |
Coroutine-free session policies + BleTransport contract. |
euc-ble-core |
io.github.tritbool:euc-ble-core |
KMP coroutine facades and async session drivers; re-exports protocols and session. |
euc-ble-android |
io.github.tritbool:euc-ble-library |
EucBleClient entry point + GATT connector (BLEManager). |
Sessions decide when. Protocols decide what the bytes mean. The transport does the I/O.
A new platform reuses the whole KMP stack and only implements BleTransport (e.g. CoreBluetooth).
A new wheel family is a single pure state machine plus entries in the catalogue.
Details: architecture — sources: PlantUML.
null instead of being guessed.| Protocol family | Wheels |
|---|---|
| Gotway / Begode | Gotway, Begode incl. ROCKET smart-BMS pages |
| ExtremeBull | Commander, HERO and siblings (Gotway-derived) |
| KingSong | Full security: PIN/password, challenge-based lock/unlock |
| InMotion | P6 / V9: model identification, dual-pack BMS, diagnostic log |
| Ninebot | Legacy + Z-series |
| LeaperKim / Veteran | Sherman family, Patton, Lynx, Oryx: tiltback/alarm writes, event log |
| Nosfet | Apex, Aero, AEON (Veteran firmware family) |
Feature availability per wheel is discoverable at runtime (getCommandSupport, descriptors with
conditional encodings, model-dependent capability lists after identification).
./gradlew -Peuc.includeAndroid=false :euc-ble-protocols:check
./gradlew -Peuc.includeAndroid=false :euc-ble-core:test --tests io.github.tritbool.euc.ble.AllTestsCI adds Android lint, coverage, SonarCloud, JVM/JS/iOS compilation and the quality dashboard: see maintenance & CI.
Work in progress — upcoming 1.0.0. Protocol support is incomplete and behavior may vary by wheel/firmware; public APIs may evolve. Validate against your specific wheel; passing unit tests do not replace physical testing.
Bluetooth Low Energy library for electric unicycle (EUC) wheels, written in Kotlin Multiplatform.
It is plug-and-play: your client app connects and works with three things — BLE devices, EUCData telemetry and commands. The library handles everything else: protocol detection, frame reassembly, CRC validation, unit conversion, safe command encoding, retries, timers and security handshakes.
val client = EucBleClient(context)
client.setConnectionCallback(object : ConnectionCallback() {
override fun onDeviceDiscovered(device: EUCDevice) = client.connect(device)
override fun onConnected() { /* connected */ }
override fun onDisconnected() { /* disconnected */ }
})
client.setDataCallback(object : DataCallback {
override fun onDataReceived(data: EUCData) {
// Metric telemetry: speed, voltage, current, temperature, distances, battery, BMS...
}
})
client.setErrorCallback(object : ErrorCallback {
override fun onError(error: BLEException) { /* handle */ }
})
client.initialize()
client.startScan()
// Commands — discovered, type-checked and state-checked before any byte is written:
client.sendCommand(CommandType.LIGHT_ON)
val descriptors = client.getCommandDescriptors() // names, inputs, valid valuesCallbacks run on background threads; switch to the Android main thread for UI.
First client app: TuxWheel (pre-release, F-Droid planned).
| Module | Artifact | Role |
|---|---|---|
euc-ble-protocols |
io.github.tritbool:euc-ble-protocols |
Synchronous manufacturer engines + shared models. No BLE I/O, no coroutines. JVM, JS, iOS, Linux and macOS targets. |
euc-ble-session |
io.github.tritbool:euc-ble-session |
Coroutine-free session policies + BleTransport contract. |
euc-ble-core |
io.github.tritbool:euc-ble-core |
KMP coroutine facades and async session drivers; re-exports protocols and session. |
euc-ble-android |
io.github.tritbool:euc-ble-library |
EucBleClient entry point + GATT connector (BLEManager). |
Sessions decide when. Protocols decide what the bytes mean. The transport does the I/O.
A new platform reuses the whole KMP stack and only implements BleTransport (e.g. CoreBluetooth).
A new wheel family is a single pure state machine plus entries in the catalogue.
Details: architecture — sources: PlantUML.
null instead of being guessed.| Protocol family | Wheels |
|---|---|
| Gotway / Begode | Gotway, Begode incl. ROCKET smart-BMS pages |
| ExtremeBull | Commander, HERO and siblings (Gotway-derived) |
| KingSong | Full security: PIN/password, challenge-based lock/unlock |
| InMotion | P6 / V9: model identification, dual-pack BMS, diagnostic log |
| Ninebot | Legacy + Z-series |
| LeaperKim / Veteran | Sherman family, Patton, Lynx, Oryx: tiltback/alarm writes, event log |
| Nosfet | Apex, Aero, AEON (Veteran firmware family) |
Feature availability per wheel is discoverable at runtime (getCommandSupport, descriptors with
conditional encodings, model-dependent capability lists after identification).
./gradlew -Peuc.includeAndroid=false :euc-ble-protocols:check
./gradlew -Peuc.includeAndroid=false :euc-ble-core:test --tests io.github.tritbool.euc.ble.AllTestsCI adds Android lint, coverage, SonarCloud, JVM/JS/iOS compilation and the quality dashboard: see maintenance & CI.
Work in progress — upcoming 1.0.0. Protocol support is incomplete and behavior may vary by wheel/firmware; public APIs may evolve. Validate against your specific wheel; passing unit tests do not replace physical testing.