Commit | Line | Data |
---|---|---|
ce01f88c JH |
1 | Let's Split |
2 | ====== | |
3 | ||
4 | This readme and most of the code are from https://github.com/ahtn/tmk_keyboard/ | |
5 | ||
6 | Split keyboard firmware for Arduino Pro Micro or other ATmega32u4 | |
7 | based boards. | |
8 | ||
f2e16098 | 9 | **Hardware files for the Let's Split are now stored at http://qmk.fm/lets_split/** |
85172f4f | 10 | **Hardware files for the sockets version can be found at https://github.com/dumle29/let-s-Split-v2/tree/socket-reverseable** |
048ef311 | 11 | |
133ed524 DN |
12 | ## Build Guide |
13 | ||
14 | A build guide for putting together the Let's Split v2 can be found here: [An Overly Verbose Guide to Building a Let's Split Keyboard](https://github.com/nicinabox/lets-split-guide) | |
15 | ||
16 | There is additional information there about flashing and adding RGB underglow. | |
17 | ||
85172f4f MJ |
18 | A build guide for putting together the sockets version can be found here: *Guide will be made and linked here when the PCBs have been received and tested* |
19 | ||
048ef311 JC |
20 | ## First Time Setup |
21 | ||
e0834cfd | 22 | Download or clone the `qmk_firmware` repo and navigate to its top level directory. Once your build environment is setup, you'll be able to generate the default .hex using: |
048ef311 JC |
23 | |
24 | ``` | |
800ec55d | 25 | $ make lets_split/rev2:default |
048ef311 JC |
26 | ``` |
27 | ||
f5f7dfa0 | 28 | You will see a lot of output and if everything worked correctly you will see the built hex file: |
048ef311 JC |
29 | |
30 | ``` | |
f5f7dfa0 | 31 | lets_split_rev2_default.hex |
048ef311 JC |
32 | ``` |
33 | ||
34 | 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: | |
35 | ||
36 | ||
37 | ``` | |
800ec55d | 38 | $ make lets_split/rev2:YOUR_KEYMAP_NAME |
048ef311 JC |
39 | ``` |
40 | ||
41 | If everything worked correctly you will see a file: | |
42 | ||
43 | ``` | |
44 | lets_split_rev2_YOUR_KEYMAP_NAME.hex | |
45 | ``` | |
46 | ||
7f7f7635 | 47 | For more information on customizing keymaps, take a look at the primary documentation for [Customizing Your Keymap](/docs/faq_keymap.md) in the main readme.md. |
048ef311 JC |
48 | |
49 | ### Let's split 1.0 | |
50 | If you have a first generation Let's Split you will need to use the revision 1 code. To do so, use `rev1` in all your commands instead. | |
51 | ||
ce01f88c JH |
52 | Features |
53 | -------- | |
54 | ||
048ef311 JC |
55 | For the full Quantum Mechanical Keyboard feature list, see [the parent readme.md](/readme.md). |
56 | ||
ce01f88c JH |
57 | Some features supported by the firmware: |
58 | ||
59 | * Either half can connect to the computer via USB, or both halves can be used | |
60 | independently. | |
61 | * You only need 3 wires to connect the two halves. Two for VCC and GND and one | |
62 | for serial communication. | |
63 | * Optional support for I2C connection between the two halves if for some | |
64 | reason you require a faster connection between the two halves. Note this | |
65 | requires an extra wire between halves and pull-up resistors on the data lines. | |
66 | ||
67 | Required Hardware | |
68 | ----------------- | |
69 | ||
70 | Apart from diodes and key switches for the keyboard matrix in each half, you | |
71 | will need: | |
72 | ||
e0834cfd | 73 | * 2 Arduino Pro Micros. You can find these on AliExpress for ≈3.50USD each. |
fbd9d045 | 74 | * 2 TRRS sockets and 1 TRRS cable, or 2 TRS sockets and 1 TRS cable |
ce01f88c JH |
75 | |
76 | Alternatively, you can use any sort of cable and socket that has at least 3 | |
77 | wires. If you want to use I2C to communicate between halves, you will need a | |
78 | cable with at least 4 wires and 2x 4.7kΩ pull-up resistors | |
79 | ||
80 | Optional Hardware | |
81 | ----------------- | |
82 | ||
83 | A speaker can be hooked-up to either side to the `5` (`C6`) pin and `GND`, and turned on via `AUDIO_ENABLE`. | |
84 | ||
85 | Wiring | |
86 | ------ | |
87 | ||
fbd9d045 | 88 | The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and digital pin 3 (i.e. |
ce01f88c JH |
89 | PD0 on the ATmega32u4) between the two Pro Micros. |
90 | ||
e0834cfd | 91 | Next, wire your key matrix to any of the remaining 17 IO pins of the pro micro |
ce01f88c JH |
92 | and modify the `matrix.c` accordingly. |
93 | ||
94 | The wiring for serial: | |
95 | ||
a7ce482d | 96 | ![serial wiring](https://i.imgur.com/C3D1GAQ.png) |
ce01f88c JH |
97 | |
98 | The wiring for i2c: | |
99 | ||
a7ce482d | 100 | ![i2c wiring](https://i.imgur.com/Hbzhc6E.png) |
ce01f88c JH |
101 | |
102 | The pull-up resistors may be placed on either half. It is also possible | |
103 | to use 4 resistors and have the pull-ups in both halves, but this is | |
104 | unnecessary in simple use cases. | |
105 | ||
f5f7dfa0 JH |
106 | You can change your configuration between serial and i2c by modifying your `config.h` file. |
107 | ||
ce01f88c JH |
108 | Notes on Software Configuration |
109 | ------------------------------- | |
110 | ||
048ef311 | 111 | Configuring the firmware is similar to any other QMK project. One thing |
479139f9 | 112 | to note is that `MATRIX_ROWS` in `config.h` is the total number of rows between |
e0834cfd | 113 | the two halves, i.e. if your split keyboard has 4 rows in each half, then use |
ce01f88c JH |
114 | `MATRIX_ROWS=8`. |
115 | ||
e0834cfd | 116 | Also, the current implementation assumes a maximum of 8 columns, but it would |
ce01f88c JH |
117 | not be very difficult to adapt it to support more if required. |
118 | ||
ce01f88c | 119 | Flashing |
048ef311 | 120 | ------- |
800ec55d JH |
121 | From the top level `qmk_firmware` directory run `make KEYBOARD:KEYMAP:avrdude` for automatic serial port resolution and flashing. |
122 | Example: `make lets_split/rev2:default:avrdude` | |
048ef311 JC |
123 | |
124 | ||
125 | Choosing which board to plug the USB cable into (choosing Master) | |
ce01f88c | 126 | -------- |
048ef311 | 127 | Because the two boards are identical, the firmware has logic to differentiate the left and right board. |
ce01f88c | 128 | |
e0834cfd | 129 | It uses two strategies to figure things out: looking at the EEPROM (memory on the chip) or looking if the current board has the usb cable. |
890ecf6a | 130 | |
e0834cfd | 131 | The EEPROM approach requires additional setup (flashing the eeprom) but allows you to swap the usb cable to either side. |
048ef311 JC |
132 | |
133 | 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. | |
890ecf6a | 134 | |
048ef311 | 135 | ### Setting the left hand as master |
56d2198b | 136 | 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. |
048ef311 JC |
137 | |
138 | ### Setting the right hand as master | |
139 | If you always plug the usb cable into the right board, add an extra flag to your `config.h` | |
140 | ``` | |
56d2198b | 141 | #define MASTER_RIGHT |
048ef311 JC |
142 | ``` |
143 | ||
144 | ### Setting EE_hands to use either hands as master | |
ce01f88c | 145 | If you define `EE_HANDS` in your `config.h`, you will need to set the |
048ef311 JC |
146 | EEPROM for the left and right halves. |
147 | ||
148 | The EEPROM is used to store whether the | |
ce01f88c JH |
149 | half is left handed or right handed. This makes it so that the same firmware |
150 | file will run on both hands instead of having to flash left and right handed | |
151 | versions of the firmware to each half. To flash the EEPROM file for the left | |
152 | half run: | |
153 | ``` | |
306f23dc | 154 | avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:"./quantum/split_common/eeprom-lefthand.eep" |
048ef311 JC |
155 | // or the equivalent in dfu-programmer |
156 | ||
ce01f88c JH |
157 | ``` |
158 | and similarly for right half | |
159 | ``` | |
306f23dc | 160 | avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:"./quantum/split_common/eeprom-righthand.eep" |
048ef311 | 161 | // or the equivalent in dfu-programmer |
ce01f88c JH |
162 | ``` |
163 | ||
048ef311 JC |
164 | NOTE: replace `$(COM_PORT)` with the port of your device (e.g. `/dev/ttyACM0`) |
165 | ||
166 | After you have flashed the EEPROM, you then need to set `EE_HANDS` in your config.h, rebuild the hex files and reflash. | |
167 | ||
ce01f88c JH |
168 | Note that you need to program both halves, but you have the option of using |
169 | different keymaps for each half. You could program the left half with a QWERTY | |
048ef311 JC |
170 | layout and the right half with a Colemak layout using bootmagic's default layout option. |
171 | Then if you connect the left half to a computer by USB the keyboard will use QWERTY and Colemak when the | |
ce01f88c JH |
172 | right half is connected. |
173 | ||
174 | ||
7550abbb YS |
175 | Notes on Using Pro Micro 3.3V |
176 | ----------------------------- | |
177 | ||
178 | Do update the `F_CPU` parameter in `rules.mk` to `8000000` which reflects | |
179 | the frequency on the 3.3V board. | |
180 | ||
181 | Also, if the slave board is producing weird characters in certain columns, | |
182 | update the following line in `matrix.c` to the following: | |
183 | ||
184 | ``` | |
185 | // _delay_us(30); // without this wait read unstable value. | |
186 | _delay_us(300); // without this wait read unstable value. | |
187 | ``` |