# Hexatana Hexatana is a 36 katana-inspired keyboard designed around [hexagonal keycaps](https://hw.s-ol.nu/HEX-keycaps/). ![front view of keyboard](front.jpeg) # 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 There exist two versions of the PCB, one has silkscreen marking for the orientation of the diodes, in the other one the shape of the solderpads indicates the direction of the diodes. ### silkscreen marking 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. A soldered diode should look like the one in the following picture. ![picture of a soldered diode](diodes.webp) Solder in all 37 diodes that way. Diodes `D1-D36` are in the center of the PCB, diode `D73` is $\approx 4\,\mathrm{cm}$ right of the MCU. ### Solderpad marking To clean up the PCB the silkscreen markings for the diodes were removed. The diodes shall be soldered in to the footprints were one pad is rectangular, and the other pad is pentagonal. The pointy bit of the pentagon points to the kathode. I.e. the line marking on the diode need to be soldered to the rectangular pad. The right direction is shown in the following picture. ![picture of how to solder diodes](diodes-footprint.webm) Solder in all 37 diodes. 36 Diodes are in the center of the PCB, the final diode is $\approx 4\,\mathrm{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. A key press corresponding to the following keymap should be registered ``` q w e r t z u i o p a s d f g h j k l OSS y x c v b n m , . - CTRL ESC TAB ALT SPACE ENTER ``` , where `OSS` is one-shot-shift. Note the keymap presented here is show with the keyboard in its natural orientation. You are probably holding it the other way round so you should a mirrored keymap. 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 $3\,\mathrm{cm}$ 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 stabilising capacitors (very optional) There are 6 spots for capacitors next to the outer most switches of the top three key-rows. The capacitors can be soldered onto the PCB to stabilise the power of the LEDs, however everything should work without them. ## 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](https://qmk.fm) can be found in the [firmware directory](./qmk-firmware). ## VIAL [Exen904](https://github.com/exen904) was so kind and build a [VIAL](https://get.vial.today/) firmware which can be found [here](https://github.com/exen904/vial-qmk/tree/exen904/keyboards/purox/hexatana) ## ZMK There is a basic [zmk](https://github.com/ThePurox/hexatana-zmk/) repository. Feel free to fork it and adjust everything to your liking.