Update new keyboard templates

Updated the new keyboard templates to use Studio features such as physical layout definitions. Also updated the links to documentation for pages that have moved.
zmkfirmware · Oct 19, 2024 · e20526f · e20526f
1 parent ff153c2
commit e20526f
Show file tree

Hide file tree

Showing 30 changed files with 86 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -147,7 +147,7 @@ Run `zmk keyboard list` to print a list of supported keyboard hardware.
 
 If ZMK doesn't support your keyboard yet, you can run `zmk keyboard new` to create a new keyboard from a template.
 
-This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](https://zmk.dev/docs/development/new-shield) guide for how to finish writing the keyboard files.
+This won't walk you through all of the details of adding support for a new keyboard, but it will generate most of the boilerplate for you. See the [New Keyboard Shield](https://zmk.dev/docs/development/hardware-integration/new-shield) guide for how to finish writing the keyboard files.
 
 ## Module Management
 

diff --git a/zmk/commands/keyboard/new.py b/zmk/commands/keyboard/new.py
@@ -197,7 +197,9 @@ def keyboard_new(
     rich.print(
         "Open this folder and edit the files to finish setting up the new keyboard."
     )
-    rich.print("See https://zmk.dev/docs/development/new-shield for help.")
+    rich.print(
+        "See https://zmk.dev/docs/development/hardware-integration/new-shield for help."
+    )
 
 
 def _prompt_keyboard_type():

diff --git a/zmk/templates/board/nrf52840/board_defconfig b/zmk/templates/board/nrf52840/board_defconfig
@@ -12,7 +12,7 @@ CONFIG_ARM_MPU=y
 # Enable GPIO
 CONFIG_GPIO=y
 
-# Use pinctrl
+# Enable pinctrl
 CONFIG_PINCTRL=y
 
 # Place application at &code_partition address
@@ -29,6 +29,9 @@ CONFIG_FLASH=y
 CONFIG_FLASH_PAGE_LAYOUT=y
 CONFIG_FLASH_MAP=y
 
+# Uncomment this if not using an external 32 kHz crystal
+# CONFIG_CLOCK_CONTROL_NRF_K32SRC_RC=y
+
 # Enable ZMK BLE and USB output
 CONFIG_ZMK_BLE=y
 CONFIG_ZMK_USB=y
diff --git a/zmk/templates/board/nrf52840/common_outer.dtsi b/zmk/templates/board/nrf52840/common_outer.dtsi
@@ -14,46 +14,50 @@
     status = "okay";
 };
 
-&usbd {
-    status = "okay";
+&uart0 {
+    compatible = "nordic,nrf-uarte";
+    current-speed = <115200>;
+    pinctrl-0 = <&uart0_default>;
+    pinctrl-1 = <&uart0_sleep>;
+    pinctrl-names = "default", "sleep";
+};
 
-    cdc_acm_uart: cdc_acm_uart {
-        compatible = "zephyr,cdc-acm-uart";
-    };
+zephyr_udc0: &usbd {
+    status = "okay";
 };
 
 &flash0 {
     // Adjust this flash map as is necessary for your board. For more information, see
-    // https://docs.zephyrproject.org/latest/reference/storage/flash_map/flash_map.html
+    // https://docs.zephyrproject.org/3.6.0/services/storage/flash_map/flash_map.html#relationship-with-devicetree
     partitions {
         compatible = "fixed-partitions";
         #address-cells = <1>;
         #size-cells = <1>;
 
         code_partition: partition@1000 {
-            reg = <0x00001000 0x000d3000>;
+            reg = <DT_SIZE_K(4) DT_SIZE_K(844)>;
         };
 
         // If using a bootloader with SoftDevice included, replace the code_partition
         // node above with the following. If using SoftDevice v7, change 26000 to 27000.
 
         // sd_partition: partition@0 {
-        //     reg = <0x00000000 0x00026000>;
+        //     reg = <0x0 <DT_SIZE_K(4)>;
         // };
         // code_partition: partition@26000 {
-        //     reg = <0x00026000 0x000c6000>;
+        //     reg = <DT_SIZE_K(152) DT_SIZE_K(792)>;
         // };
 
         // The flash starting at 0x000d4000 and ending at
         // 0x000f3fff is reserved for use by the application.
 
-        // Storage partition will be used by FCB/LittleFS/NVS if enabled.
+        // Storage partition will be used by NVS if enabled.
         storage_partition: partition@d4000 {
-            reg = <0x000d4000 0x00020000>;
+            reg = <DT_SIZE_K(848) DT_SIZE_K(128)>;
         };
 
         boot_partition: partition@f4000 {
-            reg = <0x000f4000 0x0000c000>;
+            reg = <DT_SIZE_K(976) DT_SIZE_K(48)>;
         };
     };
 };
diff --git a/zmk/templates/board/nrf52840/split/${id}-layouts.dtsi b/zmk/templates/board/nrf52840/split/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />
diff --git a/zmk/templates/board/nrf52840/split/${id}.dtsi b/zmk/templates/board/nrf52840/split/${id}.dtsi
@@ -10,8 +10,7 @@
         zephyr,flash = &flash0;
         // Uncomment this if you enabled one of the "vddh" nodes below.
         // zmk,battery = &vbatt;
-        zmk,kscan = &kscan;
-        zmk,matrix_transform = &default_transform;
+        zmk,physical-layout = &default_layout;
     };
 </%block>
 <%block name="kscan">

diff --git a/zmk/templates/board/nrf52840/unibody/${id}-layouts.dtsi b/zmk/templates/board/nrf52840/unibody/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />
diff --git a/zmk/templates/board/nrf52840/unibody/${id}.dts b/zmk/templates/board/nrf52840/unibody/${id}.dts
@@ -4,7 +4,6 @@
 </%block>
 <%block name="includes">
 #include "${id}-pinctrl.dtsi"
-
 </%block>
 <%block name="chosen">
     chosen {
@@ -14,8 +13,7 @@
         zephyr,flash = &flash0;
         // Uncomment this if you enabled one of the "vddh" nodes below.
         // zmk,battery = &vbatt;
-        zmk,kscan = &kscan;
-        zmk,matrix_transform = &default_transform;
+        zmk,physical-layout = &default_layout;
     };
 </%block>
 <%block name="nodes">

diff --git a/zmk/templates/board/other/split/${id}-layouts.dtsi b/zmk/templates/board/other/split/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />
diff --git a/zmk/templates/board/other/split/${id}.dtsi b/zmk/templates/board/other/split/${id}.dtsi
@@ -1,5 +1,4 @@
 <%inherit file="/common/board_split.dtsi" />\
 <%block name="includes">
 #include "${id}-pinctrl.dtsi"
-
 </%block>
diff --git a/zmk/templates/board/other/unibody/${id}-layouts.dtsi b/zmk/templates/board/other/unibody/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />
diff --git a/zmk/templates/board/other/unibody/${id}.dts b/zmk/templates/board/other/unibody/${id}.dts
@@ -1,5 +1,4 @@
 <%inherit file="/common/board.dts" />
 <%block name="includes">
 #include "${id}-pinctrl.dtsi"
-
 </%block>
diff --git a/zmk/templates/common/board.dts b/zmk/templates/common/board.dts
@@ -1,20 +1,22 @@
 // This file was generated from a template. Edit it to match your keyboard.
 // See https://docs.zephyrproject.org/3.6.0/hardware/porting/board_porting.html
-// and https://zmk.dev/docs/development/new-shield for more instructions.
+// and https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 /dts-v1/;
 <%block name="system_includes" />
 #include <dt-bindings/zmk/matrix_transform.h>
 
 <%block name="includes" />
+#include "${id}-layouts.dtsi"
+
 / {
     model = "${name}";
     compatible = "${id}";
 
 <%block name="chosen">
     chosen {
-        zmk,kscan = &kscan;
-        zmk,matrix_transform = &default_transform;
+        zmk,physical-layout = &default_layout;
     };
 </%block>
 

diff --git a/zmk/templates/common/board_left.dts b/zmk/templates/common/board_left.dts
@@ -1,5 +1,6 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 #include "${id}.dtsi"
 #include "${id}_left-pinctrl.dtsi"

diff --git a/zmk/templates/common/board_right.dts b/zmk/templates/common/board_right.dts
@@ -1,5 +1,6 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 #include "${id}.dtsi"
 #include "${id}_right-pinctrl.dtsi"

diff --git a/zmk/templates/common/default.conf b/zmk/templates/common/default.conf
@@ -1,5 +1,6 @@
 # This file was generated from a template. Edit it to match your keyboard.
-# See https://zmk.dev/docs/development/new-shield for more instructions.
+# See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+# instructions.
 
 # This file will be copied into the user's config directory when they add this
 # keyboard. Define any Kconfig options users may frequently want to set here,

diff --git a/zmk/templates/common/hardware.zmk.yml b/zmk/templates/common/hardware.zmk.yml
@@ -1,5 +1,6 @@
 # This file was generated from a template. Edit it to match your keyboard.
-# See https://zmk.dev/docs/development/hardware-metadata-files for instructions.
+# See https://zmk.dev/docs/development/hardware-integration/hardware-metadata-files
+# for instructions.
 
 file_format: "1"
 id: ${id}
@@ -13,7 +14,8 @@ arch: ${arch}
 url: https://example.com
 
 # Add any features your keyboard supports here.
-# See https://zmk.dev/docs/development/hardware-metadata-files#features.
+# See https://zmk.dev/docs/development/hardware-integration/hardware-metadata-files#features
 features:
   - keys
+  - studio
 ${self.body()}
diff --git a/zmk/templates/common/keymap.dtsi b/zmk/templates/common/keymap.dtsi
@@ -1,12 +1,12 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more instructions.
 
 #include <behaviors.dtsi>
 #include <dt-bindings/zmk/keys.h>
 
 / {
     // Define a default keymap here.
-    // See https://zmk.dev/docs/development/new-shield#default-keymap.
+    // See https://zmk.dev/docs/development/hardware-integration/new-shield#default-keymap.
     keymap {
         compatible = "zmk,keymap";
 

diff --git a/zmk/templates/common/kscan.dtsi b/zmk/templates/common/kscan.dtsi
@@ -11,7 +11,7 @@
         wakeup-source;
 
         // Replace these comments with the GPIO pins in the matrix.
-        // See https://zmk.dev/docs/development/new-shield#shield-overlays
+        // See https://zmk.dev/docs/development/hardware-integration/new-shield#shield-overlays
         col-gpios
             = </* ${node} 0 */ GPIO_ACTIVE_HIGH>
             , </* ${node} 0 */ GPIO_ACTIVE_HIGH>

diff --git a/zmk/templates/common/kscan_split_common.dtsi b/zmk/templates/common/kscan_split_common.dtsi
@@ -12,7 +12,7 @@
         wakeup-source;
 
         // Replace these comments with the GPIO pins in the matrix.
-        // See https://zmk.dev/docs/development/new-shield#shield-overlays
+        // See https://zmk.dev/docs/development/hardware-integration/new-shield#shield-overlays
         row-gpios
             = </* ${node} 0 */ (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
             , </* ${node} 0 */ (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>

diff --git a/zmk/templates/common/kscan_split_left.dtsi b/zmk/templates/common/kscan_split_left.dtsi
@@ -1,7 +1,7 @@
 <%page args="node = '&gpio0'" />
 &kscan {
     // Replace these comments with the GPIO pins in the matrix for the left side.
-    // See https://zmk.dev/docs/development/new-shield#shield-overlays
+    // See https://zmk.dev/docs/development/hardware-integration/new-shield#shield-overlays
     col-gpios
         = </* ${node} 0 */ GPIO_ACTIVE_HIGH>
         , </* ${node} 0 */ GPIO_ACTIVE_HIGH>

diff --git a/zmk/templates/common/kscan_split_right.dtsi b/zmk/templates/common/kscan_split_right.dtsi
@@ -6,7 +6,7 @@
 
 &kscan {
     // Replace these comments with the GPIO pins in the matrix for the right side.
-    // See https://zmk.dev/docs/development/new-shield#shield-overlays
+    // See https://zmk.dev/docs/development/hardware-integration/new-shield#shield-overlays
     col-gpios
         = </* ${node} 0 */ GPIO_ACTIVE_HIGH>
         , </* ${node} 0 */ GPIO_ACTIVE_HIGH>

diff --git a/zmk/templates/common/layouts.dtsi b/zmk/templates/common/layouts.dtsi
@@ -0,0 +1,22 @@
+// See https://zmk.dev/docs/development/hardware-integration/physical-layouts
+// for how to configure this.
+
+#include <physical_layouts.dtsi>
+
+/ {
+    default_layout: default_layout {
+        compatible = "zmk,physical-layout";
+        display-name = "Default Layout";
+        transform = <&default_layout>;
+        kscan = <&kscan>;
+
+        // Edit this to define the positions and sizes of the keys
+        // https://zmk.dev/docs/development/hardware-integration/physical-layouts#optional-keys-property
+        keys  //                     w   h    x    y     rot    rx    ry
+            = <&key_physical_attrs 100 100    0    0       0     0     0>
+            , <&key_physical_attrs 100 100  100    0       0     0     0>
+            , <&key_physical_attrs 100 100    0  100       0     0     0>
+            , <&key_physical_attrs 100 100  100  100       0     0     0>
+            ;
+    };
+};
diff --git a/zmk/templates/common/matrix_transform.dtsi b/zmk/templates/common/matrix_transform.dtsi
@@ -1,5 +1,5 @@
     default_transform: default_transform {
-        // See https://zmk.dev/docs/development/new-shield#optional-matrix-transform
+        // See https://zmk.dev/docs/development/hardware-integration/new-shield#matrix-transform
         // for how to configure this
         compatible = "zmk,matrix-transform";
         columns = <2>;

diff --git a/zmk/templates/common/matrix_transform_split.dtsi b/zmk/templates/common/matrix_transform_split.dtsi
@@ -1,5 +1,5 @@
     default_transform: default_transform {
-        // See https://zmk.dev/docs/development/new-shield#optional-matrix-transform
+        // See https://zmk.dev/docs/development/hardware-integration/new-shield#matrix-transform
         // for how to configure this
         compatible = "zmk,matrix-transform";
         columns = <4>;

diff --git a/zmk/templates/common/shield.overlay b/zmk/templates/common/shield.overlay
@@ -1,15 +1,17 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 <%block name="system_includes" />
 #include <dt-bindings/zmk/matrix_transform.h>
+
 <%block name="includes" />
+#include "${id}-layouts.dtsi"
 
 / {
 <%block name="chosen">
     chosen {
-        zmk,kscan = &kscan;
-        zmk,matrix_transform = &default_transform;
+        zmk,physical-layout = &default_layout;
     };
 </%block>
 

diff --git a/zmk/templates/common/shield_left.overlay b/zmk/templates/common/shield_left.overlay
@@ -1,5 +1,6 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 #include "${id}.dtsi"
 

diff --git a/zmk/templates/common/shield_right.overlay b/zmk/templates/common/shield_right.overlay
@@ -1,5 +1,6 @@
 // This file was generated from a template. Edit it to match your keyboard.
-// See https://zmk.dev/docs/development/new-shield for more instructions.
+// See https://zmk.dev/docs/development/hardware-integration/new-shield for more
+// instructions.
 
 #include "${id}.dtsi"
 

diff --git a/zmk/templates/shield/split/${id}-layouts.dtsi b/zmk/templates/shield/split/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />
diff --git a/zmk/templates/shield/unibody/${id}-layouts.dtsi b/zmk/templates/shield/unibody/${id}-layouts.dtsi
@@ -0,0 +1 @@
+<%inherit file="/common/layouts.dtsi" />