* Added Arduino IDE install instructions
Completed a first draft of the IDE install instructions through flashing the board with the unedited sketch.
Also made a couple edits as suggested by @algernon, and a few other refinements I noticed.
* typo
This document is intended for folks who are beginners at Arduino programming and want a quick tutorial on how to get started customizing your keyboardio. It assumes you are reasonably clever and can follow instructions. It will give you some background on how keyboards in general, the keyboardio in specific, and then will take you through setting up the Arduino Integrated Development Environment (IDE) on your computer, and finally making simple changes to your firmware.
This document is intended for folks who are new to Arduino programming or perhaps to programming in general, and want a quick tutorial on how to get started customizing your keyboardio. It assumes you are reasonably clever and can follow instructions. It will give you some background on keyboards in general, and the keyboardio in specific, Then it will take you through setting up the Arduino Integrated Development Environment (IDE) on your computer, and finally making simple changes to your firmware.
When you have worked through this document you will be able to modify the definitions of the keys on your keyboardio, enabling you to do tasks such as swapping BACKSPACE and SPACE. You will also be able to turn on and off the various standard LED pattern modules.
@ -17,12 +17,11 @@ If you already know how to do this:
```
mkdir -p hardware/keyboardio
## then clone the hardware definitions to make them available
to the arduino environment:
## then clone the hardware definitions to make them available to the arduino environment:
then you will probably find this document tedious. Perhaps glance at the next section that gives an overview of how the firmware is set up for a high level understanding, and the Appendix with keymap definitions may be a useful reference.
This is only a start-up guide. The Keyboardio team hopes you will move on to making bigger and better improvements to your keyboardio, and will share them with the community. There is an active forum full of helpful people here:
@ -36,12 +35,14 @@ where you will find both experienced folks and others who are new to programming
Keyboards work by receiving your keypresses and translating them into "keycodes". Those keycodes are passed to your computer's operating system, which can interpret them and turn into characters and control codes. Those characters and codes are passed on to the active application on your computer. Some examples:
* Press the "A" key while editing a document, and "a" will be inserted where your cursor is currently positioned.
* Hold down "shift" and press the "A" key while editing a document, and "A" will be inserted where your cursor is currently positioned.
* Press the "up arrow" key, and the cursor will move up a line in the document.
In order to change what happens when you press a key on your keyboardio, you will need to edit the firmware configuration file to change the keycode it sends to your computer's operating system when you press a given key. To say that a bit more succinctly, you will edit a keymap.
**NOTE:** There's an Appendix at the end of this document which lists all the available keycodes, and what they do.
_**NOTE:** There's an Appendix at the end of this document which lists all the available keycodes, and what they do._
<h4>Editing Keymaps</h4>
@ -49,7 +50,7 @@ The keyboardio ships with three keymaps installed: QWERTY, FUNCTION, and NUMPAD.
The default layer is numbered zero, and the zero-layer that ships on the keyboardio is called "QWERTY".
**NOTE:** If you want to use a different layout, such as Dvorak and Colemark, you will find those keymaps and instructions to swap out the default layer in an Appendix.
_**NOTE:** If you want to use a different layout, such as Dvorak and Colemark, you will find those keymaps and instructions to swap out the default layer in an Appendix._
The next layer up is 1, which is FUNCTION. 2 is NUMPAD. The FUNCTION layer is activated when one of the FN palm keys is held down. NUMPAD gets toggled on and off with the NUM key in the upper right of the right half of the keyboardio.
@ -73,7 +74,11 @@ There are some limitations to what the Keyboardio can be configured to do that a
Firstly, the operating system has control of what happens when you hold down "shift". It makes sense that pressing "A" generates the character "a", and "shift + A" generates the character "A".
What makes less sense is that "shift + 4" will always generate the character "$", no matter where you have the "4" key mapped on the keyboard. It is not possible to make "shift + 4" create a character other than "$".
What makes less sense is that "shift + 4" will always generate the character "$", no matter where you have the "4" key mapped on the keyboard. It is _possible_ to make "shift + 4" create a character other than "$" in the keyboardio firmware by enabling a plugin called ShapeShifter:
But it's probably better to consider that an advanced option, and try a few more straightforward things first.
If you want to change the shifted character on a key, the change will need to be made in the operating system. Look below for the link to the Keyboardio forum; there are discussions on the forums about how to do that, and friendly folks there who can answer questions.
@ -98,15 +103,64 @@ Another thing to be aware of is the prog key. It sends a special signal to the k
<h2>Install Arduino support</h2>
https://www.arduino.cc/en/Main/Software
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. 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. :-)
<h4>Step One: Set up the Arduino IDE</h4>
Download the Arduino IDE install package from:
https://www.arduino.cc/en/Main/Software
Click on your operating system name to download the correct version.
_**Note:** This tutorial has been written using the Mac version._
Install the Arduino IDE. On a mac the application is called "Arduino.app". You probably want to put it in your Applications directory.
<h4>Step Two: Install keyboardio support into the IDE</h4>
It will open a default sketch; just ignore that. (If you close the default sketch window the application will close.)
Open the “Arduino” menu and click on “Preferences”
At the bottom of the "Settings" tab is the 'Additional Board Manager URLs` box. Paste this into it:
Open the ‘Tools’ menu, click on ‘Board’ and then click on ‘Boards Manager’
Type ‘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".
Open 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.
Plug in the keyboardio.
Open the Tools menu again, and scroll down to "Port > ". Select the Keyboardio. (It may already be seleted.)
<h4>Step Three: Build the default firmware and load it on the Keyboardio</h4>
Click on the “File” menu, click on the “Examples” submenu. Click on ‘Model01-Firmware’
While holding down the prog key, click on the right arrow in the sketch window menu bar to compile compile and install.
The Keyboardio LED's will flash across the board as the firmware is installed, and then the "LED" key will glow blue.
Congrats, you've just installed the latest firmware!!
Jennifer Leigh
7 years ago
committed by
GitHub