diff --git a/zmk/.devcontainer/devcontainer.json b/zmk/.devcontainer/devcontainer.json index 14feeff4..0de8bcfb 100644 --- a/zmk/.devcontainer/devcontainer.json +++ b/zmk/.devcontainer/devcontainer.json @@ -6,6 +6,9 @@ "containerEnv": {"WORKSPACE_DIR": "${containerWorkspaceFolder}"}, "settings": { "terminal.integrated.shell.linux": "/bin/bash" - }, + }, + "mounts": [ + "type=volume,source=zmk-config,target=/workspaces/zmk-config" + ] } diff --git a/zmk/.github/workflows/build.yml b/zmk/.github/workflows/build.yml index e6be31ac..f6a12bf4 100644 --- a/zmk/.github/workflows/build.yml +++ b/zmk/.github/workflows/build.yml @@ -25,6 +25,10 @@ jobs: - lily58_right - iris_left - iris_right + - jorne_left + - jorne_right + - jian_left + - jian_right - reviung41 - romac - romac_plus diff --git a/zmk/.github/workflows/test.yml b/zmk/.github/workflows/test.yml index a6af058c..f3e93515 100644 --- a/zmk/.github/workflows/test.yml +++ b/zmk/.github/workflows/test.yml @@ -61,7 +61,7 @@ jobs: id: west-build with: entrypoint: /bin/bash - args: '-c "cd app && ./run-test.sh all"' + args: '-c "west test"' - name: Archive Build if: ${{ always() }} uses: actions/upload-artifact@v2 diff --git a/zmk/.gitignore b/zmk/.gitignore index 8a06510d..93c801d9 100644 --- a/zmk/.gitignore +++ b/zmk/.gitignore @@ -6,3 +6,4 @@ /zmk-config /build *.DS_Store +__pycache__ \ No newline at end of file diff --git a/zmk/app/Kconfig b/zmk/app/Kconfig index 28d2aa2e..484bd798 100644 --- a/zmk/app/Kconfig +++ b/zmk/app/Kconfig @@ -1,3 +1,6 @@ +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + mainmenu "ZMK Firmware" menu "ZMK" diff --git a/zmk/app/boards/Kconfig b/zmk/app/boards/Kconfig index 1c645e6b..fe841c48 100644 --- a/zmk/app/boards/Kconfig +++ b/zmk/app/boards/Kconfig @@ -1 +1,4 @@ +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + rsource "shields/*/Kconfig.shield" diff --git a/zmk/app/boards/shields/jian/Kconfig.defconfig b/zmk/app/boards/shields/jian/Kconfig.defconfig new file mode 100644 index 00000000..b743e7a4 --- /dev/null +++ b/zmk/app/boards/shields/jian/Kconfig.defconfig @@ -0,0 +1,23 @@ + +if SHIELD_JIAN_LEFT + +config ZMK_KEYBOARD_NAME + default "Jian Left" + +endif + + +if SHIELD_JIAN_RIGHT + +config ZMK_KEYBOARD_NAME + default "Jian Right" + +endif + +if SHIELD_JIAN_LEFT || SHIELD_JIAN_RIGHT + +config ZMK_SPLIT + default y + + +endif diff --git a/zmk/app/boards/shields/jian/Kconfig.shield b/zmk/app/boards/shields/jian/Kconfig.shield new file mode 100644 index 00000000..5b874f03 --- /dev/null +++ b/zmk/app/boards/shields/jian/Kconfig.shield @@ -0,0 +1,8 @@ +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + +config SHIELD_JIAN_LEFT + def_bool $(shields_list_contains,jian_left) + +config SHIELD_JIAN_RIGHT + def_bool $(shields_list_contains,jian_right) diff --git a/zmk/app/boards/shields/jian/jian.conf b/zmk/app/boards/shields/jian/jian.conf new file mode 100644 index 00000000..e69de29b diff --git a/zmk/app/boards/shields/jian/jian.dtsi b/zmk/app/boards/shields/jian/jian.dtsi new file mode 100644 index 00000000..331624ea --- /dev/null +++ b/zmk/app/boards/shields/jian/jian.dtsi @@ -0,0 +1,76 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <12>; + rows = <4>; +// | SW0 | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | SW0 | +// | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | +// | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < + RC(2,0) RC(0,0) RC(0,1) RC(1,2) RC(0,2) RC(0,3) RC(0,4) RC(0,7) RC(0,8) RC(0,9) RC(1,9) RC(0,10) RC(0,11) RC(2,11) + RC(1,0) RC(1,1) RC(2,2) RC(1,3) RC(1,4) RC(0,5) RC(0,6) RC(1,7) RC(1,8) RC(2,9) RC(1,10) RC(1,11) + RC(2,1) RC(3,2) RC(3,3) RC(2,3) RC(2,4) RC(1,5) RC(1,6) RC(2,7) RC(2,8) RC(3,8) RC(3,9) RC(2,10) + RC(3,4) RC(2,5) RC(3,5) RC(3,6) RC(2,6) RC(3,7) + >; + }; + + crkbd_transform: keymap_transform_1 { + compatible = "zmk,matrix-transform"; + columns = <12>; + rows = <4>; +// | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | +// | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | +// | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < + RC(0,0) RC(0,1) RC(1,2) RC(0,2) RC(0,3) RC(0,4) RC(0,7) RC(0,8) RC(0,9) RC(1,9) RC(0,10) RC(0,11) + RC(1,0) RC(1,1) RC(2,2) RC(1,3) RC(1,4) RC(0,5) RC(0,6) RC(1,7) RC(1,8) RC(2,9) RC(1,10) RC(1,11) + RC(2,1) RC(3,2) RC(3,3) RC(2,3) RC(2,4) RC(1,5) RC(1,6) RC(2,7) RC(2,8) RC(3,8) RC(3,9) RC(2,10) + RC(3,4) RC(2,5) RC(3,5) RC(3,6) RC(2,6) RC(3,7) + >; + }; + + five_column_transform: keymap_transform_2 { + compatible = "zmk,matrix-transform"; + columns = <10>; + rows = <4>; +// | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | +// | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | +// | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < + RC(0,1) RC(1,2) RC(0,2) RC(0,3) RC(0,4) RC(0,7) RC(0,8) RC(0,9) RC(1,9) RC(0,10) + RC(1,1) RC(2,2) RC(1,3) RC(1,4) RC(0,5) RC(0,6) RC(1,7) RC(1,8) RC(2,9) RC(1,10) + RC(3,2) RC(3,3) RC(2,3) RC(2,4) RC(1,5) RC(1,6) RC(2,7) RC(2,8) RC(3,8) RC(3,9) + RC(3,4) RC(2,5) RC(3,5) RC(3,6) RC(2,6) RC(3,7) + >; + }; + + kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&pro_micro_a 3 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_a 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 15 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 14 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + + }; +}; diff --git a/zmk/app/boards/shields/jian/jian.keymap b/zmk/app/boards/shields/jian/jian.keymap new file mode 100644 index 00000000..256bc51a --- /dev/null +++ b/zmk/app/boards/shields/jian/jian.keymap @@ -0,0 +1,74 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include +#include +#include + +#define DEF 0 +#define LWR 1 +#define RSE 2 +#define ADJ 3 + +/ { + keymap { + compatible = "zmk,keymap"; + + default_layer { +// ----------------------------------------------------------------------------------------- +// | GUI | ~ | Q | W | E | R | T | | Y | U | I | O | P | [ | GUI/] | +// | CTRL | A | S | D | F | G | | H | J | K | L | ; |CTRL/'| +// | LALT | Z | X | C | V | B | | N | M | , | . | / | RALT | +// | RSE | SPC | LWR | | LWR | BKSP | RSE | + bindings = < + &kp LWIN &kp GRAVE &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp LBKT &mt RWIN RBKT + &kp LCTRL &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SCLN &mt RCTRL QUOT + &kp LALT &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp BSLH + < RSE TAB &mt LSHFT SPC < LWR RET < LWR ESC &mt RSHFT BSPC < RSE DEL + >; + }; + lower_layer { +// ----------------------------------------------------------------------------------------- +// | | _ | F1 | F2 | F3 | F4 | F5 | | F6 | F7 | F8 | F9 | F10 | F11 | F12 | +// | + | ! | @ | # | $ | % | | ^ | & | * | ( | ) | - | +// | = | 1 | 2 | 3 | 4 | 5 | | 6 | 7 | 8 | 9 | 0 | | +// | GUI | | SPC | | ENT | | ALT | + bindings = < + &trans &kp UNDER &kp F1 &kp F2 &kp F3 &kp F4 &kp F5 &kp F6 &kp F7 &kp F8 &kp F9 &kp F10 &kp F11 &mt RGUI F12 + &mt LCTRL PLUS &kp EXCL &kp AT &kp HASH &kp DLLR &kp PRCNT &kp CRRT &kp AMPS &kp STAR &kp LPAR &kp RPAR &mt RCTRL MINUS + &mt LALT EQUAL &kp N1 &kp N2 &kp N3 &kp N4 &kp N5 &kp N6 &kp N7 &kp N8 &kp N9 &kp N0 &trans + < ADJ TAB &trans &trans &trans &trans < ADJ DEL + >; + }; + + raise_layer { +// ----------------------------------------------------------------------------------------- +// | | NMLK | / | 7 | 8 | 9 | - | | VOLU| HOME| PRSC| PGUP| SCLK| CLCK| | +// | CTRL | * | 4 | 5 | 6 | + | | MUT | LEFT| UP | RGHT| INS | APP | +// | | 0 | 1 | 2 | 3 | . | | VOLD| END | DOWN| PGDN| PAUS| | +// | | | ADJ | | ADJ | | | + bindings = < + &trans &kp KP_NUM &kp KP_SLASH &kp KP_N7 &kp KP_N8 &kp KP_N9 &kp KP_MINUS &kp C_VOL_UP &kp HOME &kp PSCRN &kp PG_UP &kp SLCK &kp CAPS &trans + &mt LCTRL EQL &kp KP_MULTIPLY &kp KP_N4 &kp KP_N5 &kp KP_N6 &kp KP_PLUS &kp C_MUTE &kp LEFT &kp UP &kp RIGHT &kp INS &mt RCTRL K_APP + &trans &kp KP_N0 &kp KP_N1 &kp KP_N2 &kp KP_N3 &kp KP_DOT &kp C_VOL_DN &kp END &kp DOWN &kp PG_DN &kp PAUS &trans + &trans &trans < ADJ RET < ADJ ESC &trans &trans + >; + }; + adjust_layer { +// ----------------------------------------------------------------------------------------- +// | RST | BLDR | | | | | | | | | | | | BLDR | RST | +// | BTCLR| BT0 | BT1 | BT2 | BT3 | BT4 | | BT4 | BT3 | BT2 | BT1 | BT0 | BTCLR| +// | | | | | | | | | | | | | | +// | | | | | | | | + bindings = < + &reset &bootloader &none &none &none &none &none &none &none &none &none &none &bootloader &reset + &bt BT_CLR &bt BT_SEL 0 &bt BT_SEL 1 &bt BT_SEL 2 &bt BT_SEL 3 &bt BT_SEL 4 &bt BT_SEL 4 &bt BT_SEL 3 &bt BT_SEL 2 &bt BT_SEL 1 &bt BT_SEL 0 &bt BT_CLR + &none &none &none &none &none &none &none &none &none &none &none &none + &trans &none &trans &trans &none &trans + >; + }; + }; +}; diff --git a/zmk/app/boards/shields/jian/jian_left.conf b/zmk/app/boards/shields/jian/jian_left.conf new file mode 100644 index 00000000..1e028a78 --- /dev/null +++ b/zmk/app/boards/shields/jian/jian_left.conf @@ -0,0 +1,2 @@ +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y diff --git a/zmk/app/boards/shields/jian/jian_left.overlay b/zmk/app/boards/shields/jian/jian_left.overlay new file mode 100644 index 00000000..553dbd05 --- /dev/null +++ b/zmk/app/boards/shields/jian/jian_left.overlay @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include "jian.dtsi" + +&kscan0 { + col-gpios + = <&pro_micro_d 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 8 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> + ; +}; diff --git a/zmk/app/boards/shields/jian/jian_right.conf b/zmk/app/boards/shields/jian/jian_right.conf new file mode 100644 index 00000000..990cf7c0 --- /dev/null +++ b/zmk/app/boards/shields/jian/jian_right.conf @@ -0,0 +1,2 @@ +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_PERIPHERAL=y diff --git a/zmk/app/boards/shields/jian/jian_right.overlay b/zmk/app/boards/shields/jian/jian_right.overlay new file mode 100644 index 00000000..1430b817 --- /dev/null +++ b/zmk/app/boards/shields/jian/jian_right.overlay @@ -0,0 +1,22 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include "jian.dtsi" + +&default_transform { + col-offset = <6>; +}; + +&kscan0 { + col-gpios + = <&pro_micro_d 16 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 8 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 1 GPIO_ACTIVE_HIGH> + ; +}; diff --git a/zmk/app/boards/shields/jorne/Kconfig.defconfig b/zmk/app/boards/shields/jorne/Kconfig.defconfig new file mode 100644 index 00000000..a8cf29b8 --- /dev/null +++ b/zmk/app/boards/shields/jorne/Kconfig.defconfig @@ -0,0 +1,58 @@ + +if SHIELD_JORNE_LEFT + +config ZMK_KEYBOARD_NAME + default "Jorne Left" + +endif + + +if SHIELD_JORNE_RIGHT + +config ZMK_KEYBOARD_NAME + default "Jorne Right" + +endif + +if SHIELD_JORNE_LEFT || SHIELD_JORNE_RIGHT + +config ZMK_SPLIT + default y + +if ZMK_DISPLAY + +config I2C + default y + +config SSD1306 + default y + +config SSD1306_REVERSE_MODE + default y + +endif # ZMK_DISPLAY + +if LVGL + +config LVGL_HOR_RES + default 128 + +config LVGL_VER_RES + default 32 + +config LVGL_VDB_SIZE + default 64 + +config LVGL_DPI + default 148 + +config LVGL_BITS_PER_PIXEL + default 1 + +choice LVGL_COLOR_DEPTH + default LVGL_COLOR_DEPTH_1 +endchoice + +endif # LVGL + +endif diff --git a/zmk/app/boards/shields/jorne/Kconfig.shield b/zmk/app/boards/shields/jorne/Kconfig.shield new file mode 100644 index 00000000..11766113 --- /dev/null +++ b/zmk/app/boards/shields/jorne/Kconfig.shield @@ -0,0 +1,8 @@ +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + +config SHIELD_JORNE_LEFT + def_bool $(shields_list_contains,jorne_left) + +config SHIELD_JORNE_RIGHT + def_bool $(shields_list_contains,jorne_right) diff --git a/zmk/app/boards/shields/jorne/boards/nice_nano.overlay b/zmk/app/boards/shields/jorne/boards/nice_nano.overlay new file mode 100644 index 00000000..03b868ce --- /dev/null +++ b/zmk/app/boards/shields/jorne/boards/nice_nano.overlay @@ -0,0 +1,29 @@ +&spi1 { + compatible = "nordic,nrf-spim"; + /* Cannot be used together with i2c0. */ + status = "okay"; + mosi-pin = <6>; + // Unused pins, needed for SPI definition, but not used by the ws2812 driver itself. + sck-pin = <5>; + miso-pin = <7>; + + led_strip: ws2812@0 { + compatible = "worldsemi,ws2812-spi"; + label = "WS2812"; + + /* SPI */ + reg = <0>; /* ignored, but necessary for SPI bindings */ + spi-max-frequency = <4000000>; + + /* WS2812 */ + chain-length = <6>; /* There are per-key RGB, but the first 6 are underglow */ + spi-one-frame = <0x70>; + spi-zero-frame = <0x40>; + }; +}; + +/ { + chosen { + zmk,underglow = &led_strip; + }; +}; diff --git a/zmk/app/boards/shields/jorne/jorne.conf b/zmk/app/boards/shields/jorne/jorne.conf new file mode 100644 index 00000000..c4e62fc0 --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne.conf @@ -0,0 +1,6 @@ +# Uncomment the following lines to enable the Jorne RGB Underglow +# CONFIG_ZMK_RGB_UNDERGLOW=y +# CONFIG_WS2812_STRIP=y + +# Uncomment the following line to enable the Jorne OLED Display +# CONFIG_ZMK_DISPLAY=y diff --git a/zmk/app/boards/shields/jorne/jorne.dtsi b/zmk/app/boards/shields/jorne/jorne.dtsi new file mode 100644 index 00000000..7e6cfd8b --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne.dtsi @@ -0,0 +1,98 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <12>; + rows = <4>; +// | SW0 | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | SW0 | +// | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | +// | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < + RC(3,0) RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11) RC(3,11) + RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11) + RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11) + RC(3,3) RC(3,4) RC(3,5) RC(3,6) RC(3,7) RC(3,8) + >; + }; + + crkbd_transform: keymap_transform_1 { + compatible = "zmk,matrix-transform"; + columns = <12>; + rows = <4>; +// | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | +// | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | +// | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < + RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11) + RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11) + RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11) + RC(3,3) RC(3,4) RC(3,5) RC(3,6) RC(3,7) RC(3,8) + >; + }; + + five_column_transform: keymap_transform_2 { + compatible = "zmk,matrix-transform"; + columns = <10>; + rows = <4>; +// | SW2 | SW3 | SW4 | SW5 | SW6 | | SW6 | SW5 | SW4 | SW3 | SW2 | +// | SW8 | SW9 | SW10 | SW11 | SW12 | | SW12 | SW11 | SW10 | SW9 | SW8 | +// | SW14 | SW15 | SW16 | SW17 | SW18 | | SW18 | SW17 | SW16 | SW15 | SW14 | +// | SW19 | SW20 | SW21 | | SW21 | SW20 | SW19 | + map = < +RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) +RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) +RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) + RC(3,3) RC(3,4) RC(3,5) RC(3,6) RC(3,7) RC(3,8) + >; + }; + + kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 5 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + + }; + + // TODO: per-key RGB node(s)? +}; + +&pro_micro_i2c { + status = "okay"; + + oled: ssd1306@3c { + compatible = "solomon,ssd1306fb"; + reg = <0x3c>; + label = "DISPLAY"; + width = <128>; + height = <32>; + segment-offset = <0>; + page-offset = <0>; + display-offset = <0>; + multiplex-ratio = <31>; + segment-remap; + com-invdir; + com-sequential; + prechargep = <0x22>; + }; +}; diff --git a/zmk/app/boards/shields/jorne/jorne.keymap b/zmk/app/boards/shields/jorne/jorne.keymap new file mode 100644 index 00000000..256bc51a --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne.keymap @@ -0,0 +1,74 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include +#include +#include + +#define DEF 0 +#define LWR 1 +#define RSE 2 +#define ADJ 3 + +/ { + keymap { + compatible = "zmk,keymap"; + + default_layer { +// ----------------------------------------------------------------------------------------- +// | GUI | ~ | Q | W | E | R | T | | Y | U | I | O | P | [ | GUI/] | +// | CTRL | A | S | D | F | G | | H | J | K | L | ; |CTRL/'| +// | LALT | Z | X | C | V | B | | N | M | , | . | / | RALT | +// | RSE | SPC | LWR | | LWR | BKSP | RSE | + bindings = < + &kp LWIN &kp GRAVE &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp LBKT &mt RWIN RBKT + &kp LCTRL &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SCLN &mt RCTRL QUOT + &kp LALT &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp BSLH + < RSE TAB &mt LSHFT SPC < LWR RET < LWR ESC &mt RSHFT BSPC < RSE DEL + >; + }; + lower_layer { +// ----------------------------------------------------------------------------------------- +// | | _ | F1 | F2 | F3 | F4 | F5 | | F6 | F7 | F8 | F9 | F10 | F11 | F12 | +// | + | ! | @ | # | $ | % | | ^ | & | * | ( | ) | - | +// | = | 1 | 2 | 3 | 4 | 5 | | 6 | 7 | 8 | 9 | 0 | | +// | GUI | | SPC | | ENT | | ALT | + bindings = < + &trans &kp UNDER &kp F1 &kp F2 &kp F3 &kp F4 &kp F5 &kp F6 &kp F7 &kp F8 &kp F9 &kp F10 &kp F11 &mt RGUI F12 + &mt LCTRL PLUS &kp EXCL &kp AT &kp HASH &kp DLLR &kp PRCNT &kp CRRT &kp AMPS &kp STAR &kp LPAR &kp RPAR &mt RCTRL MINUS + &mt LALT EQUAL &kp N1 &kp N2 &kp N3 &kp N4 &kp N5 &kp N6 &kp N7 &kp N8 &kp N9 &kp N0 &trans + < ADJ TAB &trans &trans &trans &trans < ADJ DEL + >; + }; + + raise_layer { +// ----------------------------------------------------------------------------------------- +// | | NMLK | / | 7 | 8 | 9 | - | | VOLU| HOME| PRSC| PGUP| SCLK| CLCK| | +// | CTRL | * | 4 | 5 | 6 | + | | MUT | LEFT| UP | RGHT| INS | APP | +// | | 0 | 1 | 2 | 3 | . | | VOLD| END | DOWN| PGDN| PAUS| | +// | | | ADJ | | ADJ | | | + bindings = < + &trans &kp KP_NUM &kp KP_SLASH &kp KP_N7 &kp KP_N8 &kp KP_N9 &kp KP_MINUS &kp C_VOL_UP &kp HOME &kp PSCRN &kp PG_UP &kp SLCK &kp CAPS &trans + &mt LCTRL EQL &kp KP_MULTIPLY &kp KP_N4 &kp KP_N5 &kp KP_N6 &kp KP_PLUS &kp C_MUTE &kp LEFT &kp UP &kp RIGHT &kp INS &mt RCTRL K_APP + &trans &kp KP_N0 &kp KP_N1 &kp KP_N2 &kp KP_N3 &kp KP_DOT &kp C_VOL_DN &kp END &kp DOWN &kp PG_DN &kp PAUS &trans + &trans &trans < ADJ RET < ADJ ESC &trans &trans + >; + }; + adjust_layer { +// ----------------------------------------------------------------------------------------- +// | RST | BLDR | | | | | | | | | | | | BLDR | RST | +// | BTCLR| BT0 | BT1 | BT2 | BT3 | BT4 | | BT4 | BT3 | BT2 | BT1 | BT0 | BTCLR| +// | | | | | | | | | | | | | | +// | | | | | | | | + bindings = < + &reset &bootloader &none &none &none &none &none &none &none &none &none &none &bootloader &reset + &bt BT_CLR &bt BT_SEL 0 &bt BT_SEL 1 &bt BT_SEL 2 &bt BT_SEL 3 &bt BT_SEL 4 &bt BT_SEL 4 &bt BT_SEL 3 &bt BT_SEL 2 &bt BT_SEL 1 &bt BT_SEL 0 &bt BT_CLR + &none &none &none &none &none &none &none &none &none &none &none &none + &trans &none &trans &trans &none &trans + >; + }; + }; +}; diff --git a/zmk/app/boards/shields/jorne/jorne_left.conf b/zmk/app/boards/shields/jorne/jorne_left.conf new file mode 100644 index 00000000..1e028a78 --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne_left.conf @@ -0,0 +1,2 @@ +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y diff --git a/zmk/app/boards/shields/jorne/jorne_left.overlay b/zmk/app/boards/shields/jorne/jorne_left.overlay new file mode 100644 index 00000000..ca6ad431 --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne_left.overlay @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include "jorne.dtsi" + +&kscan0 { + col-gpios + = <&pro_micro_a 3 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 2 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> + ; +}; diff --git a/zmk/app/boards/shields/jorne/jorne_right.conf b/zmk/app/boards/shields/jorne/jorne_right.conf new file mode 100644 index 00000000..990cf7c0 --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne_right.conf @@ -0,0 +1,2 @@ +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_PERIPHERAL=y diff --git a/zmk/app/boards/shields/jorne/jorne_right.overlay b/zmk/app/boards/shields/jorne/jorne_right.overlay new file mode 100644 index 00000000..6ae232eb --- /dev/null +++ b/zmk/app/boards/shields/jorne/jorne_right.overlay @@ -0,0 +1,22 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#include "jorne.dtsi" + +&default_transform { + col-offset = <6>; +}; + +&kscan0 { + col-gpios + = <&pro_micro_d 14 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 2 GPIO_ACTIVE_HIGH> + , <&pro_micro_a 3 GPIO_ACTIVE_HIGH> + ; +}; diff --git a/zmk/app/boards/shields/qaz/qaz.keymap b/zmk/app/boards/shields/qaz/qaz.keymap index 36229727..5dca247b 100644 --- a/zmk/app/boards/shields/qaz/qaz.keymap +++ b/zmk/app/boards/shields/qaz/qaz.keymap @@ -31,27 +31,27 @@ default_layer { bindings = < - &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P - &hm LGUI A &hm LALT S &hm LCTL D &hm LSFT F &kp G &kp H &hm RSFT J &hm RCTL K &hm RALT L &hm RGUI RET - &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp CMMA &kp DOT - &kp LSFT &kp LGUI &kp LALT < NAV RET < NUM_SYM SPC &kp COLN &kp QUOT &kp FSLH + &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P + &hm LGUI A &hm LALT S &hm LCTL D &hm LSFT F &kp G &kp H &hm RSFT J &hm RCTL K &hm RALT L &hm RGUI RET + &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp CMMA &kp DOT + &kp LSFT &kp LGUI &kp LALT < NAV RET < NUM_SYM SPC &kp COLN &kp QUOT &kp FSLH >; }; num_sym { bindings = < - &kp NUM_1 &kp NUM_2 &kp NUM_3 &kp NUM_4 &kp NUM_5 &kp NUM_6 &kp NUM_7 &kp NUM_8 &kp NUM_9 &kp NUM_0 - &trans &trans &trans &trans &trans &trans &trans &trans &kp EQL &kp MINUS - &kp DEL &none &none &none &none &none &none &none &kp DOT - &bootloader &reset &none &trans &trans &kp RET &trans &kp FSLH + &kp N1 &kp N2 &kp N3 &kp N4 &kp N5 &kp N6 &kp N7 &kp N8 &kp N9 &kp N0 + &trans &trans &trans &trans &trans &trans &trans &trans &kp EQL &kp MINUS + &kp DEL &none &none &none &none &none &none &none &kp DOT + &bootloader &reset &none &trans &trans &kp RET &trans &kp FSLH >; }; nav { bindings = < - &bt BT_CLR &bt BT_NXT &bt BT_PRV &none &none &none &none &kp UARW &none &kp BKSP - &trans &trans &trans &trans &none &none &kp LARW &kp DARW &kp RARW &none - &none &none &none &none &none &none &none &none &none - &none &none &none &trans &trans &kp RET &trans &kp FSLH + &bt BT_CLR &bt BT_NXT &bt BT_PRV &none &none &none &none &kp UARW &none &kp BKSP + &trans &trans &trans &trans &none &none &kp LARW &kp DARW &kp RARW &none + &none &none &none &none &none &none &none &none &none + &none &none &none &trans &trans &kp RET &trans &kp FSLH >; }; }; diff --git a/zmk/app/cmake/zmk_config.cmake b/zmk/app/cmake/zmk_config.cmake index 017dd111..145352a3 100644 --- a/zmk/app/cmake/zmk_config.cmake +++ b/zmk/app/cmake/zmk_config.cmake @@ -5,6 +5,8 @@ # * single overlay, # * or per board/shield. +cmake_minimum_required(VERSION 3.15) + get_property(cached_user_config_value CACHE ZMK_CONFIG PROPERTY VALUE) set(user_config_cli_argument ${cached_user_config_value}) # Either new or old diff --git a/zmk/app/drivers/zephyr/Kconfig b/zmk/app/drivers/zephyr/Kconfig index 6b177fb1..b8b2b1be 100644 --- a/zmk/app/drivers/zephyr/Kconfig +++ b/zmk/app/drivers/zephyr/Kconfig @@ -1,3 +1,6 @@ +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + config ZMK_KSCAN_GPIO_DRIVER bool "Enable GPIO kscan driver to simulate key presses" default y diff --git a/zmk/app/drivers/zephyr/module.yml b/zmk/app/drivers/zephyr/module.yml new file mode 100644 index 00000000..cbff6a1a --- /dev/null +++ b/zmk/app/drivers/zephyr/module.yml @@ -0,0 +1,3 @@ +build: + cmake: zephyr + kconfig: zephyr/Kconfig diff --git a/zmk/app/dts/behaviors/bluetooth.dtsi b/zmk/app/dts/behaviors/bluetooth.dtsi index ea09f4a2..9df974b4 100644 --- a/zmk/app/dts/behaviors/bluetooth.dtsi +++ b/zmk/app/dts/behaviors/bluetooth.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { bt: behavior_bluetooth { diff --git a/zmk/app/dts/behaviors/ext_power.dtsi b/zmk/app/dts/behaviors/ext_power.dtsi index 92f00352..471e9fa2 100644 --- a/zmk/app/dts/behaviors/ext_power.dtsi +++ b/zmk/app/dts/behaviors/ext_power.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { ext_power: behavior_ext_power { diff --git a/zmk/app/dts/behaviors/key_press.dtsi b/zmk/app/dts/behaviors/key_press.dtsi index e0668327..98064f69 100644 --- a/zmk/app/dts/behaviors/key_press.dtsi +++ b/zmk/app/dts/behaviors/key_press.dtsi @@ -1,3 +1,8 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ / { behaviors { diff --git a/zmk/app/dts/behaviors/layer_tap.dtsi b/zmk/app/dts/behaviors/layer_tap.dtsi index af7319b3..cca481a7 100644 --- a/zmk/app/dts/behaviors/layer_tap.dtsi +++ b/zmk/app/dts/behaviors/layer_tap.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { lt: behavior_layer_tap { diff --git a/zmk/app/dts/behaviors/mod_tap.dtsi b/zmk/app/dts/behaviors/mod_tap.dtsi index 4ce732b4..b972aba1 100644 --- a/zmk/app/dts/behaviors/mod_tap.dtsi +++ b/zmk/app/dts/behaviors/mod_tap.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { mt: behavior_mod_tap { diff --git a/zmk/app/dts/behaviors/momentary_layer.dtsi b/zmk/app/dts/behaviors/momentary_layer.dtsi index e5b6c3ce..d3b21da9 100644 --- a/zmk/app/dts/behaviors/momentary_layer.dtsi +++ b/zmk/app/dts/behaviors/momentary_layer.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { mo: behavior_momentary_layer { diff --git a/zmk/app/dts/behaviors/none.dtsi b/zmk/app/dts/behaviors/none.dtsi index e84ed491..1fe2cff7 100644 --- a/zmk/app/dts/behaviors/none.dtsi +++ b/zmk/app/dts/behaviors/none.dtsi @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020 Pete Johanson + * Copyright (c) 2020 The ZMK Contributors * * SPDX-License-Identifier: MIT */ diff --git a/zmk/app/dts/behaviors/outputs.dtsi b/zmk/app/dts/behaviors/outputs.dtsi index a534cbf9..ee17e1df 100644 --- a/zmk/app/dts/behaviors/outputs.dtsi +++ b/zmk/app/dts/behaviors/outputs.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { out: behavior_outputs { diff --git a/zmk/app/dts/behaviors/reset.dtsi b/zmk/app/dts/behaviors/reset.dtsi index fc4fa149..cf363425 100644 --- a/zmk/app/dts/behaviors/reset.dtsi +++ b/zmk/app/dts/behaviors/reset.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + #include / { diff --git a/zmk/app/dts/behaviors/rgb_underglow.dtsi b/zmk/app/dts/behaviors/rgb_underglow.dtsi index e8ad9da8..22aff93f 100644 --- a/zmk/app/dts/behaviors/rgb_underglow.dtsi +++ b/zmk/app/dts/behaviors/rgb_underglow.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { rgb_ug: behavior_rgb_underglow { diff --git a/zmk/app/dts/behaviors/sensor_rotate_key_press.dtsi b/zmk/app/dts/behaviors/sensor_rotate_key_press.dtsi index d06eca23..075fc38e 100644 --- a/zmk/app/dts/behaviors/sensor_rotate_key_press.dtsi +++ b/zmk/app/dts/behaviors/sensor_rotate_key_press.dtsi @@ -1,3 +1,8 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ / { behaviors { diff --git a/zmk/app/dts/behaviors/transparent.dtsi b/zmk/app/dts/behaviors/transparent.dtsi index ddd05220..09f9ea00 100644 --- a/zmk/app/dts/behaviors/transparent.dtsi +++ b/zmk/app/dts/behaviors/transparent.dtsi @@ -1,3 +1,9 @@ +/* + * Copyright (c) 2020 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + / { behaviors { trans: behavior_transparent { diff --git a/zmk/app/include/zmk/hid.h b/zmk/app/include/zmk/hid.h index 63cdf3b8..306bc26b 100644 --- a/zmk/app/include/zmk/hid.h +++ b/zmk/app/include/zmk/hid.h @@ -15,7 +15,7 @@ #define COLLECTION_REPORT 0x03 -#define ZMK_HID_KEYPAD_NKRO_SIZE 6 +#define ZMK_HID_KEYBOARD_NKRO_SIZE 6 #define ZMK_HID_CONSUMER_NKRO_SIZE 6 @@ -37,10 +37,10 @@ static const u8_t zmk_hid_report_desc[] = { HID_USAGE_KEY, /* USAGE_MINIMUM (Keyboard LeftControl) */ HID_LI_USAGE_MIN(1), - 0xE0, + HID_USAGE_KEY_KEYBOARD_LEFTCONTROL, /* USAGE_MAXIMUM (Keyboard Right GUI) */ HID_LI_USAGE_MAX(1), - 0xE7, + HID_USAGE_KEY_KEYBOARD_RIGHT_GUI, /* LOGICAL_MINIMUM (0) */ HID_GI_LOGICAL_MIN(1), 0x00, @@ -89,9 +89,9 @@ static const u8_t zmk_hid_report_desc[] = { /* REPORT_SIZE (1) */ HID_GI_REPORT_SIZE, 0x08, - /* REPORT_COUNT (ZMK_HID_KEYPAD_NKRO_SIZE) */ + /* REPORT_COUNT (ZMK_HID_KEYBOARD_NKRO_SIZE) */ HID_GI_REPORT_COUNT, - ZMK_HID_KEYPAD_NKRO_SIZE, + ZMK_HID_KEYBOARD_NKRO_SIZE, /* INPUT (Data,Ary,Abs) */ HID_MI_INPUT, 0x00, @@ -146,15 +146,15 @@ static const u8_t zmk_hid_report_desc[] = { // u8_t keys[6]; // } __packed; -struct zmk_hid_keypad_report_body { +struct zmk_hid_keyboard_report_body { zmk_mod_flags modifiers; u8_t _reserved; - u8_t keys[ZMK_HID_KEYPAD_NKRO_SIZE]; + u8_t keys[ZMK_HID_KEYBOARD_NKRO_SIZE]; } __packed; -struct zmk_hid_keypad_report { +struct zmk_hid_keyboard_report { u8_t report_id; - struct zmk_hid_keypad_report_body body; + struct zmk_hid_keyboard_report_body body; } __packed; struct zmk_hid_consumer_report_body { @@ -170,13 +170,13 @@ int zmk_hid_register_mod(zmk_mod modifier); int zmk_hid_unregister_mod(zmk_mod modifier); int zmk_hid_implicit_modifiers_press(zmk_mod_flags implicit_modifiers); int zmk_hid_implicit_modifiers_release(); -int zmk_hid_keypad_press(zmk_key key); -int zmk_hid_keypad_release(zmk_key key); -void zmk_hid_keypad_clear(); +int zmk_hid_keyboard_press(zmk_key key); +int zmk_hid_keyboard_release(zmk_key key); +void zmk_hid_keyboard_clear(); int zmk_hid_consumer_press(zmk_key key); int zmk_hid_consumer_release(zmk_key key); void zmk_hid_consumer_clear(); -struct zmk_hid_keypad_report *zmk_hid_get_keypad_report(); +struct zmk_hid_keyboard_report *zmk_hid_get_keyboard_report(); struct zmk_hid_consumer_report *zmk_hid_get_consumer_report(); diff --git a/zmk/app/include/zmk/hog.h b/zmk/app/include/zmk/hog.h index a7dda515..7523fb66 100644 --- a/zmk/app/include/zmk/hog.h +++ b/zmk/app/include/zmk/hog.h @@ -11,5 +11,5 @@ int zmk_hog_init(); -int zmk_hog_send_keypad_report(struct zmk_hid_keypad_report_body *body); +int zmk_hog_send_keyboard_report(struct zmk_hid_keyboard_report_body *body); int zmk_hog_send_consumer_report(struct zmk_hid_consumer_report_body *body); diff --git a/zmk/app/scripts/west-commands.yml b/zmk/app/scripts/west-commands.yml new file mode 100644 index 00000000..98e28997 --- /dev/null +++ b/zmk/app/scripts/west-commands.yml @@ -0,0 +1,9 @@ +# Copyright (c) 2020, ZMK Contributors +# SPDX-License-Identifier: MIT + +west-commands: + - file: scripts/west_commands/test.py + commands: + - name: test + class: Test + help: run zmk testsuite \ No newline at end of file diff --git a/zmk/app/scripts/west_commands/test.py b/zmk/app/scripts/west_commands/test.py new file mode 100644 index 00000000..26f95f73 --- /dev/null +++ b/zmk/app/scripts/west_commands/test.py @@ -0,0 +1,33 @@ +# Copyright (c) 2020 The ZMK Contributors +# +# SPDX-License-Identifier: MIT +'''Test runner for ZMK.''' + +import os +from textwrap import dedent # just for nicer code indentation + +from west.commands import WestCommand +from west import log # use this for user output + + +class Test(WestCommand): + def __init__(self): + super().__init__( + 'test', # gets stored as self.name + 'run zmk testsuite', # self.help + # self.description: + dedent('''Run the zmk testsuite.''')) + + def do_add_parser(self, parser_adder): + parser = parser_adder.add_parser(self.name, + help=self.help, + description=self.description) + + parser.add_argument('test_path', default="all", + help='The path to the test. Defaults to "all".', nargs="?") + return parser # gets stored as self.parser + + def do_run(self, args, unknown_args): + # the run-test script assumes the app directory is the current dir. + os.chdir(f'{self.topdir}/app') + exit(os.system(f'{self.topdir}/app/run-test.sh {args.test_path}')) diff --git a/zmk/app/src/endpoints.c b/zmk/app/src/endpoints.c index 9a6967c6..406d23b6 100644 --- a/zmk/app/src/endpoints.c +++ b/zmk/app/src/endpoints.c @@ -53,13 +53,13 @@ int zmk_endpoints_toggle() { return zmk_endpoints_select(new_endpoint); } -static int send_keypad_report() { - struct zmk_hid_keypad_report *keypad_report = zmk_hid_get_keypad_report(); +static int send_keyboard_report() { + struct zmk_hid_keyboard_report *keyboard_report = zmk_hid_get_keyboard_report(); switch (current_endpoint) { #if IS_ENABLED(CONFIG_ZMK_USB) case ZMK_ENDPOINT_USB: { - int err = zmk_usb_hid_send_report((u8_t *)keypad_report, sizeof(*keypad_report)); + int err = zmk_usb_hid_send_report((u8_t *)keyboard_report, sizeof(*keyboard_report)); if (err) { LOG_ERR("FAILED TO SEND OVER USB: %d", err); } @@ -69,7 +69,7 @@ static int send_keypad_report() { #if IS_ENABLED(CONFIG_ZMK_BLE) case ZMK_ENDPOINT_BLE: { - int err = zmk_hog_send_keypad_report(&keypad_report->body); + int err = zmk_hog_send_keyboard_report(&keyboard_report->body); if (err) { LOG_ERR("FAILED TO SEND OVER HOG: %d", err); } @@ -118,7 +118,7 @@ int zmk_endpoints_send_report(u8_t usage_page) { LOG_DBG("usage page 0x%02X", usage_page); switch (usage_page) { case HID_USAGE_KEY: - return send_keypad_report(); + return send_keyboard_report(); case HID_USAGE_CONSUMER: return send_consumer_report(); default: @@ -207,7 +207,7 @@ static enum zmk_endpoint get_selected_endpoint() { } static void disconnect_current_endpoint() { - zmk_hid_keypad_clear(); + zmk_hid_keyboard_clear(); zmk_hid_consumer_clear(); zmk_endpoints_send_report(HID_USAGE_KEY); diff --git a/zmk/app/src/hid.c b/zmk/app/src/hid.c index b84a693f..da2aaab6 100644 --- a/zmk/app/src/hid.c +++ b/zmk/app/src/hid.c @@ -10,7 +10,7 @@ LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL); #include #include -static struct zmk_hid_keypad_report kp_report = { +static struct zmk_hid_keyboard_report kp_report = { .report_id = 1, .body = {.modifiers = 0, ._reserved = 0, .keys = {0}}}; static struct zmk_hid_consumer_report consumer_report = {.report_id = 2, .body = {.keys = {0}}}; @@ -49,8 +49,8 @@ int zmk_hid_unregister_mod(zmk_mod modifier) { return 0; } -#define TOGGLE_KEYPAD(match, val) \ - for (int idx = 0; idx < ZMK_HID_KEYPAD_NKRO_SIZE; idx++) { \ +#define TOGGLE_KEYBOARD(match, val) \ + for (int idx = 0; idx < ZMK_HID_KEYBOARD_NKRO_SIZE; idx++) { \ if (kp_report.body.keys[idx] != match) { \ continue; \ } \ @@ -77,23 +77,23 @@ int zmk_hid_implicit_modifiers_release() { return 0; } -int zmk_hid_keypad_press(zmk_key code) { +int zmk_hid_keyboard_press(zmk_key code) { if (code >= HID_USAGE_KEY_KEYBOARD_LEFTCONTROL && code <= HID_USAGE_KEY_KEYBOARD_RIGHT_GUI) { return zmk_hid_register_mod(code - HID_USAGE_KEY_KEYBOARD_LEFTCONTROL); } - TOGGLE_KEYPAD(0U, code); + TOGGLE_KEYBOARD(0U, code); return 0; }; -int zmk_hid_keypad_release(zmk_key code) { +int zmk_hid_keyboard_release(zmk_key code) { if (code >= HID_USAGE_KEY_KEYBOARD_LEFTCONTROL && code <= HID_USAGE_KEY_KEYBOARD_RIGHT_GUI) { return zmk_hid_unregister_mod(code - HID_USAGE_KEY_KEYBOARD_LEFTCONTROL); } - TOGGLE_KEYPAD(code, 0U); + TOGGLE_KEYBOARD(code, 0U); return 0; }; -void zmk_hid_keypad_clear() { memset(&kp_report.body, 0, sizeof(kp_report.body)); } +void zmk_hid_keyboard_clear() { memset(&kp_report.body, 0, sizeof(kp_report.body)); } int zmk_hid_consumer_press(zmk_key code) { TOGGLE_CONSUMER(0U, code); @@ -107,7 +107,7 @@ int zmk_hid_consumer_release(zmk_key code) { void zmk_hid_consumer_clear() { memset(&consumer_report.body, 0, sizeof(consumer_report.body)); } -struct zmk_hid_keypad_report *zmk_hid_get_keypad_report() { +struct zmk_hid_keyboard_report *zmk_hid_get_keyboard_report() { return &kp_report; } diff --git a/zmk/app/src/hid_listener.c b/zmk/app/src/hid_listener.c index 5efb7987..b93abcab 100644 --- a/zmk/app/src/hid_listener.c +++ b/zmk/app/src/hid_listener.c @@ -23,7 +23,7 @@ static int hid_listener_keycode_pressed(u8_t usage_page, u32_t keycode, implicit_modifiers); switch (usage_page) { case HID_USAGE_KEY: - err = zmk_hid_keypad_press(keycode); + err = zmk_hid_keyboard_press(keycode); if (err) { LOG_ERR("Unable to press keycode"); return err; @@ -48,7 +48,7 @@ static int hid_listener_keycode_released(u8_t usage_page, u32_t keycode, implicit_modifiers); switch (usage_page) { case HID_USAGE_KEY: - err = zmk_hid_keypad_release(keycode); + err = zmk_hid_keyboard_release(keycode); if (err) { LOG_ERR("Unable to release keycode"); return err; diff --git a/zmk/app/src/hog.c b/zmk/app/src/hog.c index bcd652d2..ea61933e 100644 --- a/zmk/app/src/hog.c +++ b/zmk/app/src/hog.c @@ -79,9 +79,9 @@ static ssize_t read_hids_report_map(struct bt_conn *conn, const struct bt_gatt_a static ssize_t read_hids_input_report(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, u16_t len, u16_t offset) { - struct zmk_hid_keypad_report_body *report_body = &zmk_hid_get_keypad_report()->body; + struct zmk_hid_keyboard_report_body *report_body = &zmk_hid_get_keyboard_report()->body; return bt_gatt_attr_read(conn, attr, buf, len, offset, report_body, - sizeof(struct zmk_hid_keypad_report_body)); + sizeof(struct zmk_hid_keyboard_report_body)); } static ssize_t read_hids_consumer_input_report(struct bt_conn *conn, @@ -156,7 +156,7 @@ struct bt_conn *destination_connection() { return conn; } -int zmk_hog_send_keypad_report(struct zmk_hid_keypad_report_body *report) { +int zmk_hog_send_keyboard_report(struct zmk_hid_keyboard_report_body *report) { struct bt_conn *conn = destination_connection(); if (conn == NULL) { return -ENOTCONN; @@ -164,8 +164,8 @@ int zmk_hog_send_keypad_report(struct zmk_hid_keypad_report_body *report) { LOG_DBG("Sending to NULL? %s", conn == NULL ? "yes" : "no"); - int err = - bt_gatt_notify(conn, &hog_svc.attrs[5], report, sizeof(struct zmk_hid_keypad_report_body)); + int err = bt_gatt_notify(conn, &hog_svc.attrs[5], report, + sizeof(struct zmk_hid_keyboard_report_body)); bt_conn_unref(conn); return err; }; diff --git a/zmk/app/src/keymap.c b/zmk/app/src/keymap.c index 1d289e51..70db2fa5 100644 --- a/zmk/app/src/keymap.c +++ b/zmk/app/src/keymap.c @@ -130,14 +130,12 @@ int zmk_keymap_apply_position_state(int layer, u32_t position, bool pressed, s64 } int zmk_keymap_position_state_changed(u32_t position, bool pressed, s64_t timestamp) { + if (pressed) { + zmk_keymap_active_behavior_layer[position] = zmk_keymap_layer_state; + } for (int layer = ZMK_KEYMAP_LAYERS_LEN - 1; layer >= zmk_keymap_layer_default; layer--) { - u32_t layer_state = - pressed ? zmk_keymap_layer_state : zmk_keymap_active_behavior_layer[position]; - if (is_active_layer(layer, layer_state)) { + if (is_active_layer(layer, zmk_keymap_active_behavior_layer[position])) { int ret = zmk_keymap_apply_position_state(layer, position, pressed, timestamp); - - zmk_keymap_active_behavior_layer[position] = zmk_keymap_layer_state; - if (ret > 0) { LOG_DBG("behavior processing to continue to next layer"); continue; diff --git a/zmk/app/tests/momentary-layer/1-normal/events.patterns b/zmk/app/tests/momentary-layer/1-normal/events.patterns new file mode 100644 index 00000000..bd7b4880 --- /dev/null +++ b/zmk/app/tests/momentary-layer/1-normal/events.patterns @@ -0,0 +1,2 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/1-normal/keycode_events.snapshot b/zmk/app/tests/momentary-layer/1-normal/keycode_events.snapshot new file mode 100644 index 00000000..608ce093 --- /dev/null +++ b/zmk/app/tests/momentary-layer/1-normal/keycode_events.snapshot @@ -0,0 +1,4 @@ +mo_pressed: position 1 layer 1 +kp_pressed: usage_page 0x07 keycode 0x06 mods 0x00 +kp_released: usage_page 0x07 keycode 0x06 mods 0x00 +mo_released: position 1 layer 1 diff --git a/zmk/app/tests/momentary-layer/1-normal/native_posix.keymap b/zmk/app/tests/momentary-layer/1-normal/native_posix.keymap new file mode 100644 index 00000000..2fc24d2b --- /dev/null +++ b/zmk/app/tests/momentary-layer/1-normal/native_posix.keymap @@ -0,0 +1,32 @@ +#include +#include +#include +#include "../behavior_keymap.dtsi" + +/ { + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &kp B &mo 1 + &none &none>; + }; + + layer_1 { + bindings = < + &kp C &trans + &none &none>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,1,10) + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_RELEASE(0,0,10) + ZMK_MOCK_RELEASE(0,1,10) + >; +}; \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/2-early-key-release/events.patterns b/zmk/app/tests/momentary-layer/2-early-key-release/events.patterns new file mode 100644 index 00000000..bd7b4880 --- /dev/null +++ b/zmk/app/tests/momentary-layer/2-early-key-release/events.patterns @@ -0,0 +1,2 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/2-early-key-release/keycode_events.snapshot b/zmk/app/tests/momentary-layer/2-early-key-release/keycode_events.snapshot new file mode 100644 index 00000000..82ebc67c --- /dev/null +++ b/zmk/app/tests/momentary-layer/2-early-key-release/keycode_events.snapshot @@ -0,0 +1,4 @@ +kp_pressed: usage_page 0x07 keycode 0x05 mods 0x00 +mo_pressed: position 1 layer 1 +kp_released: usage_page 0x07 keycode 0x05 mods 0x00 +mo_released: position 1 layer 1 diff --git a/zmk/app/tests/momentary-layer/2-early-key-release/native_posix.keymap b/zmk/app/tests/momentary-layer/2-early-key-release/native_posix.keymap new file mode 100644 index 00000000..9ffa5f6e --- /dev/null +++ b/zmk/app/tests/momentary-layer/2-early-key-release/native_posix.keymap @@ -0,0 +1,32 @@ +#include +#include +#include +#include "../behavior_keymap.dtsi" + +/ { + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &kp B &mo 1 + &none &none>; + }; + + layer_1 { + bindings = < + &kp C &none + &none &none>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_PRESS(0,1,10) + ZMK_MOCK_RELEASE(0,0,10) + ZMK_MOCK_RELEASE(0,1,10) + >; +}; \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/3-covered/events.patterns b/zmk/app/tests/momentary-layer/3-covered/events.patterns new file mode 100644 index 00000000..08b1e987 --- /dev/null +++ b/zmk/app/tests/momentary-layer/3-covered/events.patterns @@ -0,0 +1,3 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*keymap_position_state_changed/kp_st/p \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/3-covered/keycode_events.snapshot b/zmk/app/tests/momentary-layer/3-covered/keycode_events.snapshot new file mode 100644 index 00000000..87d12817 --- /dev/null +++ b/zmk/app/tests/momentary-layer/3-covered/keycode_events.snapshot @@ -0,0 +1,2 @@ +mo_pressed: position 1 layer 1 +mo_released: position 1 layer 1 diff --git a/zmk/app/tests/momentary-layer/3-covered/native_posix.keymap b/zmk/app/tests/momentary-layer/3-covered/native_posix.keymap new file mode 100644 index 00000000..2484d8b8 --- /dev/null +++ b/zmk/app/tests/momentary-layer/3-covered/native_posix.keymap @@ -0,0 +1,33 @@ +#include +#include +#include + +/* +this test verifies that the correct key is released when a layer is enabled "on top" +and the original key is "covered". +*/ +/ { + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &trans &mo 1 + &trans &trans>; + }; + + layer_1 { + bindings = < + &trans &kp A + &trans &trans>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,1,10) + ZMK_MOCK_RELEASE(0,1,10) + >; +}; diff --git a/zmk/app/tests/momentary-layer/4-nested/events.patterns b/zmk/app/tests/momentary-layer/4-nested/events.patterns new file mode 100644 index 00000000..08b1e987 --- /dev/null +++ b/zmk/app/tests/momentary-layer/4-nested/events.patterns @@ -0,0 +1,3 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*keymap_position_state_changed/kp_st/p \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/4-nested/keycode_events.snapshot b/zmk/app/tests/momentary-layer/4-nested/keycode_events.snapshot new file mode 100644 index 00000000..f03e4d5b --- /dev/null +++ b/zmk/app/tests/momentary-layer/4-nested/keycode_events.snapshot @@ -0,0 +1,6 @@ +mo_pressed: position 1 layer 1 +mo_pressed: position 0 layer 2 +kp_pressed: usage_page 0x07 keycode 0x05 mods 0x00 +kp_released: usage_page 0x07 keycode 0x05 mods 0x00 +mo_released: position 0 layer 2 +mo_released: position 1 layer 1 diff --git a/zmk/app/tests/momentary-layer/4-nested/native_posix.keymap b/zmk/app/tests/momentary-layer/4-nested/native_posix.keymap new file mode 100644 index 00000000..0eb77d20 --- /dev/null +++ b/zmk/app/tests/momentary-layer/4-nested/native_posix.keymap @@ -0,0 +1,39 @@ +#include +#include +#include + +/ { + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &none &mo 1 + &none &none>; + }; + + layer_1 { + bindings = < + &mo 2 &none + &none &none>; + }; + + layer_2 { + bindings = < + &none &none + &kp B &none>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,1,10) + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_PRESS(1,0,10) + ZMK_MOCK_RELEASE(1,0,10) + ZMK_MOCK_RELEASE(0,0,10) + ZMK_MOCK_RELEASE(0,1,10) + >; +}; \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/5-nested-early-key-release/events.patterns b/zmk/app/tests/momentary-layer/5-nested-early-key-release/events.patterns new file mode 100644 index 00000000..08b1e987 --- /dev/null +++ b/zmk/app/tests/momentary-layer/5-nested-early-key-release/events.patterns @@ -0,0 +1,3 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*keymap_position_state_changed/kp_st/p \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/5-nested-early-key-release/keycode_events.snapshot b/zmk/app/tests/momentary-layer/5-nested-early-key-release/keycode_events.snapshot new file mode 100644 index 00000000..15be601e --- /dev/null +++ b/zmk/app/tests/momentary-layer/5-nested-early-key-release/keycode_events.snapshot @@ -0,0 +1,6 @@ +mo_pressed: position 1 layer 1 +mo_pressed: position 0 layer 2 +kp_pressed: usage_page 0x07 keycode 0x05 mods 0x00 +mo_released: position 1 layer 1 +mo_released: position 0 layer 2 +kp_released: usage_page 0x07 keycode 0x05 mods 0x00 diff --git a/zmk/app/tests/momentary-layer/5-nested-early-key-release/native_posix.keymap b/zmk/app/tests/momentary-layer/5-nested-early-key-release/native_posix.keymap new file mode 100644 index 00000000..a67035bf --- /dev/null +++ b/zmk/app/tests/momentary-layer/5-nested-early-key-release/native_posix.keymap @@ -0,0 +1,39 @@ +#include +#include +#include + +/ { + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &none &mo 1 + &none &none>; + }; + + layer_1 { + bindings = < + &mo 2 &none + &none &none>; + }; + + layer_2 { + bindings = < + &none &none + &kp B &none>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,1,10) + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_PRESS(1,0,10) + ZMK_MOCK_RELEASE(0,1,10) + ZMK_MOCK_RELEASE(0,0,10) + ZMK_MOCK_RELEASE(1,0,10) + >; +}; \ No newline at end of file diff --git a/zmk/app/tests/momentary-layer/behavior_keymap.dtsi b/zmk/app/tests/momentary-layer/behavior_keymap.dtsi index 6cc3140f..a5b6c12b 100644 --- a/zmk/app/tests/momentary-layer/behavior_keymap.dtsi +++ b/zmk/app/tests/momentary-layer/behavior_keymap.dtsi @@ -10,19 +10,13 @@ default_layer { bindings = < &kp B &mo 1 - &kp D &kp G>; + &trans &trans>; }; - lower_layer { + layer_1 { bindings = < &kp C_NEXT &trans - &kp L &kp J>; - }; - - raise_layer { - bindings = < - &kp W &kp U - &kp X &kp M>; + &trans &trans>; }; }; }; diff --git a/zmk/app/west.yml b/zmk/app/west.yml index cba53ab0..7657fdef 100644 --- a/zmk/app/west.yml +++ b/zmk/app/west.yml @@ -37,4 +37,4 @@ manifest: remote: microsoft path: tools/uf2 self: - path: zmk + west-commands: scripts/west-commands.yml \ No newline at end of file diff --git a/zmk/docs/blog/2020-08-12-zmk-sotf-1.md b/zmk/docs/blog/2020-08-12-zmk-sotf-1.md index b5b2046d..afa03405 100644 --- a/zmk/docs/blog/2020-08-12-zmk-sotf-1.md +++ b/zmk/docs/blog/2020-08-12-zmk-sotf-1.md @@ -15,13 +15,13 @@ With interest and Discord activity growing, it seemed important to lay out the p There's been lots of various activity in ZMK land! -- [Nicell](https://github.com/Nicell) (nice!nano creator) contributed initial [RGB Underglow](/docs/feature/underglow) ([#64](https://github.com/zmkfirmware/zmk/pull/64)) support to ZMK. +- [Nicell](https://github.com/Nicell) (nice!nano creator) contributed initial [RGB Underglow](/docs/features/underglow) ([#64](https://github.com/zmkfirmware/zmk/pull/64)) support to ZMK. - 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/feature/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. - 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. -- Initial [encoder](/docs/feature/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. ## Bugs and Showstoppers diff --git a/zmk/docs/blog/2020-09-21-zmk-sotf-2.md b/zmk/docs/blog/2020-09-21-zmk-sotf-2.md index 06c64f02..1ce61c9a 100644 --- a/zmk/docs/blog/2020-09-21-zmk-sotf-2.md +++ b/zmk/docs/blog/2020-09-21-zmk-sotf-2.md @@ -16,16 +16,16 @@ Hacktoberfest activity, and a current open call for community feedback on a ZMK So much going on in ZMK! -- Added a new generic [Hold Tap behavior](https://zmkfirmware.dev/docs/behavior/hold-tap) +- Added a new generic [Hold Tap behavior](https://zmkfirmware.dev/docs/behaviors/hold-tap) in [#146](https://github.com/zmkfirmware/zmk/pull/146) which now powers mod-tap, layer-tap, etc. - [okke-formsma] -- [BLE profile/connection management](https://zmkfirmware.dev/docs/behavior/bluetooth) +- [BLE profile/connection management](https://zmkfirmware.dev/docs/behaviors/bluetooth) in [#133](https://github.com/zmkfirmware/zmk/pull/133) - [petejohanson] - Integration tests were added to automate testing of behaviors in [#131](https://github.com/zmkfirmware/zmk/pull/131) by [BrainWart] & [petejohanson] -- [Toggle layer behavior](https://zmkfirmware.dev/docs/behavior/layers#toggle-layer), e.g. `&tog LOWER`, in +- [Toggle layer behavior](https://zmkfirmware.dev/docs/behaviors/layers#toggle-layer), e.g. `&tog LOWER`, in [#98](https://github.com/zmkfirmware/zmk/pull/98) - [BrainWart] - Key fix for dropped press/release over HID [#93](https://github.com/zmkfirmware/zmk/pull/93)/[#96](https://github.com/zmkfirmware/zmk/pull/96) - [careyk007](https://github.com/careyk007) & [petejohanson] - Code formatting standardized using `clang-format` in [#183](https://github.com/zmkfirmware/zmk/pull/183) - [petejohanson] -- [Bootloader reset behavior](https://zmkfirmware.dev/docs/behavior/reset#bootloader-reset), e.g. `&bootloader`, in [#116](https://github.com/zmkfirmware/zmk/pull/116) - [petejohanson] +- [Bootloader reset behavior](https://zmkfirmware.dev/docs/behaviors/reset#bootloader-reset), e.g. `&bootloader`, in [#116](https://github.com/zmkfirmware/zmk/pull/116) - [petejohanson] - Various bug fixes and documentation ## New Shields diff --git a/zmk/docs/blog/2020-11-09-zmk-sotf-3.md b/zmk/docs/blog/2020-11-09-zmk-sotf-3.md index 8752065b..9e250a99 100644 --- a/zmk/docs/blog/2020-11-09-zmk-sotf-3.md +++ b/zmk/docs/blog/2020-11-09-zmk-sotf-3.md @@ -67,7 +67,7 @@ With this change, you can add &ext_power EP_TOG ``` -to toggle (on/off) the power to external hardware like RGB underglow or OLEDs. Check out the [external power control](/docs/behavior/power#external-power-control) docs for more info. +to toggle (on/off) the power to external hardware like RGB underglow or OLEDs. Check out the [external power control](/docs/behaviors/power#external-power-control) docs for more info. #### Deep Sleep @@ -78,7 +78,7 @@ included some automatic power savings by switching to PORT events on the nRF52 c #### Output Selection -[joelspadin] added [output selection](/docs/behavior/outputs) to allow selecting whether to send output over USB or BLE if both are connected. This should now help avoid having "double keypresses" when your keyboard is plugged into a host. +[joelspadin] added [output selection](/docs/behaviors/outputs) to allow selecting whether to send output over USB or BLE if both are connected. This should now help avoid having "double keypresses" when your keyboard is plugged into a host. #### Bootloader Corruption Fix diff --git a/zmk/docs/docs/behaviors/bluetooth.md b/zmk/docs/docs/behaviors/bluetooth.md new file mode 100644 index 00000000..be0fb23c --- /dev/null +++ b/zmk/docs/docs/behaviors/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 +``` + +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. | +| `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_PRV + ``` + +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/zmk/docs/docs/behaviors/hold-tap.md b/zmk/docs/docs/behaviors/hold-tap.md new file mode 100644 index 00000000..f3c3c664 --- /dev/null +++ b/zmk/docs/docs/behaviors/hold-tap.md @@ -0,0 +1,75 @@ +--- +title: Hold-Tap Behavior +sidebar_label: Hold-Tap +--- + +## Summary + +Hold-tap is the basis for other behaviors such as layer-tap and mod-tap. + +Simply put, the hold-tap key will output the 'hold' behavior if it's held for a while, and output the 'tap' behavior when it's tapped quickly. + +### Hold-Tap + +The `tapping_term_ms` parameter decides between a 'tap' and a 'hold'. + +![Simple behavior](../assets/hold-tap/case1_2.png) + +By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active: + +![Hold preferred behavior](../assets/hold-tap/case1_2.png) + +We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a ctrl/escape key, it's not very well suited for home-row mods or layer-taps. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'. + +#### Flavors + +- The 'hold-preferred' flavor triggers the hold behavior when the tapping_term_ms has expired or another key is pressed. +- The 'balanced' flavor will trigger the hold behavior when the tapping_term_ms has expired or another key is pressed and released. +- The 'tap-preferred' flavor triggers the hold behavior when the tapping_term_ms has expired. It triggers the tap behavior when another key is pressed. + +When the hold-tap key is released and the hold behavior has not been triggered, the tap behavior will trigger. + +![Hold-tap comparison](../assets/hold-tap/comparison.png) + +### Basic usage + +For basic usage, please see [mod-tap](./mod-tap.md) and [layer-tap](./layers.md) pages. + +### Advanced Configuration + +This example configures a hold-tap that works well for homerow mods: + +``` +#include +#include + +/ { + behaviors { + hm: homerow_mods { + compatible = "zmk,behavior-hold-tap"; + label = "HOMEROW_MODS"; + #binding-cells = <2>; + tapping_term_ms = <150>; + flavor = "tap-preferred"; + bindings = <&kp>, <&kp>; + }; + }; + + keymap { + compatible = "zmk,keymap"; + + default_layer { + bindings = < + &hm LCTRL A &hm LGUI S &hm LALT D &hm LSHFT F + >; + }; + }; +}; + +``` + +If this config does not work for you, try the flavor "balanced" with a medium tapping_term_ms such as 200ms. + +#### Comparison to QMK + +The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. diff --git a/zmk/docs/docs/behaviors/key-press.md b/zmk/docs/docs/behaviors/key-press.md new file mode 100644 index 00000000..859c7973 --- /dev/null +++ b/zmk/docs/docs/behaviors/key-press.md @@ -0,0 +1,54 @@ +--- +title: Key Press Behaviors +sidebar_label: Key Press +--- + +## Summary + +The most basic of behaviors, is the ability to send certain keycode presses and releases in response to activating +a certain key. + +The categories of supported codes are: + +- [Keyboard & Keypad](../codes/keyboard-keypad) +- [Editing](../codes/editing) +- [Media](../codes/media) +- [Applications](../codes/applications) +- [Input Assist](../codes/input-assist) +- [Power](../codes/power) + +Please visit the [codes](../codes) section for a comprehensive list. + +For advanced users, user-defined HID usages are also supported but must be encoded, please see [`dt-bindings/zmk/keys.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/keys.h) for further insight. + +## Keycode Defines + +To make it easier to encode the HID keycode numeric values, most keymaps include +the [`dt-bindings/zmk/keys.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/keys.h) header +provided by ZMK near the top: + +``` +#include +``` + +Doing so makes a set of defines such as `A`, `N1`, etc. available for use with these behaviors + +### Improperly defined keymap - `dtlib.DTError: .dts.pre.tmp:` + +When compiling firmware from a keymap, it may be common to encounter an error in the form of a`dtlib.DTError: .dts.pre.tmp:`. +For instructions to resolve such an error, click [here](../troubleshooting###Improperly-defined-keymap) + +## Key Press + +The "key press" behavior sends standard keycodes on press/release. + +### Behavior Binding + +- Reference: `&kp` +- Parameter: The keycode usage ID from the usage page, e.g. `4` or `A` + +Example: + +``` +&kp A +``` diff --git a/zmk/docs/docs/behaviors/layers.md b/zmk/docs/docs/behaviors/layers.md new file mode 100644 index 00000000..fcfdc93a --- /dev/null +++ b/zmk/docs/docs/behaviors/layers.md @@ -0,0 +1,110 @@ +--- +title: Layer Behaviors +sidebar_label: Layers +--- + +## Summary + +Often, you may want a certain key position to alter which layers are enabled, change the default layer, etc. +Some of those behaviors are still in the works; the ones that are working now are documented here. + +## Defines To Refer To Layers + +When working with layers, you may have several different key positions with bindings that enable/disable those layers. +To make it easier to refer to those layers in your key bindings, and to change which layers are where later, you can +add a set of `#define`s at the top of your keymap file, and use those layer in your keymap. + +For example, if you have three layers, you can add the following to the top of your keymap: + +``` +#define DEFAULT 0 +#define LOWER 1 +#define RAISE 2 +``` + +This allows you to use those defines, e.g. `LOWER` later in your keymap. + +## Momentary Layer + +The "momentary layer" behavior enables a layer while a certain key is pressed. Immediately upon +activation of the key, the layer is enabled, and immediately open release of the key, the layer is disabled +again. + +### Behavior Binding + +- Reference: `&mo` +- Parameter: The layer number to enable/disable, e.g. `1` + +Example: + +``` +&mo LOWER +``` + +## Layer-tap + +The "layer-tap" behavior enables a layer when a key is held, and output another key when the key is only tapped for a short time. For more information on the inner workings of layer-tap, see [hold-tap](./hold-tap.md). + +### Behavior Binding + +- Reference: `<` +- Parameter: The layer number to enable when held, e.g. `1` +- Parameter: The keycode to send when tapped, e.g. `A` + +Example: + +``` +< LOWER SPACE +``` + +## Toggle Layer + +The "toggle layer" behavior enables a layer until the layer is manually disabled. + +### Behavior Binding + +- Reference: `&tog` +- Parameter: The layer number to enable/disable, e.g. `1` + +Example: + +``` +&tog LOWER +``` + +"Toggle layer" for a : + +``` +#define DEFAULT 0 +#define NAVI 1 + +#define NONE 0 + +/ { + keymap { + compatible = "zmk,keymap"; + + default_layer { + bindings = < + &tog NAVI &kp KP_DIVIDE &kp KP_MULTIPLY &kp KP_MINUS + &kp NUMBER_7 &kp NUMBER_8 &kp NUMBER_9 &kp KP_PLUS + &kp NUMBER_4 &kp NUMBER_5 &kp NUMBER_6 &kp KP_PLUS + &kp NUMBER_1 &kp NUMBER_2 &kp NUMBER_3 &kp RETURN + &kp NUMBER_0 &kp NUMBER_0 &kp DOT &kp RETURN + >; + }; + + nav_layer { + bindings = < + &tog NAVI &kp KP_DIVIDE &kp KP_MULTIPLY &kp KP_MINUS + &kp HOME &kp UP &kp PAGE_UP &kp KP_PLUS + &kp LEFT &none &kp RIGHT &kp KP_PLUS + &kp END &kp DOWN &kp PAGE_DOWN &kp RETURN + &kp INSERT &kp INSERT &kp DEL &kp RETURN + >; + }; + }; +}; +``` + +It is possible to use "toggle layer" to have keys that raise and lower the layers as well. diff --git a/zmk/docs/docs/behaviors/lighting.md b/zmk/docs/docs/behaviors/lighting.md new file mode 100644 index 00000000..2d4f532e --- /dev/null +++ b/zmk/docs/docs/behaviors/lighting.md @@ -0,0 +1,51 @@ +--- +title: Lighting Behavior +sidebar_label: Lighting +--- + +## Summary + +Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. +Currently ZMK supports RGB underglow, which can be changed and configured using its behavior. + +## RGB Action Defines + +RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header, +which is added at the top of the keymap file: + +``` +#include +``` + +This will allow you to reference the actions defined in this header such as `RGB_TOG`. + +Here is a table describing the action for each define: + +| Define | Action | +| --------- | --------------------------------------------------------- | +| `RGB_TOG` | Toggles the RGB feature on and off | +| `RGB_HUI` | Increases the hue of the RGB feature | +| `RGB_HUD` | Decreases the hue of the RGB feature | +| `RGB_SAI` | Increases the saturation of the RGB feature | +| `RGB_SAD` | Decreases the saturation of the RGB feature | +| `RGB_BRI` | Increases the brightness of the RGB feature | +| `RGB_BRD` | Decreases the brightness of the RGB feature | +| `RGB_SPI` | Increases the speed of the RGB feature effect's animation | +| `RGB_SPD` | Decreases the speed of the RGB feature effect's animation | +| `RGB_EFF` | Cycles the RGB feature's effect forwards | +| `RGB_EFR` | Cycles the RGB feature's effect reverse | + +## RGB Underglow + +The "RGB underglow" behavior completes an RGB action given on press. + +### Behavior Binding + +- Reference: `&rgb_ug` +- Parameter: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI` + +Example: + +``` +&rgb_ug RGB_TOG +``` diff --git a/zmk/docs/docs/behaviors/misc.md b/zmk/docs/docs/behaviors/misc.md new file mode 100644 index 00000000..446ba33c --- /dev/null +++ b/zmk/docs/docs/behaviors/misc.md @@ -0,0 +1,42 @@ +--- +title: Miscellaneous Behaviors +sidebar_label: Miscellaneous +--- + +## Summary + +There are a few miscellaneous behaviors that are helpful when working with layers in keymaps, +in particular, with handling what happens in higher layers, and if events are passed to +the next layer or not + +## Transparent + +The transparent behavior simply ignores key position presses/releases, so they will be +passed down to the next active layer in the stack. + +### Behavior Binding + +- Reference: `&trans` +- Parameters: None + +Example: + +``` +&trans +``` + +## None + +The none behavior simply swallows and stops key position presses/releases, so they will **not** +be passed down to the next active layer in the stack. + +### Behavior Binding + +- Reference: `&none` +- Parameters: None + +Example: + +``` +&none +``` diff --git a/zmk/docs/docs/behaviors/mod-tap.md b/zmk/docs/docs/behaviors/mod-tap.md new file mode 100644 index 00000000..da8b438a --- /dev/null +++ b/zmk/docs/docs/behaviors/mod-tap.md @@ -0,0 +1,42 @@ +--- +title: Mod-Tap Behavior +sidebar_label: Mod-Tap +--- + +## Summary + +The Mod-Tap sends a different keypress, if it's tapped or held. When you tap the key shortly, the first keycode is sent. If you hold the key for longer than 200ms, the second keycode is sent. + +If you press another key within the 200ms, the 'mod' behavior is also activated. + +## Mod-Tap + +The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode. + +### Behavior Binding + +- Reference: `&mt` +- Parameter #1: The keycode to be sent when activating as a modifier, e.g. `LSHFT` +- Parameter #2: The keycode to sent when used as a tap, e.g. `A`, `B`. + +Example: + +``` +&mt LSHFT A +``` + +### Configuration + +You can configure a different tapping term in your keymap: + +``` +&mt { + tapping_term_ms = <400>; +}; + +/ { + keymap { + ... + } +} +``` diff --git a/zmk/docs/docs/behaviors/outputs.md b/zmk/docs/docs/behaviors/outputs.md new file mode 100644 index 00000000..ae812497 --- /dev/null +++ b/zmk/docs/docs/behaviors/outputs.md @@ -0,0 +1,59 @@ +--- +title: Output Selection Behavior +sidebar_label: Output Selection +--- + +## Summary + +The output behavior allows selecting whether keyboard output is sent to the +USB or bluetooth connection when both are connected. This allows connecting a +keyboard to USB for power but outputting to a different device over bluetooth. + +By default, output is sent to USB when both USB and BLE are connected. +Once you select a different output, it will be remembered until you change it again. + +## Output Command Defines + +Output command defines are provided through the [`dt-bindings/zmk/outputs.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/outputs.h) +header, which is added at the top of the keymap file: + +``` +#include +``` + +This allows you to reference the actions defined in this header: + +| Define | Action | +| --------- | ----------------------------------------------- | +| `OUT_USB` | Prefer sending to USB | +| `OUT_BLE` | Prefer sending to the current bluetooth profile | +| `OUT_TOG` | Toggle between USB and BLE | + +## Output Selection Behavior + +The output selection behavior changes the preferred output on press. + +### Behavior Binding + +- Reference: `&out` +- Parameter #1: Command, e.g. `OUT_BLE` + +### Examples + +1. Behavior binding to prefer sending keyboard output to USB + + ``` + &out OUT_USB + ``` + +1. Behavior binding to prefer sending keyboard output to the current bluetooth profile + + ``` + &out OUT_BLE + ``` + +1. Behavior binding to toggle between preferring USB and BLE + + ``` + &out OUT_TOG + ``` diff --git a/zmk/docs/docs/behaviors/power.md b/zmk/docs/docs/behaviors/power.md new file mode 100644 index 00000000..0de50552 --- /dev/null +++ b/zmk/docs/docs/behaviors/power.md @@ -0,0 +1,64 @@ +--- +title: Power Management Behaviors +sidebar_label: Power Management +--- + +## Summary + +These page contains some of the power management behaviors currently supported by ZMK. + +## External Power Control + +The External power control behavior allows enabling or disabling the VCC power output +to save power. Some of the LEDs will consume power even in OFF state. To preserve +battery life in this scenario, some controller boards have support to disable the +external power completely. + +The following boards currently support this feature: + +- nRFMicro +- nice!nano + +## External Power Control Command Defines + +External power control command defines are provided through the [`dt-bindings/zmk/ext_power.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/ext_power.h) header, +which is added at the top of the keymap file: + +``` +#include +``` + +This will allow you to reference the actions defined in this header such as `EXT_POWER_OFF_CMD`. + +Here is a table describing the command for each define: + +| Define | Action | Alias | +| ---------------------- | --------------------------- | -------- | +| `EXT_POWER_OFF_CMD` | Disable the external power. | `EP_OFF` | +| `EXT_POWER_ON_CMD` | Enable the external power. | `EP_ON` | +| `EXT_POWER_TOGGLE_CMD` | Toggle the external power. | `EP_TOG` | + +### Behavior Binding + +- Reference: `&ext_power` +- Parameter#1: Command, e.g `EP_ON` + +### Example: + +1. Behavior binding to enable the external power + + ``` + &ext_power EP_ON + ``` + +1. Behavior binding to disable the external power + + ``` + &ext_power EP_OFF + ``` + +1. Behavior binding to toggle the external power + + ``` + &ext_power EP_TOG + ``` diff --git a/zmk/docs/docs/behaviors/reset.md b/zmk/docs/docs/behaviors/reset.md new file mode 100644 index 00000000..8cf122b4 --- /dev/null +++ b/zmk/docs/docs/behaviors/reset.md @@ -0,0 +1,43 @@ +--- +title: Reset Behaviors +sidebar_label: Reset +--- + +## Summary + +There are two available behaviors that can be used to trigger a reset of the keyboard. +The first is a soft reset, that will simply reset and re-run the currently flashed +firmware; the second when triggered will reset into the bootloader, allowing you to +flash a new firmware to the keyboard. + +## Reset + +The basic reset behavior will reset the keyboard and re-run the firmware flashed +to the device + +### Behavior Binding + +- Reference: `&reset` +- Parameters: None + +Example: + +``` +&reset +``` + +## Bootloader Reset + +The bootloader reset behavior will reset the keyboard and put it into bootloader mode, allowing +you to flash a new firmware. + +### Behavior Binding + +- Reference: `&bootloader` +- Parameters: None + +Example: + +``` +&bootloader +``` diff --git a/zmk/docs/docs/customization.md b/zmk/docs/docs/customization.md index d3372da2..626a291b 100644 --- a/zmk/docs/docs/customization.md +++ b/zmk/docs/docs/customization.md @@ -26,7 +26,7 @@ various config settings that can be commented/uncommented to modify how your fir ## Keymap Once you have the basic user config completed, you can find the keymap file in `config/.keymap` and customize from there. -Refer to the [Keymap](/docs/feature/keymaps) documentation to learn more. +Refer to the [Keymap](/docs/features/keymaps) documentation to learn more. ## Publishing @@ -39,7 +39,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https: ## Building from a local `zmk` fork using `zmk-config` -[As outlined here](dev-build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally, +[As outlined here](development/build-flash), firmware comes in the form of .uf2 files, which can be built locally using the command `west build`. Normally, `west build` will default to using the in-tree .keymap and .conf files found in your local copy of the `zmk` repository. However, you can append the command, `-DZMK_CONFIG="C:/the/absolute/path/config"` to `west build` in order to use the contents of your `zmk-config` folder instead of the default keyboard settings. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** diff --git a/zmk/docs/docs/development/boards-shields-keymaps.md b/zmk/docs/docs/development/boards-shields-keymaps.md new file mode 100644 index 00000000..e78f5d38 --- /dev/null +++ b/zmk/docs/docs/development/boards-shields-keymaps.md @@ -0,0 +1,52 @@ +--- +title: Boards, Shields, and Keymaps +--- + +## Architecture Overview + +The foundational elements needed to get a specific keyboard working with ZMK can be broken down into: + +- A [KSCAN driver](https://docs.zephyrproject.org/2.3.0/reference/peripherals/kscan.html), which uses `compatible="zmk,kscan-gpio-matrix"` for GPIO matrix based keyboards, or uses `compatible="zmk,kscan-gpio-direct"` for small direct wires. +- An optional matrix transform, which defines how the KSCAN row/column events are translated into logical "key positions". This is required for non-rectangular keyboards/matrices, where the key positions don't naturally follow the row/columns from the GPIO matrix. +- A keymap, which binds each key position to a behavior, e.g. key press, mod-tap, momentary layer, in a set of layers. + +These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that +keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](/docs/faq#why-boards-and-shields--why-not-just-keyboard). + +## Self-Contained Keyboard + +For a self-contained keyboard that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition. You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm/planck) board directory. + +With this type of keyboard, the full ZMK definition for the keyboard exists +in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck/`. In that directory, you'll have the following: + +- A `Kconfig.board` file that defines the toplevel Kconfig item for the board, including which SoC Kconfig setting it depends on. +- A `Kconfig.defconfig` file that sets some initial defaults when building this keyboard. This usually includes: + - Setting `ZMK_KEYBOARD_NAME` to a value, for the product name to be used for USB/BLE info. + - Setting `ZMK_USB` and/or `ZMK_BLE` for the default values for which HID transport(s) to enable by default +- A `${board_name}_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration. Mostly this is SoC settings around the specific hardware configuration. +- `${board_name}.dts` which contains all the devicetree definitions, including: + - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include `. + - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix) + - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix_transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. +- A `board.cmake` file with CMake directives for how to flash to the device. +- A `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. + +## Pro Micro Compatible Keyboard + +![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg) + +For keyboards that require a (usually Pro Micro compatible) add-on board to operate, the ZMK integration pieces are places +in the _shield_ definition for that keyboard, allowing users to +swap in different Pro Micro compatible boards (e.g. Proton-C, or nice!nano) and build a firmware the matches their actual +combination of physical components. + +With this type of keyboard, the partial definition for the keyboard exists +in the `app/boards/shields/${board_name}` directory, e.g. `app/boards/shields/clueboard_california/`. In that directory, you'll have the following: + +- A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`. +- A `Kconfig.defconfig` file to set default values for things like `ZMK_KEYBOARD_NAME` +- A `${shield_name}.overlay` file, which is a devicetree overlay file, that includes: + - A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,kscan` which references the configured KSCAN driver (usually a GPIO matrix). For these keyboards, to be compatible with any Pro Micro compatible boards, the KSCAN configuration should reference the [nexus node](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#gpio-nexus-nodes) that ZMK has standardized on. In particular, the `&pro_micro_a` and `&pro_micro_d` aliases can be used to reference the standard `A#` and `D#` pins in shields. + - (Optional) A [chosen](https://docs.zephyrproject.org/2.3.0/guides/dts/intro.html#aliases-and-chosen-nodes) node named `zmk,matrix_transform` that defines the mapping from KSCAN row/column values to the logical key position for the keyboard. +- A `keymap/keymap.overlay` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. diff --git a/zmk/docs/docs/development/build-flash.md b/zmk/docs/docs/development/build-flash.md new file mode 100644 index 00000000..e270a7c6 --- /dev/null +++ b/zmk/docs/docs/development/build-flash.md @@ -0,0 +1,128 @@ +--- +title: Building and Flashing +sidebar_label: Building and Flashing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Building + +From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: + +```sh +cd app +``` + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +an onboard MCU, or one that uses an MCU board addon. + +### Keyboard (Shield) + MCU Board + +ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) + +Given the following: + +- MCU Board: Proton-C +- Keyboard PCB: kyria_left +- Keymap: default + +You can build ZMK with the following: + +```sh +west build -b proton_c -- -DSHIELD=kyria_left +``` + +### Keyboard With Onboard MCU + +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/2.3.0/guides/porting/board_porting.html) as far as Zephyr™ is concerned. + +Given the following: + +- Keyboard: Planck (rev6) +- Keymap: default + +you can build ZMK with the following: + +```sh +west build -b planck_rev6 +``` + +### Pristine Building + +When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command: + +```sh +west build -p -b proton_c -- -DSHIELD=kyria_left +``` + +### Building For Split Keyboards + +:::note +For split keyboards, you will have to build and flash each side separately the first time you install ZMK. +::: + +By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`: + +``` +west build -d build/left -b nice_nano -- -DSHIELD=kyria_left +``` + +and then building right into `build/right`: + +``` +west build -d build/right -b nice_nano -- -DSHIELD=kyria_right +``` + +This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location. + +### Building from `zmk-config` Folder + +Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../user-setup#github-repo) by adding +`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.** + +For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this: + +``` +west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config" +``` + +In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config` +by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this +volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps: + +1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`. +1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only. +1. Remove the default volume via the command `docker volume rm zmk-config`. + +Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](./customization.md) folder: + +``` +docker volume create --driver local -o o=bind -o type=none -o \ + device="/full/path/to/your/zmk-config/" zmk-config +``` + +Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`. + +## Flashing + +Once built, the previously supplied parameters will be remembered so you can run the following to flash your +board with it in bootloader mode: + +``` +west flash +``` + +For boards that have drag and drop .uf2 flashing capability, the .uf2 file to flash can be found in `build/zephyr` (or `build/left|right/zephyr` if you followed the instructions for splits) and is by default named `zmk.uf2`. diff --git a/zmk/docs/docs/development/clean-room.md b/zmk/docs/docs/development/clean-room.md new file mode 100644 index 00000000..82db3a04 --- /dev/null +++ b/zmk/docs/docs/development/clean-room.md @@ -0,0 +1,28 @@ +--- +title: Clean Room Implementation +sidebar_label: Clean Room +--- + +:::warning + +Anyone wanting to contribute code to ZMK _MUST_ read this, and adhere to the steps outlines in order to not violate any licenses/copyright of other projects + +::: + +ZMK Firmware is a [clean room design](https://en.wikipedia.org/wiki/Clean_room_design) keyboard firmware, that +borrows/implements a lot of the features found in popular keyboard firmwares projects like [QMK](https://qmk.fm) +and [TMK](https://github.com/tmk/tmk_keyboard). However, in order for ZMK to use the MIT, it _must_ not +incorporate any of the GPL licensed code from those projects. + +In order to achieve this, all code for ZMK has been implemented completely fresh, _without_ referencing, copying, +or duplicating any of the GPL code found in those other projects, even though they are open source software. + +## Contributor Requirements + +Contributors to ZMK must adhere to the following standard. + +- Implementations of features for ZMK _MUST NOT_ reuse any existing code from any projects not licensed with the MIT license. +- Contributors _MUST NOT_ study or refer to any GPL licensed source code while working on ZMK. +- Contributors _MAY_ read the documentation from other GPL licensed projects, to gain a broad understanding of the behavior of certain features in order to implement equivalent features for ZMK. +- Contributors _MAY_ refer to the [QMK Configurator](https://config.qmk.fm/) to inspect existing layouts/keymaps for + keyboards, and re-implement them for ZMK. diff --git a/zmk/docs/docs/development/new-shield.md b/zmk/docs/docs/development/new-shield.md new file mode 100644 index 00000000..306f1b3f --- /dev/null +++ b/zmk/docs/docs/development/new-shield.md @@ -0,0 +1,512 @@ +--- +title: New Keyboard Shield +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import KeymapExampleFile from '../keymap-example-file.md'; + +## Overview + +This guide will walk through the steps necessary to add ZMK support for a keyboard the uses a (Pro Micro compatible) addon MCU board to provide the microprocessor. +The high level steps are: + +- Create a new shield directory. +- Add the base Kconfig files. +- Add the shield overlay file to define the KSCAN driver for detecting key press/release. +- (Optional) Add the matrix transform for mapping KSCAN row/column values to sane key positions. This is needed for non-rectangular keyboards, or where the underlying row/column pin arrangement does not map one to one with logical locations on the keyboard. +- Add a default keymap, which users can override in their own configs as needed. +- Add support for features such as encoders, OLED displays, or RGB underglow. +- Update build.yml + +It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/2.3.0/guides/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. + +:::note +ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. +::: + +## New Shield Directory + +:::note +This guide describes how to add shield to the ZMK main repository. If you are building firmware for your +own prototype or handwired keyboard, it is recommended to use your own user config repository. Follow the +[user setup guide](./user-setup.md) to create your user config repository first. When following the rest +of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your +user config repository. For example, `app/boards/shields/` should now be +`config/boards/shields/`. +::: + +Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be: + +```bash +mkdir app/boards/shields/ +``` + +## Base Kconfig Files + +There are two required Kconfig files that need to be created for your new keyboard +shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. + +### Kconfig.shield + +The `Kconfig.shield` file defines any additional Kconfig settings that may be relevant when using this keyboard. For most keyboards, there is just one additional configuration value for the shield itself, e.g.: + +``` +config SHIELD_MY_BOARD + def_bool $(shields_list_contains,my_board) +``` + +This will make sure the new configuration `SHIELD_MY_BOARD` is set to true whenever `my_board` is added as a shield in your build. + +**For split boards**, you will need to add configurations for the left and right sides. + +``` +config SHIELD_MY_BOARD_LEFT + def_bool $(shields_list_contains,my_board_left) + +config SHIELD_MY_BOARD_RIGHT + def_bool $(shields_list_contains,my_board_right) +``` + +### Kconfig.defconfig + +The `Kconfig.defconfig` file is where overrides for various configuration settings +that make sense to have different defaults when this shield is used. One main item +that usually has a new default value set here is the `ZMK_KEYBOARD_NAME` value, +which controls the display name of the device over USB and BLE. + +The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file. + +:::warning +Do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet. +::: + +``` +if SHIELD_MY_BOARD + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard" + +endif +``` + +Similarly to defining the halves of a split board in `Kconfig.shield` it is important to set the `ZMK_KEYBOARD_NAME` for each half of a split keyboard. + +``` +if SHIELD_MY_BOARD_LEFT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Left" + +endif + +if SHIELD_MY_BOARD_RIGHT + +config ZMK_KEYBOARD_NAME + default "My Awesome Keyboard Right" + +endif +``` + +## Shield Overlays + +![Labelled Pro Micro pins](../assets/pro-micro/pro-micro-pins-labelled.jpg) + +ZMK uses the green color coded pin names to generate devicetree node references. For example, to refer to the node `D0` in the devicetree files, use `&pro_micro_d 0` or to refer to `A1`, use `&pro_micro_a 1`. + + + + + +The `.overlay` is the devicetree description of the keyboard shield that is merged with the primary board devicetree description before the build. For ZMK, this file at a minimum should include the chosen node named `zmk,kscan` that references a KSCAN driver instance. For a simple 3x3 macropad matrix, +this might look something like: + +``` +/ { + chosen { + zmk,kscan = &kscan0; + }; + + kscan0: kscan_0 { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + diode-direction = "col2row"; + + col-gpios + = <&pro_micro_d 15 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> + ; + + row-gpios + = <&pro_micro_a 1 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_a 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&pro_micro_a 3 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + }; +}; +``` + + + + + +### .dtsi files and Shield Overlays (Split Shields) + +Unlike unibody keyboards, split keyboards have a core .dtsi file with shield overlays for each half of the keyboard. +It is preferred to define only the `col-gpios` or `row-gpios` in the common shield .dtsi, depending on the `diode-direction` value. +For `col2row` directed boards like the iris, the shared .dtsi file may look like this: + +``` +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <16>; + rows = <4>; +// | SW6 | SW5 | SW4 | SW3 | SW2 | SW1 | | SW1 | SW2 | SW3 | SW4 | SW5 | SW6 | +// | SW12 | SW11 | SW10 | SW9 | SW8 | SW7 | | SW7 | SW8 | SW9 | SW10 | SW11 | SW12 | +// | SW18 | SW17 | SW16 | SW15 | SW14 | SW13 | | SW13 | SW14 | SW15 | SW16 | SW17 | SW18 | +// | SW24 | SW23 | SW22 | SW21 | SW20 | SW19 | SW25 | | SW25 | SW19 | SW20 | SW21 | SW22 | SW23 | SW24 | +// | SW29 | SW28 | SW27 | SW26 | | SW26 | SW27 | SW28 | SW29 | + map = < +RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,5) RC(0,6) RC(0,7) RC(0,8) RC(0,9) RC(0,10) RC(0,11) +RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,6) RC(1,7) RC(1,8) RC(1,9) RC(1,10) RC(1,11) +RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4) RC(2,5) RC(2,6) RC(2,7) RC(2,8) RC(2,9) RC(2,10) RC(2,11) +RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4) RC(3,5) RC(4,2) RC(4,9) RC(3,6) RC(3,7) RC(3,8) RC(3,9) RC(3,10) RC(3,11) + RC(4,3) RC(4,4) RC(4,5) RC(4,6) RC(4,7) RC(4,8) + >; + }; + + kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&pro_micro_d 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row A from the schematic file + , <&pro_micro_d 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row B from the schematic file + , <&pro_micro_d 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row C from the schematic file + , <&pro_micro_d 0 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row D from the schematic file + , <&pro_micro_d 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> // Row E from the schematic file + ; + + }; +``` + +:::note +Notice that in addition to the common `row-gpios` that are declared in the kscan, the [matrix transform](#optional-matrix-transform) is defined in the .dtsi. +::: + +The missing `col-gpios` would be defined in your `_left.overlay` and `_right.overlay` files. +Keep in mind that the mirrored position of the GPIOs means that the `col-gpios` will appear reversed when the .overlay files are compared to one another. +Furthermore, the column offset for the [matrix transform](#optional-matrix-transform) should be added to the right half of the keyboard's overlay +because the keyboard's switch matrix is read from left to right, top to bottom. +This is exemplified with the iris .overlay files. + +``` +// iris_left.overlay + +#include "iris.dtsi" // Notice that the main dtsi files are included in the overlay. + +&kscan0 { + col-gpios + = <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic + , <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic + ; +}; +``` + +``` +// iris_right.overlay + +#include "iris.dtsi" + +&default_transform { // The matrix transform for this board is 6 columns over because the left half is 6 columns wide according to the matrix. + col-offset = <6>; +}; + +&kscan0 { + col-gpios + = <&pro_micro_d 10 GPIO_ACTIVE_HIGH> // col6 in the schematic + , <&pro_micro_d 16 GPIO_ACTIVE_HIGH> // col5 in the schematic + , <&pro_micro_d 14 GPIO_ACTIVE_HIGH> // col4 in the schematic + , <&pro_micro_d 15 GPIO_ACTIVE_HIGH> // col3 in the schematic + , <&pro_micro_a 0 GPIO_ACTIVE_HIGH> // col2 in the schematic + , <&pro_micro_a 1 GPIO_ACTIVE_HIGH> // col1 in the schematic + ; +}; + +``` + +### .conf files (Split Shields) + +While unibody boards only have one .conf file that applies configuration characteristics to the entire keyboard, +split keyboards are unique in that they contain multiple .conf files with different scopes. +For example, a split board called `my_awesome_split_board` would have the following files: + +- `my_awesome_split_board.conf` - Configuration elements affect both halves +- `my_awesome_split_board_left.conf` - Configuration elements only affect left half +- `my_awesome_split_board_right.conf` - Configuration elements only affect right half + +For proper communication between keyboard halves and that between the central half and the computer, +the **the central and peripheral halves of the keyboard must be defined**. This can be seen below. + +``` +// Central Half (Usually the left side: my_awesome_split_board_left.conf) + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL=y +``` + +``` +// Peripheral Half (Usually the right side: my_awesome_split_board_right.conf) + +CONFIG_ZMK_SPLIT=y +CONFIG_ZMK_SPLIT_BLE_ROLE_Peripheral=y +``` + +Using the .conf file that affects both halves of a split board would be for adding features like deep-sleep or rotary encoders. + +``` +// my_awesome_split_board.conf + +CONFIG_ZMK_SLEEP=y +``` + + + + +## (Optional) Matrix Transform + +Internally ZMK translates all row/column events into "key position" events to maintain a consistent model that works no matter what any possible GPIO matrix may look like for a certain keyboard. This is particularly helpful when: + +1. To reduce the used pins, an "efficient" number of rows/columns for the GPIO matrix is used, that does _not_ match the physical layout of rows/columns of the actual key switches. +1. For non rectangular keyboards with thumb clusters, non `1u` locations, etc. + +A "key position" is the numeric index (zero-based) of a given key, which identifies +the logical key location as perceived by the end user. All _keymap_ mappings actually bind behaviors to _key positions_, not to row/column values. + +_Without_ a matrix transform, that intentionally map each key position to the row/column pair that position corresponds to, the default equation to determine that is: + +``` +($row * NUMBER_OF_COLUMNS) + $column +``` + +Which effectively amounts to numbering the key positions by traversing each row from top to bottom and assigning numerically incrementing key positions. + +Whenever that default key position mapping is insufficient, the `.overlay` file should _also_ include a matrix transform. + +Here is an example for the [nice60](https://github.com/Nicell/nice60), which uses an efficient 8x8 GPIO matrix, and uses a transform: + +``` +#include + +/ { + chosen { + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <8>; + rows = <8>; +// | MX1 | MX2 | MX3 | MX4 | MX5 | MX6 | MX7 | MX8 | MX9 | MX10 | MX11 | MX12 | MX13 | MX14 | +// | MX15 | MX16 | MX17 | MX18 | MX19 | MX20 | MX21 | MX22 | MX23 | MX34 | MX25 | MX26 | MX27 | MX28 | +// | MX29 | MX30 | MX31 | MX32 | MX33 | MX34 | MX35 | MX36 | MX37 | MX38 | MX39 | MX40 | MX41 | +// | MX42 | MX43 | MX44 | MX45 | MX46 | MX47 | MX48 | MX49 | MX50 | MX51 | MX52 | MX53 | +// | MX54 | MX55 | MX56 | MX57 | MX58 | MX59 | MX60 | MX61 | + map = < +RC(3,0) RC(2,0) RC(1,0) RC(0,0) RC(1,1) RC(0,1) RC(0,2) RC(1,3) RC(0,3) RC(1,4) RC(0,4) RC(0,5) RC(1,6) RC(1,7) +RC(4,0) RC(4,1) RC(3,1) RC(2,1) RC(2,2) RC(1,2) RC(2,3) RC(3,4) RC(2,4) RC(2,5) RC(1,5) RC(2,6) RC(2,7) RC(3,7) +RC(5,0) RC(5,1) RC(5,2) RC(4,2) RC(3,2) RC(4,3) RC(3,3) RC(4,4) RC(4,5) RC(3,5) RC(4,6) RC(3,6) RC(4,7) +RC(6,0) RC(6,1) RC(6,2) RC(6,3) RC(5,3) RC(6,4) RC(5,4) RC(6,5) RC(5,5) RC(6,6) RC(5,6) RC(5,7) +RC(7,0) RC(7,1) RC(7,2) RC(7,3) RC(7,5) RC(7,6) RC(6,7) RC(7,7) + >; + }; +``` + +Some important things to note: + +- The `#include ` is critical. The `RC` macro is used to generate the internal storage in the matrix transform, and is actually replaced by a C preprocessor before the final devicetree is compiled into ZMK. +- `RC(row, column)` is placed sequentially to define what row and column values that position corresponds to. +- If you have a keyboard with options for `2u` keys in certain positions, or break away portions, it is a good idea to set the chosen `zmk,matrix_transform` to the default arrangement, and include _other_ possible matrix transform nodes in the devicetree that users can select in their user config by overriding the chosen node. + +## Default Keymap + +Each keyboard should provide an OOTB default keymap to be used when building the firmware, which can be overridden and customized by user configs. For "shield keyboards", this should be placed in the `app/boards/shields//.keymap` file. The keymap is configured as an additional devicetree overlay that includes the following: + +- A node with `compatible="zmk,keymap"` where each child node is a layer with a `bindings` array that binds each key position to a given behavior (e.g. key press, momentarily layer, etc). + +Here is an example simple keymap for the Kyria, with only one layer: + + + +:::note +The two `#include` lines at the top of the keymap are required in order to bring in the default set of behaviors to make them available to bind, and to import a set of defines for the key codes, so keymaps can use parameters like `N2` or `K` instead of the raw keycode numeric values. +::: + +### Keymap Behaviors + +Further documentation on behaviors and bindings is forthcoming, but a summary of the current behaviors you can bind to key positions is as follows: + +- `kp` is the "key press" behavior, and takes a single binding argument of the key code from the 'keyboard/keypad" HID usage table. +- `mo` is the "momentary layer" behaviour, and takes a single binding argument of the numeric ID of the layer to momentarily enable when that key is held. +- `trans` is the "transparent" behavior, useful to be place in higher layers above `mo` bindings to be sure the key release is handled by the lower layer. No binding arguments are required. +- `mt` is the "mod-tap" behavior, and takes two binding arguments, the modifier to use if held, and the keycode to send if tapped. + +## Adding Features + +### Encoders + +EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's configuration (.conf), device tree (.dtsi), overlay (.overlay), and keymap (.keymap) files. + + + + +In your configuration file you will need to add the following lines so that the encoders can be enabled/disabled: + +``` +# Uncomment to enable encoder +# CONFIG_EC11=y +# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y +``` + +These should be commented by default for encoders that are optional/can be swapped with switches, but can be uncommented if encoders are part of the default design. + +:::note +If building locally for split boards, you may need to add these lines to the specific half's configuration file as well as the combined configuration file. +::: + + + +In your device tree file you will need to add the following lines to define the encoder sensor: + +``` +left_encoder: encoder_left { + compatible = "alps,ec11"; + label = "LEFT_ENCODER"; + a-gpios = ; + b-gpios = ; + resolution = <4>; + }; +``` + +Here you will have to replace PIN_A and PIN_B with the appropriate pins that your PCB utilizes for the encoder(s). For keyboards that use the Pro Micro or any of the Pro Micro replacements, Sparkfun's [Pro Micro Hookup Guide](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro) has a pinout diagram that can be useful to determine the right pins. Reference either the blue numbers labeled "Arduino" (digital pins) or the green numbers labeled "Analog" (analog pins). For pins that are labeled as both digital and analog, refer to your specific board's .dtsi file to determine how you should refer to that pin. + +Add additional encoders as necessary by duplicating the above lines, replacing `left` with whatever you would like to call your encoder, and updating the pins. Note that support for peripheral (right) side sensors over BLE is still in progress. + +Once you have defined the encoder sensors, you will have to add them to the list of sensors: + +``` +sensors { + compatible = "zmk,keymap-sensors"; + sensors = <&left_encoder &right_encoder>; + }; +``` + +In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap. + + + +Add the following lines to your overlay file(s) to enable the encoder: + +``` +&left_encoder { + status = "okay"; +}; +``` + +:::note +For split keyboards, make sure to add left hand encoders to the left .overlay file and right hand encoders to the right .overlay file. +::: + + + +Add the following line to your keymap file to add default encoder behavior bindings: + +``` +sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>; +``` + +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/features/encoders) and [Keymap](/docs/features/keymaps) feature documentation for more details. + + + + +## Testing + +Once you've fully created the new keyboard shield definition, +you should be able to test with a build command like: + +``` +west build --pristine -b proton_c -- -DSHIELD=my_board +``` + +and then flash with: + +``` +west flash +``` + +:::note +Further testing your keyboard shield without altering the root keymap file can be done with the use of `-DZMK_CONFIG` in your `west build` command, +shown [here](build-flash#building-from-zmk-config-folder) +::: + +## Updating `build.yml` + +Before publishing your shield to the public via a PR, navigate to `build.yml` found in `.github/workflows` and add your shield to the appropriate list. An example edit to `build.yml` is shown below. + +``` +jobs: + build: + runs-on: ubuntu-latest + name: Build Test + strategy: + matrix: + board: [proton_c, nice_nano, bluemicro840_v1, nrfmicro_13] + shield: + - corne_left + - corne_right + - kyria_left + - kyria_right + - lily58_left + - lily58_right + - iris_left + - iris_right + - romac + - + - + - + include: + - board: proton_c + shield: clueboard_california +``` + +:::note +Notice that both the left and right halves of a split board need to be added to the list of shields for proper error checking. +:::note diff --git a/zmk/docs/docs/development/posix-board.md b/zmk/docs/docs/development/posix-board.md new file mode 100644 index 00000000..71460a87 --- /dev/null +++ b/zmk/docs/docs/development/posix-board.md @@ -0,0 +1,38 @@ +--- +title: Native Posix board target +--- + +In order to iterate quickly on firmware features, it can +be helpful to build and run the firmware on your local +workstation, with generated virtual press/release events +flowing into the handler functions. + +## Prerequisites + +In order to build targeting the `native_posix` board, you need to setup your system +with a compiler that can target 32-bit POSIX. + +On Debian, you can do this with: + +``` +apt install -y gcc-multilib +``` + +## Building + +To do this, you can build ZMK targeting the +`native_posix` board. + +``` +west build --pristine --board native_posix +``` + +Once built, you can run the firmware locally: + +``` +./build/zephyr/zephyr.exe +``` + +## Virtual Key Events + +The virtual key presses are hardcoded in `boards/native_posix.overlay` file, should you want to change the sequence to test various actions like Mod-Tap, etc. diff --git a/zmk/docs/docs/development/setup.md b/zmk/docs/docs/development/setup.md new file mode 100644 index 00000000..441299a9 --- /dev/null +++ b/zmk/docs/docs/development/setup.md @@ -0,0 +1,554 @@ +--- +title: Basic Setup +sidebar_label: Basic Setup +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const OsTabs = (props) => ({props.children}); + +## Prerequisites + +ZMK requires the following base packages to first be installed: + +- Git +- Python 3 +- `pip` +- `wget` +- devicetree compiler +- CMake +- `dfu-util` +- Various build essentials, e.g. gcc, automake, autoconf + + + + +On Debian and Ubuntu, we'll use `apt` to install our base dependencies: + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo apt update +``` + +With the latest package information, you can now install the base dependencies: + +```sh +sudo apt install -y \ + git \ + wget \ + autoconf \ + automake \ + build-essential \ + bzip2 \ + ccache \ + device-tree-compiler \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-dev \ + python3-pip \ + python3-setuptools \ + xz-utils +``` + +:::note +Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS +or download and install CMake version 3.13.1 or newer manually. +::: + + + +On Raspberry OS, we'll use `apt` to install our base dependencies: + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo apt update +``` + +With the latest package information, you can now install the base dependencies: + +```sh +sudo apt install -y \ + git \ + wget \ + autoconf \ + automake \ + build-essential \ + bzip2 \ + ccache \ + device-tree-compiler \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-dev \ + python3-pip \ + python3-setuptools \ + xz-utils +``` + + + + +On Fedora, we'll use `dnf` to install our base dependencies: + +#### DNF Update + +First, if you haven't updated recently, or if this is a new install, +you should update to get the latest package information: + +```sh +sudo dnf update +``` + +#### Install Dependencies + +With the latest package information, you can now install the base dependencies: + +```sh +sudo dnf install -y \ + git \ + wget \ + autoconf \ + automake \ + bzip2 \ + ccache \ + dtc \ + dfu-util \ + g++ \ + gcc \ + libtool \ + make \ + ninja-build \ + cmake \ + python3-devel \ + python3-pip \ + python3-setuptools \ + xz +``` + + + + +:::note +Use `cmd.exe` with these instructions rather than PowerShell. +::: + +Chocolatey is recommended and used for the following instructions. You can manually install each of these applications and add them to your `PATH` if you don't want to use Chocolatey. + +1. [Install Chocolatey](https://chocolatey.org/install) +2. Open `cmd.exe` as **Administrator** +3. Run the following `choco` commands: + ```shell + choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' + choco install ninja gperf python git + ``` + +It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey: + +```shell +choco install dfu-util +``` + + + + +#### Homebrew + +Homebrew is required to install the system dependencies. If you haven't done so, visit [Homebrew](https://brew.sh/) for instructions. Once installed, use it to install the base dependencies: + +``` +brew install cmake ninja python3 ccache dtc git wget dfu-util +``` + + + + +This setup leverages the same [image which is used by the GitHub action](https://github.com/zmkfirmware/zephyr-west-action) 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 [VS 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 includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code). +::: + + + + +## Setup + +### West Installation + +`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.0/guides/west/index.html) used to configure and build Zephyr™ applications. + +West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/latest/guides/west/install.html#installing-west) are summarized here: + + + + +```sh +pip3 install --user -U west +``` + + + + +In `cmd.exe` as **Administrator**: + +```sh +pip3 install -U west +``` + +:::note +**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply. +::: + +Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions. + + + + +:::danger `pip` user packages +If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command. +::: + + + +Run the following commands: + +```sh +echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + + + + +1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page. +2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number. +3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`. + + + + +### Toolchain Installation + +The toolchain provides the compiler, linker, etc., necessary to build for the target +platform. + + + + +#### Zephyr™ ARM SDK + +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: + +``` +export ZSDK_VERSION=0.11.2 +wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ + rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" +``` + +The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. + + + + +Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs, +the operating system's installed [cross compilers](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI. + +First, the cross compiler should be installed: + +```sh +sudo apt install gcc-arm-none-eabi +``` + +Next, we'll configure Zephyr™ with some extra environment variables needed to find the cross compiler by adding the following to `~/.zephyrrc`: + +```sh +export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile +export CROSS_COMPILE=/usr/bin/arm-none-eabi- +``` + + + + +#### Zephyr™ ARM SDK + +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: + +``` +export ZSDK_VERSION=0.11.2 +wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ + rm "zephyr-toolchain-arm-\${ZSDK_VERSION}-setup.run" +``` + +The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected. + + + + +#### GNU ARM Embedded + +Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below. + + + + +#### GNU ARM Embedded + +Since the Zephyr™ SDK is not available for macOS, we recommending following the steps to install the [GNU ARM Embedded](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded). + +:::warning Security Controls Workaround + +Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.3.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer + +::: + + + + +:::note +If you intend to build firmware straight away, make sure to correctly setup the current shell. + +Notes on setting this up can be found in the [Environment Variables](#environment-variables) section. +The transient instructions can be used to setup the current shell, and the automatic instructions can setup any newly made shells automatically. + +The transient instructions must be run to build firmware using the current shell. +::: + +### 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 + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + +```sh +cd zmk +``` + + + + + +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! + +:::caution +All subsequent steps must be performed from the VS Code terminal _inside_ the container. +::: + + + + +#### Initialize West + +```sh +west init -l app/ +``` + +:::caution Command Not Found? +If you encounter errors like `command not found: west` then your `PATH` environment variable is likely +missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) +section again for links to how to do this +::: + +#### 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.md). +::: + +#### Export Zephyr™ Core + +```sh +west zephyr-export +``` + +#### Install Zephyr Python Dependencies + +```sh +pip3 install --user -r zephyr/scripts/requirements-base.txt +``` + +### Environment Variables + + + + +#### For GNU ARM Embedded on Windows + +On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`. + +1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it. + +![Environment variables in Start Menu](../assets/env-var/start_menu.png) + +2. Click 'Environment Variables...'. + +![Environment variables button](../assets/env-var/env_var.png) + +3. Click "New..." under System variables to create a new system variable. + +![Environment variables menu](../assets/env-var/new_variable.png) + +4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save. + +![Adding Zephyr toolchain variable](../assets/env-var/zephyr_toolchain.png) + +5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save. + +![Adding GNUARMEMB variable](../assets/env-var/gnuarmemb.png) + +6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes. + + + + + +#### For Zephyr + +By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. +We suggest two main [options](https://docs.zephyrproject.org/2.3.0/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. + +##### Per Shell + +To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: + +``` +source zephyr/zephyr-env.sh +``` + +##### All Shells + +To load the environment variables for your shell every time, +append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. + + + + + +``` +cat ~/.zephyrrc >> ~/.bashrc +``` + + + + + +``` +cat ~/.zephyrrc >> ~/.zshrc +``` + + + + + + + + diff --git a/zmk/docs/docs/development/tests.md b/zmk/docs/docs/development/tests.md new file mode 100644 index 00000000..9ad689b6 --- /dev/null +++ b/zmk/docs/docs/development/tests.md @@ -0,0 +1,22 @@ +--- +title: Tests +sidebar_label: Tests +--- + +Running tests requires [native posix support](posix-board). Any folder under `/app/tests` +containing `native_posix.keymap` will be selected when running `west test`. + +Run a single test with `west test `, like `west test tests/toggle-layer/normal`. + +## Creating a New Test Set + +1. Copy the test set that most closely resembles the tests you will be creating. +2. Rename the newly created test set to the behavior you're testing e.g, toggle-layer +3. Modify `behavior_keymap.dtsi` to create a keymap using the behavior and related behaviors +4. Modify `test_case/native_posix.keymap` for a simulated use case +5. Modify `test_case/events.patterns` to collect relevant logs to the test + - See: [sed manual](https://www.gnu.org/software/sed/manual/sed.html) and + [tutorial](https://www.digitalocean.com/community/tutorials/the-basics-of-using-the-sed-stream-editor-to-manipulate-text-in-linux) +6. Modify `test_case/keycode_events.snapshot` for to include the expected output +7. Rename the `test_case` folder to describe the test. +8. Repeat steps 4 to 7 for every test case diff --git a/zmk/docs/docs/development/usb-logging.md b/zmk/docs/docs/development/usb-logging.md new file mode 100644 index 00000000..6e4e2bef --- /dev/null +++ b/zmk/docs/docs/development/usb-logging.md @@ -0,0 +1,103 @@ +--- +title: USB Logging +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Overview + +If you are developing ZMK on a device that does not have a built in UART for debugging and log/console output, +Zephyr can be configured to create a USB CDC ACM device and the direct all `printk`, console output, and log +messages to that device instead. + +:::warning Battery Life Impact + +Enabling logging increases the power usage of your keyboard, and can have a non-trivial impact to your time on battery. +It is recommended to only enable logging when needed, and not leaving it on by default. + +::: + +## Kconfig + +The following KConfig values need to be set, either by copy and pasting into the `app/prj.conf` file, or by running +`west build -t menuconfig` and manually enabling the various settings in that UI. + +:::note +If you are debugging your own keyboard in your [user config repository](./user-setup.md), use +`config/boards/shields//.conf` instead of `app/prj.conf`. In Github +Actions, you can search the `Kconfig file` build log to verify the options above have been enabled +for you successfully. +::: + +``` +# Turn on logging, and set ZMK logging to debug output +CONFIG_LOG=y +CONFIG_ZMK_LOG_LEVEL_DBG=y + +# Turn on USB CDC ACM device +CONFIG_USB=y +CONFIG_USB_DEVICE_STACK=y +CONFIG_USB_CDC_ACM=y +CONFIG_USB_CDC_ACM_RINGBUF_SIZE=1024 +CONFIG_USB_CDC_ACM_DEVICE_NAME="CDC_ACM" +CONFIG_USB_CDC_ACM_DEVICE_COUNT=1 + +# Enable serial console +CONFIG_SERIAL=y +CONFIG_CONSOLE=y +CONFIG_UART_INTERRUPT_DRIVEN=y +CONFIG_UART_LINE_CTRL=y + +# Enable USB UART, and set the console device +CONFIG_UART_CONSOLE=y +CONFIG_USB_UART_CONSOLE=y +CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0" +CONFIG_USB_UART_DTR_WAIT=n +``` + +## Viewing Logs + +After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs. + + + + +On Linux, this should be a device like `/dev/ttyACM0` and you can connect with `minicom` or `tio` as usual, e.g.: + +``` +sudo tio /dev/ttyACM0 +``` + + + + +On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Device Manager to figure out which COM port your controller is communicating on (listed under 'Ports (COM & LPT)') and specify that as the 'Serial line' in PuTTY. + +![Controller COM port](../assets/usb-logging/com.jpg) + +![PuTTY settings](../assets/usb-logging/putty.jpg) + +If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor. + + + + +On MacOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. +You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)): + +``` +sudo tio /dev/tty.usbmodem14401 +``` + +You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable. + + + +From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels. diff --git a/zmk/docs/docs/faq.md b/zmk/docs/docs/faq.md index 3822c0d8..7417a49a 100644 --- a/zmk/docs/docs/faq.md +++ b/zmk/docs/docs/faq.md @@ -76,6 +76,10 @@ Therefore in ZMK, [board](#what-is-a-board) and [shield](#what-is-a-shield) are Please note, many keyboards only have a single PCB which includes the “brains” (MCU) onboard. In ZMK, these have no [shield](#what-is-a-shield), only a [board](#what-is-a-board). +### Does ZMK support wired split? + +Currently, ZMK only supports wireless split, but wired split is possible and we welcome contributions! + ### What bootloader does ZMK use? ZMK isn’t designed for any particular bootloader, and supports flashing different boards with different flash utilities (e.g. OpenOCD, nrfjprog, etc.). So if you have any difficulties, please let us know on [Discord](https://zmkfirmware.dev/community/discord/invite)! diff --git a/zmk/docs/docs/features/displays.md b/zmk/docs/docs/features/displays.md new file mode 100644 index 00000000..2b3d001d --- /dev/null +++ b/zmk/docs/docs/features/displays.md @@ -0,0 +1,6 @@ +--- +title: OLED Displays +sidebar_label: OLED Displays +--- + +TODO: Documentation on OLED displays. diff --git a/zmk/docs/docs/features/encoders.md b/zmk/docs/docs/features/encoders.md new file mode 100644 index 00000000..01610775 --- /dev/null +++ b/zmk/docs/docs/features/encoders.md @@ -0,0 +1,44 @@ +--- +title: Encoders +sidebar_label: Encoders +--- + +Existing support for encoders in ZMK is focused around the five pin EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs. + +## Enabling EC11 Encoders + +To enable encoders for boards that have existing encoder support, uncomment the `EC11_CONFIG=y` and `CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y` lines in your board's .conf file in your `zmk-config/config` folder. Save and push your changes, then download and flash the new firmware. + +## Customizing EC11 Encoder Behavior + +Encoder behavior in ZMK is configured in two different locations as the push button and rotation behaviors are handled in two separate ways. + +### Push Button + +Keyboards and macropads with encoder support will typically take the two EC11 pins responsible for the push button and include them as part of the matrix for the keys. To configure what is sent by the push button, find the encoder's position in the keyboard matrix and assign it a behavior the same as you would any other key. + +### Rotation + +Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`, which is defined in each keymap layer in the following format: + +``` +sensor-bindings = ; +``` + +- `BINDING`, for now, has only one behavior available; `&inc_dec_kp` for key presses (see [Key Press](/docs/behaviors/key-press) for details on available keycodes). +- `CW_KEY` is the keycode activated by a clockwise turn. +- `CCW_KEY` is the keycode activated by a counter-clockwise turn. + +Additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first. + +As an example, a complete `sensor-bindings` for a Kyria with two encoders could look like: + +``` +sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>; +``` + +Here, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down. + +## Adding Encoder Support + +See the [New Keyboard Shield](../development/new-shield#encoders) documentation for how to add or modify additional encoders to your shield. diff --git a/zmk/docs/docs/features/keymaps.md b/zmk/docs/docs/features/keymaps.md new file mode 100644 index 00000000..de1f24ac --- /dev/null +++ b/zmk/docs/docs/features/keymaps.md @@ -0,0 +1,140 @@ +--- +title: Keymaps & Behaviors +sidebar_label: Keymaps +--- + +import KeymapExample from '../keymap-example.md'; +import KeymapExampleFile from '../keymap-example-file.md'; + +ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration. +Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for +supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE +service. + +:::note +For advanced users looking to implement custom behaviors for their keymaps, this will be possible +in the future by allowing user configs to add to the CMake application built by Zephyr. +::: + +## Big Picture + +All keyboard definitions (complete boards or shields) include the _default_ keymap for that keyboard, +so ZMK can produce a "stock" firmware for that keyboard without any further modifications. For users +looking to customize their keyboard's behavior, they can copy the stock `.keymap` file into their +user config directory, and customize the keymap to their liking. + +## Behaviors + +ZMK implements the concept of "behaviors", which can be bound to a certain key position, sensor (encoder), +or layer, to perform certain actions when events occur for that binding (e.g. when a certain key position +is pressed or released, or an encoder triggers a rotation event). + +For example, the simplest behavior in ZMK is the "key press" behavior, which responds to key position +(a certain spot on the keyboard), and when that position is pressed, send a keycode to the host, and +when the key position is released, updates the host to notify of the keycode being released. + +For the full set of possible behaviors, start at the [Key Press](/docs/behaviors/key-press) behavior. + +## Layers + +Like many mechanical keyboard firmwares, ZMK keymaps are composed of a collection of layers, with a +minimum of at least one layer that is the default, usually near the bottom of the "stack". Each layer +in ZMK contains a set of bindings that bind a certain behavior to a certain key position in that layer. + +| ![Diagram of three layers](../assets/features/keymaps/layer-diagram.png) | +| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| _A simplified diagram showing three layers. The layout of each layer is the same (they all contain four keys), but the behavior bindings within each layer can be different._ | + +In addition to the base default layer (which can be changed), certain bound behaviors may also +enable/disable additional layers "on top" of the default layer. + +When a key location is pressed/released, the stack of all active layers from "top to bottom" is used, +and the event is sent to the behavior bound at that position in each layer, for it to perform whatever +actions it wants to in reaction to the event. Those behaviors can choose to "handle" the event, and stop +it from being passed to any lower layers, or may choose to "pass it along", and let the next layer +in the stack _also_ get the event. + +## Behavior Bindings + +Binding a behavior at a certain key position may include up to two extra parameters that are used to +alter the behavior when that specific key position is activated/deactivated. For example, when binding +the "key press" (`kp`) behavior at a certain key position, you must specific _which_ keycode should +be used for that key position. + +``` +&kp A +``` + +In this case, the `A` is actually a define for the raw HID keycode, to make keymaps easier to read and write. + +For example of a binding that uses two parameters, you can see how "mod-tap" (`mt`) is bound: + +``` +&mt LSHFT D +``` + +Here, the first parameter is the set of modifiers that should be used for the "hold" behavior, and the second +parameter is the keycode that should be sent when triggering the "tap" behavior. + +## Keymap File + +A keymap file is composed of several sections, that together make up a valid devicetree file for describing the keymap and its layers. + +### Includes + +The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders +for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files. + +The top two lines of most keymaps should include: + +``` +#include +#include +``` + +The first defines the nodes for all the available behaviors in ZMK, which will be referenced in the behavior bindings. This is how bindings like `&kp` can reference the key press behavior defined with an anchor name of `kp`. + +The second include brings in the defines for all the keycodes (e.g. `A`, `N1`, `C_PLAY`) and the modifiers (e.g. `LSHFT`) used for various behavior bindings. + +### Root devicetree Node + +ALl the remaining keymap nodes will be nested inside of the root devicetree node, like so: + +```devicetree +/ { + // Everything else goes here! +}; +``` + +### Keymap Node + +Nested under the devicetree root, is the keymap node. The node _name_ itself is not critical, but the node **MUST** have a property +`compatible = "zmk,keymap"` in order to be used by ZMK. + +``` + keymap { + compatible = "zmk,keymap"; + + // Layer nodes go here! + }; +``` + +### Layers + +Each layer of your keymap will be nested under the keymap node. Here is a sample +that defines just one layer for this keymap: + + + +Each layer should have: + +1. A `bindings` property this will be a list of behaviour bindings, one for each key position for the keyboard. +1. (Optional) A `sensor-bindings` property that will be a list of behavior bindings for each sensor on the keyboard. (Currently, only encoders are supported as sensor hardware, but in the future devices like trackpoints would be supported the same way) + +For the full set of possible behaviors, start at the [Key Press](/docs/behaviors/key-press) behavior. + +### Complete Example + +Putting this all together, a complete [`kyria.keymap`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/kyria.keymap) looks like: + + diff --git a/zmk/docs/docs/features/underglow.md b/zmk/docs/docs/features/underglow.md new file mode 100644 index 00000000..2cea913f --- /dev/null +++ b/zmk/docs/docs/features/underglow.md @@ -0,0 +1,131 @@ +--- +title: RGB Underglow +sidebar_label: RGB Underglow +--- + +RGB underglow is a feature used to control "strips" of RGB LEDs. Most of the time this is called underglow and creates a glow underneath the board using a ring of LEDs around the edge, hence the name. However, this can be extended to be used to control anything from a single LED to a long string of LEDs anywhere on the keyboard. + +ZMK supports all the RGB LEDs supported by Zephyr. Here's the current list supported: + +- WS2812-ish (WS2812B, WS2813, SK6812, or compatible) +- APA102 +- LPD880x (LPD8803, LPD8806, or compatible) + +Of the compatible types, the WS2812 LED family is by far the most popular type. Currently each of these types of LEDs are expected to be run using SPI with a couple of exceptions. + +Here you can see the RGB underglow feature in action using WS2812 LEDs. + +
+ +
+ +## Enabling RGB Underglow + +To enable RGB underglow on your board or shield, simply enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `X_STRIP` configuration values in the `.conf` file of your user config directory as such: + +``` +CONFIG_ZMK_RGB_UNDERGLOW=y +# Use the STRIP config specific to the LEDs you're using +CONFIG_WS2812_STRIP=y +``` + +If your board or shield does not have RGB underglow configured, refer to [Adding RGB Underglow to a Board](#adding-rgb-underglow-to-a-board). + +## Configuring RGB Underglow + +There are various Kconfig options used to configure the RGB underglow feature. These can all be set in the `.conf` file. + +| Option | Description | Default | +| ------------------------------------ | ---------------------------------------------- | ------- | +| `CONFIG_ZMK_RGB_UNDERGLOW_HUE_STEP` | Hue step in degrees of 360 used by RGB actions | 10 | +| `CONFIG_ZMK_RGB_UNDERGLOW_SAT_STEP` | Saturation step in percent used by RGB actions | 10 | +| `CONFIG_ZMK_RGB_UNDERGLOW_BRT_STEP` | Brightness step in percent used by RGB actions | 10 | +| `CONFIG_ZMK_RGB_UNDERGLOW_HUE_START` | Default hue 0-359 in degrees | 0 | +| `CONFIG_ZMK_RGB_UNDERGLOW_SAT_START` | Default saturation 0-100 in percent | 100 | +| `CONFIG_ZMK_RGB_UNDERGLOW_BRT_START` | Default brightness 0-100 in percent | 100 | +| `CONFIG_ZMK_RGB_UNDERGLOW_SPD_START` | Default effect speed 1-5 | 3 | +| `CONFIG_ZMK_RGB_UNDERGLOW_EFF_START` | Default effect integer from the effect enum | 0 | +| `CONFIG_ZMK_RGB_UNDERGLOW_ON_START` | Default on state | y | + +## Adding RGB Underglow to a Board + +RGB underglow is always added to a board, not a shield. This is a consequence of needing to configure SPI to control the LEDs. +If you have a shield with RGB underglow, you must add a `boards/` directory within your shield folder to define the RGB underglow individually for each board that supports the shield. +Inside the `boards/` folder, you define a `.overlay` for each different board. +For example, the Kyria shield has a `boards/nice_nano.overlay` file that defines the RGB underglow for the `nice_nano` board specifically. + +The first step to adding support for underglow is to select you SPI output. With nRF52 boards, you can just use `&spi1` and define the pins you want to use. +For other boards, you must select an SPI definition that has the `MOSI` pin as your data pin going to your LED strip. + +Here's an example of an nRF52 SPI definition: + +``` +&spi1 { + compatible = "nordic,nrf-spim"; + status = "okay"; + mosi-pin = <6>; + // Unused pins, needed for SPI definition, but not used by the ws2812 driver itself. + sck-pin = <5>; + miso-pin = <7>; + + led_strip: ws2812@0 { + compatible = "worldsemi,ws2812-spi"; + label = "WS2812"; + + /* SPI */ + reg = <0>; /* ignored, but necessary for SPI bindings */ + spi-max-frequency = <4000000>; + + /* WS2812 */ + chain-length = <10>; /* number of LEDs */ + spi-one-frame = <0x70>; + spi-zero-frame = <0x40>; + }; +}; +``` + +:::info + +If you are configuring SPI for an nRF52840 (or other nRF52) based board, double check that you are using pins that aren't restricted to low frequency I/O. +Ignoring these restrictions may result in poor wireless performance. You can find the list of low frequency I/O pins [here](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf52840%2Fpin.html&cp=4_0_0_6_0). + +::: + +Here's another example for a non-nRF52 board on `spi1`: + +``` +&spi1 { + + led_strip: ws2812@0 { + compatible = "worldsemi,ws2812-spi"; + label = "WS2812"; + + /* SPI */ + reg = <0>; + spi-max-frequency = <5250000>; + + /* WS2812 */ + chain-length = <10>; /* number of LEDs */ + spi-one-frame = <0x70>; /* make sure to configure this properly for your SOC */ + spi-zero-frame = <0x40>; /* make sure to configure this properly for your SOC */ + }; +}; +``` + +Once you have your `led_strip` properly defined you need to add it to the root devicetree node `chosen` element: + +``` +/ { + chosen { + zmk,underglow = &led_strip; + }; +}; +``` + +Finally you need to enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `X_STRIP` configuration values in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`): + +``` +CONFIG_ZMK_RGB_UNDERGLOW=y +# Use the STRIP config specific to the LEDs you're using +CONFIG_WS2812_STRIP=y +``` diff --git a/zmk/docs/docs/hardware.md b/zmk/docs/docs/hardware.md index b142bda0..3c93313a 100644 --- a/zmk/docs/docs/hardware.md +++ b/zmk/docs/docs/hardware.md @@ -27,6 +27,8 @@ That being said, there are currently only a few specific [boards](/docs/faq#what - [Lily58](https://github.com/kata0510/Lily58) (`lily58_left` and `lily58_right`) - [Sofle](https://github.com/josefadamcik/SofleKeyboard) (`sofle_left` and `sofle_right`) - [Splitreus62](https://github.com/Na-Cly/splitreus62) (`splitreus62_left` and `splitreus62_right`) +- [Jorne](https://github.com/joric/jorne) (`jorne_left` and `jorne_right`) +- [Jian](https://github.com/KGOH/Jian-Info) (`jian_left` and `jian_right`) - [Reviung41](https://github.com/gtips/reviung/tree/master/reviung41) (`reviung41`) - [RoMac+ v4](https://www.littlekeyboards.com/products/romac) (`romac_plus`) - [RoMac v2](https://mechboards.co.uk/shop/kits/romac-macro-pad/) (`romac`) @@ -45,4 +47,4 @@ Until detailed documentation is available, feel free to ask questions about how ## Contributing -If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](/docs/dev-guide-new-shield) documentation. +If you'd like to add support for a new keyboard shield, head over to the [New Keyboard Shield](development/new-shield) documentation. diff --git a/zmk/docs/docs/intro.md b/zmk/docs/docs/intro.md index c76e4b7c..564eedb7 100644 --- a/zmk/docs/docs/intro.md +++ b/zmk/docs/docs/intro.md @@ -11,32 +11,32 @@ firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time ZMK is currently missing some features found in other popular firmware. This table compares the features supported by ZMK, BlueMicro and QMK: -| **Feature** | ZMK | BlueMicro | QMK | -| ---------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: | -| Low Latency BLE Support | ✅ | ✅ | | -| Multi-Device BLE Support | ✅ | | | -| [USB Connectivity](behavior/outputs) | ✅ | | ✅ | -| User Configuration Repositories | ✅ | | | -| Split Keyboard Support | ✅ | ✅ | ✅ | -| [Keymaps and Layers](behavior/layers) | ✅ | ✅ | ✅ | -| [Hold-Tap](behavior/hold-tap) (which includes [Mod-Tap](behavior/mod-tap) and [Layer-Tap](behavior/layers/#layer-tap)) | ✅ | ✅ | ✅ | -| [Keyboard Codes](codes/#keyboard) | ✅ | ✅ | ✅ | -| [Media](codes/#media-controls) & [Consumer](codes/#consumer-controls) Codes | ✅ | ✅ | ✅ | -| [Encoders](feature/encoders)[^1] | ✅ | | ✅ | -| [OLED Display Support](feature/displays)[^2] | 🚧 | 🚧 | ✅ | -| [RGB Underglow](feature/underglow) | ✅ | ✅ | ✅ | -| One Shot Keys | 🚧 | ✅ | ✅ | -| Combo Keys | 🚧 | | ✅ | -| Macros | 🚧 | ✅ | ✅ | -| Mouse Keys | | ✅ | ✅ | -| Low Active Power Usage | ✅ | | | -| [Low Power Sleep States](https://github.com/zmkfirmware/zmk/pull/211) | 🚧 | ✅ | | -| [Low Power Mode (VCC Shutoff)](https://github.com/zmkfirmware/zmk/pull/242) | 🚧 | | | -| [Battery Reporting](https://github.com/zmkfirmware/zmk/issues/47) | 🚧 | ✅ | | -| Shell over BLE | | | | -| Realtime Keymap Updating | 💡 | | ✅ | -| AVR/8 Bit | | | ✅ | -| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html) | ✅ | | | +| **Feature** | ZMK | BlueMicro | QMK | +| ------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :-: | +| Low Latency BLE Support | ✅ | ✅ | | +| Multi-Device BLE Support | ✅ | | | +| [USB Connectivity](behaviors/outputs) | ✅ | | ✅ | +| User Configuration Repositories | ✅ | | | +| Split Keyboard Support | ✅ | ✅ | ✅ | +| [Keymaps and Layers](behaviors/layers) | ✅ | ✅ | ✅ | +| [Hold-Tap](behaviors/hold-tap) (which includes [Mod-Tap](behaviors/mod-tap) and [Layer-Tap](behaviors/layers/#layer-tap)) | ✅ | ✅ | ✅ | +| [Keyboard Codes](codes/#keyboard) | ✅ | ✅ | ✅ | +| [Media](codes/#media-controls) & [Consumer](codes/#consumer-controls) Codes | ✅ | ✅ | ✅ | +| [Encoders](features/encoders)[^1] | ✅ | | ✅ | +| [OLED Display Support](features/displays)[^2] | 🚧 | 🚧 | ✅ | +| [RGB Underglow](features/underglow) | ✅ | ✅ | ✅ | +| One Shot Keys | 🚧 | ✅ | ✅ | +| Combo Keys | 🚧 | | ✅ | +| Macros | 🚧 | ✅ | ✅ | +| Mouse Keys | | ✅ | ✅ | +| Low Active Power Usage | ✅ | | | +| [Low Power Sleep States](https://github.com/zmkfirmware/zmk/pull/211) | 🚧 | ✅ | | +| [Low Power Mode (VCC Shutoff)](https://github.com/zmkfirmware/zmk/pull/242) | 🚧 | | | +| [Battery Reporting](https://github.com/zmkfirmware/zmk/issues/47) | 🚧 | ✅ | | +| Shell over BLE | | | | +| Realtime Keymap Updating | 💡 | | ✅ | +| AVR/8 Bit | | | ✅ | +| [Wide Range of ARM Chips Supported](https://docs.zephyrproject.org/latest/boards/index.html) | ✅ | | | [^2]: Encoders are not currently supported on peripheral side splits. [^1]: OLEDs are currently proof of concept in ZMK. diff --git a/zmk/docs/docs/keymap-example-file.md b/zmk/docs/docs/keymap-example-file.md new file mode 100644 index 00000000..5cb9b2f4 --- /dev/null +++ b/zmk/docs/docs/keymap-example-file.md @@ -0,0 +1,26 @@ +``` +#include +#include + +/ { + keymap { + compatible = "zmk,keymap"; + + default_layer { +// -------------------------------------------------------------------------------------------------------------------------------------------------------------------- +// | ESC | Q | W | E | R | T | | Y | U | I | O | P | \ | +// | TAB | A | S | D | F | G | | H | J | K | L | ; | ' | +// | SHIFT | Z | X | C | V | B | CTRL+A | CTRL+C | | CTRL+V | CTRL+X | N | M | , | . | / | R CTRL | +// | GUI | DEL | RETURN | SPACE | ESCAPE | | RETURN | SPACE | TAB | BSPC | R ALT | + bindings = < + &kp ESC &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp BSLH + &kp TAB &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SEMI &kp QUOTE + &kp LSHFT &kp Z &kp X &kp C &kp V &kp B &kp LC(A) &kp LC(C) &kp LC(V) &kp LC(X) &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp RCTRL + &kp LGUI &kp DEL &kp RET &kp SPACE &kp ESC &kp RET &kp SPACE &kp TAB &kp BSPC &kp RALT + >; + + sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>; + }; + }; +}; +``` diff --git a/zmk/docs/docs/keymap-example.md b/zmk/docs/docs/keymap-example.md new file mode 100644 index 00000000..c6e81d22 --- /dev/null +++ b/zmk/docs/docs/keymap-example.md @@ -0,0 +1,21 @@ +``` + keymap { + compatible = "zmk,keymap"; + + default_layer { +// -------------------------------------------------------------------------------------------------------------------------------------------------------------------- +// | ESC | Q | W | E | R | T | | Y | U | I | O | P | \ | +// | TAB | A | S | D | F | G | | H | J | K | L | ; | ' | +// | SHIFT | Z | X | C | V | B | CTRL+A | CTRL+C | | CTRL+V | CTRL+X | N | M | , | . | / | R CTRL | +// | GUI | DEL | RETURN | SPACE | ESCAPE | | RETURN | SPACE | TAB | BSPC | R ALT | + bindings = < + &kp ESC &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp BSLH + &kp TAB &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SEMI &kp QUOTE + &kp LSHFT &kp Z &kp X &kp C &kp V &kp B &kp LC(A) &kp LC(C) &kp LC(V) &kp LC(X) &kp N &kp M &kp COMMA &kp DOT &kp FSLH &kp RCTRL + &kp LGUI &kp DEL &kp RET &kp SPACE &kp ESC &kp RET &kp SPACE &kp TAB &kp BSPC &kp RALT + >; + + sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>; + }; + }; +``` diff --git a/zmk/docs/docs/troubleshooting.md b/zmk/docs/docs/troubleshooting.md index f11d02e4..0fe0b665 100644 --- a/zmk/docs/docs/troubleshooting.md +++ b/zmk/docs/docs/troubleshooting.md @@ -25,23 +25,8 @@ Variations of the warnings shown below occur when flashing the `.uf2` ### CMake Error -``` -CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:28 (message): - CONFIG_USB_DEVICE_VID has default value 0x2FE3. - - This value is only for testing and MUST be configured for USB products. - - -CMake Warning at C:/zmk/zephyr/subsys/usb/CMakeLists.txt:34 (message): - CONFIG_USB_DEVICE_PID has default value 0x100. - - This value is only for testing and MUST be configured for USB products. -``` - -CMake Warnings shown above during `west build` are normal occurrences. They should not negatively affect the firmware's ability to function as normal. - -On the other hand, 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, click [here](../docs/dev-setup#environment-variables). +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, click [here](../docs/development/setup#environment-variables). ### dtlib.DTError diff --git a/zmk/docs/docs/user-setup.md b/zmk/docs/docs/user-setup.md index 703e118a..4a842e41 100644 --- a/zmk/docs/docs/user-setup.md +++ b/zmk/docs/docs/user-setup.md @@ -82,7 +82,7 @@ bash -c "$(wget https://zmkfirmware.dev/setup.sh -O -)" '' --wget ``` -iex ((New-Object System.Net.WebClient).DownloadString('https://zmkfirmware.dev/setup.ps1'))" +iex ((New-Object System.Net.WebClient).DownloadString('https://zmkfirmware.dev/setup.ps1')) ``` @@ -105,7 +105,7 @@ Pick an MCU board: :::note If you are building firmware for a new keyboard shield that is not included in the built-in list of shields, you can choose any shield from the list that is similar to yours to generate the repository, -and edit / add necessary files according to the [guide for adding new keyboard shield](./dev-guide-new-shield.md). +and edit / add necessary files according to the [guide for adding new keyboard shield](./development/new-shield). ::: When prompted, enter the number for the corresponding keyboard shield you would like to target: diff --git a/zmk/docs/docusaurus.config.js b/zmk/docs/docusaurus.config.js index 97548342..2716039c 100644 --- a/zmk/docs/docusaurus.config.js +++ b/zmk/docs/docusaurus.config.js @@ -45,7 +45,7 @@ module.exports = { }, { label: "Development", - to: "docs/dev-setup/", + to: "docs/development/setup/", }, ], }, diff --git a/zmk/docs/sidebars.js b/zmk/docs/sidebars.js index 15d531ec..7d124cc6 100644 --- a/zmk/docs/sidebars.js +++ b/zmk/docs/sidebars.js @@ -1,5 +1,5 @@ module.exports = { - someSidebar: { + docs: { "Getting Started": [ "intro", "hardware", @@ -9,22 +9,22 @@ module.exports = { "troubleshooting", ], Features: [ - "feature/keymaps", - "feature/displays", - "feature/encoders", - "feature/underglow", + "features/keymaps", + "features/displays", + "features/encoders", + "features/underglow", ], Behaviors: [ - "behavior/key-press", - "behavior/layers", - "behavior/misc", - "behavior/hold-tap", - "behavior/mod-tap", - "behavior/reset", - "behavior/bluetooth", - "behavior/outputs", - "behavior/lighting", - "behavior/power", + "behaviors/key-press", + "behaviors/layers", + "behaviors/misc", + "behaviors/hold-tap", + "behaviors/mod-tap", + "behaviors/reset", + "behaviors/bluetooth", + "behaviors/outputs", + "behaviors/lighting", + "behaviors/power", ], Codes: [ "codes/index", @@ -37,13 +37,19 @@ module.exports = { "codes/power", ], Development: [ - "dev-clean-room", - "dev-setup", - "dev-build-flash", - "dev-boards-shields-keymaps", - "dev-posix-board", - "dev-tests", + "development/clean-room", + "development/setup", + "development/build-flash", + "development/boards-shields-keymaps", + "development/posix-board", + "development/tests", + "development/usb-logging", + { + type: "category", + label: "Guides", + collapsed: false, + items: ["development/new-shield"], + }, ], - "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], }, }; diff --git a/zmk/docs/src/components/codes/Table.jsx b/zmk/docs/src/components/codes/Table.jsx index c7dd20c8..0596de6a 100644 --- a/zmk/docs/src/components/codes/Table.jsx +++ b/zmk/docs/src/components/codes/Table.jsx @@ -19,7 +19,7 @@ function extractFootnoteIds(codes) { new Set( codes .flatMap(({ footnotes }) => Object.values(footnotes)) - .map((refs) => (Array.isArray(refs) ? refs.flat() : refs)) + .flatMap((refs) => (Array.isArray(refs) ? refs.flat() : refs)) ) ); } diff --git a/zmk/docs/static/setup.ps1 b/zmk/docs/static/setup.ps1 index 8a51efab..6591da93 100644 --- a/zmk/docs/static/setup.ps1 +++ b/zmk/docs/static/setup.ps1 @@ -16,13 +16,13 @@ function Get-Choice-From-Options { } Write-Host "$($Options.length + 1)) Quit" - $selection = Read-Host $Prompt + $selection = (Read-Host $Prompt) -as [int] if ($selection -eq $Options.length + 1) { Write-Host "Goodbye!" exit 1 } - elseif ($selection -le $Options.length) { + elseif ($selection -le $Options.length -and $selection -gt 0) { $choice = $($selection - 1) break } @@ -91,9 +91,9 @@ Write-Host "Keyboard Shield Selection:" $prompt = "Pick a keyboard" # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. -$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "Reviung41", "RoMac", "RoMac+", "makerdiary M60", "Microdox", "TG4X", "QAZ", "NIBBLE" -$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "reviung41", "romac", "romac_plus", "m60", "microdox", "tg4x", "qaz", "nibble" -$splits = "y", "y", "y", "y", "y", "y", "n", "n", "n", "n", "y", "n", "n", "n" +$options = "Kyria", "Lily58", "Corne", "Splitreus62", "Sofle", "Iris", "Reviung41", "RoMac", "RoMac+", "makerdiary M60", "Microdox", "TG4X", "QAZ", "NIBBLE", "Jorne", "Jian" +$names = "kyria", "lily58", "corne", "splitreus62", "sofle", "iris", "reviung41", "romac", "romac_plus", "m60", "microdox", "tg4x", "qaz", "nibble", "jorne", "jian" +$splits = "y", "y", "y", "y", "y", "y", "n", "n", "n", "n", "y", "n", "n", "n", "y", "y" $choice = Get-Choice-From-Options -Options $options -Prompt $prompt $shield_title = $($options[$choice]) diff --git a/zmk/docs/static/setup.sh b/zmk/docs/static/setup.sh index cdd6bc47..4360f2c5 100644 --- a/zmk/docs/static/setup.sh +++ b/zmk/docs/static/setup.sh @@ -92,7 +92,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "Reviung41" "RoMac" "RoMac+" "makerdiary M60" "Microdox" "TG4X" "QAZ") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "Reviung41" "RoMac" "RoMac+" "makerdiary M60" "Microdox" "TG4X" "QAZ" "Jorne" "Jian") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -115,6 +115,8 @@ select opt in "${options[@]}" "Quit"; do 12 ) shield_title="TG4X" shield="tg4x"; split="n"; break;; 13 ) shield_title="QAZ" shield="qaz"; split="n"; break;; 14 ) shield_title="NIBBLE" shield="nibble"; split="n"; break;; + 15 ) shield_title="Jorne" shield="jorne"; split="y"; break;; + 16 ) shield_title="Jian" shield="jian"; split="y"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;;