summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/blog/2020-05-24-wip.md2
-rw-r--r--docs/blog/2020-08-12-zmk-sotf-1.md52
-rw-r--r--docs/docs/dev-guide-new-shield.md53
-rw-r--r--docs/docs/feature/underglow.md8
-rw-r--r--docs/docusaurus.config.js8
5 files changed, 85 insertions, 38 deletions
diff --git a/docs/blog/2020-05-24-wip.md b/docs/blog/2020-05-24-wip.md
index 2ec2956..eaf2b79 100644
--- a/docs/blog/2020-05-24-wip.md
+++ b/docs/blog/2020-05-24-wip.md
@@ -5,7 +5,7 @@ author: Pete Johanson
author_title: Project Creator
author_url: https://gitlab.com/petejohanson
author_image_url: https://www.gravatar.com/avatar/2001ceff7e9dc753cf96fcb2e6f41110
-tags: [keyboards, firmeware, oss, ble]
+tags: [keyboards, firmware, oss, ble]
---
This blog is a work-in-progress as I work on basic docs + blog on this nascent keyboard firmware.
diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md
new file mode 100644
index 0000000..2b69535
--- /dev/null
+++ b/docs/blog/2020-08-12-zmk-sotf-1.md
@@ -0,0 +1,52 @@
+---
+title: ZMK State Of The Firmware \#1
+author: Pete Johanson
+author_title: Project Creator
+author_url: https://gitlab.com/petejohanson
+author_image_url: https://www.gravatar.com/avatar/2001ceff7e9dc753cf96fcb2e6f41110
+tags: [SOTF, keyboards, firmware, oss, ble]
+---
+
+Welcome to the first ZMK "State Of The Firmware"!
+
+With interest and Discord activity growing, it seemed important to lay out the progress made recently, current major bugs/showstoppers, and planned next steps.
+
+## Recent Activity
+
+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.
+- 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.
+- 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.
+
+## Bugs and Showstoppers
+
+Despite the flurry of activity, there are still some serious bugs and show stoppers that potential ZMK users should be aware of:
+
+- [Bluetooth Related](https://github.com/zmkfirmware/zmk/issues/58) - There are several key bugs and fixes needed, including one complete show stopper:
+ - Fully working split wireless is not working. In particular, both split halves can properly pair, but once they do so, pairing with the _central_ host will not work. Workaround: You can currently have both halves pair, and use USB on the central side (Left side right now for Kyria, Corne, Lily58) and receive HID events over USB.
+ - BT bond information is not currently stored to the devices, so after powering off or restarting your device, users need to re-pair
+- USB - There is one important USB related bug which is a showstopper:
+ - The Zephyr USB stack does not have a built in queue for endpoint data being written. As a result, HID events sent by ZMK are sometimes [dropped, or lost](https://github.com/zmkfirmware/zmk/issues/84).
+
+## Next Steps
+
+There's plenty of places to go next! To help keep folks in the loop for what's next, I've created a [Core Functionality](https://github.com/zmkfirmware/zmk/projects/1) project/kanban board in GitHub, where users should be able to get some visibility into items being focused on.
+
+Of course, at the top of that list currently is the above bugs/showstoppers, and then from there, I hope to:
+
+- Work on power management.
+- Improve our documentation on various aspects of the system, mostly around:
+ - End user documentation for understanding how to use ZMK, better installation docs, etc.
+ - Developer focused documentation, so interested contributors can start building out more behaviors and ZMK functionality.
+- Implement true "hold" detection, useful for several behaviors such as Mod-Tap and Layer-Tap.
+- Hopefully acquire a proper and official USB Product ID for use for the project.
+- Fun things that come up along the way!
+
+## Thanks!
+
+A big thanks for everyone who has shown interest in the project, tested things, asked questions, and contributed PRs ([Nicell](https://github.com/Nicell), [CrossR](https://github.com/CrossR), [careyk007](https://github.com/careyk007)).
diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md
index 1119806..8556623 100644
--- a/docs/docs/dev-guide-new-shield.md
+++ b/docs/docs/dev-guide-new-shield.md
@@ -81,9 +81,9 @@ this might look something like:
;
row-gpios
- = <&pro_micro_a 1 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
- , <&pro_micro_a 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
- , <&pro_micro_a 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+ = <&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)>
;
};
};
@@ -147,51 +147,38 @@ Some important things to note:
## 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/<shield_name>/keymap/keymap.overlay` file. The keymap is configured as an additional devicetree overlay that includes the following:
+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/<shield_name>/<shield_name>.keymap` file. The keymap is configured as an additional devicetree overlay that includes the following:
-- A node with `compatible="zmk,layers"` 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).
-- A node with `compatible="zmk,keymap"` that references the layers with a `layers` phandle-array property.
-- A chosen node named `zmk,keymap` that references the defined keymap.
+- 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 nice60, with only one layer:
+Here is an example simple keymap for the Kyria, with only one layer:
```
#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
/ {
- chosen {
- zmk,keymap = &keymap0;
- };
-
- keymap0: keymap {
+ keymap {
compatible = "zmk,keymap";
- label ="Default nice!60 Keymap";
- layers = <&default>;
- };
- layers {
- compatible = "zmk,layers";
-
- default: layer_0 {
- label = "DEFAULT";
-// ------------------------------------------------------------------------------------------
-// | 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 |
-// | CTL | WIN | ALT | SPACE | ALT | WIN | MENU | CTL |
-// ------------------------------------------------------------------------------------------
+ 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 | L SHIFT | L SHIFT | | L SHIFT | L SHIFT | N | M | , | . | / | CTRL |
+// | GUI | DEL | RET | SPACE | ESC | | RET | SPACE | TAB | BSPC | R-ALT |
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 &kp FSLH &kp RSFT
- &kp LCTL &kp LGUI &kp LALT &kp SPC &kp RALT &kp RGUI &kp GUI &kp RCTL
+ &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 SCLN &kp QUOT
+ &kp LSFT &kp Z &kp X &kp C &kp V &kp B &kp LSFT &kp LSFT &kp LSFT &kp LSFT &kp N &kp M &kp CMMA &kp DOT &kp FSLH &kp RCTL
+ &kp LGUI &kp DEL &kp RET &kp SPC &kp ESC &kp RET &kp SPC &kp TAB &kp BKSP &kp RALT
>;
+
+ sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>;
};
};
};
+
```
:::note
diff --git a/docs/docs/feature/underglow.md b/docs/docs/feature/underglow.md
index 780845a..c6517ce 100644
--- a/docs/docs/feature/underglow.md
+++ b/docs/docs/feature/underglow.md
@@ -21,10 +21,12 @@ 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 `ZMK_RGB_UNDERGLOW` configuration value in the `.conf` file of your user config directory as such:
+To enable RGB underglow on your board or shield, simply enable the `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).
@@ -114,8 +116,10 @@ Once you have your `led_strip` properly defined you need to add it to the root d
};
```
-Finally you need to enable the `ZMK_RGB_UNDERGLOW` configuration value in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`):
+Finally you need to enable the `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/docs/docusaurus.config.js b/docs/docusaurus.config.js
index 44acd69..64f9a45 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -7,6 +7,10 @@ module.exports = {
organizationName: "zmkfirmware", // Usually your GitHub org/user name.
projectName: "zmk", // Usually your repo name.
themeConfig: {
+ googleAnalytics: {
+ trackingID: "UA-145201102-2",
+ anonymizeIP: true,
+ },
// sidebarCollapsible: false,
navbar: {
title: "ZMK Firmware",
@@ -101,12 +105,12 @@ module.exports = {
homePageId: "intro",
sidebarPath: require.resolve("./sidebars.js"),
// Please change this to your repo.
- editUrl: "https://githlab.com/zmkproject/zmk/edit/main/docs/",
+ editUrl: "https://github.com/zmkfirmware/zmk/edit/main/docs/",
},
blog: {
showReadingTime: true,
// Please change this to your repo.
- editUrl: "https://gitlab.com/zmkproject/zmk/edit/main/docs/blog/",
+ editUrl: "https://github.com/zmkfirmware/zmk/edit/main/docs/",
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-03 08:16:07 +0000