Install Arduino support on Linux

The Arduino system has been designed to be accessible to people at all skill levels, and Keyboardio is built on top of the Arduino platform because we share that goal. There are many ways to set up your system to work with the Keyboardio firmware, the most typical is to use the Arduino Integrated Development Environment (IDE); an application that gives some visual context to the code you want to send to your Arduino device. This is the easiest process for folks who are new to Arduino, or to programming generally. If you follow the instructions below step by step you should be fine. :-)

Step One: Set up the Arduino IDE

1. Install version 1.6.10 or newer of the Arduino IDE from http://arduino.cc/download. Unfortunately, the version packaged in Ubuntu is too ancient to support Arduino's new way of doing 3rd-party hardware.

2. Assuming you're untarring in the download directory:

   $ cd ~/Downloads
   $ tar xvf arduino-1.8.5-linux64.tar.xz
   $ sudo mv arduino-1.8.5 /usr/local/arduino
   $ cd /usr/local/arduino
   $ sudo ./install.sh

3. On Ubuntu, you will have to prevent ModemManager from attempting to grab the keyboard virtual serial port when it goes into bootloader mode:

   $ wget https://raw.githubusercontent.com/keyboardio/Kaleidoscope/master/etc/99-kaleidoscope.rules
   $ sudo cp 99-kaleidoscope.rules /etc/udev/rules.d
   $ sudo /etc/init.d/udev reload

4. Then disconnect and reconnect the keyboard for that change to take effect.

5. To let Arduino talk to the device over the serial port, you'll need to be in the appropriate group. On Ubuntu and some other Linux distributions, the group you need is the 'dialout' group.

   From a shell:

   $ groups 

   If you see dialout in the list, you're good to go. If you don't, you'll have to add yourself and then get Linux to recognize the change in your current shell:

   $ sudo adduser $USER dialout
   $ newgrp dialout   # or su - $USER, or log out and in again

   On Arch linux, Manjaro linux, and probably other Arch derivatives, the group for the device access is uucp. To add yourself to this group if necessary, use

   $ sudo usermod -a -G uucp $USER
   $ su - $USER

6. and you most likely will have to tweak the ARDUINO_PATH (put this line in your shell-rc - minus the prompt of course)

   $ export ARDUINO_PATH=/usr/local/arduino

Step Two: Install support for your keyboard into the IDE

At this point you have two options. The first option, which is described below, is to use the Arduino IDE GUI. The second is to proceed from the command line, which is described here.

1. Open the Arduino IDE. It will open a default sketch; just ignore that (if you close the default sketch window the application will close.)

2. Open the “Arduino” menu and click on “Preferences”

3. At the bottom of the "Settings" tab is the 'Additional Board Manager URLs' box. Paste this into it: https://raw.githubusercontent.com/keyboardio/boardsmanager/master/package_keyboardio_index.json then click ‘OK’ to close the dialog

4. Go into the ‘Tools’ menu, click on ‘Board’ and then click on ‘Boards Manager’

5. Enter ‘Keyboardio’ into the search box. You will see an entry that says "keyboardio by Keyboardio" click on it to select it, and then click ‘Install’. Once the install completes, click "Close".

6. Go into the ‘Tools’ menu again, click on ‘Board’ and then click on ‘Keyboardio Model 01’ – You may have to scroll through a long list of other boards to get there.

7. Go into the Tools menu again, and scroll down to "Port > ". Select your keyboard. (It may already be selected.)

Next step: Install the latest firmware on your keyboard