diff options
| -rw-r--r-- | app/boards/arm/dz60rgb/CMakeLists.txt | 7 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/Kconfig.board | 6 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/Kconfig.defconfig | 14 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/board.cmake | 7 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/dz60rgb_rev1.dts | 88 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/dz60rgb_rev1.keymap | 25 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/dz60rgb_rev1.yaml | 19 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/dz60rgb_rev1_defconfig | 27 | ||||
| -rw-r--r-- | app/boards/arm/dz60rgb/pinmux.c | 69 | ||||
| -rw-r--r-- | app/boards/arm/planck/planck_rev6_defconfig | 3 | ||||
| -rw-r--r-- | app/tests/momentary-layer/early-key-release/pending | 0 | ||||
| -rw-r--r-- | app/tests/toggle-layer/early-key-release/pending | 0 | ||||
| -rw-r--r-- | docs/docs/dev-guide-new-shield.md | 89 | ||||
| -rw-r--r-- | docs/docs/faq.md | 6 | ||||
| -rw-r--r-- | docs/docs/feature/encoders.md | 40 | ||||
| -rw-r--r-- | docs/docs/intro.md | 2 | ||||
| -rw-r--r-- | docs/sidebars.js | 4 | ||||
| -rw-r--r-- | docs/static/setup.sh | 7 |
18 files changed, 403 insertions, 10 deletions
diff --git a/app/boards/arm/dz60rgb/CMakeLists.txt b/app/boards/arm/dz60rgb/CMakeLists.txt new file mode 100644 index 0000000..940af1f --- /dev/null +++ b/app/boards/arm/dz60rgb/CMakeLists.txt @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: MIT + +if(CONFIG_PINMUX) +zephyr_library() +zephyr_library_sources(pinmux.c) +zephyr_library_include_directories(${ZEPHYR_BASE}/drivers) +endif() diff --git a/app/boards/arm/dz60rgb/Kconfig.board b/app/boards/arm/dz60rgb/Kconfig.board new file mode 100644 index 0000000..a96271f --- /dev/null +++ b/app/boards/arm/dz60rgb/Kconfig.board @@ -0,0 +1,6 @@ +# Copyright (c) 2020 Nick Winans +# SPDX-License-Identifier: MIT + +config BOARD_DZ60RGB_REV1 + bool "DZ60RGB Keyboard" + depends on SOC_STM32F303XC diff --git a/app/boards/arm/dz60rgb/Kconfig.defconfig b/app/boards/arm/dz60rgb/Kconfig.defconfig new file mode 100644 index 0000000..c97a308 --- /dev/null +++ b/app/boards/arm/dz60rgb/Kconfig.defconfig @@ -0,0 +1,14 @@ +# DZ60RGB keyboard configuration + +# Copyright (c) 2020 Nick Winans +# SPDX-License-Identifier: MIT + +if BOARD_DZ60RGB_REV1 + +config ZMK_KEYBOARD_NAME + default "DZ60RGB Rev 1" + +config ZMK_USB + default y + +endif # BOARD_DZ60RGB_REV1 diff --git a/app/boards/arm/dz60rgb/board.cmake b/app/boards/arm/dz60rgb/board.cmake new file mode 100644 index 0000000..10f6e29 --- /dev/null +++ b/app/boards/arm/dz60rgb/board.cmake @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: MIT + +board_runner_args(dfu-util "--pid=0483:df11" "--alt=0" "--dfuse") +board_runner_args(jlink "--device=STM32F303CC" "--speed=4000") + +include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake) +include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake) diff --git a/app/boards/arm/dz60rgb/dz60rgb_rev1.dts b/app/boards/arm/dz60rgb/dz60rgb_rev1.dts new file mode 100644 index 0000000..dc1b6ea --- /dev/null +++ b/app/boards/arm/dz60rgb/dz60rgb_rev1.dts @@ -0,0 +1,88 @@ +/* + * Copyright (c) 2020 Nick Winans + * + * SPDX-License-Identifier: MIT + */ + +/dts-v1/; +#include <st/f3/stm32f303Xc.dtsi> + +#include <dt-bindings/zmk/matrix-transform.h> + +/ { + model = "DZ60RGB, Rev 1"; + compatible = "dz60rgb,rev1", "st,stm32f303"; + + chosen { + zephyr,sram = &sram0; + zephyr,flash = &flash0; + zmk,kscan = &kscan0; + zmk,matrix_transform = &default_transform; + }; + + default_transform: keymap_transform_0 { + compatible = "zmk,matrix-transform"; + columns = <14>; + rows = <5>; + 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(0,12) RC(0,13) +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(1,12) RC(1,13) +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(2,13) +RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4) RC(3,5) RC(3,6) RC(3,7) RC(3,8) RC(3,9) RC(3,10) RC(3,11) RC(3,13) +RC(4,0) RC(4,1) RC(4,2) RC(4,5) RC(4,8) RC(4,9) RC(4,10) RC(4,11) RC(4,13) + >; + }; + + kscan0: kscan { + compatible = "zmk,kscan-gpio-matrix"; + label = "KSCAN"; + + diode-direction = "col2row"; + row-gpios + = <&gpioa 9 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&gpiob 10 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&gpiob 11 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&gpiob 14 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + , <&gpiob 12 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> + ; + col-gpios + = <&gpioa 6 GPIO_ACTIVE_HIGH> + , <&gpioa 7 GPIO_ACTIVE_HIGH> + , <&gpiob 0 GPIO_ACTIVE_HIGH> + , <&gpiob 13 GPIO_ACTIVE_HIGH> + , <&gpiob 15 GPIO_ACTIVE_HIGH> + , <&gpioa 8 GPIO_ACTIVE_HIGH> + , <&gpioa 15 GPIO_ACTIVE_HIGH> + , <&gpiob 3 GPIO_ACTIVE_HIGH> + , <&gpiob 4 GPIO_ACTIVE_HIGH> + , <&gpiob 5 GPIO_ACTIVE_HIGH> + , <&gpiob 8 GPIO_ACTIVE_HIGH> + , <&gpiob 9 GPIO_ACTIVE_HIGH> + , <&gpioc 13 GPIO_ACTIVE_HIGH> + , <&gpioc 14 GPIO_ACTIVE_HIGH> + ; + }; + +}; + +&usb { + status = "okay"; +}; + +&flash0 { + /* + * For more information, see: + * http://docs.zephyrproject.org/latest/guides/dts/index.html#flash-partitions + */ + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + /* Set 6Kb of storage at the end of the 256Kb of flash */ + storage_partition: partition@3e800 { + label = "storage"; + reg = <0x0003e800 0x00001800>; + }; + }; +}; diff --git a/app/boards/arm/dz60rgb/dz60rgb_rev1.keymap b/app/boards/arm/dz60rgb/dz60rgb_rev1.keymap new file mode 100644 index 0000000..8de01c1 --- /dev/null +++ b/app/boards/arm/dz60rgb/dz60rgb_rev1.keymap @@ -0,0 +1,25 @@ +#include <behaviors.dtsi> +#include <dt-bindings/zmk/keys.h> + +/ { + keymap { + compatible = "zmk,keymap"; + + default_layer { +// ------------------------------------------------------------------------------------------ +// | ESC | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 | - | = | BKSP | +// | TAB | Q | W | E | R | T | Y | U | I | O | P | [ | ] | "|" | +// | CAPS | A | S | D | F | G | H | J | K | L | ; | ' | ENTER | +// | SHIFT | Z | X | C | V | B | N | M | , | . | SHIFT(/) | ^ | DEL | +// | CTL | WIN | ALT | SPACE | ALT | MO(1) | <- | v | -> | +// ------------------------------------------------------------------------------------------ + bindings = < + &kp ESC &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 &kp MINUS &kp EQL &kp BKSP + &kp TAB &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp LBKT &kp RBKT &kp BSLH + &kp CLCK &kp A &kp S &kp D &kp F &kp G &kp H &kp J &kp K &kp L &kp SCLN &kp QUOT &kp RET + &kp LSFT &kp Z &kp X &kp C &kp V &kp B &kp N &kp M &kp CMMA &kp DOT &mt MOD_RSFT FSLH &kp UARW &kp DEL + &kp LCTL &kp LGUI &kp LALT &kp SPC &kp RALT &mo 1 &kp LARW &kp DARW &kp RARW + >; + }; + }; +};
\ No newline at end of file diff --git a/app/boards/arm/dz60rgb/dz60rgb_rev1.yaml b/app/boards/arm/dz60rgb/dz60rgb_rev1.yaml new file mode 100644 index 0000000..d283621 --- /dev/null +++ b/app/boards/arm/dz60rgb/dz60rgb_rev1.yaml @@ -0,0 +1,19 @@ +identifier: DZ60RGB_rev1 +name: DZ60RGBREV1 +type: keyboard +arch: arm +toolchain: + - zephyr + - gnuarmemb + - xtools +ram: 40 +supported: + - gpio + - i2c + - counter + - spi + - usb_device + - lsm303dlhc + - nvs + - can + - kscan diff --git a/app/boards/arm/dz60rgb/dz60rgb_rev1_defconfig b/app/boards/arm/dz60rgb/dz60rgb_rev1_defconfig new file mode 100644 index 0000000..33840f9 --- /dev/null +++ b/app/boards/arm/dz60rgb/dz60rgb_rev1_defconfig @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: MIT + +CONFIG_SOC_SERIES_STM32F3X=y +CONFIG_SOC_STM32F303XC=y +# 72MHz system clock +CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC=72000000 + +# enable pinmux +CONFIG_PINMUX=y + +# enable GPIO +CONFIG_GPIO=y + +# clock configuration +CONFIG_CLOCK_CONTROL=y + +# Clock configuration for Cube Clock control driver +CONFIG_CLOCK_STM32_HSE_CLOCK=8000000 +CONFIG_CLOCK_STM32_SYSCLK_SRC_PLL=y +# use HSE as PLL input +CONFIG_CLOCK_STM32_PLL_SRC_HSE=y +# produce 72MHz clock at PLL output +CONFIG_CLOCK_STM32_PLL_PREDIV=1 +CONFIG_CLOCK_STM32_PLL_MULTIPLIER=9 +CONFIG_CLOCK_STM32_AHB_PRESCALER=1 +CONFIG_CLOCK_STM32_APB1_PRESCALER=2 +CONFIG_CLOCK_STM32_APB2_PRESCALER=1 diff --git a/app/boards/arm/dz60rgb/pinmux.c b/app/boards/arm/dz60rgb/pinmux.c new file mode 100644 index 0000000..60e231b --- /dev/null +++ b/app/boards/arm/dz60rgb/pinmux.c @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2017 I-SENSE group of ICCS + * + * SPDX-License-Identifier: MIT + */ + +#include <kernel.h> +#include <device.h> +#include <init.h> +#include <drivers/pinmux.h> +#include <sys/sys_io.h> + +#include <pinmux/stm32/pinmux_stm32.h> + +/* pin assignments for STM32F3DISCOVERY board */ +static const struct pin_config pinconf[] = { +#if DT_NODE_HAS_STATUS(DT_NODELABEL(usart1), okay) && CONFIG_SERIAL + {STM32_PIN_PC4, STM32F3_PINMUX_FUNC_PC4_USART1_TX}, + {STM32_PIN_PC5, STM32F3_PINMUX_FUNC_PC5_USART1_RX}, +#endif +#if DT_NODE_HAS_STATUS(DT_NODELABEL(usart2), okay) && CONFIG_SERIAL + {STM32_PIN_PA2, STM32F3_PINMUX_FUNC_PA2_USART2_TX}, + {STM32_PIN_PA3, STM32F3_PINMUX_FUNC_PA3_USART2_RX}, +#endif +#if DT_NODE_HAS_STATUS(DT_NODELABEL(i2c1), okay) && CONFIG_I2C + {STM32_PIN_PB6, STM32F3_PINMUX_FUNC_PB6_I2C1_SCL}, + {STM32_PIN_PB7, STM32F3_PINMUX_FUNC_PB7_I2C1_SDA}, +#endif +#if DT_NODE_HAS_STATUS(DT_NODELABEL(i2c2), okay) && CONFIG_I2C + {STM32_PIN_PA9, STM32F3_PINMUX_FUNC_PA9_I2C2_SCL}, + {STM32_PIN_PA10, STM32F3_PINMUX_FUNC_PA10_I2C2_SDA}, +#endif +#if DT_NODE_HAS_STATUS(DT_NODELABEL(spi1), okay) && CONFIG_SPI +#ifdef CONFIG_SPI_STM32_USE_HW_SS + {STM32_PIN_PA4, STM32F3_PINMUX_FUNC_PA4_SPI1_NSS}, +#endif /* CONFIG_SPI_STM32_USE_HW_SS */ + {STM32_PIN_PA5, STM32F3_PINMUX_FUNC_PA5_SPI1_SCK}, + {STM32_PIN_PA6, STM32F3_PINMUX_FUNC_PA6_SPI1_MISO}, + {STM32_PIN_PA7, STM32F3_PINMUX_FUNC_PA7_SPI1_MOSI}, +#endif +#if DT_NODE_HAS_STATUS(DT_NODELABEL(spi2), okay) && CONFIG_SPI +#ifdef CONFIG_SPI_STM32_USE_HW_SS + {STM32_PIN_PB12, STM32F3_PINMUX_FUNC_PB12_SPI2_NSS}, +#endif /* CONFIG_SPI_STM32_USE_HW_SS */ + {STM32_PIN_PB13, STM32F3_PINMUX_FUNC_PB13_SPI2_SCK}, + {STM32_PIN_PB14, STM32F3_PINMUX_FUNC_PB14_SPI2_MISO}, + {STM32_PIN_PB15, STM32F3_PINMUX_FUNC_PB15_SPI2_MOSI}, +#endif +#ifdef CONFIG_USB_DC_STM32 + {STM32_PIN_PA11, STM32F3_PINMUX_FUNC_PA11_USB_DM}, + {STM32_PIN_PA12, STM32F3_PINMUX_FUNC_PA12_USB_DP}, +#endif /* CONFIG_USB_DC_STM32 */ +#if DT_NODE_HAS_STATUS(DT_NODELABEL(can1), okay) && CONFIG_CAN + {STM32_PIN_PD0, STM32F3_PINMUX_FUNC_PD0_CAN1_RX}, + {STM32_PIN_PD1, STM32F3_PINMUX_FUNC_PD1_CAN1_TX}, +#endif +}; + +static int pinmux_stm32_init(struct device *port) +{ + ARG_UNUSED(port); + + stm32_setup_pins(pinconf, ARRAY_SIZE(pinconf)); + + return 0; +} + +SYS_INIT(pinmux_stm32_init, PRE_KERNEL_1, + CONFIG_PINMUX_STM32_DEVICE_INITIALIZATION_PRIORITY);
\ No newline at end of file diff --git a/app/boards/arm/planck/planck_rev6_defconfig b/app/boards/arm/planck/planck_rev6_defconfig index a440ff1..e34ce00 100644 --- a/app/boards/arm/planck/planck_rev6_defconfig +++ b/app/boards/arm/planck/planck_rev6_defconfig @@ -20,9 +20,6 @@ CONFIG_CLOCK_STM32_HSE_CLOCK=8000000 CONFIG_CLOCK_STM32_SYSCLK_SRC_PLL=y # use HSE as PLL input CONFIG_CLOCK_STM32_PLL_SRC_HSE=y -# however, the board does not have an external oscillator, so just use -# the 8MHz clock signal coming from integrated STLink -CONFIG_CLOCK_STM32_HSE_BYPASS=y # produce 72MHz clock at PLL output CONFIG_CLOCK_STM32_PLL_PREDIV=1 CONFIG_CLOCK_STM32_PLL_MULTIPLIER=9 diff --git a/app/tests/momentary-layer/early-key-release/pending b/app/tests/momentary-layer/early-key-release/pending deleted file mode 100644 index e69de29..0000000 --- a/app/tests/momentary-layer/early-key-release/pending +++ /dev/null diff --git a/app/tests/toggle-layer/early-key-release/pending b/app/tests/toggle-layer/early-key-release/pending deleted file mode 100644 index e69de29..0000000 --- a/app/tests/toggle-layer/early-key-release/pending +++ /dev/null diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md index 8556623..bc5175b 100644 --- a/docs/docs/dev-guide-new-shield.md +++ b/docs/docs/dev-guide-new-shield.md @@ -3,6 +3,9 @@ id: dev-guide-new-shield title: New Keyboard Shield --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 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. @@ -13,6 +16,7 @@ The high level steps are: - 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. 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. @@ -195,6 +199,91 @@ Further documentation on behaviors and bindings is forthcoming, but a summary of - `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. + +<Tabs +defaultValue="conf" +values={[ +{label: '.conf', value: 'conf'}, +{label: '.dtsi', value: 'dtsi'}, +{label: '.overlay', value: 'overlay'}, +{label: '.keymap', value: 'keymap'}, +]}> +<TabItem value="conf"> + +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. +::: + +</TabItem> +<TabItem value = "dtsi"> +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 = <PIN_A (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>; + b-gpios = <PIN_B (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>; + 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. + +</TabItem> +<TabItem value = "overlay"> +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. +::: + +</TabItem> +<TabItem value = "keymap"> +Add the following line to your keymap file to add default encoder behavior bindings: + +``` +sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD>; +``` +Add additional bindings as necessary to match the default number of encoders on your board. See the [Encoders](/docs/feature/encoders) and [Keymap](/docs/feature/keymaps) feature documentation for more details. + +</TabItem> +</Tabs> + ## Testing Once you've fully created the new keyboard shield definition, diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 2ab158d..d8bbd71 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -76,7 +76,7 @@ Please note, many keyboards only have a single PCB which includes the “brainsâ ### 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://discord.gg/VJnx9kr)! +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)! ### Can I contribute? @@ -84,11 +84,11 @@ Of course! Please use the developer [documentation](/docs) to get started! ### I have an idea! What should I do? -Please join us on [Discord](https://discord.gg/VJnx9kr) and discuss it with us! +Please join us on [Discord](https://zmkfirmware.dev/community/discord/invite) and discuss it with us! ### I want to add a new keyboard! What should I do? -The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://discord.gg/VJnx9kr) to get started. +The exact process for the management of all the possible hardware is still being finalized, but any developer looking to contribute new keyboard definitions should chat with us on [Discord](https://zmkfirmware.dev/community/discord/invite) to get started. ### Does ZMK have a Code of Conduct? diff --git a/docs/docs/feature/encoders.md b/docs/docs/feature/encoders.md index 16537ad..38ff9d3 100644 --- a/docs/docs/feature/encoders.md +++ b/docs/docs/feature/encoders.md @@ -3,4 +3,42 @@ title: Encoders sidebar_label: Encoders --- -TODO: Documentation on 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 CW_KEY CCW_KEY>; +``` + +- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](/docs/behavior/key-press) for the difference between the two). +- `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_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>; +``` + +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](/docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 29045f7..50a747c 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -5,7 +5,7 @@ sidebar_label: Introduction --- ZMK Firmware is an open source (MIT) keyboard -firmware built on the [Zephyr™ Project](https://zephyrproject.com/) Real Time Operating System (RTOS). +firmware built on the [Zephyr™ Project](https://zephyrproject.org/) Real Time Operating System (RTOS). The goal is to provider a powerful, featureful keyboard firmware that is free of licensing issues that prevent upstream BLE support as a first-class diff --git a/docs/sidebars.js b/docs/sidebars.js index 7da0f5b..6bd3aa4 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -32,6 +32,8 @@ module.exports = { "dev-posix-board", "dev-tests", ], - "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"], + "Dev Guides": [ + "dev-guide-new-shield", + "dev-guide-usb-logging"], }, }; diff --git a/docs/static/setup.sh b/docs/static/setup.sh index 70defdf..5d203a4 100644 --- a/docs/static/setup.sh +++ b/docs/static/setup.sh @@ -38,7 +38,7 @@ echo "" echo "Keyboard Shield Selection:" prompt="Pick an keyboard:" -options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris") +options=("Kyria" "Lily58" "Corne" "Splitreus62" "Sofle" "Iris" "RoMac") PS3="$prompt " # TODO: Add support for "Other" and linking to docs on adding custom shields in user config repos. @@ -53,6 +53,7 @@ select opt in "${options[@]}" "Quit"; do 4 ) shield_title="Splitreus62" shield="splitreus62"; split="y"; break;; 5 ) shield_title="Sofle" shield="sofle"; split="y"; break;; 6 ) shield_title="Iris" shield="iris"; split="y"; break;; + 7 ) shield_title="RoMac" shield="romac"; split="n"; break;; # Add link to docs on adding your own custom shield in your ZMK config! # $(( ${#options[@]}+1 )) ) echo "Other!"; break;; @@ -62,6 +63,10 @@ select opt in "${options[@]}" "Quit"; do esac done +if [ "$split" == "n" ]; then + repo_path="https://github.com/zmkfirmware/zmk-config-template.git" +fi + read -e -p "Copy in the stock keymap for customization? [Yn]: " copy_keymap if [ -z "$copy_keymap" ] || [ "$copy_keymap" == "Y" ] || [ "$copy_keymap" == "y" ]; then copy_keymap="yes"; fi |