Purox/Hexatana-RGB
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

added Buildguide and qmk-firmware files

Browse Source
This commit is contained in:
Nico Stuhlmueller 2024-03-07 21:33:40 +01:00
parent a820d437bc
commit ee8e636586
7 changed files with 291 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
README.md Normal file
View File

@ -0,0 +1,93 @@
# Hexatana
Hexatana is a 36 katana-inspired keyboard designed around [hexagonal keycaps](https://hw.s-ol.nu/HEX-keycaps/).
![front view of keyboard](front.png)
![back view of keyboard](back.png)
# Soldering
## MCU
The first step is to solder the RP2040 to the top center of the PCB.
You can use pin headers to align the MCU on the solder pads.
The orientation if the MCU should be such that the USB-C port is on the top side of the main PCB.
The bottom side of the main PCB has six katanas printed in its center.
So to solder the MCU in place, put the main PCB on your soldering surface, such that you do not see the six katanas, place the MCU onto of the PCB such that the USB-port is facing you.
You can now optionally stabilize the MCU with pin headers and solder the MCU to the main PCB.
## Soldering in the diodes
On the top side of the PCB you will find a lot of `U`-shaped markings in with `Dx` where `x` is a number $\in {1-36,73}$ next to them
The top side of the diodes shows a vertical line followed by the letters T4, i.e. it looks like `|T4`.
The diode has to be solder to the PCB such that the vertical line is on the closed side of the `U`-marking.
Solder in all 37 diodes that way.
Diodes `D1-D36` are in the center of the PCB, diode `D73` is $\approx 4$cm right of the MCU.
## Testing the keyboard
Now the keyboard should be functional.
You can test that by plugging the keyboard into a computer and opening a text editor of your choice.
Turn the keyboard around, such that you can see the 6 katanas and grab yourself a pair of metal tweezers or a pair of scissors.
Connect two adjacent solder pads.
Now a letter should appear on your keyboard.
Repeat these steps for all solderpads connected with white paint.
In your text editor you should see the letters `a-z` and the numbers `0-9`.
If one of them didn't show up, this likely means that one of the diodes is not soldered in correctly.
When all keys work we can install the hot-swap sockets which will allow us to mount the switches.
However before we do those it is advisable to first install the optional LED-backlight.
## Backlight (optional)
### Soldering in the LEDs
It is now time to solder in the LEDs.
The PCB should be orientated such that you can see the 6 swords.
There are 36 small rectangular cutouts in the PCB (labeled `D37-D72`) in which the LEDs will be placed.
#### Orientation of the LEDs
The LEDs emit light only on one side (the one with the transparent cover).
This side needs to be placed face down, i.e. facing the table.
Now we still have one rotational degree of freedom, which we will eliminate in the following.
Just as the diodes, the light emitting diodes (LEDs) are sensitive to the orientation in which they are soldered in.
One of the metal legs of the LEDs is cut at an angle.
This leg has to be placed at the white `L`-shaped marking next to the hole for the LED.
This fixes the last rotational degree of freedom of each LED, and you can solder in the LEDs.
Be very careful with the orientation of the LEDs!
Their orientation changes when going from one row to the next row and going from the left side of the keyboard to the right side of the keyboard.
Only the thumb clusters are consistent in the orientation of the LEDs.
The LEDs are also very sensitive to temperature, so be careful when soldering them to the PCB.
### Picking a position for the solder jumper / picking a voltage for the first LED
Turn the keyboard around once more, such that you can no longer see the swords and the MCU is facing away from you.
#### Background
Approximately 3cm to the right side of the MCU you will find a solder-jumper.
It is used to pick between two possible voltages powering the first LED of the backlight.
The datalines of the backlight-LEDs are not specified to work with the 3.3V supplied by the MCU, when the LEDs are driven by (the standard) 5V.
However usually they do still work in that scenario.
The PCB implements a hack [hack](https://hackaday.com/2017/01/20/cheating-at-5v-ws2812-control-to-use-a-3-3v-data-line/) for the unlucky chance that the LEDs do not work when the data line is driven by 3.3V and the LEDs are driven by 5V.
The hack exploits the fact, that when the first LED is powered by 4.3V, 3.3V are in spec for the dataline.
The solder jumper let's you pick whether the first LED is powered by 5V or 4.3V.
I suggest you try 5V first as all LEDs will have the same brightness that way.
Powering the first LED with a lower voltage might lead to a slightly dimmer first LED.
The center pad of the jumper is connected to the power line of the LED.
The bottom pad is connected to 5V.
The top pad has a voltage of 4.3V.
The diode just above the jumper reduces the 5V to 4.3V.
#### What to do
Bridge the center and bottom pads of the jumper, and connect the keyboard to a computer.
If all LEDs light up you can go ahead to soldering in the [hotswap sockets](#installing-the-hot-swap-sockets)
If some of the LEDs light up double check the solder joints of the LED with the highest number that is lighting up and the one with the smallest number that is not lighting up. There is most likely a problem there.
An Led might also be fried by excessive heat during soldering.
If the plastic of the LED has melted, the LED is probably dead; replace it with a new one. There a four more LEDs in the kit than you need.
If no LED lights up you might be one of the (un)lucky people with an LED produced to specification. There are two options on how to proceed.
1) you can try replacing the first LED (`D37`) and see whether the LEDs light up now, or
2) remove the solder from the solder jumper on the top side of the PCB and bridge the center pad with the top pad. Now the LED is powered with 4.3V and the 3.3V on the dataline are in spec.
## Installing the hot-swap sockets
Turn the keyboard around, such that you can see the 6 swords again.
Now solder the hot-swap sockets onto the last solderpads that are not connected to anything yet.
## Installing the switches
Now turn the keyboard around one last time and install the switches and keycaps.
# Flashing Firmware
## QMK
The ncecessary files for a [QMK-firmware](qmk.fm) can be found in the firmware directory one layer up.
## ZMK
There is a basic [zmk](https://github.com/ThePurox/hexatana-zmk/) repository.
Feel free to fork it and adjust everything to your liking.

23
qmk-firmware/config.h Normal file
View File

@ -0,0 +1,23 @@
// Copyright 2024 Nico Stuhlmüller (@ThePurox)
// SPDX-License-Identifier: GPL-2.0-or-later
#pragma once
/*
* Feature disable options
* These options are also useful to firmware size reduction.
*/
/* disable debug print */
//#define NO_DEBUG
/* disable print */
//#define NO_PRINT
/* disable action features */
//#define NO_ACTION_LAYER
//#define NO_ACTION_TAPPING
//#define NO_ACTION_ONESHOT
#define WS2812_PIO_USE_PIO1 // Force the usage of PIO1 peripheral, by default the WS2812 implementation uses the PIO0 peripheral
#define WS2812_DI_PIN GP0
#define HOLD_ON_OTHER_KEY_PRESS

12
qmk-firmware/hexatana.h Normal file
View File

@ -0,0 +1,12 @@
#define LAYOUT(k00, k01, k02, k03, k04, k05, k06, k07, k08, k09,\
k10, k11, k12, k13, k14, k15, k16, k17, k18, k19,\
k20, k21, k22, k23, k24, k25, k26, k27, k28, k29,\
k30, k31, k32, k33, k34, k35) \
{ \
{k09, k07, k05, KC_NO, k03, k01, k35}, \
{k08, k06, KC_NO, k04, k02, k00, k34}, \
{k19, k17, k15, KC_NO, k13, k11, k33}, \
{k18, k16, KC_NO, k14, k12, k10, k32}, \
{k29, k27, k25, KC_NO, k23, k21, k31}, \
{k28, k26, KC_NO, k24, k22, k20, k30} \
}

78
qmk-firmware/info.json Normal file
View File

@ -0,0 +1,78 @@
{
"manufacturer": "Nico Stuhlm\u00fcller",
"keyboard_name": "hexatana",
"maintainer": "ThePurox",
"bootloader": "rp2040",
"diode_direction": "COL2ROW",
"features": {
"bootmagic": true,
"command": false,
"console": false,
"extrakey": true,
"rgblight": true,
"mousekey": true,
"nkro": true
},
"matrix_pins": {
"cols": ["GP1", "GP2", "GP3", "GP29", "GP27", "GP28", "GP26"],
"rows": ["GP4", "GP8", "GP9", "GP15", "GP10", "GP12"]
},
"processor": "RP2040",
"url": "",
"usb": {
"device_version": "1.0.0",
"pid": "0x0000",
"vid": "0xFEED"
},
"rgblight" : {
"pin": "GP0",
"led_count" : 36,
"sleep" : false,
"animations": {
"rainbow_mood" : true,
"rainbow_swirl" : true,
},
},
"layouts": {
"LAYOUT_hexatana_7x6": {
"layout": [
{ "matrix": [0, 0], "x": 0, "y": 0 },
{ "matrix": [0, 1], "x": 2, "y": 0 },
{ "matrix": [0, 2], "x": 4, "y": 0 },
{ "matrix": [0, 4], "x": 6, "y": 0 },
{ "matrix": [0, 5], "x": 8, "y": 0 },
{ "matrix": [0, 6], "x": 0, "y": 3 },
{ "matrix": [1, 0], "x": 1, "y": 0 },
{ "matrix": [1, 1], "x": 3, "y": 0 },
{ "matrix": [1, 3], "x": 5, "y": 0 },
{ "matrix": [1, 4], "x": 7, "y": 0 },
{ "matrix": [1, 5], "x": 9, "y": 0 },
{ "matrix": [1, 6], "x": 1, "y": 3 },
{ "matrix": [2, 0], "x": 0, "y": 1 },
{ "matrix": [2, 1], "x": 2, "y": 1 },
{ "matrix": [2, 2], "x": 4, "y": 1 },
{ "matrix": [2, 4], "x": 6, "y": 1 },
{ "matrix": [2, 5], "x": 8, "y": 1 },
{ "matrix": [2, 6], "x": 2, "y": 3 },
{ "matrix": [3, 0], "x": 1, "y": 1 },
{ "matrix": [3, 1], "x": 3, "y": 1 },
{ "matrix": [3, 3], "x": 5, "y": 1 },
{ "matrix": [3, 4], "x": 7, "y": 1 },
{ "matrix": [3, 5], "x": 9, "y": 1 },
{ "matrix": [3, 6], "x": 3, "y": 3 },
{ "matrix": [4, 0], "x": 0, "y": 2 },
{ "matrix": [4, 1], "x": 2, "y": 2 },
{ "matrix": [4, 2], "x": 4, "y": 2 },
{ "matrix": [4, 4], "x": 6, "y": 2 },
{ "matrix": [4, 5], "x": 8, "y": 2 },
{ "matrix": [4, 6], "x": 4, "y": 3 },
{ "matrix": [5, 0], "x": 1, "y": 2 },
{ "matrix": [5, 1], "x": 3, "y": 2 },
{ "matrix": [5, 3], "x": 5, "y": 2 },
{ "matrix": [5, 4], "x": 7, "y": 2 },
{ "matrix": [5, 5], "x": 9, "y": 2 },
{ "matrix": [5, 6], "x": 5, "y": 3 }
]
}
}
}

56
qmk-firmware/keymaps/default/keymap.c Normal file
View File

@ -0,0 +1,56 @@
// Copyright 2023 QMK
// SPDX-License-Identifier: GPL-2.0-or-later
#include QMK_KEYBOARD_H
#include "keymap_german.h"
#define SYM LT(2, KC_ENT)
#define TAB_NUM LT(1, KC_TAB)
#define SPC_SPE LT(3, KC_SPC)
#define ALT_BSPC MT(MOD_LALT, KC_BSPC)
#define GUI_ESC MT(MOD_LGUI, KC_ESC)
#define OSS OSM(MOD_RSFT)
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/* [0] = LAYOUT( */
/* KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Z, KC_U, KC_I, KC_O, KC_P, */
/* KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_ENT, */
/* KC_Y, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_DOT, KC_2, KC_3, */
/* KC_4, KC_5, KC_SPC, KC_ENT, KC_8, KC_9 */
/* ) */
[0] = LAYOUT(
KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P,
KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, OSS,
KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH,
KC_LCTL, GUI_ESC, SPC_SPE, SYM, TAB_NUM, ALT_BSPC
),
[1] = LAYOUT(
KC_F1, KC_F2, KC_F3, KC_F4, XXXXXXX, DE_PLUS, KC_1, KC_2, KC_3, DE_MINS,
KC_F5, KC_F6, KC_F7, KC_F8, XXXXXXX, KC_0, KC_4, KC_5, KC_6, DE_DOT,
KC_F9, KC_F10, KC_F11, KC_F12, XXXXXXX, DE_ASTR, KC_7, KC_8, KC_9, DE_SLSH,
KC_LCTL, KC_LGUI, KC_SPC, _______, MO(3), KC_LALT
),
[2] = LAYOUT(
XXXXXXX, XXXXXXX, DE_LBRC, DE_RBRC, DE_ACUT, DE_EXLM, DE_QUOT, DE_DQUO, DE_CIRC, DE_PERC,
DE_BSLS, XXXXXXX, DE_LPRN, DE_RPRN, DE_TILD, DE_EQL, DE_PLUS, DE_MINS, DE_ASTR, DE_SLSH,
XXXXXXX, XXXXXXX, DE_LCBR, DE_RCBR, XXXXXXX, DE_QUES, DE_LABK, DE_RABK, DE_PIPE, DE_TILD,
KC_LCTL, KC_LGUI, KC_SPC, MO(3), _______, KC_LALT
),
[3] = LAYOUT(
DE_AT, XXXXXXX, DE_EURO, XXXXXXX, XXXXXXX, XXXXXXX, DE_UDIA, XXXXXXX, DE_ODIA, XXXXXXX,
DE_ADIA, DE_SS, RGB_HUI, RGB_SAI, RGB_VAI, KC_LEFT, KC_DOWN, KC_UP,KC_RIGHT, XXXXXXX,
RGB_MOD, RGB_TOG, RGB_HUD, RGB_SAD, RGB_VAD, KC_HOME, KC_PGDN, KC_PGUP, KC_END, XXXXXXX,
KC_LCTL, KC_LGUI, KC_SPC, KC_ENT, _______, KC_LALT
)
};
const uint16_t PROGMEM bspc_comb[] = {KC_U, KC_I, COMBO_END};
const uint16_t PROGMEM cbspc_comb[] = {KC_U, KC_O, COMBO_END};
const uint16_t PROGMEM del_comb[] = {KC_I, KC_O, COMBO_END};
combo_t key_combos[] = {COMBO(bspc_comb, KC_BSPC), COMBO(cbspc_comb, LCTL(KC_BSPC)), COMBO(del_comb, KC_DEL)};
uint16_t COMBO_LEN = sizeof(key_combos) / sizeof(*key_combos);

27
qmk-firmware/readme.md Normal file
View File

@ -0,0 +1,27 @@
# hexatana
![hexatana](imgur.com image replace me!)
*A short description of the keyboard/project*
* Keyboard Maintainer: [Nico Stuhlmüller](https://github.com/ThePurox)
* Hardware Supported: *The PCBs, controllers supported*
* Hardware Availability: *Links to where you can find this hardware*
Make example for this keyboard (after setting up your build environment):
make hexatana:default
Flashing example for this keyboard:
make hexatana:default:flash
See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
## Bootloader
Enter the bootloader in 3 ways:
* **Bootmagic reset**: Hold down the key at (0,0) in the matrix (usually the top left key or Escape) and plug in the keyboard
* **Physical reset button**: Briefly press the button on the back of the PCB - some may have pads you must short instead
* **Keycode in layout**: Press the key mapped to `QK_BOOT` if it is available

2
qmk-firmware/rules.mk Normal file
View File

@ -0,0 +1,2 @@
WS2812_DRIVER = vendor
COMBO_ENABLE = yes