Skip to content

docs: Add a hardware issues page under troubleshooting #2360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Oct 31, 2024
Merged

docs: Add a hardware issues page under troubleshooting #2360

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
83c102e
feat(shields): Added tester shields for pro micro and xiao form factors
nmunnich Sep 3, 2024
d6f34bb
feat(docs): Added a page on troubleshooting hardware issues.
nmunnich Sep 3, 2024
aeca7d7
Update docs/docs/troubleshooting/hardware-issues.mdx
nmunnich Sep 9, 2024
878204f
Added pinouts to tester shield section for better reference
nmunnich Sep 27, 2024
9dac026
Merge branch 'hardware-issues' of github.com:Nick-Munnich/zmk into ha…
nmunnich Sep 27, 2024
2bb7f0a
Apply suggestions from code review
nmunnich Oct 7, 2024
ba17001
Further suggestions from code review
nmunnich Oct 7, 2024
a487fc2
Added design flaw bit to antenna
nmunnich Oct 22, 2024
0b53d42
docs:additional feedback
nmunnich Oct 30, 2024
db4743d
Code review changes
nmunnich Oct 31, 2024
2d4456d
Merge branch 'main' into hardware-issues
nmunnich Oct 31, 2024
dbc6b41
Split keyboards keymap note
nmunnich Oct 31, 2024
6bf429d
Merge branch 'hardware-issues' of github.com:Nick-Munnich/zmk into ha…
nmunnich Oct 31, 2024
9b0397a
note
nmunnich Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions app/boards/shields/tester_pro_micro/Kconfig.defconfig
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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>;
};
};
};
45 changes: 45 additions & 0 deletions app/boards/shields/tester_pro_micro/tester_pro_micro.overlay
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
>;
};
};
6 changes: 6 additions & 0 deletions app/boards/shields/tester_pro_micro/tester_pro_micro.zmk.yml
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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]
Binary file added docs/docs/assets/troubleshooting/multimeter/schematic_probe_example.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/docs/troubleshooting/connection-issues.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading