SDK

Bluetooth mouse and keyboard

How a Kode Dot serves HID over GATT so a computer or a phone uses it as a Bluetooth mouse, a keyboard or both: the choice, the bonds, the pairing code, the reports and the console verbs.

What it is

A Kode Dot can be a Bluetooth mouse, a keyboard, or both, for a computer or a phone. The computer pairs with it from its own Bluetooth settings, with nothing to install, and the app then sends mouse movements, clicks and keys.

AO_Radio serves the HID service over GATT (HID over GATT, service 0x1812) beside the console's service. Nothing of it exists until it is asked for: an app chooses the kinds with kode_ble_hid_select(), and KodeOS reads its stored ble_hid setting. A firmware that asks for nothing keeps the GATT table and the advert it had.

HID needs CONFIG_KODEOS_BLE_CONSOLE_PAIRING=y, the default, because the service uses the console's security. Without it every kind is refused.

How it is connected

flowchart LR
app["app task<br/>kode_ble_hid_*()"] --> sys["kode_sys_ble_hid_*()"]
ao2["app AO"] --> sys
sys -- "claim a slot,<br/>BLE_HID_REPORT_REQ_SIG" --> radio["AO_Radio"]
radio -- "kdrv_ble_hid_push(), kick()" --> drv["kdrv_ble<br/>ring of 16"]
drv -- "notification" --> c5["ESP32-C5"]
c5 -- "Bluetooth" --> host["computer or phone"]
power["AO_Power"] -- "POWER_EVT_SIG" --> radio
class radio ao
class c5 chip
class app,ao2 app
From a call to the computer

A call claims a slot of the driver's ring from the calling task (kdrv_ble_hid_claim()) and posts the report to AO_Radio in a BleHidReportEvt (kind, tap, len, data). AO_Radio alone pushes the report into the ring and kicks the link, and NimBLE's host task sends the notification. The report reaches the computer once it has subscribed to the reports of that kind. A link that ends empties the ring.

AO_Radio also hands every charge reading of POWER_EVT_SIG to the Battery service, so the computer shows the Kode Dot's battery.

The choice of kinds

The radio reads the choice once, when it registers its GATT table at Bluetooth's first start in the boot. From then the choice is fixed until the next boot.

What the board serves

With HID chosen, the GATT table carries three more services after the console's and the app's: HID (0x1812) with the SDK's own report map, Battery, and Device Information with Kode as the maker. The advert carries 0x1812 and the appearance beside the console's UUID, in place of its transmit power:

KindsAppearance
Mouse0x03C2, a mouse
Keyboard0x03C1, a keyboard
Both0x03C0, a generic HID device

The board takes one link. While a computer uses it as a mouse or a keyboard, neither the console nor a phone gets in. A computer bonded as a host comes back by itself whenever it sees the board. A firmware that serves no HID hangs up on such a host once its link is encrypted, so the one link stays free for everything else.

Bonds: a host or the console

A bond belongs to the console or to the HID service, by what the board was when the bond was made, and opens that one alone:

The service that refuses answers ATT's Insufficient Authorization. A device changes its use by pairing again: to use the console from a computer that is a host, forget the board on the computer and pair again while no HID is served.

The board keeps up to three hosts in the NVS namespace kble_hid, key hosts, and the print of the GATT table it registered last in key table. When the table changes between boots, the subscriptions the bonds stored are forgotten, except Service Changed, which tells each bond to read the table again.

Pairing

Security is the console's, so with the passkey (KODEOS_BLE_PAIRING_PASSKEY, the default) a host pairs with a six-digit code shown on the Kode Dot.

The bond is kept, so a computer pairs once.

The reports

ReportBytesLayout
Mouse4 (KDRV_BLE_HID_MOUSE_LEN)Buttons (bit 0 left, 1 right, 2 middle), x, y, wheel. Movement and wheel are relative, -127 to 127
Keyboard8 (KDRV_BLE_HID_KEYS_LEN)The eight modifier bits (left Control first), a zero byte, six keys. A key is a usage ID from 1 to 101 (0x65): 4 is a

A report never waits. It is queued for the link, KODE_BLE_HID_RING_SLOTS (16) at most, and a full queue fails the call. A keyboard report says which keys are down now, so the report that lets them go must follow it. That report, all zeroes, is never refused for want of room: the driver owes it and sends it behind what is queued (kdrv_ble_hid_owe()), so a key is never left down. kode_ble_hid_tap() and kode_ble_hid_click() press and let go in one call, which takes two slots, both or neither.

A report also leaves 16 blocks of the small event pool free for the other Active Objects. Without that room, the call fails as with a full ring.

Specifications

The facade (kode.h)

For app_main() and tasks of your own. Each call returns at once.

CallWhat it does
bool kode_ble_hid_select(uint8_t kinds)KODE_BLE_HID_MOUSE (0x01), KODE_BLE_HID_KEYBOARD (0x02), both, or 0 for neither. False for a kind that does not exist, once the table is registered, or in a firmware without the console's pairing
bool kode_ble_hid_ready(void)True when a computer is connected and takes the reports of every kind chosen. Sets no error
bool kode_ble_hid_mouse(uint8_t buttons, int8_t dx, int8_t dy, int8_t wheel)One mouse report. False when Bluetooth is off in Settings, the mouse is not chosen, no computer takes its reports, or the queue is full. A report of no button and no movement never fails for a full queue
bool kode_ble_hid_click(uint8_t buttons)Presses the buttons and lets them go. False for no button too
bool kode_ble_hid_keys(uint8_t modifiers, const uint8_t *keys)One keyboard report: up to KODE_BLE_HID_KEYS_MAX (6) usage IDs held down, 0 for none, copied. NULL lets every key go
bool kode_ble_hid_tap(uint8_t modifiers, uint8_t key)Types one key: presses it with its modifiers and lets it go. False for a key out of range too
bool kode_ble_pair_open(void)Opens five minutes to pair. False when Bluetooth is off in Settings, no kind is chosen, or the radio has no room for the request

Every false return leaves kode_error() saying why. The events ble_pair_code (the code as the value, and as six digits of text with the leading zeroes) and ble_pair_done (value 1 when the device is bonded, 0 when it is not) are named by KODE_EVENT_BLE_PAIR_CODE and KODE_EVENT_BLE_PAIR_DONE (sdk/kode).

The commands (kode_sys.h)

For an Active Object of the app. The bits and limits are the same, as KODE_SYS_BLE_HID_*.

CallAnswers
kode_sys_ble_hid_select(kinds)KODE_OK, or KODE_DENIED as above
kode_sys_ble_hid_ready()A bool, from any task
kode_sys_ble_hid_mouse(buttons, dx, dy, wheel), kode_sys_ble_hid_keys(modifiers, keys)KODE_OK when queued. KODE_DENIED when the kind is not served or no host is subscribed to it. KODE_NO_RESOURCES when the ring is full: send it again, or the sum
kode_sys_ble_hid_click(buttons), kode_sys_ble_hid_tap(modifiers, key)As above, two reports, both queued or neither. KODE_DENIED for no button or a key out of range
kode_sys_ble_pair_open()KODE_OK when asked. KODE_DENIED in an app that serves no HID, or without CONFIG_KODEOS_BLE. KODE_NO_RESOURCES when AO_Radio's queue had no room, and nothing was asked
kode_sys_ble_pair_subscribe(me)Subscribes the Active Object to BLE_PAIR_SIG and links AO_Radio. KODE_DENIED for NULL, an Active Object not started, or without CONFIG_KODEOS_BLE

BLE_PAIR_SIG carries a kode_sys_ble_pair_t (BlePairEvt): phase is KODE_SYS_BLE_PAIR_SHOW (1, show passkey, six digits), KODE_SYS_BLE_PAIR_DONE (2, outcome says how it ended, KODE_SYS_BLE_PAIR_OK = 0 for bonded) or KODE_SYS_BLE_PAIR_REFUSED (3, a device asked outside the time to pair and was hung up on, with no code). In a refusal outcome says why: 5, the driver's KDRV_BLE_PAIR_APP_CLOSED, in an app that is not pairing, and 4, KDRV_BLE_PAIR_HIDDEN, in KodeOS. A phone retries, so a refusal is told at most once in KODE_BLE_PAIR_REFUSED_QUIET_MS (10 s), and it opens nothing. The standard layer makes no event of it: ble_pair_code and ble_pair_done come from SHOW and DONE alone.

The console

VerbWhat it does
ble_hid_info>|ble_hid kinds=off|mouse|keyboard|both ready=on|off sent=<n> dropped=<n> then >ok. sent counts the reports the link took since boot, dropped the reports queued or claimed and never sent
ble_hid_mouse [buttons=<0..7>] [right=] [left=] [down=] [up=] [hold=on]One mouse report. Each step is 0 to 127. Buttons are pressed and let go unless hold=on
ble_hid_wheel [up=] [down=]Turns the wheel, 0 to 127. Every button is let go
ble_hid_key code=<1..101> [mods=<0..255>]Presses one key with its modifiers and lets it go
config key="ble_hid" value=off|mouse|keyboard|bothThe stored choice in KodeOS (internals/settings)

The three report verbs run from the cable alone: Bluetooth gets >err code=5 msg=cable, the Kode channel msg=net and the scheduler msg=sched. They answer >ok, >err code=4 msg=busy for a full ring, >err code=5 msg=off when no HID is served, msg=kind when the kind is not served and msg=no_host when no host takes its reports. ble_pair answers >err code=4 msg=busy when AO_Radio's queue has no room for the request.

Gotchas

Example code

No runnable example is available for this page. The console's ble_hid_mouse, ble_hid_wheel and ble_hid_key drive the same reports from the bench once config key="ble_hid" has chosen a kind and a computer has paired.

In the SDK