WFB protocol notes

Reverse-engineering notes from Wheelie-Fun-Bike_1_0_0_apkcube.apks.

Method: unzip the .apks → base.apk → hermes-dec on the Hermes bundle. Function names, class names, and object literals survive the build, so the protocol layer decompiles readably. Register-level control flow does not — where a value below is marked inferred, it was read off register assignments rather than named source.

Caveat on OTA. Because this is an expo-updates build, the JS bundle actually executed on a device may have been replaced at runtime. Everything below describes the bundle shipped inside this APK.

1. Does it bundle any .vescpkg files?

No. Checked five ways, all negative:

1. Full ZIP listing of base.apk and split_config.arm64_v8a.apk — no .vescpkg, .lisp, .lbm, .hex, or firmware .bin. assets/ holds only app.config, app.manifest, expo-root.pem, the JS bundle, three ML Kit barcode .tflite models, and dexopt profiles. res/raw/ is fonts plus two Firebase keep-rules XMLs.
2. Byte-level search of the raw Hermes bundle for vescpkg, vesc_pkg, VESC Package, lispbm, .lbm, qmlui — zero hits.
3. Same search across all seven classes*.dex — zero hits.
4. No long base64 string literals anywhere in the decompiled bundle (regex for ≥200-char base64 runs returned nothing), so nothing is smuggled in as an encoded blob.
5. No firmware/package download endpoint. The only non-library URLs in the bundle are Expo infrastructure (exp.host, classic-assets.eascdn.net), Google Fonts, and two informational links: vesc-project.com/node/3278 and github.com/vedderb/bldc/pull/397.

But — and this is the useful part — the app does embed the config schema that a .vescpkg would normally carry. See §6. So it can read and write the package's custom config without shipping the package; it assumes the package is already flashed and refuses to proceed if the signature doesn't match ("Package Version Unsupported or failed to get config").

The only LispBM-adjacent content is the string LispBM appearing once and the standard COMM_LISP_* IDs in the packet enum. There is no code path that uploads Lisp source, and COMM_LISP_PRINT inbound is explicitly discarded.

2. Transport — BLE

The GATT profile is the standard VESC one:

This is byte-for-byte the NUS profile that nrf51_vesc and VESC Express expose - no custom service, no renamed characteristics, no vendor base UUID. Any tool that speaks stock VESC BLE will connect. All of this app's customisation lives above the transport, inside COMM_CUSTOM_APP_DATA payloads.

After discoverAllServicesAndCharacteristicsForDevice the app walks servicesForDevice and pushes 'vesc' into a capability array if the NUS service is present; that tag gates binding the vescMessageHandler listener.

(6ba7b81x-9dad-11d1-... also appears in the bundle, but those are the RFC 4122 namespace constants from a uuid library, not BLE.)

Device discovery filters on advertised name — helper bleDefaultNameIncludesWfb.

Write path — writeBuffer(deviceId, packet)

chunkSize = manager.mtu - 3
for each chunk:
    writeCharacteristicWithoutResponseForDevice(
        deviceId, VESC_SERVICE_UUID, VESC_CHARACTERISTICS_RX_UUID,
        chunk.toString('base64'))
await Promise.all(all chunk promises)

Note the chunks are issued concurrently and awaited together, not sequentially. Ordering depends on the platform BLE queue preserving submission order; on a stack that reorders, a multi-chunk packet would arrive scrambled.

Android permissions requested: BLUETOOTH, BLUETOOTH_ADMIN, BLUETOOTH_SCAN, BLUETOOTH_CONNECT, ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION, FOREGROUND_SERVICE, FOREGROUND_SERVICE_CONNECTED_DEVICE, WAKE_LOCK. iOS declares the bluetooth-central background mode. There is a VescBackgroundService that keeps the connection alive under a foreground service.

3. Framing — generatePacket(payload, canId?)

Standard VESC serial framing:

short (len <= 256):   0x02  len:u8       payload  crc16:u16be  0x03
long  (len >  256):   0x03  len:u16be    payload  crc16:u16be  0x03

CAN forwarding is applied at frame-build time: if canId is supplied and payload[0] !== COMM_FORWARD_CAN, the two bytes [34, canId] are prepended. The send path (writeData) does the same automatically from _primaryCANDeviceId, so a caller normally doesn't pass canId explicitly.

CRC

CRC-16/CCITT (XMODEM), init 0x0000, table-driven, byte-at-a-time:

crc = table[((crc >> 8) ^ byte) & 0xFF] ^ (crc << 8)   // truncated to u16

Matches crc.c in vedderb/bldc.

Two framing bugs worth knowing about

1. Off-by-one on the length-form boundary. The branch is len <= 256 for the short form; upstream uses len <= 255. A payload of exactly 256 bytes is emitted with a single length byte of 256 & 0xFF = 0, which the firmware will read as a zero-length packet. Payloads of exactly 256 bytes are therefore unusable.
2. No 3-byte length form. Upstream supports start byte 0x04 with a 24-bit length for payloads > 65535. Not implemented here — irrelevant for the commands this app sends, but a limit if you're reusing the code.

VescBuffer

A reimplementation of VESC's buffer.c. Readers: readUInt8, readInt8, readUInt16, readInt16, readUInt32, readInt32, readDouble16(scale), readDouble32(scale), readFloat32, readDouble32Auto, readString, slice, size, raw. Writers mirror these, plus writeDouble32_Old retained for compatibility.

readDouble16(scale) / readDouble32(scale) are the scaled-integer forms (read a signed int, divide by scale). readDouble32Auto is the float32-packed-in-uint32 form.

4. Packet ID enum

127 COMM_* IDs are defined. IDs 0–90 and 92–101 match upstream bldc/datatypes.h exactly. Beyond that this app targets a fork and the numbering diverges. Full table:

Continuing:

⚠ Duplicate ID 100

The enum assigns COMM_GET_MCCONF_TEMP = 100 (upstream value is 91) while also assigning COMM_BMS_FORCE_BALANCE = 100. In a TypeScript numeric enum this compiles fine but the reverse map enum[100] resolves to whichever was declared last. Since IDs 92–99 and 101 all match upstream exactly, 91 is almost certainly what was intended and 100 is a typo. If you're interoperating, treat COMM_GET_MCCONF_TEMP as 91 on the wire and expect this app to send 100.

Two other observations:

• COMM_GET_CUSTOM_CONFIG_XML (92) is defined but never sent — the app carries the config schema locally instead (§6).
• A 14-element array of "movement-capable" commands is built from COMM_JUMP_TO_BOOTLOADER, COMM_SET_DUTY, COMM_SET_CURRENT, COMM_SET_CURRENT_BRAKE, COMM_SET_RPM, COMM_SET_POS, COMM_SET_HANDBRAKE, COMM_SET_DETECT, COMM_SET_SERVO_POS, COMM_REBOOT, COMM_ALIVE, COMM_FORWARD_CAN, COMM_SET_CHUCK_DATA, COMM_CUSTOM_APP_DATA — purpose not confirmed (inferred: a gating or keep-alive list).

Also defined: HW_TYPE_VESC = 0, HW_TYPE_VESC_BMS = 1, HW_TYPE_CUSTOM_MODULE = 2, and the full upstream FAULT_CODE_* set (including FAULT_CODE_FLASH_CORRUPTION, ..._APP_CFG, ..._MC_CFG).

5. Inbound dispatch — processVESCMessage(packetId, buffer)

Only these IDs are decoded; anything else logs Unhandled packet type "N".

The COMM_PRINT handler decodes the payload as ASCII and pops a modal alert titled "Terminal Response:". Board-controlled text reaching a UI dialog unfiltered is worth flagging if you care about that class of issue.

COMM_GET_VALUES_SETUP and COMM_BMS_GET_VALUES each appear twice in the comparison chain with identical handlers — the second branch is dead code.

COMM_FW_VERSION (0) response

u8   major
u8   minor
str  hardware name (NUL-terminated)
u8[] uuid (remaining bytes)

COMM_GET_VALUES (4) response

COMM_GET_VALUES_SETUP (47) response

Same prefix through currentBattery, then:

COMM_GET_IMU_DATA (65) response

u16 mask

Then, for each set bit in ascending order, one float32: 0x001 roll, 0x002 pitch, 0x004 yaw, 0x008 accX, 0x010 accY, 0x020 accZ, 0x040 gyroX, 0x080 gyroY, 0x100 gyroZ, 0x200 magX, …

COMM_PING_CAN (62) response

u8[] — one byte per CAN device ID found, length = buffer size.

6. Custom app data — the WFB package layer

This is the app-specific layer, carried inside COMM_CUSTOM_APP_DATA (36).

COMM_CUSTOM_APP_DATA  appId:u8  subCommand:u8  [payload…]

AppPacketTypes.WFB = 102. getVescAppData reads the first two bytes and returns null unless appId === 102 — so this app will not talk to a stock Float package board (which uses app ID 101) or a Refloat board.

Sub-commands (FloatPacketTypes)

IDs 0–27 track the Float package's FLOAT_COMMAND_* layout; 100–103 are specific to this fork.

The app's telemetry loop is getRTFloatData(ctx, canId) → getData(COMM_CUSTOM_APP_DATA, WFB, GET_ALL_DATA, canId), and getAllFloatData additionally issues a plain COMM_GET_VALUES_SETUP.

GET_ALL_DATA (10) response

Requires buffer.size() >= 35, else the parse is abandoned.

u8  mode

Then, always:

After reading switchState the app normalises it: raw 2 → FULL, raw 1 → ADC1 or ADC2 depending on which of adc1/adc2 is larger, anything else → OFF.

If mode >= 2, four more fields:

Then, unconditionally:

Enums used by the telemetry

state (low nibble): 0 BOOT, 1 RUNNING, 2 RUNNING_TILTBACK, 3 RUNNING_WHEELSLIP, 4 RUNNING_UPSIDEDOWN, 5 RUNNING_FLYWHEEL, 6 STOP_ANGLE_PITCH, 7 STOP_ANGLE_ROLL, 8 STOP_SWITCH_HALF, 9 STOP_SWITCH_FULL, 11 STARTUP, 12 STOP_REVERSE, 13 STOP_QUICKSTOP, 14 CHARGING, 15 DISABLED. (No 10.)

setpointAdjustmentType (high nibble): 0 CENTERING, 1 REVERSESTOP, 2 TILTBACK_NONE, 3 TILTBACK_DUTY, 4 TILTBACK_HV, 5 TILTBACK_LV, 6 TILTBACK_TEMP.

switchState: 0 OFF, 1 ADC1, 2 ADC2, 3 FULL.

LED type: 0 NONE, 1 RGB, 2 RGBW, 3 EXTERNAL.

Ride mode: 0 DutyCycle, 1 Standard.

7. Custom config — COMM_GET_CUSTOM_CONFIG / COMM_SET_CUSTOM_CONFIG

This is where the .vescpkg content would normally live, and the reason none is bundled.

getFloatConf(buffer) reads:

u8   (discarded)
u32  signature

then looks the signature up in a version map. The map has exactly one entry, version 1 — so this build supports a single WFB config revision, and an unrecognised signature yields null, surfacing to the user as "Package Version Unsupported or failed to get config". The signature value itself is computed at runtime from the parameter table (VESC Tool-style hash), not stored as a literal, so it can't be read off directly.

Per version the app holds three generated artefacts: configPropertyMetadata (the schema), a parser built by getParser(metadata), a serialiser built by getEncoder(metadata), and configPageLayout for the UI. This is exactly the code-gen output that VESC Tool produces from a package's config XML — embedded rather than fetched.

The bike_config parameter table (27 entries)

vTx is the wire type; scale is vTxDoubleScale (value is transmitted as an integer of value × scale). Negative bounds appear below as their true signed values — in the decompiled output they show as 4294967xxx because the decompiler renders them unsigned.

The declared JS types for the whole set are: config_name: string, hw_name: undefined, package_disable: boolean, and the remainder number except the five booleans (throttle_tilt_enabled, anti_loop_enabled, anti_loop_use_button_angle, persist_wheelie_throttle, persist_wheelie_brake).

hw_name carries the description "This is the VESC Logging and Communication Module."

8. Client architecture

VescCommandManager
  ├─ getData(packetId, …args)   → builds payload, awaits matching response
  ├─ writeData(...bytes)        → prepends CAN forward, generatePacket, writeBuffer
  ├─ writeBuffer(id, packet)    → MTU chunking + base64 + BLE write
  ├─ getMotorConfigPayload / getAppConfigPayload / getFloatConfigPayload
  ├─ detectAllFoc, testDirection, setDutyCycle, setCurrent, disableAppOutput
  ├─ requestEBMSConfig, helpME
  └─ showDisconnectNotification / ensureNotificationPermissions

VescMessageHandler   — queueMessage, reassembly, ~115 accessors
VescMessageParser    — processVESCMessage, processVESCBMSMessage
VescBuffer           — buffer.c equivalent
VescBackgroundService— foreground-service connection keep-alive
VescStatsStore / VescDataContextProvider / useVescData / useVescStatsListener

Outbound commands are matched to responses via a commandCallbacks map; when callbacks are outstanding in COMMAND_MODE_SERIAL the sender backs off in 10 ms increments before writing.

Third-party SDKs linked in: Sentry (libsentry.so, libsentry-android.so), Firebase messaging + analytics, Google Play Services ML Kit barcode scanning (the QR scanner, per the camera permission rationale), Reanimated, RN Screens.

9. Summary of defects found

10. Reproducing this

unzip Wheelie-Fun-Bike_1_0_0_apkcube.apks base.apk
mkdir base && cd base && unzip ../base.apk
pip install hermes-dec
hbc-decompiler assets/index.android.bundle decompiled.js

The bundle is Hermes bytecode v96; hbctool does not support that version, hermes-dec does. Output is ~26 MB of register-level pseudo-JS — grep for // Original name: to locate functions.