keyboards/pearl/README.md

   1 # Pearl 40%
   2
   3 Pearl 40% is a keyboard designed by Koobaczech. It uses an Atmel
   4 ATMEGA32A MCU.
   5
   6 ## Compiling and flashing
   7
   8 These instructions are for building and flashing your Pearl 40% without
   9 Bootmapper Client.
  10
  11 ### Requirements
  12
  13 #### Windows
  14
  15 (to be written, help needed)
  16
  17 #### Mac
  18
  19 Apart from regular QMK and AVR dependencies you need to install
  20 `bootloadHID`. You can install it with `homebrew` as follows:
  21
  22     $ brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
  23
  24 If you don't use `homebrew` you can try following the compiling
  25 instructions defined below in the Linux section.
  26
  27 #### Linux
  28
  29 For Linux you require all regular QMK dependencies, but make sure you're
  30 using `gcc-avr` version 4.9 or higher. 4.8 and lower do not contain the
  31 proper definitions for ATMEGA32A MCUs and QMK will fail while attempting
  32 to compile a HEX for Pearl 40%.
  33
  34 E.g. you cannot compile Pearl 40% HEX on a regular Ubuntu 14.04 as
  35 `gcc-avr` version is maxed to 4.8 on it.
  36
  37 Additionally you need an operational `bootloadHID` binary.
  38
  39 You can install `bootloadHID` by taking the following steps:
  40
  41     $ git clone https://github.com/robertgzr/bootloadHID ~/tmp/bootloadHIDsrc
  42     $ cd ~/tmp/bootloadHIDsrc/commandline
  43     $ make VENDORID=0x16c0 PRODUCTID=0x05DF # vid and pid for atmega32a
  44     $ chmod +x bootloadHID && cp bootloadHID /usr/bin/bootloadHID
  45
  46 Running `which bootloadHID` should return `/usr/bin/bootloadHID`.
  47
  48 ### Compiling
  49
  50 Enter the QMK root directory and compile a keymap with the following
  51 command:
  52
  53     $ make pearl:<keymap>
  54
  55 where `<keymap>` is a layout directory under the `pearl` directory.
  56
  57 QMK should compile a HEX (called `pearl_<keymap>.hex`) for you, which
  58 you can flash using `bootloadHID`.
  59
  60 ### Flashing
  61
  62 To enable Pearl 40% bootloading mode, unplug the keyboard, then plug it
  63 in while holding `Esc` at the same time (the top-leftmost switch on the
  64 PCB, next to the USB connector). Once the board is in bootload mode,
  65 issue the following command (you might require `sudo` to perform the
  66 command):
  67
  68     # assuming we're still in the QMK root dir where you compiled a HEX into
  69     $ bootloadHID -r ./pearl_<keymap>.hex
  70
  71 You should see something similar to
  72
  73     > Page size = <value>
  74     > Device size = <value>; <value> remaining
  75     > Uploading <value> bytes starting at 0 (0x0)
  76     > <value> ... <current value>
  77
  78 where `<current value>` should be slowly increasing as the HEX is being
  79 flashed to the board. If there is some warning about `resource busy` it
  80 should still work OK.
  81
  82 Once done the board underglow should turn red and the new firmware has
  83 been flashed. If you can't type on the board try plugging it in again
  84 (without holding any keys to prevent accidentally setting it into
  85 bootload mode again).