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,44 @@
+#include <dt-bindings/zmk/matrix_transform.h>
+
+/ {
+    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
+            = <&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

@@ -68,6 +68,10 @@ The settings reset firmware has Bluetooth disabled to prevent the two sides from
 
 A very common issue is that the wrong Bluetooth profile has been selected, or the Bluetooth profile already has a saved connection. Learn more about Bluetooth profiles [here](../features/bluetooth.md), and learn how to adjust Bluetooth profiles via the `&bt` behavior [here](../keymaps/behaviors/bluetooth.md).
 
+### Hardware Issues
+
+For connectivity problems caused by hardware, please see [the appropriate section of the hardware issues page](hardware-issues.mdx#hardware-related-wireless-connectivity-issues).
+
 ### Additional Bluetooth Options
 
 Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular:
@@ -96,7 +100,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