keyboards/clueboard/readme.md

   1 Clueboard keyboard firmware
   2 ======================
   3
   4 DIY/Assembled compact 66% keyboard by [Clueboard](http://clueboard.co).
   5
   6 For the full Quantum Mechanical Keyboard feature list, see [the parent readme.md](/readme.md).
   7
   8 ## First Time Setup
   9
  10 Download or clone the whole firmware and navigate to the keyboards/clueboard directory. Once your dev env is setup, you'll be able to generate the default .hex:
  11
  12 ```
  13 $ make
  14 ```
  15
  16 You will see a lot of output and if everything worked correctly you will see something similar to this:
  17
  18 ```
  19 Size after:
  20    text    data     bss     dec     hex filename
  21       0   19992       0   19992    4e18 clueboard_rev2_default.hex
  22 ```
  23
  24 At this point you can press RESET on your Clueboard and flash your keyboard with this command:
  25
  26 ```
  27 $ make dfu
  28 ```
  29
  30 If you would like to use one of the alternative keymaps, or create your own, see below.
  31
  32 ## Clueboard 1.0
  33
  34 If you have a first generation Clueboard (one with a black PCB) you will need to use the revision 1 code. To do so add `rev1` to your make command, like this:
  35
  36 ```
  37 $ make rev1
  38 ```
  39
  40 And when flashing your keyboard:
  41
  42 ```
  43 $ make rev1-dfu
  44 ```
  45
  46 If you are flashing an alternative layout to your rev1, include both `rev1` and `<keymap>` in your command, for example when flashing max:
  47
  48 ```
  49 $ make rev1-max-dfu
  50 ```
  51
  52 ## Alternate Keymaps
  53
  54 There are many alternative and user-contributed layouts available in the [keymaps/](keymaps/) directory. To compile and flash an alternative you will want to add `<keymap>` to your command:
  55
  56 ```
  57 $ make skully
  58 ```
  59
  60 And when flashing your keyboard, put `<keymap>` between "make" and "dfu":
  61
  62 ```
  63 $ make skully-dfu
  64 ```
  65
  66 ### Notable Layouts
  67
  68 These layouts are notable for one reason or another. If you are looking for ideas or inspiration you should look at these first:
  69
  70 * [keymaps/default](keymaps/default) - The default Clueboard layout
  71 * [keymaps/max](keymaps/max) - A maximised layout that makes use of every key and feature of the Clueboard 2.0 PCB.
  72 * [keymaps/skully](keymaps/skully) - The layout that @skullydazed uses on his own Clueboards.
  73
  74 ## Create Your Own Keymap
  75
  76 There are a lot of possibilities when creating your own keymap, and the primary documentation for doing that is [Customizing Your Keymap](/readme.md##customizing-your-keymap) in the main readme.md. As a way to get started, here is the procedure I recommend:
  77
  78 * Copy `[keymaps/default](keymaps/default/)` to `keymaps/<your_layout>`.
  79 * Compile the firmware (`$ make <your_layout>`)
  80 * Flash the firmware (`$ make <your_layout>-dfu`)
  81 * Make sure everything works like the default keyboard
  82 * Modify `keymaps/<your_layout>/readme.md` to tell others about your layout.
  83 * Modify `keymaps/<your_layout>/keymap.c` to reflect your desired layout.
  84 * Compile your new custom firmware (`$ make <your_layout>`)
  85 ** If you have warnings you may flash without fixing them, but something may not work right.
  86 ** If you have any errors you must fix them before continuing.
  87 * Flash the firmware (`$ make <your_layout>-dfu`)
  88
  89 ## Share Your Keymap
  90
  91 Got your layout dialed in? Please share it with the world so we can benefit from your work! Simply submit a pull request with your layout and we'll include it in the official repository. Please use the following guidelines when putting together your pull request:
  92
  93 * Include a readme.md that states what your primary keyboard use is, how your layout differs from the default, and highlights anything you think makes your layout particularly great.
  94 * If your layout requires certain features (EG, RGB underlight or backlighting) ensure you have a Makefile and config.h that reflects that
  95 * If your layout requires special hardware to be added, please describe that in the readme.md
  96
  97 TODO: Write up or link quick how-to on creating and submitting a PR. (Pull requests accepted. :)