# 1. Introduction

TaikoHub dactyl manuform keyboard layout

## 1.1 Welcome👋

Thank you for purchasing a [TaikoHub dactyl manuform keyboard](https://taikohub.com/). This user guide will be continuously updated. If you have any questions, please email me anytime at <david@taikohub.com>. I will try to get back to you as soon as I can.

Please make sure you selected the correct keyboard version on the left. Version refers to the date of shipment. For example, Version 2021-06-24 refers to any keyboard shipped from 2021-06-24 to 2021-09-11. Version 2024-05-01, the most current version, refers to any keyboards shipped after 2025-05-01.

If you are confused about anything or have suggestions on how to improve the documentation, please share it in the GitHub discussions page [here](https://github.com/taikohub/dactyl-manuform-documentation/discussions/categories/general).

## 1.2 Getting started

1. Your keyboard should work without any configurations.&#x20;
2. Connect the audio cord to each side of the keyboard.
3. Connect the USB cord to the **left side** of the keyboard.
4. Your keyboard comes pre-flashed with the default keyboard layout seen in sections 1.1 to 1.3 below.
5. The rest of the documentation discusses how to customize the keyboard. Please read it before customizing the keyboard!

{% hint style="success" %}
Please read the relevant section in the documentation before you customize the keyboard.
{% endhint %}

{% hint style="warning" %}
Avoid disconnecting and connecting the audio cord while it is connected to a power source.
{% endhint %}

## 1.3 Keyboard layout

{% hint style="info" %}
The MO(1) and MO(2) keys seen in the keyboard layouts in section 1.2 below are also known as LOWER and RAISE keys. These function similar to a SHIFT key on a regular keyboard.
{% endhint %}

### 1.3.1 Default keyboard layout for size large (6 keyed thumb cluster)

<figure><img src="/files/-Md0KCzsDDH0pg_LX1_y" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap.</p></figcaption></figure>

<figure><img src="/files/-Md0KELhTFH-ARglV0aQ" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/-Md0KR5B1hIf_acfZgZC" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>

### 1.3.2 Default keyboard layout for size medium (5 keyed thumb cluster)

<figure><img src="/files/rOSB0UP2OPlpYhBoA9vv" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap. If your 5 keyed thumb cluster keyboard was shipped July 12, 2022 or later, it will have the keyboard layout shown above. For keyboards shipped prior to July 12, 2022, please see section 9. CHANGELOG.</p></figcaption></figure>

<figure><img src="/files/-MjLrlbqzXY8Q2oClvfp" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/-MjLroWFPagghsVut7fV" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>

### 1.3.3 Default keyboard layout for size small (3 keyed thumb cluster)

<figure><img src="/files/ZN12m1CR8mr2nqF3koZ1" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap.</p></figcaption></figure>

<figure><img src="/files/vmUwRtUN7bwpmIoKBioS" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/qEfd0kFTG3JjOlM7daa9" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>


# 2. About Your Keyboard

Keycaps and keyswitches compatible with dactyl manuform

### 2.1 Compatible keycaps

Compatible keycap profiles (keycap shapes): DSA, XDA, SA Row 3 and MA. The keyboard comes with DSA keycaps.

Keycaps that are 1u in size will fit every key on every keyboard.&#x20;

There is the option to use 1.5u sized keycaps for the 6-keyed thumb cluster, which is able to fit two 1.5u keys on each side of the keyboard. The 3-keyed thumb cluster is also able to fit three 1.5u keys on each side.  The 5-keyed thumb cluster does not fit any 1.5u keys.

### 2.2 Compatible keyswitches for hotswapping

The keyboard is best used with **5 legged switches** (Figure 2.1) although 3 legged switches should still work, it's not officially supported. It is compatible with **MX Cherry switches,** Gateron switches, Holy Panda switches and other similar MX style switches.

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

<figure><img src="/files/-Md-CCTxdBbmadiex9Ln" alt="five-leg-keyswitches-work-best-with-taiko-dactyl-keyboard"><figcaption><p>Figure 2.1. 5-leg keyswitches are preferred.</p></figcaption></figure>


# 3. Customizing Keyboard Layout for Windows and Mac with QMK

How to flash dactyl manuform on Windows and Mac with QMK

### 3.1 ✨Instructions

This section uses QMK Toolbox, a GUI (graphical user interface) compatible with Mac and Windows. The QMK CLI (command line interface) is also compatible with Mac and Windows. But if you are not familiar with programming, you should follow this section instead.

{% hint style="warning" %}
QMK Toolbox currently does not support Linux. See [Section 4](/customizing-keyboard-layout-for-linux-with-qmk) instead.
{% endhint %}

{% hint style="info" %}
For troubleshooting with QMK Toolbox, see [Section 9.1](/troubleshooting/qmk-toolbox).
{% endhint %}

<mark style="color:yellow;">`Text in this format and color refers to something you can click on.`</mark>

> Text in block quotes refers to text output from QMK Toolbox.

### 3.2 🪄[QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) - Customize Your Keyboard Layout

<figure><img src="/files/-MdNZAzBYbrwRHKUSYw6" alt="Dactyl Manuform QMK Tutorial for Windows and Mac Step 1"><figcaption><p>Figure 3.1. QMK Configurator. Letters A to H refer to each step in this section.</p></figcaption></figure>

Navigate to QMK Configurator. Steps A to H in Figure 3.1 above refer to each step in this section.

&#x20;

**Step A.** Click the <mark style="color:yellow;">`Keyboard`</mark> dropdown. Select <mark style="color:yellow;">`handwired/dactyl_manuform/5x6`</mark>.&#x20;

**Step B.** Enter the name you want to give your layout. For example, if you put <mark style="color:yellow;">my\_keymap</mark>, QMK will later generate a file with the name <mark style="color:yellow;">`handwired_dactyl_manuform_5x6_my_keymap.hex`</mark>.

<details>

<summary>Step C. keymap.json - Save your progress (Optional)</summary>

If you're not fully done customizing your keymap, the keymap.json file is a way to save your progress. You can return to your save point by uploading the keymap.json file to QMK Configurator. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

</details>

<details>

<summary>Step D. keymap.json - Load previous save point (Optional)</summary>

As described in the previous step, this gives you the option to upload the keymap.json file to return to your save point.

</details>

**Step E.** This section in Figure 3.1 highlights the keyboard layout.

**Step F.** Try dragging the <mark style="color:yellow;">`F1`</mark> keycode onto <mark style="color:yellow;">`End`</mark> on the keyboard layout. This changes that switch on the layout from <mark style="color:yellow;">`End`</mark> to <mark style="color:yellow;">`F1`</mark>. You likely won't want that button to be <mark style="color:yellow;">`F1`</mark>. Change it back by finding <mark style="color:yellow;">`End`</mark> in the keycode section and drag it to replace <mark style="color:yellow;">`F1`</mark>. Now that you're familiar with this, feel free to customize your keyboard layout.&#x20;

The sections below refer to a specific QMK functionality called layers, which is not found in a traditional keyboard. If this is not important to you, feel free to skip to part G.

<details>

<summary>Layers - What are they?</summary>

Layers are a QMK specific functionality. The concept is similar to the Fn or FnLock key that is seen on some keyboards.

If you are coming from a traditional keyboard, the easiest way to understand layers is to interact with it. In Figure 3.1, Layer 0 is selected. Try clicking on layer 1, 2, or others. Clicking on a different layer will bring up a different layout.

</details>

<details>

<summary>Layer keys - What are they?</summary>

Pressing a layer key switches the layout a different layer.&#x20;

1\. MO(layer)

In Figure 3.1, the layer keys look like <mark style="color:yellow;">`MO(1)`</mark> or <mark style="color:yellow;">`MO(2)`</mark>. This <mark style="color:yellow;">`MO(layer)`</mark> stands for momentarily activating the layer. This works similar to the Fn or Shift key on a regular keyboard.&#x20;

If you used a keyboard flashed with the keymap seen in Figure 3.1, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.

2\. DF(layer)

`DF(layer)` stands for default layer. It is similar to the FnLock key seen on some keyboards.

Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

</details>

**Step G.** When you are finished customizing your layout, click <mark style="color:yellow;">`Compile`</mark>. You should see a nice rotating potato baking in outerspace. Once this is done, the <mark style="color:yellow;">`Download Firmware`</mark> button should no longer be gray.

**Step H.** Click <mark style="color:yellow;">`Download Firmware`</mark>. It will download a file with a name similar to `handwired_dactyl_manuform_5x6_your_keymap.hex`. You will use this to flash your keyboard. You are ready to go to part 3.3.&#x20;

### 3.3 🛠️[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) - Download the Keyboard Layout Installation Tool

<figure><img src="/files/0zZzewjKPAMEDsMViCV2" alt="Dactyl Manuform QMK Tutorial for Windows and Mac Step 2"><figcaption><p>Figure 3.2. QMK Toolbox website navigation. The photo was taken when the latest version was 0.0.21. The latest version is now 0.3.2. The instructions remain the same.</p></figcaption></figure>

**Step A.** Go to the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) website. Check that you are looking at the latest release. In the photo above, the latest version was 0.3.3. The latest release as of this writing is 0.3.3. If you see a version with the name "Latest Beta", ignore it and scroll down to the next latest version.

**Step B.** Click to download <mark style="color:yellow;">`qmk_toolbox.pkg`</mark> if you use Mac.

**Step C.** Click to download <mark style="color:yellow;">`qmk_toolbox.exe`</mark> if you use Windows.

### 3.4 🛠️QMK Toolbox - Add Keyboard Layout to the Installation Tool

Open <mark style="color:yellow;">`qmk_toolbox.pkg`</mark>  or <mark style="color:yellow;">`qmk_toolbox.exe`</mark>. If you are opening QMK Toolbox for the first time, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select <mark style="color:yellow;">`Yes`</mark>.

<figure><img src="/files/-MdNxdKlCeYcwbzJyJDP" alt="Dactyl Manuform QMK Tutorial for Windows and Mac Step 3"><figcaption><p>Figure 3.3. QMK Toolbox Navigation</p></figcaption></figure>

**Step A.** If this is your first time using QMK Toolbox on your computer **and you did NOT see the install drivers dialogue box**, go to <mark style="color:yellow;">`Tool`</mark> then <mark style="color:yellow;">`Install Drivers`</mark>. If you do not see it there, move your cursor to the whitespace at the bottom of QMK Toolbox, right click with your mouse and install drivers.

**Step B.** Click <mark style="color:yellow;">`Open`</mark>. Select the <mark style="color:yellow;">`handwired_dactyl_manuform_5x6_your_keymap_name.hex`</mark> file that was downloaded earlier.

**Step C.** Make sure the dropdown menu shows <mark style="color:yellow;">`Atmega32U4`</mark>.

**Step D.** Check off <mark style="color:yellow;">`Auto-Flash`</mark>. **DO NOT click Flash just yet!**

### 3.5 🖥️Keyboard - Install the Keyboard Layout

**Step A.** Before you click Flash, ensure:

* [ ] The audio cord is not connected to the keyboard. The audio port is indicated by the blue arrow in Figure 3.5 below.
* [ ] One piece of the keyboard is connected to your computer via USB cord.

**Step B.** Click <mark style="color:yellow;">`Flash`</mark>. The toolbox will wait for you as you perform the next step.

**Step C.** Click the reset button indicated by the green arrow in Figure 3.5.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="Dactyl Manuform QMK Tutorial for Windows and Mac Step 4"><figcaption><p>Figure 3.5 The green arrow indicates the reset switch. The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

If it flashes correctly, you should see the following.

> Attempting to flash, please don't remove device
>
> avrdude.exe -p atmega32u4 -c avr109 -U flash:w:"C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6.hex":i -P COM6
>
> Connecting to programmer: . Found programmer: Id = "CATERIN"; type = S Software Version = 1.0; No Hardware Version given. Programmer supports auto addr increment. Programmer supports buffered memory access with buffersize=128 bytes.
>
> Programmer supports the following devices: Device code: 0x44
>
> avrdude.exe: AVR device initialized and ready to accept instructions
>
> Reading | ################################################## | 100% 0.00s
>
> avrdude.exe: Device signature = 0x1e9587 (probably m32u4) avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed To disable this feature, specify the -D option. avrdude.exe: erasing chip avrdude.exe: reading input file "C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6.hex" avrdude.exe: writing flash (19424 bytes):
>
> Writing | ################################################## | 100% 1.47s
>
> avrdude.exe: 19424 bytes of flash written avrdude.exe: verifying flash memory against C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex: avrdude.exe: load data flash data from input file C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex: avrdude.exe: input file C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex contains 19424 bytes avrdude.exe: reading on-chip flash data:
>
> Reading | ################################################## | 100% 0.16s
>
> avrdude.exe: verifying ... avrdude.exe: 19424 bytes of flash verified
>
> avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
>
> avrdude.exe done. Thank you.
>
> Flash complete

### 3.6 🖥️Keyboard - Repeat For the Other Piece of the Keyboard

Repeat section 3.5 for the other piece of your keyboard.

### 3.7 🥳Good Work! You Did It!🎉

* Reconnect the two pieces with the audio cord. The sockets for the audio cord are shown by the blue arrow in Figure 3.4.&#x20;
* Connect the USB cord from the **left** keyboard to the computer.&#x20;
* Good work, you did it 🎉!


# 4. Customizing Keyboard Layout for Linux with QMK

How to flash dactyl manuform on Linux with QMK

### 4.1 ✨Instructions

This section uses QMK CLI, a CLI tool compatible with Linux, Mac and Windows

{% code lineNumbers="true" %}

```
Text in code block refers to what is typed into the terminal.
Enter one line at a time.
```

{% endcode %}

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

### 4.2 ⚡QMK CLI - Installing the CLI Tool

Before installing the QMK CLI, make sure you install Python first. Take a look at the [Hitchhiker's Guide to Python](https://docs.python-guide.org/starting/install3/linux/) for how to do this.

Once Python has been installed, enter the commands below to install the QMK CLI.

{% code lineNumbers="true" %}

```bash
python3 -m pip install --user qmk 
qmk setup
```

{% endcode %}

### 4.3 ⚡QMK CLI - Test Run the CLI Tool

You can test that QMK CLI is working properly by compiling one of the default keymaps that came with the installation. For instance, we can test clueboard/66/rev3 as below.

{% code lineNumbers="true" %}

```bash
qmk compile -kb clueboard/66/rev3 -km default
```

{% endcode %}

You should see a message similar to below.

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

### 4.4 ⚡QMK CLI - Creating a Custom Keymap

{% code lineNumbers="true" %}

```bash
qmk new-keymap -kb handwired/dactyl_manuform/5x6
```

{% endcode %}

You'll then be prompted to give a name to the keymap. Here I give it the name `taiko`.&#x20;

### 4.5 [📝Keymap  - Editing keymap.c](https://github.com/taikohub/dactyl-keyboard-keymap)

Edit the keymap.c file with your preferred editor. Here I use nano.

{% code lineNumbers="true" %}

```bash
nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/taiko/keymap.c
```

{% endcode %}

While editing your keymap.c, you may wish to look at the following:

<details>

<summary>Example keymap.c - Size Medium (Five Keyed Thumb Cluster)</summary>

Below is an example of a keymap.c file for the size medium keyboard, also known as the five keyed thumb cluster. This file is also available on GitHub [here](https://github.com/taikohub/dactyl-keyboard-keymap).

{% code title="keymap.c" %}

```clike
//This is an example of a keymap.c file for the Taikohub dactyl manuform keyboard with five keyed thumb cluster (size medium).
//
//1. A blank key with no function is indicated by 7 underscores: `________`.
//
//2. The `[_QWERTY]` layer is the default layer.
//
//3. Take note of where the `________` are in the `[_QWERTY]` layer. 
//   The underscores are next to RAISE on the left and before LOWER on the right. 
//   This is because these two keys do not exist on the five keyed thumb cluster.
//   For instance, if you replaced the `_______` with KC_COPY and flashed it on your five keyed thumb cluster keyboard.
//   It would still work. It's just that there would be no key where the KC_COPY should be, 
//   so you wouldn't be able to actually press it.

#include QMK_KEYBOARD_H

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [_QWERTY] = LAYOUT_5x6(
        KC_ESC , KC_1  , KC_2  , KC_3  , KC_4  , KC_5  ,                         KC_6  , KC_7  , KC_8  , KC_9  , KC_0  ,KC_BSPC,
        KC_TAB , KC_Q  , KC_W  , KC_E  , KC_R  , KC_T  ,                         KC_Y  , KC_U  , KC_I  , KC_O  , KC_P  ,KC_MINS,
        KC_LSFT, KC_A  , KC_S  , KC_D  , KC_F  , KC_G  ,                         KC_H  , KC_J  , KC_K  , KC_L  ,KC_SCLN,KC_QUOT,
        KC_LCTL, KC_Z  , KC_X  , KC_C  , KC_V  , KC_B  ,                         KC_N  , KC_M  ,KC_COMM,KC_DOT ,KC_SLSH,KC_BSLASH,
                         KC_LBRC,KC_RBRC,                                                       KC_PLUS, KC_EQL,
                                         RAISE,_______,                        _______, LOWER,
                                         KC_TAB,KC_HOME,                         KC_DEL,  KC_ENT,
                                         KC_SPC, KC_BSPC,                        KC_LGUI, KC_LALT
    ),

    [_LOWER] = LAYOUT_5x6(
        KC_TILD,KC_EXLM, KC_AT ,KC_HASH,KC_DLR ,KC_PERC,                        KC_CIRC,KC_AMPR,KC_ASTR,KC_LPRN,KC_RPRN,KC_DEL,
        _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC, KC_P7 , KC_P8 , KC_P9 ,_______,KC_PLUS,
        _______,KC_HOME,KC_PGUP,KC_PGDN,KC_END ,KC_LPRN,                        KC_RPRN, KC_P4 , KC_P5 , KC_P6 ,KC_MINS,KC_PIPE,
        _______,_______,_______,_______,_______,_______,                        _______, KC_P1 , KC_P2 , KC_P3 ,KC_EQL ,KC_UNDS,
                                                _______,KC_PSCR,            _______, KC_P0,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______

    ),

    [_RAISE] = LAYOUT_5x6(
          KC_F12 , KC_F1 , KC_F2 , KC_F3 , KC_F4 , KC_F5 ,                        KC_F6  , KC_F7 , KC_F8 , KC_F9 ,KC_F10 ,KC_F11 ,
          _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC,_______,KC_NLCK,KC_INS ,KC_SLCK,KC_MUTE,
          _______,KC_LEFT,KC_UP  ,KC_DOWN,KC_RGHT,KC_LPRN,                        KC_RPRN,KC_MPRV,KC_MPLY,KC_MNXT,_______,KC_VOLU,
          _______,_______,_______,_______,_______,_______,                        _______,_______,_______,_______,_______,KC_VOLD,
                                                  _______,_______,            KC_EQL ,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______
    )
};
```

{% endcode %}

</details>

<details>

<summary>Example keymap.c - Size Large (Six Keyed Thumb Cluster)</summary>

Below is an example of a keymap.c file for the size large keyboard, also known as the six keyed thumb cluster keyboard. This file is also available on GitHub [here](https://github.com/taikohub/dactyl-keyboard-keymap).

{% code title="keymap.c" %}

```clike
//This is an example of a keymap.c file for the Taikohub dactyl manuform keyboard with six keyed thumb cluster (size large).
//
//1. A blank key with no function is indicated by 7 underscores: `________`.
//
//2. The `[_QWERTY]` layer is the default layer.

#include QMK_KEYBOARD_H

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [_QWERTY] = LAYOUT_5x6(
        KC_ESC , KC_1  , KC_2  , KC_3  , KC_4  , KC_5  ,                         KC_6  , KC_7  , KC_8  , KC_9  , KC_0  ,KC_BSPC,
        KC_TAB , KC_Q  , KC_W  , KC_E  , KC_R  , KC_T  ,                         KC_Y  , KC_U  , KC_I  , KC_O  , KC_P  ,KC_MINS,
        KC_LSFT, KC_A  , KC_S  , KC_D  , KC_F  , KC_G  ,                         KC_H  , KC_J  , KC_K  , KC_L  ,KC_SCLN,KC_QUOT,
        KC_LCTL, KC_Z  , KC_X  , KC_C  , KC_V  , KC_B  ,                         KC_N  , KC_M  ,KC_COMM,KC_DOT ,KC_SLSH,KC_BSLASH,
                         KC_LBRC,KC_RBRC,                                                       KC_PLUS, KC_EQL,
                                         RAISE,KC_SPC,                           KC_ENT, LOWER,
                                         KC_TAB,KC_HOME,                         KC_END,  KC_DEL,
                                         KC_BSPC, KC_GRV,                        KC_LGUI, KC_LALT
    ),

    [_LOWER] = LAYOUT_5x6(
        KC_TILD,KC_EXLM, KC_AT ,KC_HASH,KC_DLR ,KC_PERC,                        KC_CIRC,KC_AMPR,KC_ASTR,KC_LPRN,KC_RPRN,KC_DEL,
        _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC, KC_P7 , KC_P8 , KC_P9 ,_______,KC_PLUS,
        _______,KC_HOME,KC_PGUP,KC_PGDN,KC_END ,KC_LPRN,                        KC_RPRN, KC_P4 , KC_P5 , KC_P6 ,KC_MINS,KC_PIPE,
        _______,_______,_______,_______,_______,_______,                        _______, KC_P1 , KC_P2 , KC_P3 ,KC_EQL ,KC_UNDS,
                                                _______,KC_PSCR,            _______, KC_P0,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______

    ),

    [_RAISE] = LAYOUT_5x6(
          KC_F12 , KC_F1 , KC_F2 , KC_F3 , KC_F4 , KC_F5 ,                        KC_F6  , KC_F7 , KC_F8 , KC_F9 ,KC_F10 ,KC_F11 ,
          _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC,_______,KC_NLCK,KC_INS ,KC_SLCK,KC_MUTE,
          _______,KC_LEFT,KC_UP  ,KC_DOWN,KC_RGHT,KC_LPRN,                        KC_RPRN,KC_MPRV,KC_MPLY,KC_MNXT,_______,KC_VOLU,
          _______,_______,_______,_______,_______,_______,                        _______,_______,_______,_______,_______,KC_VOLD,
                                                  _______,_______,            KC_EQL ,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______
    )
};
Footer

```

{% endcode %}

</details>

<details>

<summary>Layers - What are they?</summary>

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality.&#x20;

Layers are similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://docs.qmk.fm/feature_layers#switching-and-toggling-layers) on the QMK website.

Layer keys are what you press on your keyboard to switch to a different layer. The `RAISE` and `LOWER` keycodes raises and lowers the layer, similar to Fn or Shift on a regular keyboard.&#x20;

If you have been following along, look in your current keymap.c file. As an example of how layere keys work, here you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. It is similar to a FnLock key seen on some keyboards. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

`[QWERTY] = LAYOUT5x6()` refers to the default base layer.

</details>

<details>

<summary>Keycodes - What are they?</summary>

Keycodes are functions that start with `KC_`.&#x20;

For example, say we want it so that when we press the top left button of our keyboard, it produces an `=` equal sign.

If we look at our current keymap.c, we will see that the keycode furthest to the top left is `KC_ESC` (assuming you have been following along this section). We want to replace `KC_ESC` with the keymap for `=`, so we go to the[ QMK List of Keycodes](https://docs.qmk.fm/#/keycodes) to check.

A quick Ctrl+F for `=` brings us to the following.&#x20;

<img src="/files/N0eBcYuoSFk1uLJVQK7f" alt="dactyl-manuform-qmk-tutorial-for-linux-what-are-keycodes" data-size="line">

Now we know to replace `KC_ESC` with `KC_EQUAL`, or its alias `KC_EQL`. After we flash the firmware in section 4.6 with our new keymap.c, the keyswitch to the top left of our keyboard will output `=` .

</details>

<details>

<summary>Keymap Extras - Add non-English languages.</summary>

Add non-English languages to QMK with keymap extras. List of supported languages shown here: <https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras>.

The below is an example of a `keymap.c` file that includes the `keymap_spanish.h` module. You can also see the example [here](https://gist.github.com/taikohub/1a0beb8892bf20db36ccbbff81747ba7).

{% code title=".../5x6/keymaps/taiko/keymap.c" %}

```clike
//This is an example of a keymap.c file where we include an extra module.
//Here we will use the keymap_spanish.h module, seen here: https://github.com/qmk/qmk_firmware/blob/master/quantum/keymap_extras/keymap_spanish.h.
//We'll add the Spanish keycodes to the [_RAISE] layer, also known as the Layer #2. You would press MO(2) to access this layer.
#include QMK_KEYBOARD_H

//Step 1. Include the keymap_spanish.h module after `#include QMK_KEYBOARD_H`
#include "keymap_spanish.h"

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {

    [_QWERTY] = LAYOUT_5x6(
        ...
    ),
    [_LOWER] = LAYOUT_5x6(
        ...
    ),
    [_RAISE] = LAYOUT_5x6(
          //Step 2. You can then add keycodes from the keymap_spanish.h module similar to below.
          //Step 3. You can still use default QMK keycodes such as KC_F10 and KC_F11 seen below.
          ES_MORD, ES_1, ES_2, ES_3, ES_4, ES_5,                                ES_6, ES_7, ES_8, ES_9, ES_0, KC_F10, KC_F11,
          ...
    )
};
```

{% endcode %}

</details>

Save your keymap.c after you are finished editing.

### 4.6 🖥️Keyboard - Flashing the Firmware

Before you flash the firmware:

* [ ] The audio cord is not connected to the keyboard. The audio port is indicated by the blue arrow in Figure 4.1 below.
* [ ] One piece of the keyboard is connected to your computer via USB cord.

Then flash the firmware:

{% code lineNumbers="true" %}

```bash
qmk flash -kb handwired/dactyl_manuform/5x6 -km taiko
```

{% endcode %}

You should see:

> Detecting USB port, reset your controller now\...

When you see "Detecting USB port, reset your controller now\..." in the terminal, **click reset button on the keyboard**, as indicated by the green arrow in Figure 4.1. No need to rush, QMK will wait for you.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="Dactyl Manuform QMK Tutorial for Linux - Flashing a Custom Keymap"><figcaption><p>Figure 4.1 The green arrow indicates the reset switch. The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

### 4.7 🖥️Keyboard - Repeat Section 4.6 For the Other Piece of the Keyboard

### 4.8 🥳Good Work! You Did It!🎉

* Make sure the keyboard is not connected to the computer before reconnecting the audio cord to each piece of the keyboard.
* Connect the USB cord from your computer to the **left** keyboard.&#x20;
* Good work, you did it 🎉!


# 5. Customizing Keyboard Layout with ZMK

How to flash wireless bluetooth dactyl manuform with ZMK

### 5.1 🌀ZMK Firmware

**Firmware:** Firmware is software installed on microcontrollers to make your keyboard work.

**ZMK Firmware:** ZMK firmware is also known as just ZMK. It is a keyboard firmware similar to QMK, which is what your keyboard initially came with. ZMK and QMK are nearly identical for most users. The main difference being: If you want Bluetooth, use ZMK. If you want wired, use QMK.

{% hint style="warning" %}
Swap in bluetooth compatible microcontrollers before following this section. See [7.1 Swapping Microcontrollers: Bluetooth](/swapping-microcontrollers/bluetooth) before continuing below. Bluetooth compatible microcontrollers include nice!nano, Pro Micro nRF52840, SuperMini nRF52840 BLE, among many others.
{% endhint %}

### 5.2 📶Adding Bluetooth Functionality: Default Keyboard Layout

* This adds the default QWERTY layout seen in the [1. Introduction](/).
* This process takes about 10 minutes.

1. Download the firmware zip file for your keyboard below.

{% tabs %}
{% tab title="Size Large (6 Key Thumb Cluster)" %}
{% file src="/files/7hkUIpIeoKAM4g1eAMGA" %}
Zip file that contains firmware files for the size large keyboard
{% endfile %}
{% endtab %}

{% tab title="Size Medium (5 Key Thumb Cluster)" %}
{% file src="/files/WCl1W0RkzEpEmgdRwvp6" %}
Zip file that contains firmware files for the size medium keyboard
{% endfile %}
{% endtab %}

{% tab title="Size Small (3 Key Thumb Cluster)" %}
{% file src="/files/Rj1TyKWozl5mVShiAwjJ" %}
Zip file that contains firmware files for the size small keyboard
{% endfile %}
{% endtab %}
{% endtabs %}

2. Extract the zip file. You'll see 3 files. You'll use these files later.
   1. settings\_reset-nice\_nano\_v2-zmk.uf2
   2. dactyl\_manuform\_5x6\_left-nice\_nano\_v2-zmk.uf2
   3. dactyl\_manuform\_5x6\_right-nice\_nano\_v2-zmk.uf2
3. Plug the left piece of the keyboard to the computer. Make sure the two keyboard pieces are not connected to one another.
4. Click the reset switch twice. The reset switch is shown in the image below.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="" width="375"><figcaption><p>Figure 5.1 The green arrow indicates the reset switch. <br>The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

5. You should see that your computer has detected a new USB device called `NICE!NANO`. Open this in file explorer. Ignore the files that are in there.

<figure><img src="/files/7QVsxDlISVAQtlDgn11Y" alt="Dactyl Manuform ZMK Tutorial for Customizing Keyboard Layout" width="563"><figcaption><p>Figure 5.2 You should see <code>NICE!NANO</code> show up as a USB device.</p></figcaption></figure>

6. Drag the `settings_reset-nice_nano_v2-zmk.uf2` file into file explorer. After a few seconds, the USB device should disconnect itself. A pop up notification may show up saying "Error while copying "dactyl\_manuform\_5x6\_left-nice\_nano\_v2-zmk.uf2". This is not an actual error.

<figure><img src="/files/DQPpLxETWKElE1fs0rUQ" alt="Dactyl Manuform ZMK Tutorial - Error while copying dactyl manuform" width="563"><figcaption><p>Figure 5.3 This prompt is not an error.</p></figcaption></figure>

7. Click the reset switch twice again.
8. Open up the USB device again.
9. Drag the `dactyl_manuform_5x6_left-nice_nano_v2-zmk.uf2` file into the file explorer.&#x20;
10. Repeat the above steps for the right side of the keyboard. Use `dactyl_manuform_5x6_right-nice_nano_v2-zmk.uf2` for the last step.
11. Charge the battery for each keyboard by separately connecting each piece to the computer. Then make sure the on/off switch is **not** pressed down. The keyboard is ON when the switch is **not** pressed down. The keyboard is OFF when the switch is pressed down.

<div><figure><img src="/files/yuEUGhDTJftXsmOWADDX" alt="Dactyl Manuform ZMK Tutorial - Adding a battery" width="375"><figcaption><p>Figure 5.4 The green arrow points to the on/off switch.</p></figcaption></figure> <figure><img src="/files/SNVJTW8TThHsQjq5mlJu" alt="" width="550"><figcaption><p>Figure 5.5 The red arrow shows the OFF position. The switch is pressed down.<br>The green arrow shows the ON position. The switch is <strong>not</strong> pressed down.</p></figcaption></figure></div>

12. If you are using the default 110mAh battery that came with the keyboard, it will take about 1 hour to fully charge the keyboards. This will last 1 - 2 weeks for the left side of the keyboard, and 3 months for the right side of the keyboard. The reason the left side of the keyboard has a shorter battery life is because it needs to maintain two Bluetooth connections concurrently, one with the computer and another with the right piece of the keyboard.
13. Once you are done charging, test the keyboard by turning on Bluetooth on your computer. You should see a Bluetooth device called `TAIKO-DACTYL-L`. Connect to the device and it should start working. You will not see  `TAIKO-DACTY-R` because the left piece of the keyboard connects to the right piece automatically.

### 5.3 📶Adding Bluetooth Functionality: Custom Keyboard Layout

* This adds your own custom keymap.
* It uses the ZMK CLI tool.
* This process may take 30 minutes or longer depending on how familiar you are with programming.

1. Navigate to <https://github.com/taikohub/zmk-config> and fork the repository.
2. Clone the forked repository to your local machine.

```bash
# replace yourusername with your Github username
git clone https://github.com/yourusername/zmk-config.git
```

3. Git checkout the branch that matches your keyboard size.

```bash
# Size large (6 keyed-thumb cluster)
git checkout large

# Size medium (5 keyed-thumb cluster)
git checkout medium

# Size small (3 keyed-thumb cluster)
git checkout small
```

4. Open the `config/dactyl_manuform_5x6.keymap` to edit the keyboard layout.

```bash
cd zmk-config

# Use your preferred code editor to open the file
code config/dactyl_manuform_5x6.keymap
```

5. Once you are done, commit and push the change.

```bash
git commit -m "Update keymap"
git push
```

6. Go to your Github repo and check the Actions tab. You should see a new workflow run. Once the workflow is complete, you should see a new firmware file in the "Artifacts" section. Download the `firmware.zip` file.
7. Extract the `firmware.zip` file. You'll see 3 files. You'll use these files later.
   1. settings\_reset-nice\_nano\_v2-zmk.uf2
   2. dactyl\_manuform\_5x6\_left-nice\_nano\_v2-zmk.uf2
   3. dactyl\_manuform\_5x6\_right-nice\_nano\_v2-zmk.uf2
8. Plug the left piece of the keyboard to the computer. Make sure the two keyboard pieces are not connected to one another.
9. Click the reset switch twice. The reset switch is shown in the image below.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="" width="375"><figcaption><p>Figure 5.1 The green arrow indicates the reset switch. <br>The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

5. You should see that your computer has detected a new USB device called `NICE!NANO`. Open this in file explorer. Ignore the files that are in there.

<figure><img src="/files/7QVsxDlISVAQtlDgn11Y" alt="Dactyl Manuform ZMK Tutorial for Customizing Keyboard Layout" width="563"><figcaption><p>Figure 5.2 You should see <code>NICE!NANO</code> show up as a USB device.</p></figcaption></figure>

6. Drag the `settings_reset-nice_nano_v2-zmk.uf2` file into file explorer. After a few seconds, the USB device should disconnect itself. A pop up notification may show up saying "Error while copying "dactyl\_manuform\_5x6\_left-nice\_nano\_v2-zmk.uf2". This is not an actual error.

<figure><img src="/files/DQPpLxETWKElE1fs0rUQ" alt="Dactyl Manuform ZMK Tutorial - Error while copying dactyl manuform" width="563"><figcaption><p>Figure 5.3 This prompt is not an error.</p></figcaption></figure>

7. Click the reset switch twice again.
8. Open up the USB device again.
9. Drag the `dactyl_manuform_5x6_left-nice_nano_v2-zmk.uf2` file into the file explorer.&#x20;
10. Repeat the above steps for the right side of the keyboard. Use `dactyl_manuform_5x6_right-nice_nano_v2-zmk.uf2` for the last step.
11. Charge the battery for each keyboard by separately connecting each piece to the computer. Then make sure the on/off switch is **not** pressed down. The keyboard is ON when the switch is **not** pressed down. The keyboard is OFF when the switch is pressed down.

<div><figure><img src="/files/yuEUGhDTJftXsmOWADDX" alt="Dactyl Manuform ZMK Tutorial - Adding a battery" width="375"><figcaption><p>Figure 5.4 The green arrow points to the on/off switch.</p></figcaption></figure> <figure><img src="/files/SNVJTW8TThHsQjq5mlJu" alt="" width="550"><figcaption><p>Figure 5.5 The red arrow shows the OFF position. The switch is pressed down.<br>The green arrow shows the ON position. The switch is <strong>not</strong> pressed down.</p></figcaption></figure></div>

12. If you are using the default 110mAh battery that came with the keyboard, it will take about 1 hour to fully charge the keyboards. This will last 1 - 2 weeks for the left side of the keyboard, and 3 months for the right side of the keyboard. The reason the left side of the keyboard has a shorter battery life is because it needs to maintain two Bluetooth connections concurrently, one with the computer and another with the right piece of the keyboard.
13. Once you are done charging, test the keyboard by turning on Bluetooth on your computer. You should see a Bluetooth device called `TAIKO-DACTYL-L`. Connect to the device and it should start working. You will not see  `TAIKO-DACTY-R` because the left piece of the keyboard connects to the right piece automatically.


# 6. Hot Swapping Keyswitches

How to hot swap keyswitches on the dactyl manuform keyboard

### 6.1 🔀Hotswapping Keyswitches

Hotswapping refers to swapping out a component on your keyboard. By hotswapping keyswitches, we can customize the smoothness and the clicking sensation when you press a key on the keyboard.

<figure><img src="/files/k3Vrkgk0wQ7OtLw9LGyB" alt=""><figcaption><p>Figure 5.1 Keyswitch</p></figcaption></figure>

### 6.2 🛠️Necessary Tools and Components

* Keyswitches: **5-legged MX style keyswitches** are recommended. MX Cherry and Gaterons are officially supported. But it should work with all MX style switches.
* Keyswitch puller
* Keycap puller

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

### 6.3️ 📖Instructions

#### Step 1. Remove Keycaps

* Remove keycaps with a keycap puller.

<div data-full-width="false"><figure><img src="/files/BgP9chgtP35eBtzNLHHV" alt="" width="375"><figcaption><p>Step 1. Keyboard with keycaps removed</p></figcaption></figure></div>

#### Step 2. Open the Keyboard

* Open the keyboard by unscrewing the M6 screws on the back of the keyboard.
* You will need an M6 sized hex key. A hex key is also called an Allen key.

<div align="center" data-full-width="true"><figure><img src="/files/sb2I55lAnr024CWeboNs" alt="" width="563"><figcaption><p>Step 2. Remove the screws with an M6 hex key</p></figcaption></figure> <figure><img src="/files/dZrJ3tMuKdsOO1aFkV4s" alt="" width="563"><figcaption><p>Step 2. Keyboard after M6 screws are removed</p></figcaption></figure></div>

<figure><img src="/files/2JtWPAO8IItt8Oclmtth" alt="" width="563"><figcaption><p>Step 2. This is what the keyboard looks like now</p></figcaption></figure>

#### Step 3. Swap the Keyswitch

* Remove a keyswitch with a keyswitch puller.
  * You may need to pull with a bit of force. This does **not** require excessive force.
  * It may be helpful to hold the base plate and the top case together in one hand while you use the keyswitch puller with the other hand.
* Gently push the Kailh socket on the circuit board upwards with your finger. Next align the metal pins on the keyswitch with the metal foils on the Kailh socket. Then insert the new keyswitch. See [#id-6.5-tips](#id-6.5-tips "mention") for more details.&#x20;
  * The Kailh socket is the black plastic component that has a flipped "L" shape (﹃ ).
* Then repeat this to swap out each keyswitch.

<div data-full-width="true"><figure><img src="/files/9eJBLzuQ27KaaYjeNE4U" alt="" width="375"><figcaption><p>Step 3.1 Remove a keyswtich with a keyswitch puller.</p></figcaption></figure> <figure><img src="/files/lApR4zGn4fStb33zrcYw" alt="" width="375"><figcaption><p>Step 3.2. Push Kailh socket with your finger and insert new keyswitch</p></figcaption></figure></div>

<figure><img src="/files/MuSB4TfCyq6wsCfEtkAs" alt="" width="375"><figcaption><p>Step 3.3 The Kailh Socket is the black L shaped component</p></figcaption></figure>

#### Step 4. Close the Keyboard

* Close the keyboard by screwing the M6 screws back on.

<figure><img src="/files/sb2I55lAnr024CWeboNs" alt="" width="375"><figcaption><p>Step 4. Close the keyboard with the M6 screws.</p></figcaption></figure>

#### Step 5. Add Keycaps

* Add the keycaps back on and you're done! 🎉

### 6.4 📒Summary

1. Remove keycaps with the keycap puller.
2. Open the keyboard by unscrewing the M6 screws on the back of the keyboard.
3. Pull out the keyswitch with a keyswitch puller.
4. &#x20;If the keyswitch is not coming out, try orienting it from a different angle. It may help to pull it in a curved motion.
5. &#x20;Insert the new keyswitch.

### 6.5 ❇️Tips

{% tabs %}
{% tab title="Align the keyswitch metal pins" %}

* In order for the keyswitch to make an electrical connection with the PCB, the metal pins on the keyswitch seen in Figure 6.1 needs to slide between the two metal foils in the hotswap socket seen in Figure 6.2A
* The purple arrow in Figure 6.2.A and Figure 6.2.B points to the thinner, more flexible, metal pin on the keyswitch. This pin is harder to align. If this is aligned, the other stiffer metal pin is generally not a problem.&#x20;

<figure><img src="/files/1RcikGzyiOEg6i4s7PeZ" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-align-keyswitch-with-pcb" width="375"><figcaption><p>Figure 6.1 Purple arrow points to the thinner, more flexible, metal pin. There generally shouldn't be any issues as long as this pin is aligned when inserting the new keyswitch.</p></figcaption></figure>

<div><figure><img src="/files/u4S0zcedmf4HhwwkKGuN" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-kailh-socket-pcb-close-up" width="375"><figcaption><p>Figure 6.2.A The purple arrows point to the metal foils in the hotswap socket. The metal pins on the keyswitch need to slide between the foils.</p></figcaption></figure> <figure><img src="/files/jLkzp2Uqjx0Ekm5e24t7" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-kailh-socket-pcb-side-view" width="375"><figcaption><p>Figure 6.2.B Side view of the PCB. The purple arrows point to the metal foils in the hotswap socket.</p></figcaption></figure></div>
{% endtab %}

{% tab title="Holding the keyswitch" %}

* The orange arrows in Figure 6.3 point to where I prefer to hold the keyswitch while aligning it.
* The easiest way to determine whether the keyswitch inserted properly is have it plugged into your computer. Push on the keyswitch before fully locking it into the keyboard. If it outputs a value onto the computer, it's been inserted properly&#x20;
* Then push the keyswitch all the way in.

<figure><img src="/files/RAPFPEz3ESZGlVt1mC7q" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-tip"><figcaption><p>Figure 6.3 The orange arrows point to where I prefer to hold the keyswitch while aligning it.</p></figcaption></figure>
{% endtab %}
{% endtabs %}


# 7. Swapping Microcontrollers

How to swap microcontrollers on the dactyl manuform

### 7.1 Microcontrollers

A microcontroller is a small device that controls your keyboard. Each piece of your keyboard comes with a Pro Micro microcontroller. You may come across it abbreviated as MCU, which stands for MicroController Unit.

### 7.2 Why swap microcontrollers?

The main reason to swap microcontrollers is to add new features. For example, you may want to use a nice!nano microcontroller to add Bluetooth functionality. Or you may want to use a Adafruit KB2040, which uses a more powerful RP2040 chip, to add very complex macros.&#x20;

{% hint style="danger" %}
Unplug any cords or batteries before swapping your microcontrollers.
{% endhint %}

### 7.3 Necessary tools and components

* 3mm Allen key
* Two new microcontrollers
  * These need to have a similar footprint to the Arduino Pro Micro.&#x20;
  * Compatible microcontrollers includes Adafruit KB2040, nice!nano, Pro Micro nrf52840, SuperMini nRF52840, among many others.&#x20;

{% hint style="warning" %}
Not compatible with BlueMicro840 V1.0.
{% endhint %}

### 7.4. Swapping microcontrollers

a. Remove all power source from your keyboard. Unplug any cords or batteries.

b. Take off the plastic cover on the base plate of the keyboard, indicated by the yellow arrow in Figure 7.2. You can use a pen or an Allen key to **gently** wedge it out from the sides, as indicated by the blue arrows in Figure 7.2.A You should take turns wedging from each side.

<figure><img src="/files/yyh76qUgatuH88fgjuB3" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-1"><figcaption><p>Figure 7.2.A Take off the cover for the microcontroller indicated by the yellow arrow. You may need to use a pen to gently wedge on either side of the cover, indicated by the blue arrows.</p></figcaption></figure>

c. Remove the microcontroller that came with the keyboard. Hold the microcontrollers by the top and bottom as indicated by the yellow arrows on Figure 7.3. Then gently wiggle it out.&#x20;

<figure><img src="/files/lDDaiP9P9UnvNuuejrFB" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-2"><figcaption><p>Figure 7.3. Put your fingers on each side of the microcontroller indicated by the yellow arrows, then gently wiggle it out.</p></figcaption></figure>

d. **Gently** plug in your own microcontroller. Note that some microcontrollers will require you to solder pin headers onto them.

<figure><img src="/files/RqrlZKnmiYjprLCqw4cu" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-3"><figcaption><p>Figure 7.4. Insert the new microcontroller. Adafruit KB2040 is shown here.</p></figcaption></figure>

e. Some microcontrollers, such as the KB2040, are slightly smaller than the microcontroller that came with your keyboard. If you want the USB-C port closer to the front of the keyboard, you need to open up the baseplate to slide the microcontroller forward. Put the cover back on and you're finished 🎉!


# 7.1 Swapping Microcontrollers: Bluetooth

Converting dactyl manuform keyboard to bluetooth

### 7.1.1 Introduction

This page discusses how to convert your non-Bluetooth dactyl manuform keyboard to a Bluetooth-enabled keyboard. If you have purchased a Bluetooth-enabled keyboard directly on our [store](https://taikohub.com), then this page is not relevant to you because Bluetooth has already been setup for you.

{% hint style="danger" %}
Unplug any cords or batteries before swapping your microcontrollers.
{% endhint %}

### 7.1.2 Necessary tools and components

* [ ] 3mm Allen key
* [ ] 2 x Microcontroller that support Bluetooth. The nice!nano V2, the SuperMini nRF52840 and the Pro Micro nRF52840 are officially supported, but most microcontrollers with a footprint similar to the Arduino Pro Micro should work. <mark style="color:red;">Not compatible with BlueMicro840 V1.0.</mark>
* [ ] &#x20;2 x LiPo batteries with 2-Pin JST-PH. It's safest to get them from [Adafruit ](https://www.adafruit.com/product/1570)or [Sparkfun](https://www.sparkfun.com/products/13853).

{% hint style="danger" %}
Double check the LiPo battery for your microcontroller! Different microcontrollers may require different batteries. <mark style="color:red;">**Using the wrong battery can lead to**</mark> <mark style="color:red;">**explosions**</mark>!

Make sure that your JST-PH is correctly wired! The black wire and red wire should be in the correct orientation on the JST-PH connector, as shown in Figure 7.1.1.&#x20;

It's recommended you use batteries from Adafruit or Sparkfun. You can use other vendors, but note that some vendors sell LiPo batteries with their wires reversed. See video on this issue by Adafruit [here](https://www.youtube.com/watch?v=ILArrTIMFyM).
{% endhint %}

<div><figure><img src="/files/Fm4IPADjZI12xRqvuKU7" alt="dactyl manuform keyboard bluetooth lipo battery wiring"><figcaption><p>Figure 7.1.1 Orient your JST connector same way as the photo above. The black wire should be on the right and red should be on the left.</p></figcaption></figure> <figure><img src="/files/shOEAnpGRvaqUkZuHFz5" alt="dactyl manuform keyboard bluetooth lipo battery example"><figcaption><p>Figure 7.1.2. This 3.7V 110mAh LiPo battery worked with nice!nano's during testing.</p></figcaption></figure></div>

### 7.1.3 Adding Bluetooth

1. Remove the plastic cover and take out the default microcontroller that came with the keyboard.

<figure><img src="/files/7jCL59OB7nOfq4cqusFs" alt="taikohub dactyl manuform keyboard adding bluetooth functionality with nice nanos step one" width="375"><figcaption><p>Figure 7.1.2.1 Take out the default microcontroller that came with the keyboard.</p></figcaption></figure>

2. Insert the Bluetooth enabled microcontroller.

* Optional: If you want the USB-C port to be closer to the edge of the keyboard, you can loosen the screws counterclockwise with an 3mm Allen Key by a half circle. Then slide the PCB forward. Tighten the screw again afterwards by turning it clockwise.

<figure><img src="/files/VAXxYeYNuLjUtiPLEZ7E" alt="taikohub dactyl manuform keyboard adding bluetooth functionality with nice nanos step two" width="375"><figcaption><p>Figure 7.1.2.2 Insert the new Bluetooth-enabled microcontroller. <br>If you want the USB-C port to be closer to the edge of the keyboard, <br>you can loosen the screws.</p></figcaption></figure>

3. Insert the LiPo battery.

* No special instructions for inserting the battery. As long as you obtained the correct battery, the connector will insert correctly. This is because the JST-PH socket can only accept the battery header in one direction.

<figure><img src="/files/dGCzSLoFfRsroLrHxkYz" alt="taikohub dactyl manuform keyboard adding bluetooth functionality with nice nanos step three" width="375"><figcaption><p>Figure 7.1.2.3 Insert the new Bluetooth enabled microcontroller <br>and the LiPo battery.</p></figcaption></figure>

4. Put the cover back on.&#x20;

* You did it 🎉! Proceed to the section on flashing your keyboard with ZMK.

<figure><img src="/files/R59sxKn4WTS4ECS0TFgP" alt="taikohub dactyl manuform keyboard adding bluetooth functionality with nice nanos step four" width="375"><figcaption><p>Figure 7.1.2.4 Put the cover back on.</p></figcaption></figure>


# 8. Troubleshooting

Troubleshooting the dactyl manuform keyboard

### 8.1 Opening up the base plate

#### Resin Keyboards

* Use a 6mm Allen key to loosen the screws.

#### PLA Keyboards

* Use a 3mm Allen key to loosen the screws.&#x20;
* Please turn the screws **slowly** and **gently**. About 1/4 turn per second is a good speed.
* It may seem counterintuitive, but turning the screws too quickly or applying too much downward pressure will make it **harder** to tighten or loosen the screws. It can also damage the screw threads.&#x20;

{% hint style="danger" %}
**PLA Keyboards**: Turn the screws **slowly** and **gently.** Turning too quickly or applying too much downward pressure can damage the screw threads!
{% endhint %}

### 8.2 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller.

### 8.3 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes the keyboard connected to it is the left side. It assumes the right side is other piece.

If you had not disconnected the TRRS cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.

### 8.4 Thumb cluster not working after flashing right side of the keyboard

If the right side of the keyboard is directly connected to the computer, some keys on the thumb cluster will not register. This is normal. Simply make sure USB cable is connected to the left side of the keyboard and the TRRS cable is connected to the right side of the keyboard. The keyboard should start working as normal.

### 8.5 Keyboard doesn't register any keys

If you are using a different USB cord from the one that came with your keyboard, it may be a USB cord issue. Check to see if the keyboard works with the default USB cord. Certain USB cords do not play well with the microcontroller. If you are using a USB-C to USB-C cord, try switching which side of the cord you plug into the computer and which side you plug into the keyboard. This can sometimes resolve the problem.&#x20;

### 8.6 My problem isn't mentioned in the documentation

Please share it in the GitHub discussion section seen below.

{% embed url="<https://github.com/taikohub/dactyl-manuform-documentation/discussions/categories/general>" %}


# 8.1 Troubleshooting: QMK Toolbox

Troubleshooting QMK Toolbox with the dactyl manuform keyboard

QMK Toolbox is the graphical interface for Windows and Mac. It is not compatible with Linux.

<details>

<summary>8.1.1 <code>read error: The I/O operation has been aborted because of either a thread exit or an application request.</code></summary>

Problem: You tried to flash with QMK Toolbox. It completed the flash, but the keyboard didn't get flashed with your new keymapping at all. You see an output similar to the following in QMK Toolbox.

```
Caterina device connected (usbser): Arduino LLC (www.arduino.cc) Arduino Leonardo bootloader (COM6) (2341:0036:0001) [COM6] Attempting to flash, please don't remove device
avrdude.exe -p atmega32u4 -c avr109 -U flash:w:"C:\Users\username\Desktop\firmware\qmk\windows\five\handwired_dactyl_manuform_5x6.hex":i -P COM6 avrdude.exe: ser_drain(): read error: The I/O operation has been aborted because of either a thread exit or an application request.

Connecting to programmer: .avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_drain(): read error: The device does not recognize the command.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding

avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_drain(): read error: The device does not recognize the command.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding Found programmer: Id = "‹"; type = > Software Version = â.·; Hardware Version = ö. avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: buffered memory access not supported. Maybe it isn't a butterfly/AVR109 but a AVR910 device? avrdude.exe: initialization failed, rc=-1 Double check connections and try again, or use -F to override this check.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: programmer did not respond to command: leave prog mode avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: programmer did not respond to command: exit bootloader
avrdude.exe done. Thank you.
```

Possible Causes:

a. Another computer peripheral is interfering with QMK Toolbox. Try disconnecting anything connected to the computer except the keyboard. A computer peripheral is anything that physically connects to your computer, and includes: mouse, phone, cables, monitors, another keyboard, among others.

b. If the above doesn't work, please contact <david@taikohub.com>

</details>


# 9. Terminology

Mechanical keyboard glossary

**Keycode:** The output after you press a keyswitch. For example, "Q" or "F11".

**Keymap:** Also called keyboard layout. Examples of keymaps include QWERTY, DVORAK, Colemak.

**Layers:**  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

**Layer Key:** The keycode you use to switch to a different layer. If you are using QMK Configurator, you'll see M(0) or M(1). If you are following [4. Customizing Keyboard Layout for Linux with QMK](/customizing-keyboard-layout-for-linux-with-qmk), you'll see the RAISE and LOWER layer keys in the default dactyl\_manuform/5x6 layout.

**QMK Toolbox:** A software tool used to flash a new layout onto your keyboard. It is available on Mac and Windows.

**Flashing:** Refers to when you install software onto your keyboard.

**QMK Configurator:** A website that allows you to create a custom keyboard layout and export the layout as a `.hex` file. This file is then used in QMK Toolbox.

**QMK CLI:** QMK's official command line interface tool.

**Microcontroller:** A microcontroller is a small device that controls your keyboard. Each piece of your keyboard comes with a Pro Micro microcontroller. You may come across it abbreviated as MCU, which stands for MicroController Unit.

**Firmware:** The software installed on microcontrollers to make your keyboard work. QMK firmware and ZMK firmware are examples.


# 10. Changelog

Taikohub dactyl manuform keyboard changelog

The following describes changes to the [TaikoHub dactyl manuform keyboard](https://taikohub.com).

**2024-05-01:** All keyboards shipped after May 10, 2024 no longer come with internal supports. Hotswapping now requires opening up the keyboard and holding the PCB with your hand. This change was made because the internal supports are difficult to align. This made tinkering and troubleshooting more difficult without substantial improvement to the hotswapping experience.&#x20;


# 11. Hardware Issues Tracking

If you have any hardware issues with your new keyboard, please email `david@taikohub.com`. Please email even if you fixed the issue, so that we can keep track of it.

<details>

<summary>PCB is Lifted Away from Keyboard</summary>

Incidences: 1 report of this issue as of Sep-11-2022.

Description: You plug in your new keyboard and find many keys do not work. You open up the keyboard with a 3mm allen key and find the PCB lifted. It's lifted enough that you see Kailh sockets do not come in contact with the switches at all.

Repair: Gently put one finger on the Kailh socket on the inside of the keyboard while you push the keyswitch into the keyboard on the other side. There's no need to push very hard with your other finger.

Reporting: Please report to `david@taikohub.com` or on the website chat widget. Thank you.

</details>


# 1. Introduction (Version 2022-07-01)

(5 min read)

## 1.1 Welcome👋

Thank you for purchasing a [TaikoHub dactyl manuform keyboard](https://taikohub.com/). This user guide will be continuously updated. If you have any questions, please email me anytime at <david@taikohub.com>. I will try to get back to you as soon as I can.

Please make sure you selected the correct keyboard version on the left. Version refers to the date of shipment. For example, Version 2021-06-24 refers to any keyboard shipped from 2021-06-24 to 2021-09-11. Version 2022-07-01, the most current version, refers to any keyboards shipped after 2022-07-01.

If you are confused about anything or have suggestions on how to improve the documentation, please share it in the GitHub discussions page [here](https://github.com/taikohub/dactyl-manuform-documentation/discussions/categories/general).

## 1.2 Getting started

1. Your keyboard should work without any configurations.&#x20;
2. Connect the audio cord to each side of the keyboard.
3. Connect the USB cord to the **left side** of the keyboard.
4. Your keyboard comes pre-flashed with the default keyboard layout seen in sections 1.1 to 1.3 below.
5. The rest of the documentation discusses how to customize the keyboard. Please read it before customizing the keyboard!

{% hint style="success" %}
Please read the relevant section in the documentation before you customize the keyboard.
{% endhint %}

{% hint style="warning" %}
Avoid disconnecting and connecting the audio cord while it is connected to a power source.
{% endhint %}

## 1.3 Keyboard layout

{% hint style="info" %}
The MO(1) and MO(2) keys seen in the keyboard layouts in section 1.2 below are also known as LOWER and RAISE keys. These function similar to a SHIFT key on a regular keyboard.
{% endhint %}

### 1.3.1 Default keyboard layout for size large (6 keyed thumb cluster)

<figure><img src="/files/-Md0KCzsDDH0pg_LX1_y" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap.</p></figcaption></figure>

<figure><img src="/files/-Md0KELhTFH-ARglV0aQ" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/-Md0KR5B1hIf_acfZgZC" alt="taikohub-dactyl-manuform-keyboard-with-six-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>

### 1.3.2 Default keyboard layout for size medium (5 keyed thumb cluster)

<figure><img src="/files/rOSB0UP2OPlpYhBoA9vv" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap. If your 5 keyed thumb cluster keyboard was shipped July 12, 2022 or later, it will have the keyboard layout shown above. For keyboards shipped prior to July 12, 2022, please see section 9. CHANGELOG.</p></figcaption></figure>

<figure><img src="/files/-MjLrlbqzXY8Q2oClvfp" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/-MjLroWFPagghsVut7fV" alt="taikohub-dactyl-manuform-keyboard-with-five-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>

### 1.3.3 Default keyboard layout for size small (3 keyed thumb cluster)

<figure><img src="/files/ZN12m1CR8mr2nqF3koZ1" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-base-layer"><figcaption><p>Layer 0 - Default keymap.</p></figcaption></figure>

<figure><img src="/files/vmUwRtUN7bwpmIoKBioS" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-lower-layer"><figcaption><p>Layer 1 - The keymap when you hold MO(1).</p></figcaption></figure>

<figure><img src="/files/qEfd0kFTG3JjOlM7daa9" alt="taikohub-dactyl-manuform-keyboard-with-three-keyed-thumb-cluster-keyboard-layout-raised-layer"><figcaption><p>Layer 2 - The keymap when you hold MO(2).</p></figcaption></figure>


# 2. About Your Keyboard (Version 2022-07-01)

(5 min read)

### 2.1 Compatible keycaps

Compatible keycap profiles (keycap shapes): DSA, XDA, SA Row 3 and MA. The keyboard comes with DSA keycaps.

Keycaps that are 1u in size will fit every key on every keyboard.&#x20;

There is the option to use 1.5u sized keycaps for the 6-keyed thumb cluster, which is able to fit two 1.5u keys on each side of the keyboard. The 3-keyed thumb cluster is also able to fit three 1.5u keys on each side.  The 5-keyed thumb cluster does not fit any 1.5u keys.

### 2.2 Compatible keyswitches for hotswapping

The keyboard is best used with **5 legged switches** (Figure 2.1) although 3 legged switches should still work, it's not officially supported. It is compatible with **MX Cherry switches,** Gateron switches, Holy Panda switches and other similar MX style switches.

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

<figure><img src="/files/-Md-CCTxdBbmadiex9Ln" alt="five-leg-keyswitches-work-best-with-taiko-dactyl-keyboard"><figcaption><p>Figure 2.1. 5-leg keyswitches are preferred.</p></figcaption></figure>


# 3. Customizing Keyboard Layout for Windows and Mac with QMK (Version 2022-07-01)

(15 min read)

### 3.1 ✨Instructions

This section uses QMK Toolbox, a GUI (graphical user interface) compatible with Mac and Windows. The QMK CLI (command line interface) is also compatible with Mac and Windows. But if you are not familiar with programming, you should follow section instead.

{% hint style="warning" %}
QMK Toolbox currently does not support Linux. See [Section 4](/version-2022-07-01/customizing-keyboard-layout-for-linux-with-qmk) instead.
{% endhint %}

{% hint style="info" %}
For troubleshooting with QMK Toolbox, see [Section 8.1](/version-2022-07-01/troubleshooting/qmk-toolbox).
{% endhint %}

<mark style="color:yellow;">`Text in this format and color refers to something you can click on.`</mark>

> Text in block quotes refers to text output from QMK Toolbox.

### 3.2 🪄[QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) - Customize Your Keyboard Layout

<figure><img src="/files/-MdNZAzBYbrwRHKUSYw6" alt="dactyl-manuform-qmk-tutorial-for-windows-and-mac-step-1"><figcaption><p>Figure 3.1. QMK Configurator. Letters A to H refer to each step in this section.</p></figcaption></figure>

Navigate to QMK Configurator. Steps A to H in Figure 3.1 above refer to each step in this section.

&#x20;

**Step A.** Click the <mark style="color:yellow;">`Keyboard`</mark> dropdown. Select <mark style="color:yellow;">`handwired/dactyl_manuform/5x6`</mark>.&#x20;

**Step B.** Enter the name you want to give your layout. For example, if you put <mark style="color:yellow;">my\_keymap</mark>, QMK will later generate a file with the name <mark style="color:yellow;">`handwired_dactyl_manuform_5x6_my_keymap.hex`</mark>.

<details>

<summary>Step C. keymap.json - Save your progress (Optional)</summary>

If you're not fully done customizing your keymap, the keymap.json file is a way to save your progress. You can return to your save point by uploading the keymap.json file to QMK Configurator. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

</details>

<details>

<summary>Step D. keymap.json - Load previous save point (Optional)</summary>

As described in the previous step, this gives you the option to upload the keymap.json file to return to your save point.

</details>

**Step E.** This section in Figure 3.1 highlights the keyboard layout.

**Step F.** Try dragging the <mark style="color:yellow;">`F1`</mark> keycode onto <mark style="color:yellow;">`End`</mark> on the keyboard layout. This changes that switch on the layout from <mark style="color:yellow;">`End`</mark> to <mark style="color:yellow;">`F1`</mark>. You likely won't want that button to be <mark style="color:yellow;">`F1`</mark>. Change it back by finding <mark style="color:yellow;">`End`</mark> in the keycode section and drag it to replace <mark style="color:yellow;">`F1`</mark>. Now that you're familiar with this, feel free to customize your keyboard layout.&#x20;

The sections below refer to a specific QMK functionality called layers, which is not found in a traditional keyboard. If this is not important to you, feel free to skip to part G.

<details>

<summary>Layers - What are they?</summary>

Layers are a QMK specific functionality. The concept is similar to the Fn or FnLock key that is seen on some keyboards.

If you are coming from a traditional keyboard, the easiest way to understand layers is to interact with it. In Figure 3.1, Layer 0 is selected. Try clicking on layer 1, 2, or others. Clicking on a different layer will bring up a different layout.

</details>

<details>

<summary>Layer keys - What are they?</summary>

Pressing a layer key switches the layout a different layer.&#x20;

1\. MO(layer)

In Figure 3.1, the layer keys look like <mark style="color:yellow;">`MO(1)`</mark> or <mark style="color:yellow;">`MO(2)`</mark>. This <mark style="color:yellow;">`MO(layer)`</mark> stands for momentarily activating the layer. This works similar to the Fn or Shift key on a regular keyboard.&#x20;

If you used a keyboard flashed with the keymap seen in Figure 3.1, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.

2\. DF(layer)

`DF(layer)` stands for default layer. It is similar to the FnLock key seen on some keyboards.

Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

</details>

**Step G.** When you are finished customizing your layout, click <mark style="color:yellow;">`Compile`</mark>. You should see a nice rotating potato baking in outerspace. Once this is done, the <mark style="color:yellow;">`Download Firmware`</mark> button should no longer be gray.

**Step H.** Click <mark style="color:yellow;">`Download Firmware`</mark>. It will download a file with a name similar to `handwired_dactyl_manuform_5x6_your_keymap.hex`. You will use this to flash your keyboard. You are ready to go to part 3.3.&#x20;

### 3.3 🛠️[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) - Download the Keyboard Layout Installation Tool

<figure><img src="/files/-MdNo47Op8rilV153B70" alt="dactyl-manuform-qmk-tutorial-for-windows-and-mac-step-2"><figcaption><p>Figure 3.2. QMK Toolbox website navigation. The photo was taken when the latest version was 0.0.21. The latest version is now 0.2.2.</p></figcaption></figure>

**Step A.** Go to the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) website. Check that you are looking at the latest release. In the photo above, the latest version was 0.0.21. The latest release as of this writing is 0.2.2. If the latest version has the name "Latest Beta", ignore it and scroll down to the next latest version.

**Step B.** Click to download <mark style="color:yellow;">`qmk_toolbox.pkg`</mark> if you use Mac.

**Step C.** Click to download <mark style="color:yellow;">`qmk_toolbox.exe`</mark> if you use Windows.

### 3.4 🛠️QMK Toolbox - Add Keyboard Layout to the Installation Tool

Open <mark style="color:yellow;">`qmk_toolbox.pkg`</mark>  or <mark style="color:yellow;">`qmk_toolbox.exe`</mark>. If you are opening QMK Toolbox for the first time, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select <mark style="color:yellow;">`Yes`</mark>.

<figure><img src="/files/-MdNxdKlCeYcwbzJyJDP" alt="dactyl-manuform-qmk-tutorial-for-windows-and-mac-step-3"><figcaption><p>Figure 3.3. QMK Toolbox Navigation</p></figcaption></figure>

**Step A.** If this is your first time using QMK Toolbox on your computer **and you did NOT see the install drivers dialogue box**, go to <mark style="color:yellow;">`Tool`</mark> then <mark style="color:yellow;">`Install Drivers`</mark>. If you do not see it there, move your cursor to the whitespace at the bottom of QMK Toolbox, right click with your mouse and install drivers.

**Step B.** Click <mark style="color:yellow;">`Open`</mark>. Select the <mark style="color:yellow;">`handwired_dactyl_manuform_5x6_your_keymap_name.hex`</mark> file that was downloaded earlier.

**Step C.** Make sure the dropdown menu shows <mark style="color:yellow;">`Atmega32U4`</mark>.

**Step D.** Check off <mark style="color:yellow;">`Auto-Flash`</mark>. **DO NOT click Flash just yet!**

### 3.5 🖥️Keyboard - Install the Keyboard Layout

**Step A.** Before you click Flash, ensure you have:

* [ ] Disconnected the audio cord from each piece of the keyboard. This cord normally connects to the socket indicated by the blue arrow in Figure 3.5 below.
* [ ] Connected one piece of the keyboard to your computer via USB cord.

**Step B.** Click <mark style="color:yellow;">`Flash`</mark>. The toolbox will wait for you as you perform the next step.

**Step C.** Click the reset button indicated by the green arrow in Figure 3.5.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="dactyl-manuform-qmk-tutorial-for-windows-and-mac-step-4"><figcaption><p>Figure 3.5 The green arrow indicates the reset switch. The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

If it flashes correctly, you should see the following.

> Attempting to flash, please don't remove device
>
> avrdude.exe -p atmega32u4 -c avr109 -U flash:w:"C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6.hex":i -P COM6
>
> Connecting to programmer: . Found programmer: Id = "CATERIN"; type = S Software Version = 1.0; No Hardware Version given. Programmer supports auto addr increment. Programmer supports buffered memory access with buffersize=128 bytes.
>
> Programmer supports the following devices: Device code: 0x44
>
> avrdude.exe: AVR device initialized and ready to accept instructions
>
> Reading | ################################################## | 100% 0.00s
>
> avrdude.exe: Device signature = 0x1e9587 (probably m32u4) avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed To disable this feature, specify the -D option. avrdude.exe: erasing chip avrdude.exe: reading input file "C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6.hex" avrdude.exe: writing flash (19424 bytes):
>
> Writing | ################################################## | 100% 1.47s
>
> avrdude.exe: 19424 bytes of flash written avrdude.exe: verifying flash memory against C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex: avrdude.exe: load data flash data from input file C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex: avrdude.exe: input file C:\Users\username\Desktop\firmware\qmk\windows\five\handwired\_dactyl\_manuform\_5x6\_five.hex contains 19424 bytes avrdude.exe: reading on-chip flash data:
>
> Reading | ################################################## | 100% 0.16s
>
> avrdude.exe: verifying ... avrdude.exe: 19424 bytes of flash verified
>
> avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
>
> avrdude.exe done. Thank you.
>
> Flash complete

### 3.6 🖥️Keyboard - Repeat For the Other Piece of the Keyboard

Repeat section 3.5 for the other piece of your keyboard.

### 3.7 🥳Good Work! You Did It!🎉

* Reconnect the two pieces with the audio cord. The sockets for the audio cord are shown by the blue arrow in Figure 3.4.&#x20;
* Connect the USB cord from the **left** keyboard to the computer.&#x20;
* Good work, you did it 🎉!


# 4. Customizing Keyboard Layout for Linux with QMK (Version 2022-07-01)

(10 min read) This section uses QMK CLI, a CLI tool compatible with Linux, Mac and Windows.

### 4.1 ✨Instructions

{% code lineNumbers="true" %}

```
Text in code block refers to what is typed into the terminal.
Enter one line at a time.
```

{% endcode %}

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

### 4.2 ⚡QMK CLI - Installing the CLI Tool

{% code lineNumbers="true" %}

```bash
python3 -m pip install --user qmk 
qmk setup
```

{% endcode %}

### 4.3 ⚡QMK CLI - Test Run the CLI Tool

You can test that QMK CLI is working properly by compiling one of the default keymaps that came with the installation. For instance, we can test clueboard/66/rev3 as below.

{% code lineNumbers="true" %}

```bash
qmk compile -kb clueboard/66/rev3 -km default
```

{% endcode %}

You should see a message similar to below.

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

### 4.4 ⚡QMK CLI - Creating a Custom Keymap

{% code lineNumbers="true" %}

```bash
qmk new-keymap -kb handwired/dactyl_manuform/5x6
```

{% endcode %}

You'll then be prompted to give a name to the keymap. Here I give it the name `taiko`.&#x20;

### 4.5 [📝Keymap  - Editing keymap.c](https://github.com/taikohub/dactyl-keyboard-keymap)

Edit the keymap.c file with your preferred editor. Here I use nano.

{% code lineNumbers="true" %}

```bash
nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/taiko/keymap.c
```

{% endcode %}

While editing your keymap.c, you may wish to look at the following:

<details>

<summary>Example keymap.c - Size Medium (Five Keyed Thumb Cluster)</summary>

Below is an example of a keymap.c file for the size medium keyboard, also known as the five keyed thumb cluster. This file is also available on GitHub [here](https://github.com/taikohub/dactyl-keyboard-keymap).

{% code title="keymap.c" %}

```clike
//This is an example of a keymap.c file for the Taikohub dactyl manuform keyboard with five keyed thumb cluster (size medium).
//
//1. A blank key with no function is indicated by 7 underscores: `________`.
//
//2. The `[_QWERTY]` layer is the default layer.
//
//3. Take note of where the `________` are in the `[_QWERTY]` layer. 
//   The underscores are next to RAISE on the left and before LOWER on the right. 
//   This is because these two keys do not exist on the five keyed thumb cluster.
//   For instance, if you replaced the `_______` with KC_COPY and flashed it on your five keyed thumb cluster keyboard.
//   It would still work. It's just that there would be no key where the KC_COPY should be, 
//   so you wouldn't be able to actually press it.

#include QMK_KEYBOARD_H

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [_QWERTY] = LAYOUT_5x6(
        KC_ESC , KC_1  , KC_2  , KC_3  , KC_4  , KC_5  ,                         KC_6  , KC_7  , KC_8  , KC_9  , KC_0  ,KC_BSPC,
        KC_TAB , KC_Q  , KC_W  , KC_E  , KC_R  , KC_T  ,                         KC_Y  , KC_U  , KC_I  , KC_O  , KC_P  ,KC_MINS,
        KC_LSFT, KC_A  , KC_S  , KC_D  , KC_F  , KC_G  ,                         KC_H  , KC_J  , KC_K  , KC_L  ,KC_SCLN,KC_QUOT,
        KC_LCTL, KC_Z  , KC_X  , KC_C  , KC_V  , KC_B  ,                         KC_N  , KC_M  ,KC_COMM,KC_DOT ,KC_SLSH,KC_BSLASH,
                         KC_LBRC,KC_RBRC,                                                       KC_PLUS, KC_EQL,
                                         RAISE,_______,                        _______, LOWER,
                                         KC_TAB,KC_HOME,                         KC_DEL,  KC_ENT,
                                         KC_SPC, KC_BSPC,                        KC_LGUI, KC_LALT
    ),

    [_LOWER] = LAYOUT_5x6(
        KC_TILD,KC_EXLM, KC_AT ,KC_HASH,KC_DLR ,KC_PERC,                        KC_CIRC,KC_AMPR,KC_ASTR,KC_LPRN,KC_RPRN,KC_DEL,
        _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC, KC_P7 , KC_P8 , KC_P9 ,_______,KC_PLUS,
        _______,KC_HOME,KC_PGUP,KC_PGDN,KC_END ,KC_LPRN,                        KC_RPRN, KC_P4 , KC_P5 , KC_P6 ,KC_MINS,KC_PIPE,
        _______,_______,_______,_______,_______,_______,                        _______, KC_P1 , KC_P2 , KC_P3 ,KC_EQL ,KC_UNDS,
                                                _______,KC_PSCR,            _______, KC_P0,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______

    ),

    [_RAISE] = LAYOUT_5x6(
          KC_F12 , KC_F1 , KC_F2 , KC_F3 , KC_F4 , KC_F5 ,                        KC_F6  , KC_F7 , KC_F8 , KC_F9 ,KC_F10 ,KC_F11 ,
          _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC,_______,KC_NLCK,KC_INS ,KC_SLCK,KC_MUTE,
          _______,KC_LEFT,KC_UP  ,KC_DOWN,KC_RGHT,KC_LPRN,                        KC_RPRN,KC_MPRV,KC_MPLY,KC_MNXT,_______,KC_VOLU,
          _______,_______,_______,_______,_______,_______,                        _______,_______,_______,_______,_______,KC_VOLD,
                                                  _______,_______,            KC_EQL ,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______
    )
};
```

{% endcode %}

</details>

<details>

<summary>Example keymap.c - Size Large (Six Keyed Thumb Cluster)</summary>

Below is an example of a keymap.c file for the size large keyboard, also known as the six keyed thumb cluster keyboard. This file is also available on GitHub [here](https://github.com/taikohub/dactyl-keyboard-keymap).

{% code title="keymap.c" %}

```clike
//This is an example of a keymap.c file for the Taikohub dactyl manuform keyboard with six keyed thumb cluster (size large).
//
//1. A blank key with no function is indicated by 7 underscores: `________`.
//
//2. The `[_QWERTY]` layer is the default layer.

#include QMK_KEYBOARD_H

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [_QWERTY] = LAYOUT_5x6(
        KC_ESC , KC_1  , KC_2  , KC_3  , KC_4  , KC_5  ,                         KC_6  , KC_7  , KC_8  , KC_9  , KC_0  ,KC_BSPC,
        KC_TAB , KC_Q  , KC_W  , KC_E  , KC_R  , KC_T  ,                         KC_Y  , KC_U  , KC_I  , KC_O  , KC_P  ,KC_MINS,
        KC_LSFT, KC_A  , KC_S  , KC_D  , KC_F  , KC_G  ,                         KC_H  , KC_J  , KC_K  , KC_L  ,KC_SCLN,KC_QUOT,
        KC_LCTL, KC_Z  , KC_X  , KC_C  , KC_V  , KC_B  ,                         KC_N  , KC_M  ,KC_COMM,KC_DOT ,KC_SLSH,KC_BSLASH,
                         KC_LBRC,KC_RBRC,                                                       KC_PLUS, KC_EQL,
                                         RAISE,KC_SPC,                           KC_ENT, LOWER,
                                         KC_TAB,KC_HOME,                         KC_END,  KC_DEL,
                                         KC_BSPC, KC_GRV,                        KC_LGUI, KC_LALT
    ),

    [_LOWER] = LAYOUT_5x6(
        KC_TILD,KC_EXLM, KC_AT ,KC_HASH,KC_DLR ,KC_PERC,                        KC_CIRC,KC_AMPR,KC_ASTR,KC_LPRN,KC_RPRN,KC_DEL,
        _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC, KC_P7 , KC_P8 , KC_P9 ,_______,KC_PLUS,
        _______,KC_HOME,KC_PGUP,KC_PGDN,KC_END ,KC_LPRN,                        KC_RPRN, KC_P4 , KC_P5 , KC_P6 ,KC_MINS,KC_PIPE,
        _______,_______,_______,_______,_______,_______,                        _______, KC_P1 , KC_P2 , KC_P3 ,KC_EQL ,KC_UNDS,
                                                _______,KC_PSCR,            _______, KC_P0,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______,
                                                _______,_______,            _______,_______

    ),

    [_RAISE] = LAYOUT_5x6(
          KC_F12 , KC_F1 , KC_F2 , KC_F3 , KC_F4 , KC_F5 ,                        KC_F6  , KC_F7 , KC_F8 , KC_F9 ,KC_F10 ,KC_F11 ,
          _______,_______,_______,_______,_______,KC_LBRC,                        KC_RBRC,_______,KC_NLCK,KC_INS ,KC_SLCK,KC_MUTE,
          _______,KC_LEFT,KC_UP  ,KC_DOWN,KC_RGHT,KC_LPRN,                        KC_RPRN,KC_MPRV,KC_MPLY,KC_MNXT,_______,KC_VOLU,
          _______,_______,_______,_______,_______,_______,                        _______,_______,_______,_______,_______,KC_VOLD,
                                                  _______,_______,            KC_EQL ,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______,
                                                  _______,_______,            _______,_______
    )
};
Footer

```

{% endcode %}

</details>

<details>

<summary>Layers - What are they?</summary>

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality.&#x20;

Layers are similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://beta.docs.qmk.fm/using-qmk/software-features/feature_layers#switching-and-toggling-layers-id-switching-and-toggling-layers) on the QMK website.

Layer keys are what you press on your keyboard to switch to a different layer. The `RAISE` and `LOWER` keycodes raises and lowers the layer, similar to Fn or Shift on a regular keyboard.&#x20;

If you have been following along, look in your current keymap.c file. As an example of how layere keys work, here you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. It is similar to a FnLock key seen on some keyboards. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

`[QWERTY] = LAYOUT5x6()` refers to the default base layer.

</details>

<details>

<summary>Keycodes - What are they?</summary>

Keycodes are functions that start with `KC_`.&#x20;

For example, say we want it so that when we press the top left button of our keyboard, it produces an `=` equal sign.

If we look at our current keymap.c, we will see that the keycode furthest to the top left is `KC_ESC` (assuming you have been following along this section). We want to replace `KC_ESC` with the keymap for `=`, so we go to the[ QMK List of Keycodes](https://docs.qmk.fm/#/keycodes) to check.

A quick Ctrl+F for `=` brings us to the following.&#x20;

<img src="/files/N0eBcYuoSFk1uLJVQK7f" alt="dactyl-manuform-qmk-tutorial-for-linux-what-are-keycodes" data-size="line">

Now we know to replace `KC_ESC` with `KC_EQUAL`, or its alias `KC_EQL`. After we flash the firmware in section 4.6 with our new keymap.c, the keyswitch to the top left of our keyboard will output `=` .

</details>

<details>

<summary>Keymap Extras - Add non-English languages.</summary>

Add non-English languages to QMK with keymap extras. List of supported languages shown here: <https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras>.

The below is an example of a `keymap.c` file that includes the `keymap_spanish.h` module. You can also see the gist [here](https://gist.github.com/taikohub/1a0beb8892bf20db36ccbbff81747ba7).

{% code title=".../5x6/keymaps/taiko/keymap.c" %}

```clike
//This is an example of a keymap.c file where we include an extra module.
//Here we will use the keymap_spanish.h module, seen here: https://github.com/qmk/qmk_firmware/blob/master/quantum/keymap_extras/keymap_spanish.h.
//We'll add the Spanish keycodes to the [_RAISE] layer, also known as the Layer #2. You would press MO(2) to access this layer.
#include QMK_KEYBOARD_H

//Step 1. Include the keymap_spanish.h module after `#include QMK_KEYBOARD_H`
#include "keymap_spanish.h"

#define _QWERTY 0
#define _LOWER 1
#define _RAISE 2

#define RAISE MO(_RAISE)
#define LOWER MO(_LOWER)

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {

    [_QWERTY] = LAYOUT_5x6(
        ...
    ),
    [_LOWER] = LAYOUT_5x6(
        ...
    ),
    [_RAISE] = LAYOUT_5x6(
          //Step 2. You can then add keycodes from the keymap_spanish.h module similar to below.
          //Step 3. You can still use default QMK keycodes such as KC_F10 and KC_F11 seen below.
          ES_MORD, ES_1, ES_2, ES_3, ES_4, ES_5,                                ES_6, ES_7, ES_8, ES_9, ES_0, KC_F10, KC_F11,
          ...
    )
};
```

{% endcode %}

</details>

Save your keymap.c after you are finished editing.

### 4.6 🖥️Keyboard - Flashing the Firmware

Before you flash the firmware:

* [ ] Disconnect the audio cord from each piece of the keyboard. The audio cord connects to the socket indicated by the blue arrow in Figure 4.1 below.
* [ ] Connect one piece of the keyboard to your computer via USB cord.

Then flash the firmware:

{% code lineNumbers="true" %}

```bash
qmk flash -kb handwired/dactyl_manuform/5x6 -km taiko
```

{% endcode %}

You should see:

> Detecting USB port, reset your controller now\...

When you see "Detecting USB port, reset your controller now\..." in the terminal, **click reset button on the keyboard**, as indicated by the green arrow in Figure 4.1. No need to rush, QMK will wait for you.

<figure><img src="/files/bwOWcmc6Vd6qzZbKzC1J" alt="dactyl-manuform-qmk-tutorial-for-linux-reset-button"><figcaption><p>Figure 4.1 The green arrow indicates the reset switch. The blue arrow indicates the socket connecting the two pieces of the keyboard.</p></figcaption></figure>

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

### 4.7 🖥️Keyboard - Repeat Section 4.6 For the Other Piece of the Keyboard

### 4.8 🥳Good Work! You Did It!🎉

* Make sure the keyboard is not connected to the computer before reconnecting the audio cord to each piece of the keyboard.
* Connect the USB cord from your computer to the **left** keyboard.&#x20;
* Good work, you did it 🎉!


# 5. Customizing Keyboard Layout with ZMK (Version 2022-07-01)

(10 min read)

### 5.1 🌀ZMK Firmware

**Firmware:** Firmware is software installed on microcontrollers to make your keyboard work.

**ZMK Firmware:** ZMK firmware is also known as just ZMK. It is a keyboard firmware similar to QMK, which is what your keyboard initially came with. ZMK and QMK are nearly identical for most users. The main difference being: If you want Bluetooth, use ZMK. If you want wired, use QMK.

{% hint style="warning" %}
Swap in nice!nanos before following this section. See [7.1 Swapping Microcontrollers: Bluetooth (Version 2022-07-01)](/version-2022-07-01/swapping-microcontrollers/bluetooth) before continuing below.
{% endhint %}

### 5.2 📶Adding Bluetooth Functionality

**Step 1.A** Add Bluetooth the Fast Way Using Default Configuration Files (5 minutes)

If you want your keyboard to have the same QWERTY layout as it initially came with, continue with this step. If you want to customize your keyboard layout, see Step 1.B instead.&#x20;

Download the configuration file for the left and right piece of your keyboard. Then skip Step 1.B and continue to Step 2.

{% tabs %}
{% tab title="Size Large (6 Key Thumb Cluster)" %}

{% file src="/files/erDzwQMamjBGiQZqmQsm" %}
ZMK Configuration File for the **Left** side of the TaikoHub Dactyl Manuform Keyboard in Size Large (Six Keyed Thumb Cluster)
{% endfile %}

{% file src="/files/z5dwC7an4m0hCxH4nIYa" %}
ZMK Configuration File for the **Right** side of the TaikoHub Dactyl Manuform Keyboard in Size Large (Six Keyed Thumb Cluster)
{% endfile %}
{% endtab %}

{% tab title="Size Medium (5 Key Thumb Cluster)" %}

{% file src="/files/c0zt7Zcxk8XFH2Z34Chj" %}
ZMK Configuration File for the **Left** side of the TaikoHub Dactyl Manuform Keyboard in Size Medium (Five Keyed Thumb Cluster)
{% endfile %}

{% file src="/files/uUCth4Lk0s1MMe6Ecs9d" %}
ZMK Configuration File for the **Right** side of the TaikoHub Dactyl Manuform Keyboard in Size Medium (Five Keyed Thumb Cluster)
{% endfile %}
{% endtab %}

{% tab title="Size Small (3 Key Thumb Cluster)" %}

{% file src="/files/NoyKF8Cg6TSQixxK7E4N" %}
ZMK Configuration File for the **Left** side of the TaikoHub Dactyl Manuform Keyboard in Size Small (Three Keyed Thumb Cluster)
{% endfile %}

{% file src="/files/mg0LGgQXX4xTkChSzbiK" %}
ZMK Configuration File for the **Left** side of the TaikoHub Dactyl Manuform Keyboard in Size Small (Three Keyed Thumb Cluster)
{% endfile %}
{% endtab %}
{% endtabs %}

**Step 1.B** Add Bluetooth the Slow Way By Customizing Your Own Configuration Files (10+ minutes)

Navigate to <https://github.com/taikohub/zmk-config>. See the `Getting Started` section in the README. The steps can be summarized as:&#x20;

1. Fork the repo.
2. Clone it to your local machine.
3. Edit `config/dactyl_manuform_5x6.keymap`.
4. Push the edits to your remote repo.
5. Navigate to GitHub Actions.
6. Click `firmware` to download the firmware.zip file.&#x20;
7. Unzip the firmware.zip. Then continue to Step 2.

**Step 2.** Make sure the two sides of the keyboard are **not** connected to each other. Connect only the left piece of your keyboard to the computer.

**Step 3.** Click the reset switch twice. You should see `NICE!NANO` show up as a USB device. If you opened up the directory, you would see 3 files. Ignore them. Do not edit or delete them. Even after you flash the keyboard, there will only be these 3 files.

<figure><img src="/files/7QVsxDlISVAQtlDgn11Y" alt=""><figcaption><p>Figure 5.1 You should see <code>NICE!NANO</code> show up as a USB device.</p></figcaption></figure>

**Step 4.** Drag the  `dactyl_manuform_5x6_left-nice_nano_v2-zmk.uf` file into the USB device directory. You may see the following prompt: `Error while copying "dactyl_manuform_5x6_left-nice_nano_v2-zmk.uf2"`. This is not an actual error. The nice!nano uses the file you dragged to flash itself, then automatically ejects itself as a USB device.

<figure><img src="/files/DQPpLxETWKElE1fs0rUQ" alt=""><figcaption><p>Figure 5.2 This prompt is not an error: <code>Error while copying "dactyl_manuform_5x6_left-nice_nano_v2-zmk.uf2"</code> .</p></figcaption></figure>

### 5.3 🖥️Repeat for the Other Piece of the Keyboard

* Repeat Section 5.2 Steps 2 to 4 for the right piece of the keyboard.

### 5.4 🎊Woot you're done!

* Turn on the keyboard by clicking the on-off switch indicated by the green arrow in the figure below, then snap in the transparent plastic cover.
* If the switch button height lowers, it means it's now turned on. If the switch button height rises, it means it's now turned off.
* Since it's wireless, you no longer need to connect the USB cord or the audio cord. Turn on Bluetooth on your computer then pair with your keyboard.
* Charge the keyboard battery by connecting a piece of the keyboard to your computer via USB.

<figure><img src="/files/yuEUGhDTJftXsmOWADDX" alt=""><figcaption><p>Figure 5.3 The green arrow points to the on/off switch.</p></figcaption></figure>


# 6. Hot Swapping Keyswitches (Version 2022-07-01)

(10 min read)

### 6.1 🔀Hotswapping

Hotswapping refers to swapping out components while your keyboard is connected to your computer or another power source. Hotswapping keyswitches is safe and has been tested countless times. But you should **not** hotswap microcontrollers, as noted in Section 7.&#x20;

### 6.2 🛠️Necessary Tools and Components

* Keyswitches: **5-legged MX style keyswitches** are recommended. MX Cherry and Gaterons are officially supported. But it should work with most MX style switches.
* Keyswitch puller
* Keycap puller

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

### 6.3️🎬Hotswapping Demo

{% embed url="<https://www.youtube.com/watch?v=1mZf4qUze8s>" %}
Video 6.1 Full Demo of Hotswapping a TaikoHub Dactyl Manuform Keyboard
{% endembed %}

{% embed url="<https://youtu.be/o79LDrqGqjs>" %}
Video 6.2 Short Hotswapping demo.
{% endembed %}

{% embed url="<https://youtu.be/oQxY-tLORR0>" %}
Video 6.3 Another short hotswap demo.
{% endembed %}

{% hint style="danger" %}
Hotswap up to one row of keyswitch at a time to avoid any issues.

The PCB is stabilized by the keyswitches. Removing one row of keyswitch at a time will minimize movement of the PCB and avoid any hassle. Please don't remove every keyswitch all at once.
{% endhint %}

### 6.4 📒Summary

1. Remove all the keycaps with the keycap puller.
2. Remove a single row of keyswitch at a time.
3. Pull out the keyswitch with a keyswitch puller, it should not take a lot of force. If the keyswitch is not coming out, try orienting it from a different angle. It may help to pull it in a curved motion.
4. &#x20;Insert the new keyswitch.

### 6.5 ❇️Tips

{% tabs %}
{% tab title="Align the keyswitch metal pins" %}

* In order for the keyswitch to make an electrical connection with the PCB, the metal pins on the keyswitch seen in Figure 5.1 needs to slide between the two metal foils in the hotswap socket seen in Figure 5.2A.
* The purple arrow in Figure 5.2.A and Figure 5.2.B points to the thinner, more flexible, metal pin on the keyswitch. This pin is harder to align. If this is aligned, the other stiffer metal pin is generally not a problem.&#x20;

<figure><img src="/files/1RcikGzyiOEg6i4s7PeZ" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-align-keyswitch-with-pcb"><figcaption><p>Figure 5.1 Purple arrow points to the thinner, more flexible, metal pin. There generally shouldn't be any issues as long as this pin is aligned when inserting the new keyswitch.</p></figcaption></figure>

<div><figure><img src="/files/u4S0zcedmf4HhwwkKGuN" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-kailh-socket-pcb-close-up"><figcaption><p>Figure 5.2.A The purple arrows point to the metal foils in the hotswap socket. The metal pins on the keyswitch need to slide between the foils.</p></figcaption></figure> <figure><img src="/files/jLkzp2Uqjx0Ekm5e24t7" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-kailh-socket-pcb-side-view"><figcaption><p>Figure 5.2.B Side view of the PCB. The purple arrows point to the metal foils in the hotswap socket.</p></figcaption></figure></div>
{% endtab %}

{% tab title="Holding the keyswitch" %}

* The orange arrows in Figure 5.3 point to where I prefer to hold the keyswitch while aligning it.
* The easiest way to determine whether the keyswitch inserted properly is have it plugged into your computer. Push on the keyswitch before fully locking it into the keyboard. If it outputs a value onto the computer, it's been inserted properly&#x20;
* Then push the keyswitch all the way in.

<figure><img src="/files/RAPFPEz3ESZGlVt1mC7q" alt="taikohub-dactyl-manuform-keyboard-hotswapping-tutorial-tip"><figcaption><p>Figure 5.3 The orange arrows point to where I prefer to hold the keyswitch while aligning it.</p></figcaption></figure>
{% endtab %}
{% endtabs %}


# 7. Swapping Microcontrollers (Version 2022-07-01)

(10 min read)

### 7.1 Microcontrollers

A microcontroller is a small device that controls your keyboard. Each piece of your keyboard comes with a Pro Micro microcontroller. You may come across it abbreviated as MCU, which stands for MicroController Unit.

### 7.2 Why swap microcontrollers?

The main reason to swap microcontrollers is to add new features. For example, you may want to use a nice!nano microcontroller to add Bluetooth functionality. Or you may want to use a Adafruit KB2040, which uses a more powerful RP2040 chip, to add very complex macros.&#x20;

{% hint style="danger" %}
Unplug any cords or batteries before swapping your microcontrollers.
{% endhint %}

### 7.3 Necessary tools and components

* 3mm Allen key
* Two new microcontrollers
  * These need to have a similar footprint to the Arduino Pro Micro.&#x20;
  * Compatible microcontrollers includes Adafruit KB2040, nice!nano, among many others.&#x20;

{% hint style="warning" %}
Not compatible with BlueMicro840 V1.0.
{% endhint %}

### 7.4. Swapping microcontrollers

a. Remove all power source from your keyboard. Unplug any cords or batteries.

b. Take off the plastic cover on the base plate of the keyboard, indicated by the yellow arrow in Figure 7.2. You can use a pen or an Allen key to **gently** wedge it out from the sides, as indicated by the blue arrows in Figure 7.2.A You should take turns wedging from each side.

<figure><img src="/files/yyh76qUgatuH88fgjuB3" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-1"><figcaption><p>Figure 7.2.A Take off the cover for the microcontroller indicated by the yellow arrow. You may need to use a pen to gently wedge on either side of the cover, indicated by the blue arrows.</p></figcaption></figure>

c. Remove the microcontroller that came with the keyboard. Hold the microcontrollers by the top and bottom as indicated by the yellow arrows on Figure 7.3. Then gently wiggle it out.&#x20;

<figure><img src="/files/lDDaiP9P9UnvNuuejrFB" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-2"><figcaption><p>Figure 7.3. Put your fingers on each side of the microcontroller indicated by the yellow arrows, then gently wiggle it out.</p></figcaption></figure>

d. **Gently** plug in your own microcontroller. Note that some microcontrollers will require you to solder pin headers onto them.

<figure><img src="/files/RqrlZKnmiYjprLCqw4cu" alt="taikohub-dactyl-manuform-keyboard-swap-mcu-tutorial-step-3"><figcaption><p>Figure 7.4. Insert the new microcontroller. Adafruit KB2040 is shown here.</p></figcaption></figure>

e. Some microcontrollers, such as the KB2040, are slightly smaller than the microcontroller that came with your keyboard. If you want the USB-C port closer to the front of the keyboard, you need to open up the baseplate to slide the microcontroller forward. Put the cover back on and you're finished 🎉!


# 7.1 Swapping Microcontrollers: Bluetooth (Version 2022-07-01)

(10 min read)

{% hint style="danger" %}
Unplug any cords or batteries before swapping your microcontrollers.
{% endhint %}

{% hint style="info" %}
QMK does not work well with Bluetooth. ZMK should be used instead.
{% endhint %}

### 7.1.1 Necessary tools and components

* [ ] 3mm Allen key
* [ ] 2 x Microcontroller that support Bluetooth. The nice!nano V2 is officially supported, but most microcontrollers with a footprint similar to the Arduino Pro Micro should work. <mark style="color:red;">Not compatible with BlueMicro840 V1.0.</mark>
* [ ] &#x20;2 x LiPo batteries with 2-Pin JST-PH. It's safest to get them from [Adafruit ](https://www.adafruit.com/product/1570)or [Sparkfun](https://www.sparkfun.com/products/13853).
* [ ] If your keyboard shipped before 2022-08-01, you will also need either 2 On-Off switches or 2 wires with female pin headers on both ends. See[#choice-1-add-a-switch-onto-the-keyboard](#choice-1-add-a-switch-onto-the-keyboard "mention") for details.

{% hint style="danger" %}
Double check the LiPo battery for your microcontroller! Different microcontrollers may require different batteries. <mark style="color:red;">**Using the wrong battery can lead to**</mark> <mark style="color:red;">**explosions**</mark>!

Make sure that your JST-PH is correctly wired! The black wire and red wire should be in the correct orientation on the JST-PH connector, as shown in Figure 7.1.1.&#x20;

It's recommended you use batteries from Adafruit or Sparkfun. You can use other vendors, but note that some vendors sell LiPo batteries with their wires reversed. See video on this issue by Adafruit [here](https://www.youtube.com/watch?v=ILArrTIMFyM).
{% endhint %}

<div><figure><img src="/files/Fm4IPADjZI12xRqvuKU7" alt="taikohub-dactyl-manuform-keyboard-bluetooth-lipo-battery-caution"><figcaption><p>Figure 7.1.1 Orient your JST connector same way as the photo above. The black wire should be on the right and red should be on the left.</p></figcaption></figure> <figure><img src="/files/shOEAnpGRvaqUkZuHFz5" alt="taikohub-dactyl-manuform-keyboard-bluetooth-lipo-battery"><figcaption><p>Figure 7.1.2. This 3.7V 110mAh LiPo battery worked with nice!nano's during testing.</p></figcaption></figure></div>

### 7.1.2 Adding Bluetooth

{% tabs %}
{% tab title="Keyboards shipped after 2022-08-01" %}
If your keyboard shipped after 2022-08-01, follow the steps below.

### **Step 1**

Remove the plastic cover and take out the default microcontroller that came with the keyboard.

<figure><img src="/files/7jCL59OB7nOfq4cqusFs" alt="taikohub-dactyl-manuform-keyboard-bluetooth-nice-nanos-step-1"><figcaption><p>Figure 7.1.2.1 Step 1 - Take out the default microcontroller that came with the keyboard.</p></figcaption></figure>

### **Step 2**&#x20;

Insert the Bluetooth enabled microcontroller.

Optional: If you want the USB-C port to be closer to the edge of the keyboard, you can loosen the screws counterclockwise with an 3mm Allen Key by a half circle. Then slide the PCB forward. Tighten the screw again afterwards by turning it clockwise.

<figure><img src="/files/VAXxYeYNuLjUtiPLEZ7E" alt="taikohub-dactyl-manuform-keyboard-bluetooth-nice-nanos-step-2"><figcaption><p>Figure 7.1.2.2 Step 2 - Insert the new Bluetooth enabled microcontroller. If you want the USB-C port to be closer to the edge of the keyboard, you can loosen the screws.</p></figcaption></figure>

### **Step 3**

Insert the LiPo battery.&#x20;

No special instructions for inserting the battery. As long as you obtained the correct battery, the connector will insert correctly. This is because the JST-PH socket can only accept the battery header in one direction.

<figure><img src="/files/dGCzSLoFfRsroLrHxkYz" alt="taikohub-dactyl-manuform-keyboard-bluetooth-nice-nanos-step-3"><figcaption><p>Figure 7.1.2.3 Step 3 - Insert the new Bluetooth enabled microcontroller and the LiPo battery.</p></figcaption></figure>

### **Step 4**

Put the cover back on. You did it 🎉! Proceed to the section on flashing your keyboard with ZMK.

<figure><img src="/files/R59sxKn4WTS4ECS0TFgP" alt="taikohub-dactyl-manuform-keyboard-bluetooth-nice-nanos-step-4"><figcaption><p>Figure 7.1.2.4 Step 4 - Put the cover back on.</p></figcaption></figure>
{% endtab %}

{% tab title="Keyboards shipped before 2022-08-01" %}

### **Step 1**

If your keyboard was shipped prior to 2022-08-01, you have 2 choices.

#### **Choice 1: Add a switch onto the keyboard**

* [ ] 2 x On-Off switches with wires attached. Compatible switches include [toggle switch](https://www.amazon.com/STARELO-Rocker-Switch-Latching-Pre-Wired/dp/B09BKXVCQ8/ref=sr_1_14?crid=10ULQMILV856\&keywords=latching+switch\&qid=1661997333\&sprefix=latching+switch%2Caps%2C105\&sr=8-14), [latching switch](https://www.amazon.com/Twidec-Latching-Self-Locking-Pre-soldered-L-PBS-110-XBK/dp/B086QTH8RW/ref=sr_1_5?crid=10ULQMILV856\&keywords=latching+switch\&qid=1661997312\&sprefix=latching+switch%2Caps%2C105\&sr=8-5) or slide switch. Momentary switches will not work.
* [ ] A Dupont connector kit such as this [one ](https://www.amazon.com/Connector-Crimper-Connectors-Ratcheting-AWG28-18/dp/B0B4BKX3H6/ref=sr_1_1_sspa?crid=24D9U7IQM19EH\&keywords=crimping+tool+female+pin+header\&qid=1661997633\&sprefix=crimping+tool+female+pin+heade%2Caps%2C105\&sr=8-1-spons\&psc=1\&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEyVk9ZRzBYSk1HN1dGJmVuY3J5cHRlZElkPUExMDQ2NjA0MVpIWFJTREVMN1E5JmVuY3J5cHRlZEFkSWQ9QTAxNTY4MDkzTVRPRllMS0U0MDkyJndpZGdldE5hbWU9c3BfYXRmJmFjdGlvbj1jbGlja1JlZGlyZWN0JmRvTm90TG9nQ2xpY2s9dHJ1ZQ==)will include the necessary tools below:
  * [ ] Crimping tool
  * [ ] 2 x female 2-pin header shells
  * [ ] 2 x female 2-pin header pins

Crimp the Dupont connectors onto the On-Off switch. To see how this is done, check [this excellent guide from **I**nstructables](https://www.instructables.com/Make-a-Good-Dupont-Pin-Crimp-EVERY-TIME/).

<div><figure><img src="/files/lnfx5tfiMYuB9qbnKyBV" alt="taikohub-dactyl-manuform-keyboard-bluetooth-latching-switch"><figcaption><p>Latching switch</p></figcaption></figure> <figure><img src="/files/kNqYCex6zhPdGAxnkBF2" alt="taikohub-dactyl-manuform-keyboard-bluetooth-toggle-switch"><figcaption><p>Toggle switch</p></figcaption></figure></div>

#### **Choice 2: Use a wire**

* [ ] 2 x Wire with female pin headers on both ends

It's not the most exciting, but it works. Although the keyboard would remain 'ON' until you disconnect the wire or the battery runs out.

<figure><img src="/files/Bv3PI2MLbfZ4QduMZuR8" alt="taikohub-dactyl-manuform-keyboard-bluetooth-on-off-switch-wire"><figcaption><p>Wire with female 2-pin headers on both sides.</p></figcaption></figure>

### Step 2

a. Swap in your Bluetooth enabled microcontroller.

b. Attach the LiPo battery to the JST-PH socket indicated by the green arrow in Figure 7.7.

<figure><img src="/files/cBLbp7eWd11eXBTHzby2" alt="taikohub-dactyl-manuform-keyboard-bluetooth-swap-nice-nano"><figcaption><p>Figure 7.7. Keyboard with nice!nano microcontroller. Green arrow indicates the JST-PH socket for the Lipo battery. Purple arrow indicates pin headers for the on-off switch.</p></figcaption></figure>

c. Attach the female pin headers of the on-off switch as indicated by the purple arrow in Figure 7.7. It should attach to the two male pin headers on the top right as indicated by the red arrows in Figure 7.8. The orientation doesn't matter.&#x20;

If you are using a wire, connect one end to position 1 and another to position 3 as indicated in Figure 7.8. Note that if you use a wire, the keyboard would remain 'ON' until you disconnect the wire.

<figure><img src="/files/V7DB2jG5ftZC5FBNxtHm" alt="taikohub-dactyl-manuform-keyboard-bluetooth-pcb-pin-headers"><figcaption><p>Figure 7.8. Attach the on-off switch to the two male pin headers on the top right as indicated by the red arrows.</p></figcaption></figure>

d. Put the cover back on. You did it 🎉! Proceed to the section on flashing your keyboard with ZMK.
{% endtab %}
{% endtabs %}


# 8. Tenting Your Keyboard (Version 2022-07-01)

(3 min read)

### 8.1 Tenting your keyboard with plastic attachments

Insert the plastic attachments into the slots on the base plate. It's a tight fit so it helps to wiggle it in. Similarly, the attachments should be removed by wigging them out.

<figure><img src="/files/-MjbacBGxjHFHgPEpKV6" alt="taikohub-dactyl-manuform-keyboard-plastic-tents-step-1"><figcaption><p>Figure 8.1. Slots for the plastic attachment</p></figcaption></figure>

<figure><img src="/files/-Mjbb6eNi4aN12HecUo4" alt="taikohub-dactyl-manuform-keyboard-plastic-tents-step-2"><figcaption><p>Figure 8.2. Base plate with plastic attachment inserted partially to illustrate the insertion.</p></figcaption></figure>


# 9. Troubleshooting (Version 2022-07-01)

### 9.1 Opening up the base plate

#### Resin Keyboards

* Use a 6mm Allen key to loosen the screws.

#### PLA Keyboards

* Use a 3mm Allen key to loosen the screws.&#x20;
* Please turn the screws **slowly** and **gently**. About 1/4 turn per second is a good speed.
* It may seem counterintuitive, but turning the screws too quickly or applying too much downward pressure will make it **harder** to tighten or loosen the screws. It can also damage the screw threads.&#x20;

{% hint style="danger" %}
**PLA Keyboards**: Turn the screws **slowly** and **gently.** Turning too quickly or applying too much downward pressure can damage the screw threads!
{% endhint %}

### 9.2 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller.

### 9.3 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes the keyboard connected to it is the left side. It assumes the right side is other piece.

If you had not disconnected the TRRS cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.

### 9.4 Thumb cluster not working after flashing right side of the keyboard

If the right side of the keyboard is directly connected to the computer, some keys on the thumb cluster will not register. This is normal. Simply make sure USB cable is connected to the left side of the keyboard and the TRRS cable is connected to the right side of the keyboard. The keyboard should start working as normal.

### 9.5 Keyboard doesn't register any keys

If you are using a different USB cord from the one that came with your keyboard, it may be a USB cord issue. Check to see if the keyboard works with the default USB cord. Certain USB cords do not play well with the microcontroller. If you are using a USB-C to USB-C cord, try switching which side of the cord you plug into the computer and which side you plug into the keyboard. This can sometimes resolve the problem.&#x20;

### 9.6 My problem isn't mentioned in the documentation

Please share it in the GitHub discussion section seen below.

{% embed url="<https://github.com/taikohub/dactyl-manuform-documentation/discussions/categories/general>" %}


# 9.1 Troubleshooting: QMK Toolbox (Version 2022-07-01)

QMK Toolbox is the graphical interface for Windows and Mac. It is not compatible with Linux.

<details>

<summary>9.1.1 <code>read error: The I/O operation has been aborted because of either a thread exit or an application request.</code></summary>

Problem: You tried to flash with QMK Toolbox. It completed the flash, but the keyboard didn't get flashed with your new keymapping at all. You see an output similar to the following in QMK Toolbox.

```
Caterina device connected (usbser): Arduino LLC (www.arduino.cc) Arduino Leonardo bootloader (COM6) (2341:0036:0001) [COM6] Attempting to flash, please don't remove device
avrdude.exe -p atmega32u4 -c avr109 -U flash:w:"C:\Users\username\Desktop\firmware\qmk\windows\five\handwired_dactyl_manuform_5x6.hex":i -P COM6 avrdude.exe: ser_drain(): read error: The I/O operation has been aborted because of either a thread exit or an application request.

Connecting to programmer: .avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_drain(): read error: The device does not recognize the command.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding

avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_drain(): read error: The device does not recognize the command.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding Found programmer: Id = "‹"; type = > Software Version = â.·; Hardware Version = ö. avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: buffered memory access not supported. Maybe it isn't a butterfly/AVR109 but a AVR910 device? avrdude.exe: initialization failed, rc=-1 Double check connections and try again, or use -F to override this check.

avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: programmer did not respond to command: leave prog mode avrdude.exe: ser_send(): write error: sorry no info avail avrdude.exe: ser_recv(): read error: The device does not recognize the command.

avrdude.exe: butterfly_recv(): programmer is not responding avrdude.exe: error: programmer did not respond to command: exit bootloader
avrdude.exe done. Thank you.
```

Possible Causes:

a. Another computer peripheral is interfering with QMK Toolbox. Try disconnecting anything connected to the computer except the keyboard. A computer peripheral is anything that physically connects to your computer, and includes: mouse, phone, cables, monitors, another keyboard, among others.

b. If the above doesn't work, please contact <david@taikohub.com>

</details>


# 10. Terminology (Version 2022-07-01)

**Keycode:** The output after you press a keyswitch. For example, "Q" or "F11".

**Keymap:** Also called keyboard layout. Examples of keymaps include QWERTY, DVORAK, Colemak.

**Layers:**  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

**Layer Key:** The keycode you use to switch to a different layer. If you are using QMK Configurator, you'll see M(0) or M(1). If you are following [4. Customizing Keyboard Layout for Linux with QMK (Version 2022-07-01)](/version-2022-07-01/customizing-keyboard-layout-for-linux-with-qmk), you'll see the RAISE and LOWER layer keys in the default dactyl\_manuform/5x6 layout.

**QMK Toolbox:** A software tool used to flash a new layout onto your keyboard. It is available on Mac and Windows.

**Flashing:** Refers to when you install software onto your keyboard.

**QMK Configurator:** A website that allows you to create a custom keyboard layout and export the layout as a `.hex` file. This file is then used in QMK Toolbox.

**QMK CLI:** QMK's official command line interface tool.

**Microcontroller:** A microcontroller is a small device that controls your keyboard. Each piece of your keyboard comes with a Pro Micro microcontroller. You may come across it abbreviated as MCU, which stands for MicroController Unit.

**Firmware:** The software installed on microcontrollers to make your keyboard work. QMK firmware and ZMK firmware are examples.


# 11. Changelog (Version 2022-07-01)

The following describes changes to the [TaikoHub dactyl manuform keyboard](https://taikohub.com).

**2022-07-12**: Medium sized keyboards (keyboards with 5 keyed thumb clusters) shipped July 12, 2022 or later, it's default layer will  have the keymap shown in Figure 9.1. For keyboards shipped prior to July 12, 2022, please see keymap from Version 2022-01-10.

<figure><img src="/files/rOSB0UP2OPlpYhBoA9vv" alt="taikohub-dactyl-manuform-keyboard-five-keyed-thumb-cluster-old-keyboard-layout"><figcaption><p>Figure 11.1. Default keymap layer for medium sized keyboards shipped July 12, 2022 or later.</p></figcaption></figure>

<figure><img src="/files/-MjLrgvRgLrULxLQ_g9r" alt="taikohub-dactyl-manuform-keyboard-five-keyed-thumb-cluster-new-keyboard-layout"><figcaption><p>Figure 11.2. Default keymap layer for medium sized keyboards shipped earlier than July 12, 2022.</p></figcaption></figure>

**2022-08-01**: All keyboards shipped after Aug 1, 2022 have a TRS port and come with a TRS cord. Though TRRS cords will also work. Keyboards shipped prior to this date have a TRRS port and come with a TRRS cord. TRS cords will not work.

<figure><img src="/files/a2Pnhv0OyeEmtBQX2UoU" alt="taikohub-dactyl-manuform-keyboard-trrs-vs-trs-port"><figcaption><p>Figure 11.3 Keyboards shipped Aug 1 2022  or later have a TRS cord. Keyboards shipped prior to Aug 1 2022 have a TRRS port.</p></figcaption></figure>

**2022-08-01:** All keyboards shipped after Aug 1, 2022 no longer come with long M3 screws. Screw based tenting no longer officially supported due to lack of interest.


# 12. Hardware Issues Tracking (Version 2022-07-01)

If you have any hardware issues with your new keyboard, please email `david@taikohub.com`. Please email even if you fixed the issue, so that we can keep track of it.

<details>

<summary>PCB is Lifted Away from Keyboard</summary>

Incidences: 1 report of this issue as of Sep-11-2022.

Description: You plug in your new keyboard and find many keys do not work. You open up the keyboard with a 3mm allen key and find the PCB lifted. It's lifted enough that you see Kailh sockets do not come in contact with the switches at all.

Repair: Gently put one finger on the Kailh socket on the inside of the keyboard while you push the keyswitch into the keyboard on the other side. There's no need to push very hard with your other finger.

Reporting: Please report to `david@taikohub.com` or on the website chat widget. Thank you.

</details>


# 1. Introduction (Version 2021-09-11)

Thank you for purchasing a dactyl manuform keyboard. The user guide will be continuously updated.&#x20;

Please make sure you selected the correct keyboard version on the left. Version refers to the date of shipment. For example, Version 2021-06-24 refers to any keyboard shipped from 2021-06-24 to 2021-09-11. Version 2021-09-11, the most current version, refers to any keyboards shipped after 2021-09-11.

1.1 Default keymap for the dactyl manuform 5x6 with 6 keyed thumb cluster

![](/files/-Md0KCzsDDH0pg_LX1_y)

![](/files/-Md0KELhTFH-ARglV0aQ)

![](/files/-Md0KR5B1hIf_acfZgZC)

1.2 Default keymap for the dactyl manuform 5x6 with 5 keyed thumb cluster

![](/files/-MjLrgvRgLrULxLQ_g9r)

![](/files/-MjLrlbqzXY8Q2oClvfp)

![](/files/-MjLroWFPagghsVut7fV)

1.3 Default keymap for the dactyl manuform 5x6 with 3 keyed thumb cluster

{% hint style="info" %}
For the 3 keyed thumb cluster keyboards, the keymap for the thumb cluster in QMK corresponds to a keyswitch at a different position on your keyboard. Figure 1 shows that the physical keys for the thumb cluster is shifted by 1 key towards the right compared to the QMK keymap. Below presents the same idea in a different format:

QMK Keymap:                                    MO(2) -- Space -- Backspace

Physical Keyboard:   Backspace -- MO(2) -- Space
{% endhint %}

![Figure 1. The QMK GUI keymap position map to a different physical position for the thumb cluster.](/files/-Mki-IkFSQZYFTP0S6K5)

![](/files/-Mkhs70h0pzHIwAz3xfk)

![](/files/-MkhtN5-pzuIvC5aKuHy)

![](/files/-MkhtRvVKUa5dM5tFx2O)


# 2. About Your Keyboard (Version 2021-09-11)

2.1 Compatible keycaps

The keyboard comes with DSA keycaps, but is also compatible with SA and XDA keycaps. All keycaps must be 1u in size to fit this keyboard, with the exception of the thumb cluster, which can fit up to 1.5u depending on the number of keys on the thumb cluster. A 6-keyed thumb cluster will be able to fit two 1.5u keys on each side of the keyboard. A 3-keyed thumb cluster will be able to fit three 1.5u keys on each side.  The 5-keyed thumb cluster does not fit any 1.5u keys.

2.2 Non-hotswappable keyboards

Not recommended to open the back plate unless there are issues.

2.3 Compatible keyswitches for hotswappable keyboards

The hotswappable keyboard come with Kailh hotswap sockets, which are compatible with MX Cherry switches and clones including Kailh and Gateron switches. They are not compatible with low profile switches. Both three and five legged switches will work, but **five legged switches are substantially easier to insert**.

![Figure 2.1. The 5-leg keyswitches are preferred, but 3-leg switches will still work.](/files/-Md-CCTxdBbmadiex9Ln)


# 3. Customizing Keyboard Layout for Windows and Mac with QMK (Version 2021-09-11)

QMK Toolbox currently does not support Linux. See section 4 instead.

3.1 Navigate to  [QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) to begin creating a custom key map for your keyboard.

![Figure 3.1. QMK Configurator](/files/-MdNZAzBYbrwRHKUSYw6)

A. Keyboard: Selects pre-configured key mappings. Typing in dactyl will bring up a list of different variations of the dactyl\_manuform keymapping. Select handwired/dactyl\_manuform/5x6 here.

B. Keymap Name: Enter a name for your custom keymap. Eventually, QMK will generate a hex file with the name `handwired_dactyl_manuform_5x6_your_keymap_name.hex`

C. Download keymap.json: Downloads a keymap.json file with your current keymapping. This file saves your progress as you create a new keymap. You can return to your save point by uploading the keymap.json file on the QMK Configurator website. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

D. Upload keymap.json: As described in *C*, this gives you the option to upload the keymap.json file to return to your save point.

E. Layers: Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. In *Figure 3.1*, layer 0 is selected. Clicking on 1 or 2 in the layer section will bring up a different keymap.&#x20;

A layer key is what you actually press on your keyboard to switch to a different layer. On the keymap in *Figure 3.1*, the layer keys look like "MO(1)" or "MO(2)". The MO(layer) stands for Momentarily activating the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap in *Figure 3.1*, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.&#x20;

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

F. Keycodes: Drag the keycode onto the keymap to replace the key. As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. You'll find the MO(layer) and DF(layer) keys by navigating to *Quantum > Layer* *and Layer Tap functions.*

G. When you are finished customizing your keymap, click compile. You should see a nice rotating potato baking in outerspace. Once QMK has finished compiling, the Download Firmware button should become clickable.

H. Download Firmware: Download the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file. You will use this to flash your keyboard.

3.2 Open the website to [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases), which is used to flash the hex file onto your keyboard.

![Figure 3.2. QMK Toolbox website navigation](/files/-MdNo47Op8rilV153B70)

A. Check that you are looking at the latest release. As of this writing, the latest version is 0.0.21. This could be different from what you see.

B. Download QMK.Toolbox.pkg if you use a Mac.

C. Download qmk\_toolbox.exe if you use Windows.

3.3 Open QMK.Toolbox.pkg or qmk\_toolbox.exe. If you are opening QMK Toolbox for the first time on Windows, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select "Yes".

![Figure 3.3. QMK Toolbox Navigation](/files/-MdNxdKlCeYcwbzJyJDP)

A.  Install Drivers: If this is your first time using QMK Toolbox on your Windows PC and you did not see the install drivers dialogue box, right click the bottom bar of the QMK Toolbox and select Install Drivers.

B. Open Local File: Open the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file you previously downloaded.

C. Make sure it says atmega32u4. If it doesn't, it select from the drop down.

D. Select Auto-Flash. **Do not click Flash yet!** First ensure your keyboard is unplugged from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Then connect only one piece of the keyboard to your computer via USB.

E. After ensuring only one piece of the keyboard is connected to your computer and the RJ9 cord is disconnected from both sides, click Flash. The toolbox will wait for you as you perform the following step.

3.4 Next, double click the reset button seen in Figure 3.4. You will need to use a stick or a pen to click it.

![Figure 3.4. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

3.5 Repeat sections 2.4 and 2.5 for the other piece of your keyboard.

3.6 Make sure both pieces of the keyboard are not connected to your computer. Connect the RJ9 cord to the two pieces. Then connect the USB cord from the **left** keyboard to the computer.


# 4. Customizing Keyboard Layout for Linux with QMK (Version 2021-09-11)

4.1 Instructions

```
$ Text after the $ sign refers to what is typed into the terminal.
```

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

4.2 Install the QMK CLI if you have not used it before

```
$ python3 -m pip install --user qmk
$ qmk setup
```

4.3 Test that the QMK CLI tool works by compiling a keymapping. Here I use the clueboard/66/rev3 keymap

```
$ qmk compile -kb clueboard/66/rev3 -km default
```

You should see a message similar to below:

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

4.4 Create a custom keymap

```
$ qmk new-keymap -kb handwired/dactyl_manuform/5x6
```

You'll then be prompted to give a name to the keymap. Here I give it the name `keyboard_alpaca`.

4.5 Edit the keymap.c file with your preferred editor.

```
$ nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/keyboard_alpaca/keymap.c
```

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://beta.docs.qmk.fm/using-qmk/software-features/feature_layers#switching-and-toggling-layers-id-switching-and-toggling-layers) on the QMK website.

A layer key is what you press on your keyboard to switch to a different layer. The RAISE and LOWER keycodes raises and lowers the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap, you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

\[QWERTY] = LAYOUT5x6(...) refers to the default base layer.

See *Figure 4.1* below as reference for what key to use, or the table linked [here](https://docs.qmk.fm/#/keycodes). As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS.

![Figure 4.1. Basic keycodes](/files/-MdKGRZy6-E6C9x9Bo1x)

4.6 Flash the firmware.

Unplug your keyboard from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Connect one piece of the keyboard to your computer via USB.&#x20;

```
$ qmk flash -kb handwired/dactyl_manuform/5x6 -km keyboard_alpaca
```

When you see "Detecting USB port, reset your controller now\..." in the terminal, click the keyboard reset button twice.&#x20;

![Figure 4.2. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

4.7 Repeat section 4.6 with the other piece of the keyboard.&#x20;

4.8 Make sure no keyboard is connected to your computer before attaching the RJ9 cord to both pieces of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the **left** keyboard.


# 5. Hot Swapping Keyswitches (Version 2021-09-11)

Each piece of your keyboard contains a PCB. The PCB on each side will look and feel different. Please read the entire page before you hot swap your keyboard.

5.1 Necessary tools and components

* Keyswitches: **5-legged keyswitches are substantially easier to insert.** This does not change anything if your keyboard already has 3-legged keyswitches inserted. It will work as intended. But when hot swapping, 5-legged switches have been found to be much easier to work with. &#x20;
* 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key)
* Keyswitch puller
* Keycap puller (Included)

5.2 Remove keycaps

Remove all the keycaps with the keycap puller that came with your keyboard. It should not take much force for the keycap to come off.&#x20;

5.3 Open the base plate

See section 7.1 in [Troubleshooting ](/version-2021-09-11/troubleshooting)on how to open the base plate.

5.4 Remove a single keyswitch

In general, you should hot swap a single keyswitch at a time. This is because the PCB is stretched taut and is stabilized by the keyswitches. Removing one keyswitch at a time will minimize movement of the PCB and avoid needless hassle later on.&#x20;

Pull out the keyswitch gently, it should not take a lot of force. If the keyswitch is not coming out, try orienting it from a different angle.&#x20;

{% hint style="warning" %}
When removing keyswitches, make sure to use a keyswitch puller. Do not use pliers. It will damage the components.&#x20;
{% endhint %}

5.5 Insert the new keyswitch

This section is a bit of a longer read. But after doing it once, it's much faster to do subsequent times. The video at the bottom of this section is not comprehensive. You should still read this section to prevent damaging the keyboard.

The base plate of the keyboard should already be open. Put one finger on the Kailh socket from the inside of the keyboard. In a subsequent step, you will put pressure on the socket while you insert the new keyswitch.&#x20;

Align the keyswitch pins with the copper slots on the Kailh sockets, which are shown in Figure 5.1. It may help to wiggle the keyswitch back and forth while keeping the keyswitch pins near the slots. If you feel a bit of resistance while wiggling, the pins are likely aligned.

![Figure 5.1. Kailh socket copper slots](/files/-MjbITqmvZyslHo26I5Z)

While putting a gentle amount of pressure on the Kailh socket, push the keyswitch into the slots.&#x20;

{% hint style="info" %}
The primary purpose of putting pressure on the Kailh socket is to allow the keyswitch pins to squeeze into the slots. Otherwise, the pins will push the PCB away from it. The secondary purpose is to prevent the socket from breaking of the PCB in case of excessive force.&#x20;
{% endhint %}

{% hint style="warning" %}
It should not take a lot of force to insert the keyswitch into the keyboard. Generally, it should only require the force of one finger. If the keyswitch is not going into the socket, try to realign it then try again. Each keyswitch sockets for this keyboard is at a different angle, so it may take a few times before insert it.&#x20;

If the keyswitch is still not going in despite trying a few times, try applying less pressure to the Kailh socket.
{% endhint %}

After inserting the keyswitch, the PCB will sit a few milimeters above the surface of the keyboard. This is expected. In fact, applying too much pressure on the Kailh socket can prevent the keyswitch from fully locking onto the keyboard. This is because the keyswitch cannot fully insert into the keyboard unless the PCB sits slightly above the surface of the keyboard. To visualize why this is, see Figure 5.2 below.

![Figure 5.2. Applying excessive pressure to the socket can prevent keyswitch from fully inserting](/files/-Mjb7o9lfYj79SK-KDl9)

5.6 Close the base plate

See section 7.2 in [Troubleshooting ](/version-2021-09-11/troubleshooting)on how to close the base plate.


# 6. Tenting Your Keyboard (Version 2021-09-11)

6.1 Tenting your keyboard with plastic attachments

Insert the plastic attachments into the slots on the base plate. It's a tight fit so it helps to wiggle it in. Similarly, the attachments should be removed by wigging them out.

{% hint style="warning" %}
Don't use excessive force when pushing or pulling the attachments. It can damage the base plate.
{% endhint %}

![Figure 6.1. Slots for the plastic attachment](/files/-MjbacBGxjHFHgPEpKV6)

![Figure 6.2. Base plate with plastic attachment inserted partially to illustrate the insertion.](/files/-Mjbb6eNi4aN12HecUo4)

6.2 Tenting your keyboard with screws

If you want to adjust the tenting to an exact angle, you can replace the two M3 screws with longer screws at your preferred length. The screws that came with the keyboard are 5mm in length.&#x20;

![Figure 6.3. These two M3 screws can be replaced](/files/-MjbdW6MIMmrI0AIT1lv)


# 7. Troubleshooting (Version 2021-09-11)

7.1 Opening the base plate

Take out the screws with a 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key) then very slowly lift the plate. The plate is different from the open source design and has a holder for the USB adapter. Lifting with too much force could damage the USB adapter and the microcontroller.

Next, slide the USB adapter off the side of the holder before fully lifting the base plate. Figure 7.1 shows how the USB holder is attached on the base plate. Leave the USB adapter attached to the microcontroller, as the micro-USB port on the ProMicro can be fragile and easily dislodged.

![Figure 7.1. USB adapter holder highlighted in yellow](/files/-MjbT_SqPMJo0ov_tjSR)

7.2 Closing the base plate

When you close the base plate, the USB holder may push on some of the wiring. You shouldn't need to use force to close the base plate. If the base plate doesn't close with gentle pressure, carefully push away some of the wiring to make room for the USB holder.

Tighten the screws with an Allen key.

Always wash your hands after handling the insides of the keyboard.

7.2 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller.

7.3 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes that left side is the piece directly connected to it. It assumes the right side is other piece.

If you had not disconnected the RJ9 cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.

7.4 Thumb cluster not working after flashing right side of the keyboard

If the right side of the keyboard is directly connected to the computer, some keys on the thumb cluster will not register. This is normal. Simply make sure USB cable is connected to the left side of the keyboard and the RJ9 cable is connected to the right side of the keyboard. The keyboard should start working as normal.


# 8. Terminology (Version 2021-09-11)

8.1 Keycode: The output after you press the key. For example, "Q" or "F11".

8.2 Keymapping: Your custom keyboard layout. For example, QWERTY or DVORAK.

8.3 Layers:  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

8.4 Layer Key: The keycode you use to switch to a different layer. If you are using the QMK Configurator web tool, you'll see M(0) or M(1). If you follow section 4, you'll see RAISE and LOWER in the default dactyl\_manuform/5x6 keymapping.


# 1. Introduction (Version 2021-06-24)

Thank you for purchasing a dactyl manuform keyboard. The user guide will be continuously updated for your reference.

1.1 Default keymap for the dactyl manuform 5x6 with 6 keyed thumb cluster

![](/files/-Md0KCzsDDH0pg_LX1_y)

![](/files/-Md0KELhTFH-ARglV0aQ)

![](/files/-Md0KR5B1hIf_acfZgZC)

1.2 Default keymap for the dactyl manuform 5x6 with 5 keyed thumb cluster

![](/files/-MjLrgvRgLrULxLQ_g9r)

![](/files/-MjLrlbqzXY8Q2oClvfp)

![](/files/-MjLroWFPagghsVut7fV)

1.3 Default keymap for the dactyl manuform 5x6 with 3 keyed thumb cluster

![](/files/-Md0MODTK367EDSMjGZW)

![](/files/-Md0MODWpb2-EF0Jmd99)

![](/files/-Md0MODXS6tmg0QFT7fL)


# 2. About Your Keyboard (Version 2021-06-24)

2.1 Compatible keycaps

The keyboard comes with DSA keycaps, but is also compatible with SA keycaps. All keycaps must be 1u in size to fit this keyboard, with the exception of the thumb cluster, which can fit up to 1.5u depending on the number of keys on the thumb cluster. A regular dactyl manuform with a 6-keyed thumb cluster, will be able to fit two 1.5u keys on each side of the keyboard.

2.2 Compatible keyswitches (Hotswappable keyboard)

The hotswappable keyboard come with Kailh hotswap sockets, which are compatible with MX Cherry switches and clones including Kailh and Gateron switches. They are not compatible with low profile switches. The keyboard only supports three legged switches.

![Figure 2.1. Only 3-leg keyswitches are compatible.](/files/-Md-CCTxdBbmadiex9Ln)


# 3. Customizing Keyboard Layout for Windows and Mac with QMK (Version 2021-06-24)

QMK Toolbox currently does not support Linux. See section 4 instead.

3.1 Navigate to  [QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) to begin creating a custom key map for your keyboard.

![Figure 3.1. QMK Configurator](/files/-MdNZAzBYbrwRHKUSYw6)

A. Keyboard: Selects pre-configured key mappings. Typing in dactyl will bring up a list of different variations of the dactyl\_manuform keymapping. Select handwired/dactyl\_manuform/5x6 here.

B. Keymap Name: Enter a name for your custom keymap. Eventually, QMK will generate a hex file with the name `handwired_dactyl_manuform_5x6_your_keymap_name.hex`

C. Download keymap.json: Downloads a keymap.json file with your current keymapping. This file saves your progress as you create a new keymap. You can return to your save point by uploading the keymap.json file on the QMK Configurator website. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

D. Upload keymap.json: As described in *C*, this gives you the option to upload the keymap.json file to return to your save point.

E. Layers: Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. In *Figure 3.1*, layer 0 is selected. Clicking on 1 or 2 in the layer section will bring up a different keymap.&#x20;

A layer key is what you actually press on your keyboard to switch to a different layer. On the keymap in *Figure 3.1*, the layer keys look like "MO(1)" or "MO(2)". The MO(layer) stands for Momentarily activating the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap in *Figure 3.1*, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.&#x20;

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

F. Keycodes: Drag the keycode onto the keymap to replace the key. As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. You'll find the MO(layer) and DF(layer) keys by navigating to *Quantum > Layer* *and Layer Tap functions.*

G. When you are finished customizing your keymap, click compile. You should see a nice rotating potato baking in outerspace. Once QMK has finished compiling, the Download Firmware button should become clickable.

H. Download Firmware: Download the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file. You will use this to flash your keyboard.

3.2 Open the website to [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases), which is used to flash the hex file onto your keyboard.

![Figure 3.2. QMK Toolbox website navigation](/files/-MdNo47Op8rilV153B70)

A. Check that you are looking at the latest release. As of this writing, the latest version is 0.0.21. This could be different from what you see.

B. Download QMK.Toolbox.pkg if you use a Mac.

C. Download qmk\_toolbox.exe if you use Windows.

3.3 Open QMK.Toolbox.pkg or qmk\_toolbox.exe. If you are opening QMK Toolbox for the first time on Windows, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select "Yes".

![Figure 3.3. QMK Toolbox Navigation](/files/-MdNxdKlCeYcwbzJyJDP)

A.  Install Drivers: If this is your first time using QMK Toolbox on your Windows PC and you did not see the install drivers dialogue box, right click the bottom bar of the QMK Toolbox and select Install Drivers.

B. Open Local File: Open the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file you previously downloaded.

C. Make sure it says atmega32u4. If it doesn't, it select from the drop down.

D. Select Auto-Flash. **Do not click Flash yet!** First ensure your keyboard is unplugged from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Then connect only one piece of the keyboard to your computer via USB.

E. After ensuring only one piece of the keyboard is connected to your computer and the RJ9 cord is disconnected from both sides, click Flash. The toolbox will wait for you as you perform the following step.

3.4 Next, double click the reset button seen in Figure 3.4. You will need to use a stick or a pen to click it.

![Figure 3.4. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

3.5 Repeat sections 2.4 and 2.5 for the other piece of your keyboard.

3.6 Make sure both pieces of the keyboard are not connected to your computer. Connect the RJ9 cord to the two pieces. Then connect the USB cord from the **left** keyboard to the computer.


# 4. Customizing Keyboard Layout for Linux with QMK (Version 2021-06-24)

4.1 Instructions

`$ Text after the $ sign refers to what is typed into the terminal.`

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

4.2 Install the QMK CLI if you have not used it before.

`$ python3 -m pip install --user qmk`

`$ qmk setup`

4.3 Test that the QMK CLI tool works by compiling a keymapping. Here I use the clueboard/66/rev3 keymap.

`$ qmk compile -kb clueboard/66/rev3 -km default`

You should see a message similar to below:

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

4.4 Create a custom keymap.

`$ qmk new-keymap -kb handwired/dactyl_manuform/5x6`

You'll then be prompted to give a name to the keymap. Here I give it the name `keyboard_alpaca`.

4.5 Edit the keymap.c file with your preferred editor.

`$ nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/keyboard_alpaca/keymap.c`

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://beta.docs.qmk.fm/using-qmk/software-features/feature_layers#switching-and-toggling-layers-id-switching-and-toggling-layers) on the QMK website.

A layer key is what you press on your keyboard to switch to a different layer. The RAISE and LOWER keycodes raises and lowers the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap, you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

\[QWERTY] = LAYOUT5x6(...) refers to the default base layer.

See *Figure 4.1* below as reference for what key to use, or the table linked [here](https://docs.qmk.fm/#/keycodes). As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS.

![Figure 4.1. Basic keycodes](/files/-MdKGRZy6-E6C9x9Bo1x)

4.6 Flash the firmware.

Unplug your keyboard from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Connect one piece of the keyboard to your computer via USB.&#x20;

`$ qmk flash -kb handwired/dactyl_manuform/5x6 -km keyboard_alpaca`

When you see "Detecting USB port, reset your controller now\..." in the terminal, click the keyboard reset button twice.&#x20;

![Figure 4.2. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

4.7 Repeat section 4.6 with the other piece of the keyboard.&#x20;

4.8 Make sure no keyboard is connected to your computer before attaching the RJ9 cord to both pieces of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the **left** keyboard.


# 5. Hot Swapping Keyswitches (Version 2021-06-24)

5.1 Removing keyswitches

When removing keyswitches, make sure to use a keyswitch puller. Do not use pliers. It will damage the components.

5.2 Inserting keyswitches

You do not need to use a lot of force when inserting keyswitches. You should be able to insert it with the force of just one finger. If the keyswitch is not going into the socket, try to realign it then try again. Each keyswitch sockets for this keyboard is at a different angle, so it may take a few times before you insert it. It may help to slightly wiggle the keyswitch to see if the metal pins have inserted into the Kailh sockets.

Using an excessive amount of force might loosen a Kailh hotswap socket, although it should not be possible to dislodge a socket without breaking the keyboard. If you notice a keyswitch is not working after inserting new keyswitches, see section 6.2 to troubleshoot.


# 6. Troubleshooting (Version 2021-06-24)

6.1 Opening the base plate

Take out the screws, then very slowly lift the plate. The plate is different from the open source design and has a holder for the USB adapter. Slide the USB adapter off the side of the holder before fully lifting the base plate. *Figure 1* shows how the USB holder is attached on the base plate.

When you close the base plate, the USB holder may push on some of the wiring. You shouldn't need to use force to close the base plate. If the base plate doesn't close with gentle pressure, carefully push away some of the wiring to make room for the USB holder. *Figure 2* shows the space occupied by the USB holder when the base plate is closed.

When closing the base plate, tighten the screws with your fingers. Using an [Allen Key](https://en.wikipedia.org/wiki/Hex_key) will loosen the brass screw inserts.

Always wash your hands after handling the insides of the keyboard.

![Figure 1. Base plate for the left keyboard. Yellow arrow points to the USB holder.](/files/-MdO8qTlJSw_excRXjZn)

![Figure 2. 3D cross section of the left piece of the keyboard. Base plate rendered in blue. Case is in silver.](/files/-MdO6ewrgHtIey-HDSgE)

6.2 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller. If you have a hotswappable keyboard, check to see if any hotswap sockets are loose by pushing on them.

6.3 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes that left side is the piece directly connected to it. It assumes the right side is other piece.

If you had not disconnected the RJ9 cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.


# 7. Terminology (Version 2021-06-24)

7.1 Keycode: The output after you press the key. For example, "Q" or "F11".

7.2 Keymapping: Your custom keyboard layout. For example, QWERTY or DVORAK.

7.3 Layers:  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

7.4 Layer Key: The keycode you use to switch to a different layer. If you are using the QMK Configurator web tool, you'll see M(0) or M(1). If you follow section 4, you'll see RAISE and LOWER in the default dactyl\_manuform/5x6 keymapping.


# 1. Introduction (Version 2022-01-10)

Thank you for purchasing a dactyl manuform keyboard. This user guide will be continuously updated. If you have any questions, please email me anytime at <david@taikorobotics.com>. I will try to get back to you as soon as I can.

Please make sure you selected the correct keyboard version on the left. Version refers to the date of shipment. For example, Version 2021-06-24 refers to any keyboard shipped from 2021-06-24 to 2021-09-11. Version 2022-01-10, the most current version, refers to any keyboards shipped after 2022-01-10.

1.1 Getting started

Your keyboard should work without any configurations. Simply plug in the USB cord to the left side of the keyboard. Your keyboard comes pre-flashed with the default keymap seen in sections 1.1 to 1.3 below.

The rest of the documentation discusses how to customize the keyboard.

1.1 Default keymap for the dactyl manuform 5x6 with 6 keyed thumb cluster

![](/files/-Md0KCzsDDH0pg_LX1_y)

![](/files/-Md0KELhTFH-ARglV0aQ)

![](/files/-Md0KR5B1hIf_acfZgZC)

1.2 Default keymap for the dactyl manuform 5x6 with 5 keyed thumb cluster

![](/files/-MjLrgvRgLrULxLQ_g9r)

![](/files/-MjLrlbqzXY8Q2oClvfp)

![](/files/-MjLroWFPagghsVut7fV)

1.3 Default keymap for the dactyl manuform 5x6 with 3 keyed thumb cluster

![](/files/-Mkhs70h0pzHIwAz3xfk)

![](/files/-MkhtN5-pzuIvC5aKuHy)

![](/files/-MkhtRvVKUa5dM5tFx2O)


# 2. About Your Keyboard (Version 2022-01-10)

2.2 Compatible keycaps

Compatible keycap profiles (keycap shapes): DSA, XDA, SA Row 3 and MA. The keyboard comes with DSA keycaps.

Keycaps that are 1u in size will fit every key on every keyboard.&#x20;

There is the option to use 1.5u sized keycaps for the 6-keyed thumb cluster, which is able to fit two 1.5u keys on each side of the keyboard. The 3-keyed thumb cluster is also able to fit three 1.5u keys on each side.  The 5-keyed thumb cluster does not fit any 1.5u keys.

2.3 Compatible keyswitches for hotswapping

The keyboard is best used with **5 legged switches** (Figure 2.1) although 3 legged switches should still work. It is compatible with **MX Cherry switches,** Gateron switches and Holy Panda switches.

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

![Figure 2.1. 5-leg keyswitches are preferred.](/files/-Md-CCTxdBbmadiex9Ln)


# 3. Customizing Keyboard Layout for Windows and Mac with QMK (Version 2022-01-10)

{% hint style="warning" %}
QMK Toolbox currently does not support Linux. See [Section 4](/version-2022-01-10/customizing-keyboard-layout-for-linux-with-qmk) instead.
{% endhint %}

3.1 Navigate to  [QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) to begin creating a custom key map for your keyboard.

![Figure 3.1. QMK Configurator](/files/-MdNZAzBYbrwRHKUSYw6)

A. Keyboard: Selects pre-configured key mappings. Typing in dactyl will bring up a list of different variations of the dactyl\_manuform keymapping. Select handwired/dactyl\_manuform/5x6 here.

B. Keymap Name: Enter a name for your custom keymap. Eventually, QMK will generate a hex file with the name `handwired_dactyl_manuform_5x6_your_keymap_name.hex`

C. Download keymap.json: Downloads a keymap.json file with your current keymapping. This file saves your progress as you create a new keymap. You can return to your save point by uploading the keymap.json file on the QMK Configurator website. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

D. Upload keymap.json: As described in *C*, this gives you the option to upload the keymap.json file to return to your save point.

E. Layers: Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. In *Figure 3.1*, layer 0 is selected. Clicking on 1 or 2 in the layer section will bring up a different keymap.&#x20;

A layer key is what you actually press on your keyboard to switch to a different layer. On the keymap in *Figure 3.1*, the layer keys look like "MO(1)" or "MO(2)". The MO(layer) stands for Momentarily activating the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap in *Figure 3.1*, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.&#x20;

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

F. Keycodes: Drag the keycode onto the keymap to replace the key. As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. You'll find the MO(layer) and DF(layer) keys by navigating to *Quantum > Layer* *and Layer Tap functions.*

G. When you are finished customizing your keymap, click compile. You should see a nice rotating potato baking in outerspace. Once QMK has finished compiling, the Download Firmware button should become clickable.

H. Download Firmware: Download the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file. You will use this to flash your keyboard.

3.2 Open the website to [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases), which is used to flash the hex file onto your keyboard.

![Figure 3.2. QMK Toolbox website navigation](/files/-MdNo47Op8rilV153B70)

A. Check that you are looking at the latest release. In the photo above, the latest version was 0.0.21. The latest release as of this writing is 0.1.1, but this could be different from what you see.

B. Download QMK.Toolbox.pkg if you use a Mac.

C. Download qmk\_toolbox.exe if you use Windows.

3.3 Open QMK.Toolbox.pkg or qmk\_toolbox.exe. If you are opening QMK Toolbox for the first time on Windows, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select "Yes".

![Figure 3.3. QMK Toolbox Navigation](/files/-MdNxdKlCeYcwbzJyJDP)

A.  Install Drivers: If this is your first time using QMK Toolbox on your Windows PC and you did not see the install drivers dialogue box, right click the bottom bar of the QMK Toolbox and select Install Drivers.

B. Open Local File: Open the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file you previously downloaded.

C. Make sure it says atmega32u4. If it doesn't, it select from the drop down.

D. Select Auto-Flash. **Do not click Flash yet!** First ensure your keyboard is unplugged from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Then connect only one piece of the keyboard to your computer via USB.

E. After ensuring only one piece of the keyboard is connected to your computer and the RJ9 cord is disconnected from both sides, click Flash. The toolbox will wait for you as you perform the following step.

3.4 Next, double click the reset button seen in Figure 3.4. You will need to use a stick or a pen to click it.

![Figure 3.4. Reset button.](/files/-MdO07VL16W1P3Zmqvx0)

3.5 Repeat sections 2.4 and 2.5 for the other piece of your keyboard.

3.6 Connect the RJ9 cord to the two pieces. Then connect the USB cord from the **left** keyboard to the computer.


# 4. Customizing Keyboard Layout for Linux with QMK (Version 2022-01-10)

4.1 Instructions

```
$ Text after the $ sign refers to what is typed into the terminal.
```

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

4.2 Install the QMK CLI tool if you have not used it before

```
$ python3 -m pip install --user qmk
$ qmk setup
```

4.3 Test that the QMK CLI tool works by compiling a keymapping. Here I use the clueboard/66/rev3 keymap

```
$ qmk compile -kb clueboard/66/rev3 -km default
```

You should see a message similar to below:

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

4.4 Create a custom keymap

```
$ qmk new-keymap -kb handwired/dactyl_manuform/5x6
```

You'll then be prompted to give a name to the keymap. Here I give it the name `keyboard_alpaca`.&#x20;

4.5 Edit the keymap.c file with your preferred editor.

```
$ nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/keyboard_alpaca/keymap.c
```

While editing your keymap.c, you may wish to look at the following:

<details>

<summary>Layers - What are they?</summary>

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality.&#x20;

Layers are similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://beta.docs.qmk.fm/using-qmk/software-features/feature_layers#switching-and-toggling-layers-id-switching-and-toggling-layers) on the QMK website.

Layer keys are what you press on your keyboard to switch to a different layer. The `RAISE` and `LOWER` keycodes raises and lowers the layer, similar to Fn or Shift on a regular keyboard.&#x20;

If you have been following along, look in your current keymap.c file. As an example of how layere keys work, here you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. It is similar to a FnLock key seen on some keyboards. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

`[QWERTY] = LAYOUT5x6()` refers to the default base layer.

</details>

<details>

<summary>Keycodes - What are they?</summary>

Keycodes are functions that start with `KC_`.&#x20;

For example, say we want it so that when we press the top left button of our keyboard, it produces an `=` equal sign.

If we look at our current keymap.c, we will see that the keycode furthest to the top left is `KC_ESC` (assuming you have been following along this section). We want to replace `KC_ESC` with the keymap for `=`, so we go to the[ QMK List of Keycodes](https://docs.qmk.fm/#/keycodes) to check.

A quick Ctrl+F for `=` brings us to the following.&#x20;

<img src="/files/N0eBcYuoSFk1uLJVQK7f" alt="" data-size="line">

Now we know to replace `KC_ESC` with `KC_EQUAL`, or its alias `KC_EQL`. After we flash the firmware in section 4.6 with our new keymap.c, the keyswitch to the top left of our keyboard will output `=` .

</details>

Save your keymap.c after you are finished editing.

4.6 Flash the firmware

Before you flash the firmware, ensure you have:

* [ ] Disconnect the RJ9 cord from each piece of the keyboard
* [ ] Connected one piece of the keyboard to your computer via USB cord

Then flash the firmware:

```
$ qmk flash -kb handwired/dactyl_manuform/5x6 -km keyboard_alpaca
```

You should see:

> Detecting USB port, reset your controller now\...

When you see "Detecting USB port, reset your controller now\..." in the terminal, **click the keyboard reset button** **twice**, as seen in Figure 4.2.

![Figure 4.2. Reset button. New versions of the keyboard look slightly different but the button is at the same location.](/files/-MdO07VL16W1P3Zmqvx0)

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

4.7 Repeat section 4.6 with the other piece of the keyboard

4.8 Before using the keyboard

Make sure no keyboard is connected to your computer before attaching the RJ9 cord to each piece of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the **left** keyboard.


# 5. Hot Swapping Keyswitches (Version 2022-01-10)

5.1 Hot Swapping Demo

{% embed url="<https://youtu.be/o79LDrqGqjs>" %}

5.2 Necessary tools and components

* Keyswitches: **5-legged MX Cherry and Gateron keyswitches** work best
* Keyswitch puller
* Keycap puller

{% hint style="warning" %}
Not compatible with Kailh switches and low profile switches.
{% endhint %}

5.3 Summary

1. Remove all the keycaps with the keycap puller that came with your keyboard.
2. Remove a single keyswitch at a time. Pull out the keyswitch with a keyswitch puller, it should not take a lot of force. If the keyswitch is not coming out, try orienting it from a different angle.
3. &#x20;Insert the new keyswitch.


# 6. Tenting Your Keyboard (Version 2022-01-10)

6.1 Tenting your keyboard with plastic attachments

Insert the plastic attachments into the slots on the base plate. It's a tight fit so it helps to wiggle it in. Similarly, the attachments should be removed by wigging them out.

![Figure 6.1. Slots for the plastic attachment](/files/-MjbacBGxjHFHgPEpKV6)

![Figure 6.2. Base plate with plastic attachment inserted partially to illustrate the insertion.](/files/-Mjbb6eNi4aN12HecUo4)

6.2 Tenting your keyboard with screws

If you want to adjust the tenting to an exact angle, you can replace the two M3 screws with longer screws at your preferred length. The screws that came assembled with the keyboard are 5mm in length. Included with the keyboard are 35mm screws.

&#x20;

First, unscrew the two 5mm M3 screws that came assembled with your keyboard with a 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key).&#x20;

![Figure 6.3. These two M3 screws can be replaced with the longer 35mm screws. ](/files/-MjbdW6MIMmrI0AIT1lv)

Second, screw the hex nuts onto the tip of the 35mm M3 screws so that it's easier to push them into the base plate.

![Figure 6.4. Screw the hex nuts onto the tip of the 35mm M3 screws.](/files/iAjy1STw8oSN4ipLLH8t)

Push the hex nuts into the base plate. Finally, tighten the 35mm M3 screws until they do not wobble. There is another hex nut on the inside of the base plate, when the 35mm screw goes inside that hex nut, it will no longer wobble. Adjust the screws to change the degree of tenting to your liking.

![Figure 6.5 Push in the hex nuts and tighten the new 35mm screws.](/files/FiLiZIGDHu1xcBvQ1AfL)


# 7. Troubleshooting (Version 2022-01-10)

7.1 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller.

7.2 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes the keyboard connected to it is the left side. It assumes the right side is other piece.

If you had not disconnected the RJ9 cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.

7.3 Thumb cluster not working after flashing right side of the keyboard

If the right side of the keyboard is directly connected to the computer, some keys on the thumb cluster will not register. This is normal. Simply make sure USB cable is connected to the left side of the keyboard and the RJ9 cable is connected to the right side of the keyboard. The keyboard should start working as normal.


# 8. Terminology (Version 2022-01-10)

8.1 Keycode: The output after you press the key. For example, "Q" or "F11".

8.2 Keymapping: Your custom keyboard layout. For example, QWERTY or DVORAK.

8.3 Layers:  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

8.4 Layer Key: The keycode you use to switch to a different layer. If you are using the QMK Configurator web tool, you'll see M(0) or M(1). If you follow section 4, you'll see RAISE and LOWER in the default dactyl\_manuform/5x6 keymapping.


# 1. Introduction (Version 2021-11-29)

Thank you for purchasing a dactyl manuform keyboard. The user guide will be continuously updated.&#x20;

Please make sure you selected the correct keyboard version on the left. Version refers to the date of shipment. For example, Version 2021-06-24 refers to any keyboard shipped from 2021-06-24 to 2021-09-11. Version 2021-11-29, the most current version, refers to any keyboards shipped after 2021-11-29.

1.1 Default keymap for the dactyl manuform 5x6 with 6 keyed thumb cluster

![](/files/-Md0KCzsDDH0pg_LX1_y)

![](/files/-Md0KELhTFH-ARglV0aQ)

![](/files/-Md0KR5B1hIf_acfZgZC)

1.2 Default keymap for the dactyl manuform 5x6 with 5 keyed thumb cluster

![](/files/-MjLrgvRgLrULxLQ_g9r)

![](/files/-MjLrlbqzXY8Q2oClvfp)

![](/files/-MjLroWFPagghsVut7fV)

1.3 Default keymap for the dactyl manuform 5x6 with 3 keyed thumb cluster

{% hint style="info" %}
For the 3 keyed thumb cluster keyboards, the keymap for the thumb cluster in QMK corresponds to a keyswitch at a different position on your keyboard. Figure 1 shows that the physical keys for the thumb cluster is shifted by 1 key towards the right compared to the QMK keymap. Below presents the same idea in a different format:

QMK Keymap:                                    MO(2) -- Space -- Backspace

Physical Keyboard:   Backspace -- MO(2) -- Space
{% endhint %}

![Figure 1. The QMK GUI keymap position map to a different physical position for the thumb cluster.](/files/-Mki-IkFSQZYFTP0S6K5)

![](/files/-Mkhs70h0pzHIwAz3xfk)

![](/files/-MkhtN5-pzuIvC5aKuHy)

![](/files/-MkhtRvVKUa5dM5tFx2O)


# 2. About Your Keyboard (Version 2021-11-29)

2.1 Compatible keycaps

The keyboard comes with DSA keycaps, but is also compatible with SA and XDA keycaps. All keycaps must be 1u in size to fit this keyboard, with the exception of the thumb cluster, which can fit up to 1.5u depending on the number of keys on the thumb cluster. A 6-keyed thumb cluster will be able to fit two 1.5u keys on each side of the keyboard. A 3-keyed thumb cluster will be able to fit three 1.5u keys on each side.  The 5-keyed thumb cluster does not fit any 1.5u keys.

2.2 Non-hotswappable keyboards

Not recommended to open the back plate unless there are issues.

2.3 Compatible keyswitches for hotswappable keyboards

The hotswappable keyboard come with Kailh hotswap sockets, which are compatible with **five legged MX Cherry switches.** They are compatible with Kailh and Gateron switches, but MX Cherry switches are easier to hotswap because the plastic legs are slightly longer.&#x20;

The keyboard is not compatible with low profile switches.&#x20;

![Figure 2.1. 5-leg keyswitches are preferred. MX Cherry switches are easier to hotswap because the plastic legs (identified by the ① in the rightmost keyswitch above) are slightly longer.](/files/-Md-CCTxdBbmadiex9Ln)


# 3. Customizing Keyboard Layout for Windows and Mac with QMK (Version 2021-11-29)

QMK Toolbox currently does not support Linux. See section 4 instead.

3.1 Navigate to  [QMK Configurator](https://config.qmk.fm/#/handwired/dactyl_manuform/5x6/LAYOUT_5x6) to begin creating a custom key map for your keyboard.

![Figure 3.1. QMK Configurator](/files/-MdNZAzBYbrwRHKUSYw6)

A. Keyboard: Selects pre-configured key mappings. Typing in dactyl will bring up a list of different variations of the dactyl\_manuform keymapping. Select handwired/dactyl\_manuform/5x6 here.

B. Keymap Name: Enter a name for your custom keymap. Eventually, QMK will generate a hex file with the name `handwired_dactyl_manuform_5x6_your_keymap_name.hex`

C. Download keymap.json: Downloads a keymap.json file with your current keymapping. This file saves your progress as you create a new keymap. You can return to your save point by uploading the keymap.json file on the QMK Configurator website. Note that downloading the keymap.json file is optional and the file is not what you use to flash your keyboard.

D. Upload keymap.json: As described in *C*, this gives you the option to upload the keymap.json file to return to your save point.

E. Layers: Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. In *Figure 3.1*, layer 0 is selected. Clicking on 1 or 2 in the layer section will bring up a different keymap.&#x20;

A layer key is what you actually press on your keyboard to switch to a different layer. On the keymap in *Figure 3.1*, the layer keys look like "MO(1)" or "MO(2)". The MO(layer) stands for Momentarily activating the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap in *Figure 3.1*, you must hold both "MO(2)" and "P" to get "Scroll Lock" on layer 2. As soon as you release the "MO(2)" key, it goes back to the original layer. Layers range from 0 to 15.&#x20;

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key switches your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

F. Keycodes: Drag the keycode onto the keymap to replace the key. As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. You'll find the MO(layer) and DF(layer) keys by navigating to *Quantum > Layer* *and Layer Tap functions.*

G. When you are finished customizing your keymap, click compile. You should see a nice rotating potato baking in outerspace. Once QMK has finished compiling, the Download Firmware button should become clickable.

H. Download Firmware: Download the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file. You will use this to flash your keyboard.

3.2 Open the website to [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases), which is used to flash the hex file onto your keyboard.

![Figure 3.2. QMK Toolbox website navigation](/files/-MdNo47Op8rilV153B70)

A. Check that you are looking at the latest release. In the photo above, the latest version was 0.0.21. The latest release as of this writing is 0.1.1, but this could be different from what you see.

B. Download QMK.Toolbox.pkg if you use a Mac.

C. Download qmk\_toolbox.exe if you use Windows.

3.3 Open QMK.Toolbox.pkg or qmk\_toolbox.exe. If you are opening QMK Toolbox for the first time on Windows, you might see a dialogue box asking "Would you like to install drivers for your devices?". Select "Yes".

![Figure 3.3. QMK Toolbox Navigation](/files/-MdNxdKlCeYcwbzJyJDP)

A.  Install Drivers: If this is your first time using QMK Toolbox on your Windows PC and you did not see the install drivers dialogue box, right click the bottom bar of the QMK Toolbox and select Install Drivers.

B. Open Local File: Open the `handwired_dactyl_manuform_5x6_your_keymap_name.hex` file you previously downloaded.

C. Make sure it says atmega32u4. If it doesn't, it select from the drop down.

D. Select Auto-Flash. **Do not click Flash yet!** First ensure your keyboard is unplugged from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Then connect only one piece of the keyboard to your computer via USB.

E. After ensuring only one piece of the keyboard is connected to your computer and the RJ9 cord is disconnected from both sides, click Flash. The toolbox will wait for you as you perform the following step.

3.4 Next, double click the reset button seen in Figure 3.4. You will need to use a stick or a pen to click it.

![Figure 3.4. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

3.5 Repeat sections 2.4 and 2.5 for the other piece of your keyboard.

3.6 Make sure both pieces of the keyboard are not connected to your computer. Connect the RJ9 cord to the two pieces. Then connect the USB cord from the **left** keyboard to the computer.


# 4. Customizing Keyboard Layout for Linux with QMK (Version 2021-11-29)

4.1 Instructions

```
$ Text after the $ sign refers to what is typed into the terminal.
```

> Text in block quotes refers to the terminal output.

For reference, see the [QMK documentation](https://docs.qmk.fm/).

4.2 Install the QMK CLI if you have not used it before

```
$ python3 -m pip install --user qmk
$ qmk setup
```

4.3 Test that the QMK CLI tool works by compiling a keymapping. Here I use the clueboard/66/rev3 keymap

```
$ qmk compile -kb clueboard/66/rev3 -km default
```

You should see a message similar to below:

> Linking: .build/clueboard\_66\_rev3\_default.elf \[OK]
>
> Creating load file for flashing: .build/clueboard\_66\_rev3\_default.hex \[OK]
>
> Copying clueboard\_66\_rev3\_default.hex to qmk\_firmware folder > \[OK]
>
> Checking file size of clueboard\_66\_rev3\_default.hex \[OK]
>
> \* The firmware size is fine - 26356/28672 (2316 bytes free)

4.4 Create a custom keymap

```
$ qmk new-keymap -kb handwired/dactyl_manuform/5x6
```

You'll then be prompted to give a name to the keymap. Here I give it the name `keyboard_alpaca`.

4.5 Edit the keymap.c file with your preferred editor.

```
$ nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/keyboard_alpaca/keymap.c
```

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the [Switching and Toggling Layers](https://beta.docs.qmk.fm/using-qmk/software-features/feature_layers#switching-and-toggling-layers-id-switching-and-toggling-layers) on the QMK website.

A layer key is what you press on your keyboard to switch to a different layer. The RAISE and LOWER keycodes raises and lowers the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap, you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

\[QWERTY] = LAYOUT5x6(...) refers to the default base layer.

See *Figure 4.1* below as reference for what key to use, or the table linked [here](https://docs.qmk.fm/#/keycodes). As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS.

![Figure 4.1. Basic keycodes](/files/-MdKGRZy6-E6C9x9Bo1x)

4.6 Flash the firmware.

Unplug your keyboard from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Connect one piece of the keyboard to your computer via USB.&#x20;

```
$ qmk flash -kb handwired/dactyl_manuform/5x6 -km keyboard_alpaca
```

When you see "Detecting USB port, reset your controller now\..." in the terminal, click the keyboard reset button twice.&#x20;

![Figure 4.2. Reset button](/files/-MdO07VL16W1P3Zmqvx0)

If it flashes correctly, you should see this message:&#x20;

> avrdude: 18874 bytes of flash verified&#x20;
>
> avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)&#x20;
>
> avrdude done. Thank you.

4.7 Repeat section 4.6 with the other piece of the keyboard.&#x20;

4.8 Make sure no keyboard is connected to your computer before attaching the RJ9 cord to both pieces of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the **left** keyboard.


# 5. Hot Swapping Keyswitches (Version 2021-11-29)

Each piece of your keyboard contains a PCB. The PCB on each side will be slightly different. Please read the entire page before you hot swap your keyboard.

5.1 Necessary tools and components

* Keyswitches: **5-legged MX Cherry keyswitches** strongly recommended &#x20;
* 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key)
* Keyswitch puller
* Keycap puller (Included)

5.2 Remove keycaps

Remove all the keycaps with the keycap puller that came with your keyboard. It should not take much force for the keycap to come off.&#x20;

5.3 Open the base plate

See section 7.1 in [Troubleshooting ](/version-2021-11-29/troubleshooting)on how to open the base plate.

{% hint style="info" %}
Section 7.1 is different for Version 2021-11-29 compared with previous versions. Please make sure you are looking at the correct version.&#x20;
{% endhint %}

5.4 Remove a single keyswitch

In general, you should hot swap a single keyswitch at a time. This is because the PCB is stretched taut and is stabilized by the keyswitches. Removing one keyswitch at a time will minimize movement of the PCB and avoid needless hassle later on.&#x20;

Pull out the keyswitch gently, it should not take a lot of force. If the keyswitch is not coming out, try orienting it from a different angle.&#x20;

{% hint style="warning" %}
When removing keyswitches, make sure to use a keyswitch puller. Do not use pliers. It will damage the components.&#x20;
{% endhint %}

5.5 Insert the new keyswitch

This section is a bit of a longer read. But after doing it once, it's much faster to do subsequent times. The video at the bottom of this section is not comprehensive. You should still read this section to prevent damaging the keyboard.

The base plate of the keyboard should already be open. Put one finger on the Kailh socket from the inside of the keyboard. In a subsequent step, you will put pressure on the socket while you insert the new keyswitch.&#x20;

Align the keyswitch pins with the copper slots on the Kailh sockets, which are shown in Figure 5.1. It may help to wiggle the keyswitch back and forth while keeping the keyswitch pins near the slots. If you feel a bit of resistance while wiggling, the pins are likely aligned.

![Figure 5.1. Kailh socket copper slots](/files/-MjbITqmvZyslHo26I5Z)

While putting a gentle amount of pressure on the Kailh socket, push the keyswitch into the slots.&#x20;

{% hint style="info" %}
The primary purpose of putting pressure on the Kailh socket is to allow the keyswitch pins to squeeze into the slots. Otherwise, the pins will push the PCB away from it. The secondary purpose is to prevent the socket from breaking of the PCB in case of excessive force.&#x20;
{% endhint %}

{% hint style="warning" %}
It should not take a lot of force to insert the keyswitch into the keyboard. Generally, it should only require the force of one finger. If the keyswitch is not going into the socket, try to realign it then try again. Each keyswitch sockets for this keyboard is at a different angle, so it may take a few times before insert it.&#x20;

If the keyswitch is still not going in despite trying a few times, try applying less pressure to the Kailh socket.
{% endhint %}

After inserting the keyswitch, the PCB will sit a few milimeters above the surface of the keyboard. This is expected. In fact, applying too much pressure on the Kailh socket can prevent the keyswitch from fully locking onto the keyboard. This is because the keyswitch cannot fully insert into the keyboard unless the PCB sits slightly above the surface of the keyboard. To visualize why this is, see Figure 5.2 below.

![Figure 5.2. Applying excessive pressure to the socket can prevent keyswitch from fully inserting](/files/-Mjb7o9lfYj79SK-KDl9)

{% embed url="<https://www.youtube.com/watch?v=2_pCkKHsXeQ>" %}
Video 5.1 Dactyl manuform hot swap demo
{% endembed %}

5.6 Close the base plate

See section 7.2 in [Troubleshooting ](/version-2021-11-29/troubleshooting)on how to close the base plate.


# 6. Tenting Your Keyboard (Version 2021-11-29)

6.1 Tenting your keyboard with plastic attachments

Insert the plastic attachments into the slots on the base plate. It's a tight fit so it helps to wiggle it in. Similarly, the attachments should be removed by wigging them out.

{% hint style="warning" %}
Don't use excessive force when pushing or pulling the attachments. It can damage the base plate.
{% endhint %}

![Figure 6.1. Slots for the plastic attachment](/files/-MjbacBGxjHFHgPEpKV6)

![Figure 6.2. Base plate with plastic attachment inserted partially to illustrate the insertion.](/files/-Mjbb6eNi4aN12HecUo4)

6.2 Tenting your keyboard with screws

If you want to adjust the tenting to an exact angle, you can replace the two M3 screws with longer screws at your preferred length. The screws that came assembled with the keyboard are 5mm in length. Included with the keyboard are 35mm screws.

&#x20;

First, unscrew the two 5mm M3 screws that came assembled with your keyboard with a 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key).&#x20;

![Figure 6.3. These two M3 screws can be replaced with the longer 35mm screws. ](/files/-MjbdW6MIMmrI0AIT1lv)

Second, screw the hex nuts onto the tip of the 35mm M3 screws so that it's easier to push them into the base plate.

![Figure 6.4. Screw the hex nuts onto the tip of the 35mm M3 screws.](/files/iAjy1STw8oSN4ipLLH8t)

Push the hex nuts into the base plate. Finally, tighten the 35mm M3 screws until they do not wobble. There is another hex nut on the inside of the base plate, when the 35mm screw goes inside that hex nut, it will no longer wobble. Adjust the screws to change the degree of tenting to your liking.

![Figure 6.5 Push in the hex nuts and tighten the new 35mm screws.](/files/FiLiZIGDHu1xcBvQ1AfL)


# 7. Troubleshooting (Version 2021-11-29)

7.1 Opening the base plate

First, take out the screws with a 3mm [Allen Key](https://en.wikipedia.org/wiki/Hex_key) then very slowly lift the plate. There is a PCB held to the base plate, as seen in Figure 7.1 and 7.2.

Second, slide the PCB off the base plate before fully lifting the base plate. See Figure 7.1 and 7.2 for how to do this. Leave the PCB attached to the microcontroller.

![Figure 7.1 A PCB is attached to the base plate, shown in green. Yellow arrow shows the PCB holder on the base plate. Red arrow shows the direction to slide off the PCB.](/files/5jugUaFBjzFwXqJbtAsL) ![Figure 7.2 Slide the PCB off in the direction of the red arrow to detach it from the base plate.](/files/KNxlWSzT0MOwyG6o4fat)

Third, pull the female RJ9 socket up to remove it from its holder in the direction seen in the red arrow in Figure 7.3. Pull the reset switch up to remove it from its holder seen in the blue arrow in Figure 7.3. Flip the black plastic cap on the FFC connector and slide the flat cable out of the FFC connector as seen in #3 in Figure 7.3.

![Figure 7.3. Remove the RJ9 socket by pulling it up out of the holder in the direction of the red arrow (#1).  Remove the reset switch by pulling it out of the holder in the direction of the blue arrow (#2). Flip the black plastic cap on the FFC connector and slide the flat cable out of the FFC connector (#3).](/files/xaFLqSlVBbYpQxOQm8mT)

The base plate is now fully detached and can be put to the side.

7.2 Closing the base plate

When you close the base plate, the USB holder may push on some of the wiring. You shouldn't need to use force to close the base plate. If the base plate doesn't close with gentle pressure, carefully push away some of the wiring to make room for the USB holder.

Tighten the screws with an Allen key.

Always wash your hands after handling the insides of the keyboard.

7.2 Keyswitch is not working

Remove the keyswitch from the socket with a keyswitch puller. Check if the metal pins on the bottom of the keyswitch are straight. If any of them are bent, gently bend it straight with pliers. If you don’t have pliers, you can use the pads of your fingers to gently pinch it straight.

If the keyswitch pins are straight, open up the base plate and check if any wires have come off of the microcontroller.

7.3 Keymapping is flipped

Check whether the USB cord is connecting the **left** piece of the keyboard to the computer. The USB socket on the right keyboard should only be used to flash keymapping. Conceptually, your computer assumes that left side is the piece directly connected to it. It assumes the right side is other piece.

If you had not disconnected the RJ9 cord from each piece of the keyboard while flashing a new keymapping, you will need to re-flash each piece of the keyboard.

7.4 Thumb cluster not working after flashing right side of the keyboard

If the right side of the keyboard is directly connected to the computer, some keys on the thumb cluster will not register. This is normal. Simply make sure USB cable is connected to the left side of the keyboard and the RJ9 cable is connected to the right side of the keyboard. The keyboard should start working as normal.


# 8. Terminology (Version 2021-11-29)

8.1 Keycode: The output after you press the key. For example, "Q" or "F11".

8.2 Keymapping: Your custom keyboard layout. For example, QWERTY or DVORAK.

8.3 Layers:  Layers are a QMK specific functionality. The concept is similar to a Fn or FnLock key that is seen on some keyboards.

8.4 Layer Key: The keycode you use to switch to a different layer. If you are using the QMK Configurator web tool, you'll see M(0) or M(1). If you follow section 4, you'll see RAISE and LOWER in the default dactyl\_manuform/5x6 keymapping.