Setting up a development environment

Page Status

Caveat: this page was created by a newb without a global understanding of the system. Please update it if you know better.

Who this page is for

This page is for developers who want to go beyond using the Arduino IDE in order to do more complicated things. (If you are happy with the Arduino IDE, then you can ignore this page.)

Mac OS X

Note: This workflow has been verified from a blank slate on Mac OS X High Sierra as of December 2, 2017

If you want to make changes to the Kaleidoscope runtime or any of the bundled plugins and have previously installed Kaleidoscope or the Keyboardio hardware definitions using the Arduino Boards Manager, you will need to uninstall that prebuilt package and replace it with the GitHub version. This will make it easier to update to the latest versions of Kaleidoscope and Kaleidoscope plugins, and to propose changes to them with GitHub pull requests.

1. The procedure might be to go into the boards manager and click “uninstall” on the keyboardio hardware definitions. If you do this step, please update this page to validate or correct this instruction.
2. Follow the instructions in the Kaleidoscope readme. [NOTE: The instructions in that README will be changing to push users to installing from the Arduino IDE]
3. Follow instructions in in the Model01-Firmware readme. (I cloned this repo inside $HOME/kaleidoscope which seemed to work.)

At this point, you should have a directory structure like this:

$HOME 
    |____ kaleidoscope (note lower-case k)
    |     \
    |      |--- Arduino-Boards
    |      |--- Kaleidoscope (upper-case k) 
    |      |--- Model01-Firmware
    |
    |----Documents
        \
         |--- Arduino
             \
               --- hardware
                   \
                     --- keyboardio

TODO - you shouldn't have a separate checkout of Kaleidoscope

2. You will also have a link from $HOME/kaleidoscope/Arduino-Boards to $HOME/Documents/Arduino/hardware/keyboardio/avr (Why? See below.) TODO: Instead of a forward reference, integrate the content here or just remove it. This makes the docs platform specific when they may not otherwise need to be, as the item covered here is covered in the referenced docs
3. cd Model01-Firmware
4. make flash. When you get the Press ENTER to continue prompt, hold down the Prog key on your keyboard, then press enter, and release the prog key. You should see red leds light up along the left half of your keyboard. When that command completes, the board should have the new layout. TODO The workflow as presented doesn't actually change the layout.

At this point, you've got a command-line workflow to install the default sketch. The next step is...

Using GitHub to publish and share your sketch.

If you only want to develop locally, and don't want to share your setup or have public backups on github, you're done! You can make all the changes you want in the directories you cloned above.
To modify the firmware and keep your own copy of it on GitHub, fork theModel01-Firmware repo on github and check that out locally:

$ cd $HOME/kaleidoscope
$ git clone [email protected]:mygithubuname/Model01-Firmware.git mygithubuname-firmware
$ cd mygithubuname-firmware
$ make flash
edit edit edit edit
$ make flash

Modify your local copy to your heart's content, and push your changes to github whenever you want.

TODO: If this tutorial is intended as a gentle introduction to GitHub, it should actually show the user how to fork and push. If it's not, it might want to either link to documentation on the topic or just skip it.

Some explanations

Q: Why link from $HOME/..../Arduino-Boards into $HOME/Documents/Arduino/hardware/keyboardio/avr?

A: Most people like to keep their git checkouts in one top-level directory like ~/src, but Arduino has two specific places it will look for hardware definitions:

1. One is their boards manager directory.
2. The other is inside the sketchbook directory. On OSX, that’s Documents/Arduino/. On linux, that’s just Arduino/. This link lets us keep the git checkout in a top-level dir we control -- in this case, $HOME/kaleidoscope -- rather than buried in a directory owned by Arduino.

An alternative procedure

1. Install Arduino (OS dependent)
2. Create a working directory:

mkdir $HOME/kaleidoscope

3. Get a copy of the Kaleidoscope core:

cd $HOME/kaleidoscope
git clone --recursive --branch v1.22 https://github.com/keyboardio/Arduino-Boards.git

4. Link the Arduino-Boards directory (OS dependent):

ln -s $HOME/kaleidoscope/Arduino-Boards $SKETCHBOOK_DIR/hardware/keyboardio/avr

5. Get a copy of the firmware sketch to work on:

cd $HOME/kaleidoscope
git clone https://github.com/keyboardio/Model01-Firmware.git

6. Build the default firmware:

cd $HOME/kaleidoscope/Model01-Firmware
make

7. Flash the firmware (hold down prog and press enter when prompted):

make flash

8. Edit your sketch file:

$EDITOR $HOME/kaleidoscope/Model01-Firmware/Model01-Firmware.ino

If you want to store your changes in GitHub, create a github account, then fork the Model01-Firmware repository. After that, add your repository as a remote on your existing local repository:

cd $HOME/kaleidoscope/Model01-Firmware
git remote add <remote-name> <fork-url>

At some point, you'll probably want to update the version of Arduino-Boards, too:

cd $HOME/kaleidoscope/Arduino-Boards
git pull
git submodule update --recursive --remote --init