docs: Add a hardware issues page under troubleshooting

app/boards/shields/tester_pro_micro/Kconfig.defconfig

@@ -0,0 +1,12 @@
+if SHIELD_TESTER_PRO_MICRO
+
+config ZMK_KEYBOARD_NAME
+    default "ZMK Tester"
+
+config ZMK_BLE
+    def_bool n
+
+config SETTINGS
+    def_bool n
+
+endif

app/boards/shields/tester_pro_micro/Kconfig.shield

@@ -0,0 +1,2 @@
+config SHIELD_TESTER_PRO_MICRO
+    def_bool $(shields_list_contains,tester_pro_micro)

app/boards/shields/tester_pro_micro/tester_pro_micro.keymap

@@ -0,0 +1,61 @@
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+
+#define PIN_MACRO(name, pin) \
+/ { \
+    macros { \
+        name: name { \
+            compatible = "zmk,behavior-macro"; \
+            wait-ms = <5>; \
+            tap-ms = <5>; \
+            #binding-cells = <0>; \
+            bindings = <&kp P &kp I &kp N &kp SPACE>, pin, <&kp ENTER>; \
+        }; \
+    }; \
+};
+
+PIN_MACRO(pin0, <&kp N0>)
+PIN_MACRO(pin1, <&kp N1>)
+PIN_MACRO(pin2, <&kp N2>)
+PIN_MACRO(pin3, <&kp N3>)
+PIN_MACRO(pin4, <&kp N4>)
+PIN_MACRO(pin5, <&kp N5>)
+PIN_MACRO(pin6, <&kp N6>)
+PIN_MACRO(pin7, <&kp N7>)
+PIN_MACRO(pin8, <&kp N8>)
+PIN_MACRO(pin9, <&kp N9>)
+PIN_MACRO(pin10, <&kp N1 &kp N0>)
+PIN_MACRO(pin14, <&kp N1 &kp N4>)
+PIN_MACRO(pin15, <&kp N1 &kp N5>)
+PIN_MACRO(pin16, <&kp N1 &kp N6>)
+PIN_MACRO(pin18, <&kp N1 &kp N8>)
+PIN_MACRO(pin19, <&kp N1 &kp N9>)
+PIN_MACRO(pin20, <&kp N2 &kp N0>)
+PIN_MACRO(pin21, <&kp N2 &kp N1>)
+
+/ {
+    keymap {
+        compatible = "zmk,keymap";
+
+        default_layer {
+            bindings = <&pin0
+                        &pin1
+                        &pin2
+                        &pin3
+                        &pin4
+                        &pin5
+                        &pin6
+                        &pin7
+                        &pin8
+                        &pin9
+                        &pin10
+                        &pin14
+                        &pin15
+                        &pin16
+                        &pin18
+                        &pin19
+                        &pin20
+                        &pin21>;
+        };
+    };
+};

app/boards/shields/tester_pro_micro/tester_pro_micro.overlay

@@ -0,0 +1,45 @@
+#include <dt-bindings/zmk/matrix_transform.h>
+
+/ {
+    chosen {
+        zmk,kscan = &kscan0;
+        zmk,matrix-transform = &transform0;
+    };
+
+    kscan0: kscan {
+        compatible = "zmk,kscan-gpio-direct";
+        toggle-mode;
+        wakeup-source;
+        debounce-press-ms = <10>;
+        debounce-release-ms = <10>;
+        input-gpios
+            = <&pro_micro 0 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 1 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 5 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 6 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 7 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 8 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 9 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 10 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 14 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 15 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 16 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 18 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 19 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 20 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&pro_micro 21 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            ;
+    };
+
+    transform0: keymap_transform {
+        compatible = "zmk,matrix-transform";
+        columns = <18>;
+        rows = <1>;
+        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(0,14)  RC(0,15)  RC(0,16)  RC(0,17)
+        >;
+    };
+};

app/boards/shields/tester_pro_micro/tester_pro_micro.zmk.yml

@@ -0,0 +1,6 @@
+file_format: "1"
+id: tester_pro_micro
+name: TesterProMicro
+type: shield
+url: https://zmk.dev/docs/troubleshooting/hardware-issues
+requires: [pro_micro]

app/boards/shields/tester_xiao/Kconfig.defconfig

@@ -0,0 +1,12 @@
+if SHIELD_TESTER_XIAO
+
+config ZMK_KEYBOARD_NAME
+    default "ZMK Tester"
+
+config ZMK_BLE
+    def_bool n
+
+config SETTINGS
+    def_bool n
+
+endif

app/boards/shields/tester_xiao/Kconfig.shield

@@ -0,0 +1,2 @@
+config SHIELD_TESTER_XIAO
+    def_bool $(shields_list_contains,tester_xiao)

app/boards/shields/tester_xiao/tester_xiao.keymap

@@ -0,0 +1,47 @@
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+
+#define PIN_MACRO(name, pin) \
+/ { \
+    macros { \
+        name: name { \
+            compatible = "zmk,behavior-macro"; \
+            wait-ms = <5>; \
+            tap-ms = <5>; \
+            #binding-cells = <0>; \
+            bindings = <&kp P &kp I &kp N &kp SPACE>, pin, <&kp ENTER>; \
+        }; \
+    }; \
+};
+
+PIN_MACRO(pin0, <&kp N0>)
+PIN_MACRO(pin1, <&kp N1>)
+PIN_MACRO(pin2, <&kp N2>)
+PIN_MACRO(pin3, <&kp N3>)
+PIN_MACRO(pin4, <&kp N4>)
+PIN_MACRO(pin5, <&kp N5>)
+PIN_MACRO(pin6, <&kp N6>)
+PIN_MACRO(pin7, <&kp N7>)
+PIN_MACRO(pin8, <&kp N8>)
+PIN_MACRO(pin9, <&kp N9>)
+PIN_MACRO(pin10, <&kp N1 &kp N0>)
+
+/ {
+    keymap {
+        compatible = "zmk,keymap";
+
+        default_layer {
+            bindings = <&pin0
+                        &pin1
+                        &pin2
+                        &pin3
+                        &pin4
+                        &pin5
+                        &pin6
+                        &pin7
+                        &pin8
+                        &pin9
+                        &pin10>;
+        };
+    };
+};

app/boards/shields/tester_xiao/tester_xiao.overlay

@@ -0,0 +1,35 @@
+/ {
+    chosen {
+        zmk,kscan = &kscan0;
+        zmk,matrix-transform = &transform0;
+    };
+
+    kscan0: kscan {
+        compatible = "zmk,kscan-gpio-direct";
+        wakeup-source;
+        debounce-press-ms = <10>;
+        debounce-release-ms = <10>;
+        input-gpios
+            = <&xiao_d 0 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 1 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 3 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 4 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 5 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 6 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 7 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 8 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 9 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            , <&xiao_d 10 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>
+            ;
+    };
+
+    transform0: keymap_transform {
+        compatible = "zmk,matrix-transform";
+        columns = <11>;
+        rows = <1>;
+        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)
+        >;
+    };
+};

app/boards/shields/tester_xiao/tester_xiao.zmk.yml

@@ -0,0 +1,6 @@
+file_format: "1"
+id: tester_xiao
+name: TesterXiao
+type: shield
+url: https://zmk.dev/docs/troubleshooting/hardware-issues
+requires: [seeed_xiao]

docs/docs/troubleshooting/connection-issues.mdx

@@ -125,7 +125,7 @@ Other microcontrollers may have similar configuration options [found in the Zeph
 
 ### Unreliable/Weak Connection
 
-Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
+Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a [metal enclosure on the keyboard or host](hardware-issues.mdx#antenna), or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such:
 
 ```ini
 CONFIG_BT_CTLR_TX_PWR_PLUS_8=y