Skip to content

Commit

Permalink
docs: Add a hardware issues page under troubleshooting (zmkfirmware#2360
Browse files Browse the repository at this point in the history
)

Co-authored-by: Cem Aksoylar <[email protected]>
Co-authored-by: Anant Thazhemadam <[email protected]>
Co-authored-by: Less/Rikki <[email protected]>
  • Loading branch information
4 people authored and EnotionZ committed Nov 6, 2024
1 parent 84c03aa commit a425356
Show file tree
Hide file tree
Showing 14 changed files with 457 additions and 1 deletion.
12 changes: 12 additions & 0 deletions app/boards/shields/tester_pro_micro/Kconfig.defconfig
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions app/boards/shields/tester_pro_micro/Kconfig.shield
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
config SHIELD_TESTER_PRO_MICRO
def_bool $(shields_list_contains,tester_pro_micro)
61 changes: 61 additions & 0 deletions app/boards/shields/tester_pro_micro/tester_pro_micro.keymap
Original file line number Diff line number Diff line change
@@ -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>;
};
};
};
44 changes: 44 additions & 0 deletions app/boards/shields/tester_pro_micro/tester_pro_micro.overlay
Original file line number Diff line number Diff line change
@@ -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)
>;
};
};
6 changes: 6 additions & 0 deletions app/boards/shields/tester_pro_micro/tester_pro_micro.zmk.yml
Original file line number Diff line number Diff line change
@@ -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]
12 changes: 12 additions & 0 deletions app/boards/shields/tester_xiao/Kconfig.defconfig
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions app/boards/shields/tester_xiao/Kconfig.shield
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
config SHIELD_TESTER_XIAO
def_bool $(shields_list_contains,tester_xiao)
47 changes: 47 additions & 0 deletions app/boards/shields/tester_xiao/tester_xiao.keymap
Original file line number Diff line number Diff line change
@@ -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>;
};
};
};
35 changes: 35 additions & 0 deletions app/boards/shields/tester_xiao/tester_xiao.overlay
Original file line number Diff line number Diff line change
@@ -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)
>;
};
};
6 changes: 6 additions & 0 deletions app/boards/shields/tester_xiao/tester_xiao.zmk.yml
Original file line number Diff line number Diff line change
@@ -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]
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 5 additions & 1 deletion docs/docs/troubleshooting/connection-issues.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit a425356

Please sign in to comment.