Foreground Android preview

Keyboard Helper Companion

A phone-sized companion for layout Browse, connection evidence, and compatible read-only Live telemetry. This guide separates the linked release from newer workspace work in the repository.

Published artifact

Signed v0.6.4 preview for API 31+ arm64 devices. The public physical-device baseline is Android 12 / API 31+ on arm64-v8a.

Open v0.6.4 release

1. Download, verify, and install

Open the published release above and download both Keyboard-Helper-Companion_<version>_android-arm64_preview.apk and its neighboring .sha256 sidecar.
Compare the APK's SHA-256 value with the sidecar using a trusted checksum-capable file manager or utility.
Open the APK and allow unknown-app installation only for the browser or file manager that opened it. Do not disable Android security globally.
Launch Keyboard Helper Companion. Grant Nearby devices when the app asks for it during connection.

If Android refuses an update over a locally built debug APK, the signatures differ. Uninstall the debug app once and install the signed preview. App permission and private imported-layout data may reset; Android usually owns keyboard pairing separately.

2. Pair and connect

Wake the keyboard and choose an available ZMK Bluetooth profile.
Pair the keyboard in Android Settings before selecting it in the companion.
In v0.6.4, choose Connect, select the bonded keyboard, and wait for Connection: connected.
Optional Battery Service and Device Information values appear only when the keyboard exposes them; a missing value is not itself a connection failure.

3. Browse workspace

Browse displays bundled layouts with stock or enhanced ZMK firmware. The companion is foreground-only: active connection, keyboard selection, highlights, and Live session state are process-local.

Later release preview — not in v0.6.4. A newer adaptive workspace moves device actions to Settings > Connection, custom definitions to Settings > Layouts, and secondary Live diagnostics to Settings > Status. Those directions and screenshots are not current for the linked APK.

4. Manage custom layouts

Import one Keyboard Helper JSON document. After validation, the companion copies the definition and inline image bytes atomically into private app storage and does not retain the source URI. The selected visual layout returns at its first layer after relaunch; connection and Live state do not persist.

Text-only layouts remain supported.
Image-bearing layouts declare keyboard-helper-layout version 1, define a top-level embeddedAssets table, and reference images with asset:<id>.
Use non-animated PNG, JPEG, or WebP bitmaps. Limits are 128 KiB per image, 512 KiB total decoded image bytes, 16 assets, 256 × 256 pixels per image, and 1 MiB for the JSON document.
Keep accessible text beside each image legend. External paths, remote URLs, arbitrary data URLs, SVG, missing or unused assets, malformed base64, and oversized content are rejected.
Equivalent canonical JSON selects the existing record. Different content with the same custom name asks before replacement.
Removing a custom layout also removes its private images. Clearing app data or uninstalling removes every import. Nothing synchronizes with desktop or cloud storage.

The old .khlayout ZIP package was an unsupported preview format. It has no migration, conversion, or re-import compatibility path; use a supported JSON definition instead.

5. Use compatible read-only Live

Stock firmware remains useful for Browse and connection overview. Live requires the compatible Keyboard Helper enhanced firmware extension and follows read-only layer, key, combo, and diagnostic telemetry. The phone never activates or writes a remote keyboard layer.

Use the Live control available in v0.6.4. The adaptive Settings > Status route belongs to a later unpublished workspace.

6. Understand the support boundary

Public preview support

Physical BLE acceptance and the downloadable preview baseline are Android 12 / API 31+ and arm64-v8a.

Android 11 evidence

Browse startup has deterministic UI/runtime compatibility evidence on Android 11 / API 30 with WebView 91. This is not a claim of accepted physical BLE support.

Package minimum

The declared minimum SDK allows installation below the public baseline, but it is not a promise that all product behavior or BLE paths are supported there.

7. Troubleshoot bounded failures

Permission, Bluetooth, or empty scan

Grant Nearby devices, enable Bluetooth, wake the keyboard, confirm Android pairing, and retry. If no bonded device appears, pair in system Settings first.

PIN, security, capacity, or reconnect exhaustion

Remove the Android pairing, clear the selected ZMK Bluetooth profile, restart both sides, pair again, and reconnect. If connection capacity is exhausted, disconnect another central or choose a free keyboard profile.

Waiting for Live, unsupported protocol, or sequence gap

Stock firmware honestly reports Live as unavailable. With enhanced firmware, press a key or change a physical layer, then reconnect if waiting persists. A sequence gap means telemetry was missed and the app will resubscribe; repeated unsupported-protocol errors require matching firmware and companion versions.

Layout mismatch or invalid stored layout

Select a layout containing the reported layer. If imported JSON fails, check its version, asset references, bitmap type, base64, dimensions, byte limits, and duplicate name. A missing or corrupt stored record is skipped and selection repairs to the bundled default.

Need the shorter diagnostic answer? Go to the FAQ. Using the desktop overlay instead? Follow desktop setup.