zmk/docs/docs/behavior/bluetooth.md at cf970efb98c5af97955bfffbcebb3b065b16edc4

Pete Johanson cf970efb98 feat(bluetooth): Proper bond management, identity support for non-splits

* Add `bt` behavior that can be used to perform certain actions,
  such as next/prev identity, reset identity, etc.
  NOTE: Multiple identities is only supported for non-split shields,
  due to missing Zephyr identity functionality for dual
  central/peripheral devices.
* Proper bond reset tied to action, that honors peripheral bonds,
  so folks can reset and pair to other hosts, without breaking
  bonds between splt halves.

2020-09-13 22:33:05 -04:00

3.2 KiB

Raw Blame History

title	sidebar_label
Bluetooth Behavior	Bluetooth

Summary

The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) between the keyboard and the host.

Bluetooth Command Defines

Bluetooth command defines are provided through the dt-bindings/zmk/bt.h header, which is added at the top of the keymap file:

#include <dt-bindings/zmk/bt.h>

This will allow you to reference the actions defined in this header such as BT_IDENT_CLR_CMD.

Here is a table describing the command for each define:

Define	Action
`BT_IDENT_CLR_CMD`	Clear paired keyboards (for the current identity)¹
`BT_IDENT_NEXT_CMD`	Switch to the next identity¹
`BT_IDENT_PREV_CMD`	Switch to the previous identity
`BT_IDENT_SEL_CMD`	Switch to a specific numbered identity
`BT_RST_CMD`	Hard reset of all bluetooth bonds

Because the BT_IDENT_SEL_CMD command takes an additional parameter, the numeric index of the identity to select, all the commands for the bluetooth behavior must take that additional parameter, and ignore the value. To make this easier, there are alias defines that add those default parameters for you:

Define	Action
`BT_IDENT_CLR`	Alias for `BT_IDENT_CLR_CMD 0` to clear paired keyboards (for the current identity)¹
`BT_IDENT_NEXT`	Alias for `BT_IDENT_NEXT_CMD 0` to switch to the next identity¹
`BT_IDENT_PREV`	Alias for `BT_IDENT_PREV_CMD 0` to switch to the previous identity
`BT_IDENT_SEL`	Alias for `BT_IDENT_SEL_CMD` to switch to a specific numbered identity
`BT_RST`	Alias for `BT_RST_CMD 0` to reset all bonds²

Bluetooth Behavior

The bluetooth behavior completes an bluetooth action given on press.

Behavior Binding

Reference: &bt
Parameter #1: The bluetooth command define, e.g. BT_IDENT_CLR_CMD or BT_RST_CMD
Parameter #2: The parameter for the command, when used to identify an identity/profile to select, e.g. 0

Examples

Behavior to clear the paired host:
```
&bt BT_IDENT_CLR
```
Behavior to hard reset all bonded devices²:
```
&bt BT_IDENT_CLR
```

Examples for non-split keyboards with multiple identities:

Behavior to switch to the next identity:
```
&bt BT_IDENT_NEXT
```
Behavior to switch to the specific numbered identity:
```
&bt BT_IDENT_SEL 1
```

Multiple keyboard identities/profiles is only support on non-split keyboards as of this time. ↩︎
This may interrupt pairing between both halves of a split keyboard. For split keyboards, it is preferred to use the [/docs/bond-reset] combo to clear bonds on both devices ↩︎

3.2 KiB Raw Blame History