tgrosinger/zmk
1
0
Fork 0
Code Actions Packages

Compare commits

base: tgrosinger:308d6bce6eb338f387a454c7366d0bcb07463d7b
Branches Tags
tgrosinger:tgrosinger-keyboards
..
compare: tgrosinger:0d3a4b7bbb199103d151ee1cadde613101859054
Branches Tags
tgrosinger:tgrosinger-keyboards

No commits in common. "308d6bce6eb338f387a454c7366d0bcb07463d7b" and "0d3a4b7bbb199103d151ee1cadde613101859054" have entirely different histories.
308d6bce6e ... 0d3a4b7bbb

44 changed files with 377 additions and 525 deletions
Show Stats Expand all files Collapse all files

2
.github/workflows/pre-commit.yml vendored
View File

@ -12,4 +12,4 @@ jobs:
- uses: actions/setup-python@v5 - uses: actions/setup-python@v5
with: with:
python-version: 3.x python-version: 3.x
- uses: pre-commit/action@v3.0.1 - uses: pre-commit/action@v3.0.0

4
app/Kconfig
View File

@ -157,7 +157,7 @@ config ZMK_BLE_EXPERIMENTAL_CONN
bool "Experimental BLE connection changes" bool "Experimental BLE connection changes"
help help
Enables a combination of settings that are planned to be default in future versions of ZMK Enables a combination of settings that are planned to be default in future versions of ZMK
to improve connection stability. This includes changes to timing on BLE pairing initiation, to improve connection stability. This includes changes to timing on BLE pairing initation,
restores use of the updated/new LLCP implementation, and disables 2M PHY support. restores use of the updated/new LLCP implementation, and disables 2M PHY support.
config ZMK_BLE_EXPERIMENTAL_SEC config ZMK_BLE_EXPERIMENTAL_SEC
@ -257,7 +257,7 @@ menu "Display/LED Options"
rsource "src/display/Kconfig" rsource "src/display/Kconfig"
menuconfig ZMK_RGB_UNDERGLOW menuconfig ZMK_RGB_UNDERGLOW
bool "RGB Addressable LED Underglow" bool "RGB Adressable LED Underglow"
select LED_STRIP select LED_STRIP
select ZMK_LOW_PRIORITY_WORK_QUEUE select ZMK_LOW_PRIORITY_WORK_QUEUE

2
app/boards/arm/corneish_zen/corneish_zen_v1_left.dts
View File

@ -88,7 +88,7 @@
fuelgauge: bq274xx@55 { fuelgauge: bq274xx@55 {
compatible = "ti,bq274xx"; compatible = "ti,bq274xx";
reg = <0x55>; reg = <0x55>;
design-voltage = <3700>; //Battery Design Voltage in mV design-voltage = <3700>; //Battery Design Volatge in mV
design-capacity = <180>; //Battery Design Capacity in mAh design-capacity = <180>; //Battery Design Capacity in mAh
taper-current = <2>; //Battery Taper current in mAh taper-current = <2>; //Battery Taper current in mAh
terminate-voltage = <2750>; //Battery Terminate Voltage in mV terminate-voltage = <2750>; //Battery Terminate Voltage in mV

2
app/boards/arm/corneish_zen/corneish_zen_v1_right.dts
View File

@ -96,7 +96,7 @@
fuelgauge: bq274xx@55 { fuelgauge: bq274xx@55 {
compatible = "ti,bq274xx"; compatible = "ti,bq274xx";
reg = <0x55>; reg = <0x55>;
design-voltage = <3700>; //Battery Design Voltage in mV design-voltage = <3700>; //Battery Design Volatge in mV
design-capacity = <180>; //Battery Design Capacity in mAh design-capacity = <180>; //Battery Design Capacity in mAh
taper-current = <2>; //Battery Taper current in mAh 2.1 taper-current = <2>; //Battery Taper current in mAh 2.1
terminate-voltage = <2750>; //Battery Terminate Voltage in mV terminate-voltage = <2750>; //Battery Terminate Voltage in mV

6
app/boards/arm/mikoto/Kconfig
View File

@ -4,12 +4,6 @@ config BOARD_ENABLE_DCDC
default y default y
depends on (BOARD_MIKOTO_520) depends on (BOARD_MIKOTO_520)
config BOARD_ENABLE_DCDC_HV
bool "High voltage DCDC converter"
select SOC_DCDC_NRF52X_HV
default y
depends on (BOARD_MIKOTO_520)
choice BOARD_MIKOTO_CHARGER_CURRENT choice BOARD_MIKOTO_CHARGER_CURRENT
prompt "Charge current to supply to attached batteries" prompt "Charge current to supply to attached batteries"
depends on (BOARD_MIKOTO_520) depends on (BOARD_MIKOTO_520)

6
app/boards/arm/nice_nano/Kconfig
View File

@ -5,9 +5,3 @@ config BOARD_ENABLE_DCDC
select SOC_DCDC_NRF52X select SOC_DCDC_NRF52X
default y default y
depends on (BOARD_NICE_NANO || BOARD_NICE_NANO_V2) depends on (BOARD_NICE_NANO || BOARD_NICE_NANO_V2)
config BOARD_ENABLE_DCDC_HV
bool "High voltage DCDC converter"
select SOC_DCDC_NRF52X_HV
default y
depends on (BOARD_NICE_NANO_V2)

2
app/boards/interconnects/seeed_xiao/seeed_xiao.zmk.yml
View File

@ -5,7 +5,7 @@ type: interconnect
url: https://wiki.seeedstudio.com/Seeeduino-XIAO/ url: https://wiki.seeedstudio.com/Seeeduino-XIAO/
manufacturer: Seeed manufacturer: Seeed
description: | description: |
The Seeed(uino) XIAO is a popular smaller format micro-controller, that has gained popularity as an alternative The Seeed(uino) XIAO is a popular smaller format micro-controller, that has gained popularity as an alterative
to the SparkFun Pro Micro. Since its creation, several pin compatible controllers, such to the SparkFun Pro Micro. Since its creation, several pin compatible controllers, such
as the Seeeduino XIAO BLE, Adafruit QT Py and Adafruit QT Py RP2040, have become available. as the Seeeduino XIAO BLE, Adafruit QT Py and Adafruit QT Py RP2040, have become available.
node_labels: node_labels:

6
app/boards/shields/zmk_uno/zmk_uno.dtsi
View File

@ -125,9 +125,9 @@ nice_view_spi: &arduino_spi {
toggle-mode; toggle-mode;
input-gpios input-gpios
= <&arduino_header 4 GPIO_ACTIVE_LOW> = <&arduino_header 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
, <&arduino_header 3 GPIO_ACTIVE_LOW> , <&arduino_header 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
, <&arduino_header 2 GPIO_ACTIVE_LOW> , <&arduino_header 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
; ;
}; };

2
app/dts/behaviors/soft_off.dtsi
View File

@ -6,7 +6,7 @@
/ { / {
behaviors { behaviors {
/omit-if-no-ref/ soft_off: z_so_off { /omit-if-no-ref/ soft_off: keymap_soft_off {
compatible = "zmk,behavior-soft-off"; compatible = "zmk,behavior-soft-off";
#binding-cells = <0>; #binding-cells = <0>;
split-peripheral-off-on-press; split-peripheral-off-on-press;

2
app/dts/common/arduino_uno_pro_micro_map.dtsi
View File

@ -4,7 +4,7 @@
* SPDX-License-Identifier: MIT * SPDX-License-Identifier: MIT
*/ */
/* This provides a mapping from Arduino Uno to Arduino Pro Micro pins for development */ /* This provies a mapping from Arduino Uno to Arduino Pro Micro pins for development */
/ { / {
pro_micro_d: connector_d { pro_micro_d: connector_d {

6
app/include/zmk/display.h
View File

@ -23,12 +23,12 @@ int zmk_display_init(void);
* *
* @param listener THe ZMK Event manager listener name. * @param listener THe ZMK Event manager listener name.
* @param state_type The struct/enum type used to store/transfer state. * @param state_type The struct/enum type used to store/transfer state.
* @param cb The callback to invoke in the display queue context to update the UI. Should be `void * @param cb The callback to invoke in the dispaly queue context to update the UI. Should be `void
* func(state_type)` signature. * func(state_type)` signature.
* @param state_func The callback function to invoke to fetch the updated state from ZMK core. * @param state_func The callback function to invoke to fetch the updated state from ZMK core.
* Should be `state type func(const zmk_event_t *eh)` signature. * Should be `state type func(const zmk_event_t *eh)` signature.
* @retval listener##_init Generates a function `listener##_init` that should be called by the * @retval listner##_init Generates a function `listener##_init` that should be called by the widget
* widget once ready to be updated. * once ready to be updated.
**/ **/
#define ZMK_DISPLAY_WIDGET_LISTENER(listener, state_type, cb, state_func) \ #define ZMK_DISPLAY_WIDGET_LISTENER(listener, state_type, cb, state_func) \
K_MUTEX_DEFINE(listener##_mutex); \ K_MUTEX_DEFINE(listener##_mutex); \

2
app/src/behaviors/behavior_hold_tap.c
View File

@ -181,7 +181,7 @@ static void release_captured_events() {
// //
// Events for different mod-tap instances are separated by a NULL pointer. // Events for different mod-tap instances are separated by a NULL pointer.
// //
// The first event popped will never be caught by the next active hold-tap // The first event popped will never be catched by the next active hold-tap
// because to start capturing a mod-tap-key-down event must first completely // because to start capturing a mod-tap-key-down event must first completely
// go through the events queue. // go through the events queue.
// //

3
app/src/behaviors/behavior_soft_off.c
View File

@ -57,9 +57,6 @@ static int on_keymap_binding_released(struct zmk_behavior_binding *binding,
uint32_t hold_time = k_uptime_get() - data->press_start; uint32_t hold_time = k_uptime_get() - data->press_start;
if (hold_time > config->hold_time_ms) { if (hold_time > config->hold_time_ms) {
if (IS_ENABLED(CONFIG_ZMK_SPLIT) && IS_ENABLED(CONFIG_ZMK_SPLIT_ROLE_CENTRAL)) {
k_sleep(K_MSEC(100));
}
zmk_pm_soft_off(); zmk_pm_soft_off();
} else { } else {
LOG_INF("Not triggering soft off: held for %d and hold time is %d", hold_time, LOG_INF("Not triggering soft off: held for %d and hold time is %d", hold_time,

2
app/src/combo.c
View File

@ -162,7 +162,7 @@ static int setup_candidates_for_first_keypress(int32_t position, int64_t timesta
static int filter_candidates(int32_t position) { static int filter_candidates(int32_t position) {
// this code iterates over candidates and the lookup together to filter in O(n) // this code iterates over candidates and the lookup together to filter in O(n)
// assuming they are both sorted on key_position_len, virtual_key_position // assuming they are both sorted on key_position_len, virtal_key_position
int matches = 0, lookup_idx = 0, candidate_idx = 0; int matches = 0, lookup_idx = 0, candidate_idx = 0;
while (lookup_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY && while (lookup_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY &&
candidate_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY) { candidate_idx < CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY) {

2
app/src/kscan_sideband_behaviors.c
View File

@ -173,7 +173,7 @@ static int ksbb_pm_action(const struct device *dev, enum pm_device_action action
struct ksbb_data ksbb_data_##n = {}; \ struct ksbb_data ksbb_data_##n = {}; \
PM_DEVICE_DT_INST_DEFINE(n, ksbb_pm_action); \ PM_DEVICE_DT_INST_DEFINE(n, ksbb_pm_action); \
DEVICE_DT_INST_DEFINE(n, ksbb_init, PM_DEVICE_DT_INST_GET(n), &ksbb_data_##n, \ DEVICE_DT_INST_DEFINE(n, ksbb_init, PM_DEVICE_DT_INST_GET(n), &ksbb_data_##n, \
&ksbb_config_##n, APPLICATION, \ &ksbb_config_##n, POST_KERNEL, \
CONFIG_ZMK_KSCAN_SIDEBAND_BEHAVIORS_INIT_PRIORITY, &ksbb_api); CONFIG_ZMK_KSCAN_SIDEBAND_BEHAVIORS_INIT_PRIORITY, &ksbb_api);
DT_INST_FOREACH_STATUS_OKAY(KSBB_INST) DT_INST_FOREACH_STATUS_OKAY(KSBB_INST)

2
app/src/split/Kconfig
View File

@ -24,7 +24,7 @@ config ZMK_SPLIT_PERIPHERAL_HID_INDICATORS
bool "Peripheral HID Indicators" bool "Peripheral HID Indicators"
depends on ZMK_HID_INDICATORS depends on ZMK_HID_INDICATORS
help help
Enable propagating the HID (LED) Indicator state to the split peripheral(s). Enable propogating the HID (LED) Indicator state to the split peripheral(s).
#ZMK_SPLIT #ZMK_SPLIT
endif endif

2
app/src/split/bluetooth/central.c
View File

@ -585,7 +585,7 @@ static bool split_central_eir_found(const bt_addr_le_t *addr) {
return false; return false;
} }
LOG_DBG("Initiating new connection"); LOG_DBG("Initiating new connnection");
struct bt_le_conn_param *param = struct bt_le_conn_param *param =
BT_LE_CONN_PARAM(CONFIG_ZMK_SPLIT_BLE_PREF_INT, CONFIG_ZMK_SPLIT_BLE_PREF_INT, BT_LE_CONN_PARAM(CONFIG_ZMK_SPLIT_BLE_PREF_INT, CONFIG_ZMK_SPLIT_BLE_PREF_INT,
CONFIG_ZMK_SPLIT_BLE_PREF_LATENCY, CONFIG_ZMK_SPLIT_BLE_PREF_TIMEOUT); CONFIG_ZMK_SPLIT_BLE_PREF_LATENCY, CONFIG_ZMK_SPLIT_BLE_PREF_TIMEOUT);

2
app/tests/mod-morph/2b-masked-morph-implicit-overwrite/native_posix_64.keymap
View File

@ -7,7 +7,7 @@
mod_morph: mod_morph { mod_morph: mod_morph {
compatible = "zmk,behavior-mod-morph"; compatible = "zmk,behavior-mod-morph";
#binding-cells = <0>; #binding-cells = <0>;
bindings = <&kp A>, <&kp LS(B)>; // implicit mod overwrite bindings = <&kp A>, <&kp LS(B)>; // implict mod overwrite
mods = <(MOD_LSFT|MOD_RSFT)>; mods = <(MOD_LSFT|MOD_RSFT)>;
}; };
}; };

2
docs/blog/2020-08-12-zmk-sotf-1.md
View File

@ -19,7 +19,7 @@ There's been lots of various activity in ZMK land!
- Tons of [documentation](/docs) work. - Tons of [documentation](/docs) work.
- Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users. - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users.
- Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now. - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.
- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. - An initial [`setup.sh`](http://localhost:3000/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
- Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added. - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added.
- Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added. - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added.

2
docs/blog/2021-07-17-zephyr-2-5.md
View File

@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
The following steps will get you building ZMK locally against Zephyr 2.5: The following steps will get you building ZMK locally against Zephyr 2.5:
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- pull the latest ZMK `main` with `git pull` for your ZMK checkout - pull the latest ZMK `main` with `git pull` for your ZMK checkout
- run `west update` to pull the updated Zephyr version and its dependencies - run `west update` to pull the updated Zephyr version and its dependencies

2
docs/blog/2022-04-02-zephyr-3-0.md
View File

@ -62,7 +62,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image.
The following steps will get you building ZMK locally against Zephyr 3.0: The following steps will get you building ZMK locally against Zephyr 3.0:
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- pull the latest ZMK `main` with `git pull` for your ZMK checkout - pull the latest ZMK `main` with `git pull` for your ZMK checkout
- run `west update` to pull the updated Zephyr version and its dependencies - run `west update` to pull the updated Zephyr version and its dependencies

2
docs/blog/2022-04-10-zmk-sotf-5.md
View File

@ -132,7 +132,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes: The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:
- [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly. - [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed. - [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
#### Split Connections #### Split Connections

4
docs/blog/2023-04-06-zephyr-3-2.md
View File

@ -57,7 +57,7 @@ and then update it as appropriate to build the right shields/boards for your con
### Upgrade a manual script ### Upgrade a manual script
If you have a custom GitHub Actions workflow you need to maintain for some reason, you can update the workflow to use the `stable` Docker image tag for the build: If you have a custom GitHub Actions workflow you need to maintain for some reason, you can update the workflow to to use the `stable` Docker image tag for the build:
- Open `.github/workflows/build.yml` in your editor/IDE - Open `.github/workflows/build.yml` in your editor/IDE
- Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found - Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found
@ -87,7 +87,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image.
The following steps will get you building ZMK locally against Zephyr 3.2: The following steps will get you building ZMK locally against Zephyr 3.2:
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- Install the latest version of `west` by running `pip3 install --user --update west`. - Install the latest version of `west` by running `pip3 install --user --update west`.
- pull the latest ZMK `main` with `git pull` for your ZMK checkout - pull the latest ZMK `main` with `git pull` for your ZMK checkout
- run `west update` to pull the updated Zephyr version and its dependencies - run `west update` to pull the updated Zephyr version and its dependencies

2
docs/blog/2024-01-05-zmk-tools.md
View File

@ -145,7 +145,7 @@ I should note that, as a native English speaker and typer, I don't use any of th
## Keyboard Latency Testing ## Keyboard Latency Testing
The last project I want to mention is a tool for testing keyboard latency. It requires only a Raspberry Pi, an optocoupler IC, a resistor, and some wire. If you've ever wondered how ZMK's latency compares to other keyboards, you can [check the results here](https://github.com/joelspadin/keyboard-latency-tester/blob/main/results/chart.ipynb)! The last project I want to mention is a tool for testing keyboard latency. It requires only a Rasbperry Pi, an optocoupler IC, a resistor, and some wire. If you've ever wondered how ZMK's latency compares to other keyboards, you can [check the results here](https://github.com/joelspadin/keyboard-latency-tester/blob/main/results/chart.ipynb)!
I don't have a very large collection of keyboards though, so the data is pretty limited so far. If you want to try it on your own keyboard, see the instructions on the [keyboard latency tester README](https://github.com/joelspadin/keyboard-latency-tester), and please send me a PR with your results! I don't have a very large collection of keyboards though, so the data is pretty limited so far. If you want to try it on your own keyboard, see the instructions on the [keyboard latency tester README](https://github.com/joelspadin/keyboard-latency-tester), and please send me a PR with your results!

2
docs/blog/2024-02-09-zephyr-3-5.md
View File

@ -70,7 +70,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image.
The following steps will get you building ZMK locally against Zephyr 3.5: The following steps will get you building ZMK locally against Zephyr 3.5:
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work) - Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- Install the latest version of `west` by running `pip3 install --user --update west`. - Install the latest version of `west` by running `pip3 install --user --update west`.
- Pull the latest ZMK `main` with `git pull` for your ZMK checkout - Pull the latest ZMK `main` with `git pull` for your ZMK checkout
- Run `west update` to pull the updated Zephyr version and its dependencies - Run `west update` to pull the updated Zephyr version and its dependencies

2
docs/docs/behaviors/caps-word.md
View File

@ -7,7 +7,7 @@ sidebar_label: Caps Word
The caps word behavior behaves similar to a caps lock, but will automatically deactivate when any key not in a continue list is pressed, or if the caps word key is pressed again. For smaller keyboards using [mod-taps](/docs/behaviors/mod-tap), this can help avoid repeated alternating holds when typing words in all caps. The caps word behavior behaves similar to a caps lock, but will automatically deactivate when any key not in a continue list is pressed, or if the caps word key is pressed again. For smaller keyboards using [mod-taps](/docs/behaviors/mod-tap), this can help avoid repeated alternating holds when typing words in all caps.
The modifiers are applied only to the alphabetic (`A` to `Z`) keycodes, to avoid automatically applying them to numeric values, etc. The modifiers are applied only to to the alphabetic (`A` to `Z`) keycodes, to avoid automatically applying them to numeric values, etc.
### Behavior Binding ### Behavior Binding

4
docs/docs/behaviors/index.mdx
View File

@ -47,9 +47,9 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
## Reset behaviors ## Reset behaviors
| Binding | Behavior | Description | | Binding | Behavior | Description |
| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- | | ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device | | `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware | | `&bootloader` | [Bootloader](reset.md#bootloader) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
## Output selection behaviors ## Output selection behaviors

2
docs/docs/config/battery.md
View File

@ -18,7 +18,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
:::note[Default setting] :::note[Default setting]
While `CONFIG_ZMK_BATTERY_REPORTING` is disabled by default it is implied by `CONFIG_ZMK_BLE`, thus any board with BLE enabled will have this automatically enabled unless explicitly overridden. While `CONFIG_ZMK_BATTERY_REPORTING` is disabled by default it is implied by `CONFIG_ZMK_BLE`, thus any board with BLE enabled will have this automatically enabled unless explicitly overriden.
::: :::

4
docs/docs/config/bluetooth.md
View File

@ -10,8 +10,8 @@ See [Configuration Overview](index.md) for instructions on how to change these s
## Kconfig ## Kconfig
| Option | Type | Description | Default | | Option | Type | Description | Default |
| -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | -------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. This includes changes to timing on BLE pairing initiation, restores use of the updated/new LLCP implementation, and disables 2M PHY support. | n | | `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` | bool | Enables a combination of settings that are planned to be default in future versions of ZMK to improve connection stability. This includes changes to timing on BLE pairing initation, restores use of the updated/new LLCP implementation, and disables 2M PHY support. | n |
| `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n | | `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC` | bool | Enables a combination of settings that are planned to be officially supported in the future. This includes enabling BT Secure Connection passkey entry, and allows overwrite of keys from previously paired hosts. | n |
| `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n | | `CONFIG_ZMK_BLE_EXPERIMENTAL_FEATURES` | bool | Aggregate config that enables both `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN` and `CONFIG_ZMK_BLE_EXPERIMENTAL_SEC`. | n |
| `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n | | `CONFIG_ZMK_BLE_PASSKEY_ENTRY` | bool | Enable passkey entry during pairing for enhanced security. (Note: After enabling this, you will need to re-pair all previously paired hosts.) | n |

23
docs/docs/config/kscan.md
View File

@ -81,6 +81,10 @@ Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-direct.yaml](
| `toggle-mode` | bool | Use toggle switch mode. | n | | `toggle-mode` | bool | Use toggle switch mode. | n |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n | | `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n |
By default, a switch will drain current through the internal pull up/down resistor whenever it is pressed. This is not ideal for a toggle switch, where the switch may be left in the "pressed" state for a long time. Enabling `toggle-mode` will make the driver flip between pull up and down as the switch is toggled to optimize for power.
`toggle-mode` applies to all switches handled by the instance of the driver. To use a toggle switch with other, non-toggle, direct GPIO switches, create two instances of the direct GPIO driver, one with `toggle-mode` and the other without. Then, use a [composite driver](#composite-driver) to combine them.
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`: Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
```dts ```dts
@ -94,25 +98,6 @@ Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](http
}; };
``` ```
By default, a switch will drain current through the internal pull up/down resistor whenever it is pressed. This is not ideal for a toggle switch, where the switch may be left in the "pressed" state for a long time. Enabling `toggle-mode` will make the driver enable and disable the internal pull up/down resistor as needed when the switch is toggled to minimise power draw. For `toggle-mode` to work correctly each pole of the switch needs a dedicated GPIO pin.
`toggle-mode` applies to all switches handled by the instance of the driver. To use a toggle switch with other, non-toggle, direct GPIO switches, create two instances of the direct GPIO driver, one with `toggle-mode` and the other without. Then, use a [composite driver](#composite-driver) to combine them. The state of the switch is read on power on, so if the switch is moved whilst the board is off this will get correctly interpreted by the driver.
When using `toggle-mode` the pull resistors get automatically set by the driver and should not be set in the devicetree via GPIO flags. Assuming the common pole of the switch is connected to ground with an SP3T switch:
```dts
kscan_sp3t_toggle: kscan_sp3t_toggle {
compatible = "zmk,kscan-gpio-direct";
toggle-mode;
input-gpios
= <&pro_micro 4 GPIO_ACTIVE_LOW>
, <&pro_micro 3 GPIO_ACTIVE_LOW>
, <&pro_micro 2 GPIO_ACTIVE_LOW>
;
};
```
## Matrix Driver ## Matrix Driver
Keyboard scan driver where keys are arranged on a matrix with one GPIO per row and column. Keyboard scan driver where keys are arranged on a matrix with one GPIO per row and column.

2
docs/docs/config/system.md
View File

@ -31,7 +31,7 @@ Making changes to any of the settings in this section modifies the HID report de
| Config | Type | Description | Default | | Config | Type | Description | Default |
| ------------------------------------- | ---- | -------------------------------------------------------------- | ------- | | ------------------------------------- | ---- | -------------------------------------------------------------- | ------- |
| `CONFIG_ZMK_HID_INDICATORS` | bool | Enable receipt of HID/LED indicator state from connected hosts | n | | `CONFIG_ZMK_HID_INDICATORS` | bool | Enable reciept of HID/LED indicator state from connected hosts | n |
| `CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE` | int | Number of consumer keys simultaneously reportable | 6 | | `CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE` | int | Number of consumer keys simultaneously reportable | 6 |
Exactly zero or one of the following options may be set to `y`. The first is used if none are set. Exactly zero or one of the following options may be set to `y`. The first is used if none are set.

2
docs/docs/customization.md
View File

@ -40,7 +40,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
::: :::
:::note :::note
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and
[building instructions](development/build-flash.mdx), which includes pointers to [building instructions](development/build-flash.mdx), which includes pointers to
[building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder). [building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
::: :::

4
docs/docs/development/new-shield.mdx
View File

@ -554,7 +554,7 @@ Add additional bindings as necessary to match the default number of encoders on
### GitHub Actions ### GitHub Actions
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md), Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx),
at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build: at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
- Add all your pending changes with `git add .` - Add all your pending changes with `git add .`
@ -566,7 +566,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
### Local Build ### Local Build
:::note :::note
To build locally, be sure you've followed the [development setup](./setup/index.md) guide first. To build locally, be sure you've followed the [development setup](./setup.mdx) guide first.
::: :::
Once you've fully created the new keyboard shield definition, Once you've fully created the new keyboard shield definition,

322
docs/docs/development/setup.mdx Normal file
View File

@ -0,0 +1,322 @@
---
title: Toolchain Setup
sidebar_label: Toolchain Setup
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
export const OsTabs = (props) => (
<Tabs
groupId="operating-systems"
defaultValue="debian"
values={[
{ label: "VS Code & Docker", value: "docker" },
{ label: "Debian/Ubuntu", value: "debian" },
{ label: "Windows", value: "win" },
{ label: "macOS", value: "mac" },
{ label: "Raspberry OS", value: "raspberryos" },
{ label: "Fedora", value: "fedora" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
This guide will show you how to set up a development environment for building ZMK locally.
## Install Dependencies
Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)
<OsTabs>
<TabItem value="docker">
This option use the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach is also the easiest to set up. No toolchain or dependencies are necessary when using Docker; the container image you'll be using already has the toolchain installed and set up to use.
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
2. Install [Visual Studio Code](https://code.visualstudio.com/)
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
:::info
The docker container already includes `west`. Skip past the following section to [Get Source Code](#get-source-code).
:::
</TabItem>
<TabItem value="debian">
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
Return to this guide once you are finished with each section.
</TabItem>
<TabItem value="win">
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
Return to this guide once you are finished with each section.
`dfu-util` is required to flash devices that use DFU, but there is currently no maintained package for it on Chocolatey. [QMK Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it though.
</TabItem>
<TabItem value="mac">
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
Return to this guide once you are finished with each section.
</TabItem>
<TabItem value="raspberryos">
#### Install Base Dependencies
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
Return to this guide once you are finished with each section.
#### Install Cross-Compile Toolchain
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
First, the cross compiler should be installed:
```sh
sudo apt install gcc-arm-none-eabi
```
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
```sh
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
```
</TabItem>
<TabItem value="fedora">
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora.
</TabItem>
</OsTabs>
### Install West
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.5.0/develop/west/index.html) used to configure and build Zephyr OS applications.
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.5.0/develop/west/install.html) are summarized here:
<Tabs
defaultValue="linux"
groupId="python-os"
values={[
{label: 'Linux', value: 'linux'},
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="linux">
Install west:
```sh
pip3 install --user -U west
```
Verify that west is installed:
```sh
west --version
```
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure `~/.local/bin` is on your `PATH` environment variable. You can add it with these commands:
```sh
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
</TabItem>
<TabItem value="win">
Install west:
```sh
pip3 install -U west
```
Verify that west is installed:
```sh
west --version
```
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure that the Python scripts directory is on your `PATH` environment variable. You can add it by opening a PowerShell window and running the following commands:
```powershell
$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
$env:PATH += ";$Scripts"
```
</TabItem>
<TabItem value="mac">
Install west:
```sh
pip3 install -U west
```
</TabItem>
</Tabs>
## Get Source Code
Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command:
```
git clone https://github.com/zmkfirmware/zmk.git
```
## Initialize & Update Zephyr Workspace
Since ZMK is built as a Zephyr™ application, the next step is
to use `west` to initialize and update your workspace. The ZMK
Zephyr™ application is in the `app/` source directory:
### Step into the repository
<OsTabs>
<TabItem value="debian">
```sh
cd zmk
```
</TabItem>
<TabItem value="raspberryos">
```sh
cd zmk
```
</TabItem>
<TabItem value="fedora">
```sh
cd zmk
```
</TabItem>
<TabItem value="mac">
```sh
cd zmk
```
</TabItem>
<TabItem value="win">
```sh
cd zmk
```
</TabItem>
<TabItem value="docker">
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
![VS Code Dev Container Configuration Alert](../assets/dev-setup/vscode_devcontainer.png)
Click `Reopen in Container` in order to reopen the VS Code with the running container.
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
:::warning
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
:::
</TabItem>
</OsTabs>
### Initialize the Application
```sh
west init -l app/
```
### Update to Fetch Modules
```sh
west update
```
:::tip
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
:::
:::info
If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx).
:::
### Export Zephyr CMake package
This allows CMake to load the code needed to build ZMK.
```sh
west zephyr-export
```
### Install Zephyr Python Dependencies
Some additional Python dependencies are listed in Zephyr's `scripts/requirements.txt` file.
<Tabs
defaultValue="linux"
groupId="python-os"
values={[
{label: 'Linux', value: 'linux'},
{label: 'Windows', value: 'win'},
{label: 'macOS', value: 'mac'},
]}>
<TabItem value="linux">
```sh
pip3 install --user -r zephyr/scripts/requirements.txt
```
</TabItem>
<TabItem value="win">
```sh
pip3 install -r zephyr/scripts/requirements.txt
```
</TabItem>
<TabItem value="mac">
```sh
pip3 install -r zephyr/scripts/requirements.txt
```
</TabItem>
</Tabs>

53
docs/docs/development/setup/docker.md
View File

@ -1,53 +0,0 @@
---
title: Docker
sidebar_label: Docker
---
:::note
Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode) (not [Code OSS](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code)). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome!
:::
### Source Code
First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
### Installing Development Tools
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
2. Install [VS Code](https://code.visualstudio.com/).
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
### Initialize & Update Zephyr Workspace
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
![VS Code Dev Container Configuration Alert](../../assets/dev-setup/vscode_devcontainer.png)
Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`.
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
:::caution
The following step and any future [build commands](../build-flash.mdx) must be executed from the VS Code terminal _inside_ the container.
:::
Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
:::info
You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
Your setup is complete once your container has restarted.
:::

20
docs/docs/development/setup/index.md
View File

@ -1,20 +0,0 @@
---
title: Getting Started
sidebar_label: Getting Started
---
:::tip
We recommend reading through the setup process before following it step by step, to ensure that you are happy with installing the required dependencies.
:::
## Environment Setup
There are two ways to set up the ZMK development environment:
- [Docker](/docs/development/setup/docker): \
A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use.
- [Native](/docs/development/setup/native):\
This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system.
Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup.

353
docs/docs/development/setup/native.mdx
View File

@ -1,353 +0,0 @@
---
title: Native Setup
sidebar_label: Native
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
export const OsTabs = (props) => (
<Tabs
groupId="operating-system"
defaultValue="ubuntu"
values={[
{ label: "Ubuntu", value: "ubuntu" },
{ label: "Windows", value: "win" },
{ label: "Mac OS", value: "mac" }
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const OsNoteTabs = (props) => (
<Tabs
groupId="operating-system"
defaultValue="win"
values={[
{ label: "Windows", value: "win" },
{ label: "Raspberry OS", value: "raspberryos" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const EnvTabs = (props) => (
<Tabs
groupId="python-environment"
defaultValue="venv"
values={[
{ label: "Install within Virtual Environment", value: "venv" },
{ label: "Install globally", value: "glob" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const WinTermTabs = (props) => (
<Tabs
groupId="windows-terminal-choice"
defaultValue="cmd"
values={[
{ label: "Command Prompt", value: "cmd" },
{ label: "Powershell", value: "ps" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
## 1. Install Zephyr Dependencies
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
:::info
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
:::
## 2. Source Code
Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
Then step into the repository.
```sh
cd zmk
```
## 3. Get Zephyr and install Python dependencies
:::note
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
:::
<EnvTabs>
<TabItem value="venv">
<Tabs groupId="operating-systems" defaultValue="ubuntu">
<TabItem value="ubuntu" label="Ubuntu">
1. Use `apt` to install Python `venv` package:
```sh
sudo apt install python3-venv
```
2. Create a new virtual environment and activate it:
```sh
python3 -m venv .venv
source .venv/bin/activate
```
</TabItem>
<TabItem value="win" label="Windows">
1. Create a new virtual environment:
```sh
python -m venv .venv
```
2. Activate the virtual environment:
<WinTermTabs>
<TabItem value="cmd">
```sh
.venv\Scripts\activate.bat
```
</TabItem>
<TabItem value="ps">
```powershell
.venv\Scripts\Activate.ps1
```
</TabItem>
</WinTermTabs>
</TabItem>
<TabItem value="mac" label="Mac OS">
1. Create a new virtual environment:
```sh
python3 -m venv .venv
```
2. Activate the virtual environment:
```sh
source .venv/bin/activate
```
</TabItem>
</Tabs>
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
4. Install west:
```sh
pip install west
```
5. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="glob">
<Tabs groupId="operating-systems" defaultValue="ubuntu">
<TabItem value="ubuntu" label="Ubuntu">
1. Install `west`:
```sh
pip3 install --user -U west
```
:::note
You need `~/.local/bin` to be on your `PATH` environment variable; verify that it is by running
```sh
west --version
```
If this prints an error rather than a `west` version number, then add `~/.local/bin` to your `PATH`:
```sh
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
:::
</TabItem>
<TabItem value="win" label="Windows">
1. Install `west`:
```sh
pip install -U west
```
:::note
You need the Python scripts directory to be on your PATH environment variable; verify that it is by running
```sh
west --version
```
If this prints an error rather than a `west` version number, then add said directory to your `PATH` with PowerShell:
```powershell
$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
$env:PATH += ";$Scripts"
```
:::
</TabItem>
<TabItem value="mac" label="Mac OS">
1. Install `west`:
```sh
pip3 install -U west
```
</TabItem>
</Tabs>
2. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
<Tabs groupId="operating-systems" defaultValue="ubuntu" className="secrettabs">
<TabItem value="ubuntu" label="Ubuntu">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="win" label="Windows">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="mac" label="Mac OS">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
</Tabs>
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
### OS specific notes
<OsNoteTabs>
<TabItem value="win">
`dfu-util` is required to flash devices that use DFU, but there is currently
no maintained package for it on Chocolatey. [QMK
Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it
though.
</TabItem>
<TabItem value="raspberryos">
#### Install Cross-Compile Toolchain
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
First, the cross compiler should be installed:
```sh
sudo apt install gcc-arm-none-eabi
```
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
```sh
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
```
</TabItem>
</OsNoteTabs>
Your setup is now complete.

2
docs/docs/features/backlight.mdx
View File

@ -58,7 +58,7 @@ config LED_PWM
endif # ZMK_BACKLIGHT endif # ZMK_BACKLIGHT
``` ```
Create a `<board>-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `<board>.dts` file. `CONFIG_PINCTRL=y` must be added to `<board>_defconfig` if it isn't already enabled. Create a `<board>-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `<board>.dts` file. `CONFIG_PINCTRL=y` must be added to to `<board>_defconfig` if it isn't already enabled.
The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges): The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges):

2
docs/docs/troubleshooting.md
View File

@ -34,7 +34,7 @@ macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `<firmwar
### CMake Error ### CMake Error
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined. An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html). For more information, see [toolchain setup documentation](../docs/development/setup.mdx).
### West Build Errors ### West Build Errors

3
docs/docusaurus.config.js
View File

@ -31,7 +31,6 @@ module.exports = {
"linker-script", "linker-script",
"log", "log",
"powershell", "powershell",
"diff",
], ],
theme, theme,
darkTheme, darkTheme,
@ -80,7 +79,7 @@ module.exports = {
}, },
{ {
label: "Development", label: "Development",
to: "docs/development/setup", to: "docs/development/setup/",
}, },
], ],
}, },

11
docs/sidebars.js
View File

@ -76,16 +76,7 @@ module.exports = {
"development/clean-room", "development/clean-room",
"development/pre-commit", "development/pre-commit",
"development/documentation", "development/documentation",
{ "development/setup",
type: "category",
label: "Setup",
collapsed: true,
items: [
"development/setup/index",
"development/setup/docker",
"development/setup/native",
],
},
"development/build-flash", "development/build-flash",
"development/boards-shields-keymaps", "development/boards-shields-keymaps",
"development/posix-board", "development/posix-board",

4
docs/src/css/custom.css
View File

@ -46,7 +46,3 @@
width: 100%; width: 100%;
height: 100%; height: 100%;
} }
.secrettabs {
display: none;
}

2
docs/src/templates/setup.ps1.mustache
View File

@ -308,6 +308,6 @@ if ($github_repo -ne "") {
if ($github_repo -imatch "https") { if ($github_repo -imatch "https") {
$actions = "$($github_repo.substring(0, $github_repo.length - 4))/actions" $actions = "$($github_repo.substring(0, $github_repo.length - 4))/actions"
Write-Host "Your firmware should be available from GitHub Actions shortly: $actions" Write-Host "Your firmware should be availalbe from GitHub Actions shortly: $actions"
} }
} }

2
docs/src/templates/setup.sh.mustache
View File

@ -297,7 +297,7 @@ if [ -n "$github_repo" ]; then
exit 1 exit 1
fi fi
# TODO: Support determining the actions URL when non-https:// repo URL is used. # TODO: Support determing the actions URL when non-https:// repo URL is used.
if [ "${github_repo}" != "${github_repo#https://}" ]; then if [ "${github_repo}" != "${github_repo#https://}" ]; then
echo "Your firmware should be available from GitHub Actions shortly: ${github_repo%.git}/actions" echo "Your firmware should be available from GitHub Actions shortly: ${github_repo%.git}/actions"
fi fi