Setting up a development environment

Page Status

This page was created using OSX Catalina as an underlying system. the procedure should also work with other operating systems, but directories will be different. (on linux the Arduino dir is in $HOME/Arduino, on OSX it is $HOME/Documents/Arduino).

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, and you do not want to have the latest and greatest, maybe unstable development version of kaleidoscope running on your keyboard, then you can ignore this page.) You should be familiar with basic git commands. If that is totally new to you, you should consider having a look at some tutorials first.

Mac OS X

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. If you installed the Keyboardio via the Arduino Boards Manager, you have to click “remove” there on the keyboardio hardware definitions. If you miss that step, your checked out keyboardio-bundle will always use the sources installed/downloaded in Arduino. You can see that when compiling from commandline: a different path for the includes is being used (~/Library/Arduino15/...)
2. Follow the instructions in the Kaleidoscope readme. Please make sure, you checkout all submodules! The command would be git submodules update --recursive --init, if you miss that step, you will not have a firmware folder!

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

$HOME 
   \
    |----Documents
        \
         |--- Arduino
          \
           |--- hardware
             \
              |--- keyboardio     <--- this is the dir you checked out the code into
               \
                |--- build-tools
                |--- tool-chain
                |--- ...    (some other files)
                |--- avr
                   \
                    |--- libraries
                     \
                      |--- Model01-Firmware    <--- this is where you customize your code, a git submodule!                  

3. Try compiling the standard Firmware: cd ~/Documents/Arduino/hardware/keyboardio/avr/libraries/Model01-Firmware
4. make - this will just compile your code and not try to upload things. It will show a ton of output, which you can ignore in most cases. If it fails, check, if all prerequisites are met and the checkout worked properly.
5. 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 as soon as it glows red. You should see red leds light up along the left half of your keyboard. When that command completes, the board should have flashed the standard layout. If you did any changes before using Arduino, you might want to copy that over and try it. The path for the Arduino sketches Model01 firmware example is usually ~/Documents/Arduino/Model01-Firmware.

I would recommend creating your own Firmware-Directory for developing purpose (or more than one?). This way, you can keep the original one always as a reference, and you can publish yours on github independently.

I did the following:

1. create a new directory in the libraries folder: `mkdir ~/Documents/Arduino/hardware/keyboardio/avr/libraries/MyLayout´
2. copy the contents of the Model01-Firmware directory over into that: cd ~/Documents/Arduino/hardware/keyboardio/avr/libraries/MyLayout; cp -r ../Model01-Firmware/* .
3. in that directory, the make and make flash commands should work.
4. if you want to (also) use the Arduino IDE for this, you need to rename the ino-file to match the directory name (in our case MyLayout.ino and change the name in the file library.properties accordingly. This way you can use the Arduino IDE for flashing your Keyboard, which might be more convenient. But: if you use a different Editor than the Arduino IDE but want to compile and flash using it, make sure that in preferences the checkbox for external editor is set!

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 or in your own firmware directory.

To modify the firmware and keep your own copy of it on GitHub, you can use two options:

1. fork the Model01-Firmware repo on github and check that out locally:

$ cd ~/Documents/Arduino/hardware/keyboardio/avr/libraries/
$ git clone git@github.com:mygithubuname/Model01-Firmware.git mygithubuname-firmware
$ cd mygithubuname-firmware
$ make flash
edit edit edit edit
$ make flash

2. use the directory created for your own developtment, where you copied the content from the default Firmware to. To use that, create a new repository on github and follow the instructions shown for adding existing projects. i the first option has the advantage that you could open pull requests for having your changes included into the official repository. The second one makes things more independent.

But in both cases: Modify your local copy to your heart's content, and push your changes to github whenever you want.

To make things accessible more convinient you can add a link to your Firmware-directory somewhere in the filesystem: cd ~/projects; ln -s ~/Documents/Arduino/hardware/keyboardio/avr/libraries/MyLayout- this would create a link to your layout directory in our personal projects-folder. Compiling and flashing it should also work from that directory.

getting up to date

At some point, you'll probably want to update the version of Kaleidoscope-Bundle-Keyboardio, too:

cd ~/Documents/Arduino/hardware/keyboardio/
git pull
git submodule update --recursive --remote --init

Just try some git frontends to help you find you way round in that directory and all those submodules.

A word on plugin development

Having the layout is one thing, but you maybe want to include some special functions using kaleidoscopes own plugin api. You can add your own plugins in your sketch directory in the src folder. There you created the .cpp and .h files and those can be included in your sketch.