From 7e33ee173118472b526b1c4bf35996c3be26c187 Mon Sep 17 00:00:00 2001 From: Mikkel Jeppesen Date: Thu, 18 Jan 2018 01:38:05 +0100 Subject: [PATCH] Updated readme --- keyboards/lets_split_vitamins/readme.md | 184 ++++++++++-------------- keyboards/lets_split_vitamins/rules.mk | 5 +- 2 files changed, 80 insertions(+), 109 deletions(-) diff --git a/keyboards/lets_split_vitamins/readme.md b/keyboards/lets_split_vitamins/readme.md index 155f69f156..c3fe0bdb8f 100644 --- a/keyboards/lets_split_vitamins/readme.md +++ b/keyboards/lets_split_vitamins/readme.md @@ -1,53 +1,45 @@ Let's Split ====== +![Let's Split Vitamins included, assmebled in 3D printed case](https://i.imgur.com/btl0vNQ.jpg) This readme and most of the code are from https://github.com/ahtn/tmk_keyboard/ -Split keyboard firmware for Arduino Pro Micro or other ATmega32u4 -based boards. - -**Hardware files for the Let's Split are now stored at http://qmk.fm/lets_split/** -**Hardware files for the sockets version can be found at https://github.com/dumle29/let-s-Split-v2/tree/socket-reverseable** - -## Build Guide - -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) - -There is additional information there about flashing and adding RGB underglow. - -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* +**Hardware files for the Let's Split vitamins included are stored [here](http://github.com/duckle29/let-s-Split-v2/tree/onboardMCU)** ## First Time Setup -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: +Clone the `qmk_firmware` repo and navigate to its top level directory. [Once your build environment is setup](https://docs.qmk.fm/getting_started_build_tools.html), you'll be able to generate the default .hex using: -``` -$ make lets_split/rev2:default +```bash +make lets_split_vitamins/rev1:default ``` You will see a lot of output and if everything worked correctly you will see the built hex file: -``` -lets_split_rev2_default.hex +```bash +lets_split_vitamins_rev1_default.hex ``` 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: -``` -$ make lets_split/rev2:YOUR_KEYMAP_NAME +```bash +make lets_split_vitamins/rev1:YOUR_KEYMAP_NAME ``` If everything worked correctly you will see a file: +```bash +lets_split_vitamins_rev1_YOUR_KEYMAP_NAME.hex ``` -lets_split_rev2_YOUR_KEYMAP_NAME.hex -``` +If you are on linux, you can also flash the hex file to the keyboard right after compilation, by adding `:avrdude` to the end of the make command like so: + +```bash +make lets_split_vitamins/rev1:default:avrdude +``` 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. -### Let's split 1.0 -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. Features -------- @@ -58,50 +50,38 @@ Some features supported by the firmware: * Either half can connect to the computer via USB, or both halves can be used independently. -* You only need 3 wires to connect the two halves. Two for VCC and GND and one +* You only need 3 wires to connect the two halves. One for VCC, one for GND and one for serial communication. * Optional support for I2C connection between the two halves if for some reason you require a faster connection between the two halves. Note this requires an extra wire between halves and pull-up resistors on the data lines. + This is supported on the vitamins included. + The extra data line can also be used for ws2812 type LEDs. + If neither I2C nor RGB underglow is used, a TRS cable can be used instead of the 4wire TRRS cables. Required Hardware ----------------- - -Apart from diodes and key switches for the keyboard matrix in each half, you -will need: - -* 2 Arduino Pro Micros. You can find these on AliExpress for ≈3.50USD each. -* 2 TRRS sockets and 1 TRRS cable, or 2 TRS sockets and 1 TRS cable - -Alternatively, you can use any sort of cable and socket that has at least 3 -wires. If you want to use I2C to communicate between halves, you will need a -cable with at least 4 wires and 2x 4.7kΩ pull-up resistors +|Amount| Description | +|--|--| +| 1 | PCB kit from novelkeys | +| 48 | MX compatible switches | +| 48 | 1U keycaps +| 2 | Half cases. A 3D model for the left half is available [here](https://cad.onshape.com/documents/c6e5ae250d1e24fe46c9ef6c/w/d69f7049c0921df3d2b241f9/e/ecc2b176ab52a6d77bc55051). Mirror that to get a right-half case. Plate cases will be designed in the future. +| 1 | USB-mini-B cable of your choice | +| 1 | TRS / TRRS cable Optional Hardware ----------------- -A speaker can be hooked-up to either side to the `5` (`C6`) pin and `GND`, and turned on via `AUDIO_ENABLE`. - -Wiring ------- +A speaker can be hooked-up to the footprint on the PCBs. It is already enabled in the default firmware from github. -The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and digital pin 3 (i.e. -PD0 on the ATmega32u4) between the two Pro Micros. +A strip of WS2812 LEDs can be hooked up too, a guide will be written on how to do that once I get mine in the mail. +The PCB and connectors can safely handle 1A of current, but the USB standard is only rated at 500mA. Keep that in mind when picking the amount of LEDs. -Next, wire your key matrix to any of the remaining 17 IO pins of the pro micro -and modify the `matrix.c` accordingly. -The wiring for serial: +## Using I2C -![serial wiring](https://i.imgur.com/C3D1GAQ.png) - -The wiring for i2c: - -![i2c wiring](https://i.imgur.com/Hbzhc6E.png) - -The pull-up resistors may be placed on either half. It is also possible -to use 4 resistors and have the pull-ups in both halves, but this is -unnecessary in simple use cases. +On the left half PCB, there's two pads labled ***I2C Pullup*** if you want to use I2C, you need to bridge those two solder jumpers with a soldering iron. You can change your configuration between serial and i2c by modifying your `config.h` file. @@ -110,7 +90,7 @@ Notes on Software Configuration Configuring the firmware is similar to any other QMK project. One thing to note is that `MATRIX_ROWS` in `config.h` is the total number of rows between -the two halves, i.e. if your split keyboard has 4 rows in each half, then use +the two halves, so because the let's split vitamins included has 4 rows in each half, it's `MATRIX_ROWS=8`. Also, the current implementation assumes a maximum of 8 columns, but it would @@ -118,70 +98,62 @@ not be very difficult to adapt it to support more if required. Flashing ------- -From the top level `qmk_firmware` directory run `make KEYBOARD:KEYMAP:avrdude` for automatic serial port resolution and flashing. -Example: `make lets_split/rev2:default:avrdude` +### Entering bootloader +If the keyboard isn't new, and has been flashed before, you need to enter bootloader. +To enter bootloader, either use the assigned keys on the keymap, or if none have been put in the keymap, quickly short the reset to gnd twice. (Bottom pins of programming header, see image) ![Reset pins](https://i.imgur.com/LCXlv9W.png) +If using the default keymap, there's a reset key-combination on each half: +***Lower (SW23) and left-shift (SW13)*** on the left half, or +***Raise(SW44) and Enter(SW42)*** on the right half +It is recommended to add such reset keys to any custom keymaps. It shouldn't be necesarry to have one on each half, but the default layout has that. -Choosing which board to plug the USB cable into (choosing Master) --------- -Because the two boards are identical, the firmware has logic to differentiate the left and right board. +The board exits bootloader mode after 8 seconds, if you haven't started flashing. -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. +### Linux -The EEPROM approach requires additional setup (flashing the eeprom) but allows you to swap the usb cable to either side. +If this is the first time you're flashing the boards, it's easier to also flash EEPROM at the same time. -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. +0. If your keyboard is plugged in, unplug it +1. Open a terminal, and navigate to the qmk_firmware folder +2. Run `make lets_split_vitamins/rev1:default` +3. Plug the keyboard in, if it's new, it should enter bootloader, if it's not new, see **Entering bootloader** on how to enter bootloader mode +4. Run `dmesg | tail -10 | grep tty` +5. Note the port the port the bootloader has connected to. If nothing shows see **Entering bootloader** on how to enter bootloader mode +6. Run `avrdude -c avr109 -p m32u4 -P /dev/ttyACM0 -U flash:w:"lets_split_vitamins_rev1_default.hex":a -U eeprom:w:"./keyboards/lets_split_vitamins/eeprom-lefthand.eep":a` +for the left hand. Replace ***/dev/ttyACM0*** with the port you noted down earlier. For the right hand, change it to ***eeprom-righthand.eep*** -### Setting the left hand as master -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. +Your keyboard should be flashed :) -### Setting the right hand as master -If you always plug the usb cable into the right board, add an extra flag to your `config.h` -``` - #define MASTER_RIGHT +In the future, you shouldn't need to flash EEPROM (it will in fact wear the eeprom memory, so don't) +In the future just run: +```bash +make lets_split_vitamins/rev1:[KEYMAP]:avrdude ``` +from the qmk_firmware folder. -### Setting EE_hands to use either hands as master -If you define `EE_HANDS` in your `config.h`, you will need to set the -EEPROM for the left and right halves. +### Windows 10 -The EEPROM is used to store whether the -half is left handed or right handed. This makes it so that the same firmware -file will run on both hands instead of having to flash left and right handed -versions of the firmware to each half. To flash the EEPROM file for the left -half run: -``` -avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:eeprom-lefthand.eep -// or the equivalent in dfu-programmer +Follow this guide [here](https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/) to get ubuntu bash on windows. Then, in ubuntu bash for windows, follow the linux instructions [here](https://docs.qmk.fm/getting_started_build_tools.html) -``` -and similarly for right half -``` -avrdude -p atmega32u4 -P $(COM_PORT) -c avr109 -U eeprom:w:eeprom-righhand.eep -// or the equivalent in dfu-programmer -``` - -NOTE: replace `$(COM_PORT)` with the port of your device (e.g. `/dev/ttyACM0`) - -After you have flashed the EEPROM, you then need to set `EE_HANDS` in your config.h, rebuild the hex files and reflash. - -Note that you need to program both halves, but you have the option of using -different keymaps for each half. You could program the left half with a QWERTY -layout and the right half with a Colemak layout using bootmagic's default layout option. -Then if you connect the left half to a computer by USB the keyboard will use QWERTY and Colemak when the -right half is connected. +Then install [AVRDUDESS](http://blog.zakkemble.co.uk/avrdudess-a-gui-for-avrdude/). +0. If your keyboard is plugged in, unplug it +1. Open AVRDUDESS +2. Pick ***Atmel AppNote AVR109 Boot Loader*** as the programmer +3. Select ATMega32U4 as the MCU. +4. Check which COM ports are available under Port. Note these down if there's too many to remember. +5. Plug in the keyboard, If you just got the PCBs, there's only the bootloader on there, and it it will connect in bootloader mode automatically. If it's not new, see **Entering bootloader** on how to enter bootloader mode +6. Check the Port drop-down in AVRDUDESS, and see which new COM port has appeared. Do this within 8 seconds of entering bootloader. Pick the new COM port. If none have shown, try entering bootloader again. +7. Open a ubuntu bash terminal, and navigate to the qmk_firmware folder. Windows drives are in `/mnt/[DRIVE LETTER no caps]/` +8. Run `make lets_split_vitamins/rev1:default` +9. Go back into AVRDUDESS when it has finished compiling, and pick the .hex file in the **flash** field +10. In the EEPROM field, navigate into `keyboards/lets_split_vitamins/` and pick `eeprom-lefthand.eep` or `eeprom-righthand.eep` depending on which half you are flashing. +11. Make sure the board is in bootloader mode, and hit the **Program!** button. +12. Repeat for the other half. -Notes on Using Pro Micro 3.3V ------------------------------ +Your board should be flashed :) +For further flashes, you should clear the eeprom field, as you shouldn't wear the eeprom unnecessarily. -Do update the `F_CPU` parameter in `rules.mk` to `8000000` which reflects -the frequency on the 3.3V board. +You can plug either half into USB and it will work. you can also remove the TRS/TRRS cable, and plug both halves in. (which is why the default layout has reset on both halves) -Also, if the slave board is producing weird characters in certain columns, -update the following line in `matrix.c` to the following: - -``` -// _delay_us(30); // without this wait read unstable value. -_delay_us(300); // without this wait read unstable value. -``` +Enjoy your keyboard! :D diff --git a/keyboards/lets_split_vitamins/rules.mk b/keyboards/lets_split_vitamins/rules.mk index f9dc127bc6..501b8c32cc 100644 --- a/keyboards/lets_split_vitamins/rules.mk +++ b/keyboards/lets_split_vitamins/rules.mk @@ -5,7 +5,6 @@ SRC += matrix.c \ ssd1306.c # MCU name -#MCU = at90usb1287 MCU = atmega32u4 # Processor frequency. @@ -42,7 +41,7 @@ F_USB = $(F_CPU) # Bootloader # This definition is optional, and if your keyboard supports multiple bootloaders of -# different sizes, comment this out, and the correct address will be loaded +# different sizes, comment this out, and the correct address will be loaded # automatically (+60). See bootloader.mk for all options. BOOTLOADER = caterina @@ -74,4 +73,4 @@ CUSTOM_MATRIX = yes LAYOUTS = ortho_4x12 -DEFAULT_FOLDER = lets_split/rev2 \ No newline at end of file +DEFAULT_FOLDER = lets_split/rev1