diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/behavior/bluetooth.md | 76 | ||||
| -rw-r--r-- | docs/sidebars.js | 1 |
2 files changed, 77 insertions, 0 deletions
diff --git a/docs/docs/behavior/bluetooth.md b/docs/docs/behavior/bluetooth.md new file mode 100644 index 0000000..f802a9a --- /dev/null +++ b/docs/docs/behavior/bluetooth.md @@ -0,0 +1,76 @@ +--- +title: Bluetooth Behavior +sidebar_label: Bluetooth +--- + +## Summary + +The bluetooth behavior allows management of various settings and states related to the bluetooth connection(s) +between the keyboard and the host. By default, ZMK supports five "profiles" for selecting which bonded host +computer/laptop/keyboard should receive the keyboard input; many of the commands here operation on those profiles. + +## Bluetooth Command Defines + +Bluetooth command defines are provided through the [`dt-bindings/zmk/bt.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/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_CLR_CMD`. + +Here is a table describing the command for each define: + +| Define | Action | +| ------------ | ---------------------------------------------------------------------------------------------- | +| `BT_CLR_CMD` | Clear bond information between the keyboard and host for the selected profile [^1] | +| `BT_NXT_CMD` | Switch to the next profile, cycling through to the first one when the end is reached. | +| `BT_PRV_CMD` | Switch to the previous profile, cycling through to the last one when the beginning is reached. | +| `BT_SEL_CMD` | Select the 0-indexed profile by number. | + +Because at least one bluetooth commands takes an additional parameter, it is recommended to use +the following aliases in your keymap to avoid having to specify an ignored second parameter: + +| Define | Action | +| -------- | -------------------------------------------------------------------------------- | +| `BT_CLR` | Alias for `BT_CLR_CMD 0` to clear the current profile's bond to the current host | +| `BT_NXT` | Alias for `BT_NXT_CMD 0` to select the next profile | +| `BT_PRV` | Alias for `BT_PRV_CMD 0` to select the previous profile | +| `BT_SEL` | Alias for `BT_SEL_CMD` to select the given profile, e.g. `&bt BT_SEL 1` | + +## 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_CLR_CMD` +- Parameter #2: (Reserved for future bluetooth command types) + +### Examples + +1. Behavior binding to clear the paired host for the selected profile: + + ``` + &bt BT_CLR + ``` + +1. Behavior binding to select the next profile: + + ``` + &bt BT_NXT + ``` + +1. Behavior binding to select the previous profile: + + ``` + &bt BT_NXT + ``` + +1. Behavior binding to select the 2nd profile (passed parameters are [zero based](https://en.wikipedia.org/wiki/Zero-based_numbering)): + + ``` + &bt BT_SEL 1 + ``` diff --git a/docs/sidebars.js b/docs/sidebars.js index 6bd3aa4..ace7fa1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -22,6 +22,7 @@ module.exports = { "behavior/hold-tap", "behavior/mod-tap", "behavior/reset", + "behavior/bluetooth", "behavior/lighting", ], Development: [ |