Commit | Line | Data |
---|---|---|
43579a80 AO |
1 | Orthodox |
2 | ======== | |
3 | ||
4 | *Please note this guide is a work in progress and is based directly on the Let's Split guide.* | |
5 | ||
6 | Orthodox is a split ortholinear keyboard with thumb-clusters designed in 2017 by /u/Deductivemonkee, expected to be available in group buys. | |
7 | Each half has 18 keys in a 3x6 grid and a five key thumb-cluster, of which three use 1.25-unit keycaps. | |
8 | ||
9 | ![Example prototype build by /u/Deductivemonkee](http://i.imgur.com/R4PPKdog.jpg) | |
10 | ||
11 | Its firmware is based on the Let's Split's. | |
12 | Each side is controlled by an Arduino Pro Micro (or compatible), and they're connected by a TRRS cable using the serial protocol. | |
13 | Support for the protocol using TWI (i2c®) is a work-in-progress. | |
14 | ||
15 | ||
16 | ## Revisions | |
17 | ||
18 | - `Rev.1` Prototype GB version, supporting only Pro Micro in the corner footprint, and using PCB top- and bottom-plates. | |
19 | ||
20 | Note that the second number after the `Rev.` text is the pcb *order number.* The prototypes will say 1, and the next order of any revision will say 2 and so on. | |
21 | ||
22 | ## Keymaps | |
23 | ||
24 | [The default layout can be unofficially referred to here.](http://www.keyboard-layout-editor.com/#/gists/f120e2703a22a6a69c7be9a65a9d1342) | |
25 | ||
26 | The thumb-clusters are an extension of row 2 and row 3 along columns 7, 8, and 9. | |
27 | Row 2 does not have a physical key in column 8, so when editing keymaps a placeholder constant (`XXXXXXX` or `KC_NO`) must be used in the row2-col8 position. | |
28 | ||
29 | ## Build Guide | |
30 | ||
31 | [Official build guide by /u/Deductivemonkee](http://imgur.com/a/9c0NP) | |
32 | ||
33 | For further reading on build- and flashing-procedures for split ortholinear skeleton-case keyboards, please refer to [An Overly Verbose Guide to Building a Let's Split Keyboard](https://github.com/nicinabox/lets-split-guide), much of which can be applied to the Orthodox. | |
34 | ||
35 | ## First Time Setup | |
36 | ||
800ec55d | 37 | Download or clone the whole firmware and navigate to the root directory. Once your dev env is setup, you'll be able to generate the default .hex using: |
43579a80 AO |
38 | |
39 | ``` | |
800ec55d | 40 | $ make orthodox/rev1:default |
43579a80 AO |
41 | ``` |
42 | ||
43 | You will see a lot of output and if everything worked correctly you will see the built hex files in your *root qmk_firmware directory* two levels up: | |
44 | ||
45 | ``` | |
663d3906 | 46 | orthodox_rev1_default.hex |
43579a80 AO |
47 | ``` |
48 | ||
49 | If you would like to use one of the alternative keymaps, or create your own, copy one of the existing [keymaps](keymaps/) and run make like so: | |
50 | ||
51 | ||
52 | ``` | |
800ec55d | 53 | $ make orthodox/rev1:YOUR_KEYMAP_NAME |
43579a80 AO |
54 | ``` |
55 | ||
56 | If everything worked correctly you will see a file: | |
57 | ||
58 | ``` | |
59 | orthodox_rev1_YOUR_KEYMAP_NAME.hex | |
60 | ``` | |
61 | ||
62 | For more information on customizing keymaps, take a look at the primary documentation for [Customizing Your Keymap](/readme.md##customizing-your-keymap) in the main readme.md. | |
63 | ||
64 | ||
65 | Features | |
66 | -------- | |
67 | ||
68 | For the full Quantum Mechanical Keyboard feature list, see [the parent readme.md](/readme.md). | |
69 | ||
70 | Some features supported by the firmware: | |
71 | ||
72 | * Either half can connect to the computer via USB, or both halves can be used | |
73 | independently. | |
74 | * You only need 3 wires to connect the two halves. Two for VCC and GND and one | |
75 | for serial communication. | |
76 | ||
77 | ||
78 | Required Hardware | |
79 | ----------------- | |
80 | ||
81 | Apart from diodes and key switches for the keyboard matrix in each half, you | |
82 | will need: | |
83 | ||
84 | * 2 Arduino Pro Micro's. You can find theses on aliexpress for ≈3.50USD each. | |
85 | * 2 TRRS sockets and 1 TRRS cable | |
86 | ||
87 | ||
88 | Notes on Software Configuration | |
89 | ------------------------------- | |
90 | ||
91 | Configuring the firmware is similar to any other QMK project. One thing | |
92 | to note is that `MATRIX_ROWS` in `config.h` is the total number of rows between | |
93 | the two halves, i.e. if your split keyboard has 3 rows in each half, then | |
94 | `MATRIX_ROWS=6`. | |
95 | ||
96 | ||
97 | Flashing | |
98 | ------- | |
800ec55d JH |
99 | From the root directory run `make PROJECT:KEYMAP:avrdude` for automatic serial port resolution and flashing. |
100 | Example: `make orthodox/rev2:default:avrdude` | |
43579a80 AO |
101 | |
102 | ||
103 | Choosing which board to plug the USB cable into (choosing Master) | |
104 | -------- | |
105 | Because the two boards are identical, the firmware has logic to differentiate the left and right board. | |
106 | ||
107 | It uses two strategies to figure things out: look at the EEPROM (memory on the chip) or looks if the current board has the usb cable. | |
108 | ||
109 | The EEPROM approach requires additional setup (flashing the eeeprom) but allows you to swap the usb cable to either side. | |
110 | ||
111 | The USB cable approach is easier to setup and if you just want the usb cable on the left board, you do not need to do anything extra. | |
112 | ||
113 | ### Setting the left hand as master | |
114 | If you always plug the usb cable into the left board, nothing extra is needed as this is the default. Comment out `EE_HANDS` and comment out `I2C_MASTER_RIGHT` or `MASTER_RIGHT` if for some reason it was set. | |
115 | ||
116 | ### Setting the right hand as master | |
117 | If you always plug the usb cable into the right board, add an extra flag to your `config.h` | |
118 | ``` | |
119 | #define MASTER_RIGHT | |
120 | ``` | |
121 | ||
122 | ### Setting EE_hands to use either hands as master | |
123 | If you define `EE_HANDS` in your `config.h`, you will need to set the | |
124 | EEPROM for the left and right halves. | |
125 | ||
126 | The EEPROM is used to store whether the | |
127 | half is left handed or right handed. This makes it so that the same firmware | |
306f23dc | 128 | file will run on both hands instead of having to flash [left](../../quantum/split_common/eeprom-lefthand.eep) and [right](../../quantum/split_common/eeprom-righthand.eep) handed |
43579a80 AO |
129 | versions of the firmware to each half. To flash the EEPROM file for the left |
130 | half run: | |
131 | ``` | |
132 | avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:eeprom-lefthand.eep | |
133 | // or the equivalent in dfu-programmer | |
43579a80 AO |
134 | ``` |
135 | and similarly for right half | |
136 | ``` | |
137 | avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:eeprom-righhand.eep | |
138 | // or the equivalent in dfu-programmer | |
139 | ``` | |
140 | ||
141 | NOTE: replace `$(COM_PORT)` with the port of your device (e.g. `/dev/ttyACM0`) | |
142 | ||
143 | After you have flashed the EEPROM, you then need to set `EE_HANDS` in your config.h, rebuild the hex files and reflash. | |
144 | ||
145 | Note that you need to program both halves, but you have the option of using | |
146 | different keymaps for each half. You could program the left half with a QWERTY | |
147 | layout and the right half with a Colemak layout using bootmagic's default layout option. | |
148 | Then if you connect the left half to a computer by USB the keyboard will use QWERTY and Colemak when the | |
149 | right half is connected. | |
150 | ||
151 | ||
152 | Notes on Using Pro Micro 3.3V | |
153 | ----------------------------- | |
154 | ||
155 | Do update the `F_CPU` parameter in `rules.mk` to `8000000` which reflects | |
156 | the frequency on the 3.3V board. | |
157 | ||
158 | Also, if the slave board is producing weird characters in certain columns, | |
159 | update the following line in `matrix.c` to the following: | |
160 | ||
161 | ``` | |
162 | // _delay_us(30); // without this wait read unstable value. | |
163 | _delay_us(300); // without this wait read unstable value. | |
164 | ``` |