diff --git a/docs/images/2017-03-08--model-01-layout-card-0002.png b/docs/images/2017-03-08--model-01-layout-card-0002.png new file mode 100644 index 00000000..c7c71ea7 Binary files /dev/null and b/docs/images/2017-03-08--model-01-layout-card-0002.png differ diff --git a/docs/images/arduino-setup/add-boards-manager-link.png b/docs/images/arduino-setup/add-boards-manager-link.png new file mode 100644 index 00000000..e891a687 Binary files /dev/null and b/docs/images/arduino-setup/add-boards-manager-link.png differ diff --git a/docs/images/arduino-setup/boards-manager-close.png b/docs/images/arduino-setup/boards-manager-close.png new file mode 100644 index 00000000..d40f369c Binary files /dev/null and b/docs/images/arduino-setup/boards-manager-close.png differ diff --git a/docs/images/arduino-setup/boards-manager-install.png b/docs/images/arduino-setup/boards-manager-install.png new file mode 100644 index 00000000..e0c2beca Binary files /dev/null and b/docs/images/arduino-setup/boards-manager-install.png differ diff --git a/docs/images/arduino-setup/flash-firmware.png b/docs/images/arduino-setup/flash-firmware.png new file mode 100644 index 00000000..ea1b781a Binary files /dev/null and b/docs/images/arduino-setup/flash-firmware.png differ diff --git a/docs/images/arduino-setup/open-boards-manager.png b/docs/images/arduino-setup/open-boards-manager.png new file mode 100644 index 00000000..5a88a278 Binary files /dev/null and b/docs/images/arduino-setup/open-boards-manager.png differ diff --git a/docs/images/arduino-setup/open-preferences.png b/docs/images/arduino-setup/open-preferences.png new file mode 100644 index 00000000..dccb5ccc Binary files /dev/null and b/docs/images/arduino-setup/open-preferences.png differ diff --git a/docs/images/arduino-setup/pick-keyboardio-from-boards-manager.png b/docs/images/arduino-setup/pick-keyboardio-from-boards-manager.png new file mode 100644 index 00000000..f4d3b9cf Binary files /dev/null and b/docs/images/arduino-setup/pick-keyboardio-from-boards-manager.png differ diff --git a/docs/images/arduino-setup/press-prog.png b/docs/images/arduino-setup/press-prog.png new file mode 100644 index 00000000..b58f9788 Binary files /dev/null and b/docs/images/arduino-setup/press-prog.png differ diff --git a/docs/images/arduino-setup/select-board-in-menu.png b/docs/images/arduino-setup/select-board-in-menu.png new file mode 100644 index 00000000..e794473c Binary files /dev/null and b/docs/images/arduino-setup/select-board-in-menu.png differ diff --git a/docs/images/arduino-setup/select-model-01-firmware.png b/docs/images/arduino-setup/select-model-01-firmware.png new file mode 100644 index 00000000..6d213e84 Binary files /dev/null and b/docs/images/arduino-setup/select-model-01-firmware.png differ diff --git a/docs/images/arduino-setup/select-port.png b/docs/images/arduino-setup/select-port.png new file mode 100644 index 00000000..04ffac66 Binary files /dev/null and b/docs/images/arduino-setup/select-port.png differ diff --git a/docs/images/arduino-setup/upload-failed.png b/docs/images/arduino-setup/upload-failed.png new file mode 100644 index 00000000..1c1de9ad Binary files /dev/null and b/docs/images/arduino-setup/upload-failed.png differ diff --git a/docs/images/arduino-setup/upload-ok.png b/docs/images/arduino-setup/upload-ok.png new file mode 100644 index 00000000..057dd386 Binary files /dev/null and b/docs/images/arduino-setup/upload-ok.png differ diff --git a/docs/images/arduino-setup/upload-sketch.png b/docs/images/arduino-setup/upload-sketch.png new file mode 100644 index 00000000..4df6fb29 Binary files /dev/null and b/docs/images/arduino-setup/upload-sketch.png differ diff --git a/docs/images/arduino-setup/verify-failed.png b/docs/images/arduino-setup/verify-failed.png new file mode 100644 index 00000000..311f7c84 Binary files /dev/null and b/docs/images/arduino-setup/verify-failed.png differ diff --git a/docs/images/arduino-setup/verify-model-01-firmware.png b/docs/images/arduino-setup/verify-model-01-firmware.png new file mode 100644 index 00000000..50d4e1eb Binary files /dev/null and b/docs/images/arduino-setup/verify-model-01-firmware.png differ diff --git a/docs/images/arduino-setup/verify-ok.png b/docs/images/arduino-setup/verify-ok.png new file mode 100644 index 00000000..e9999455 Binary files /dev/null and b/docs/images/arduino-setup/verify-ok.png differ diff --git a/docs/images/arduino_bootloader_side.jpg b/docs/images/arduino_bootloader_side.jpg new file mode 100644 index 00000000..65b15f66 Binary files /dev/null and b/docs/images/arduino_bootloader_side.jpg differ diff --git a/docs/images/arduino_bootloader_top.jpg b/docs/images/arduino_bootloader_top.jpg new file mode 100644 index 00000000..e67c5d3f Binary files /dev/null and b/docs/images/arduino_bootloader_top.jpg differ diff --git a/docs/images/books.png b/docs/images/books.png new file mode 100644 index 00000000..b7a1b6f2 Binary files /dev/null and b/docs/images/books.png differ diff --git a/docs/images/books2x.png b/docs/images/books2x.png new file mode 100644 index 00000000..ae40bcfa Binary files /dev/null and b/docs/images/books2x.png differ diff --git a/docs/images/bootloader-remove-screws.png b/docs/images/bootloader-remove-screws.png new file mode 100644 index 00000000..b1ca0950 Binary files /dev/null and b/docs/images/bootloader-remove-screws.png differ diff --git a/docs/images/butterfly.png b/docs/images/butterfly.png new file mode 100644 index 00000000..1400c4b4 Binary files /dev/null and b/docs/images/butterfly.png differ diff --git a/docs/images/chrysalis/change-layout/change-to-backspace.png b/docs/images/chrysalis/change-layout/change-to-backspace.png new file mode 100644 index 00000000..3e7038f1 Binary files /dev/null and b/docs/images/chrysalis/change-layout/change-to-backspace.png differ diff --git a/docs/images/chrysalis/change-layout/click-old-backspace-2.png b/docs/images/chrysalis/change-layout/click-old-backspace-2.png new file mode 100644 index 00000000..4ab79b73 Binary files /dev/null and b/docs/images/chrysalis/change-layout/click-old-backspace-2.png differ diff --git a/docs/images/chrysalis/change-layout/click-old-backspace.png b/docs/images/chrysalis/change-layout/click-old-backspace.png new file mode 100644 index 00000000..8dd58e2f Binary files /dev/null and b/docs/images/chrysalis/change-layout/click-old-backspace.png differ diff --git a/docs/images/chrysalis/change-layout/click-space-2.png b/docs/images/chrysalis/change-layout/click-space-2.png new file mode 100644 index 00000000..7c6a50cd Binary files /dev/null and b/docs/images/chrysalis/change-layout/click-space-2.png differ diff --git a/docs/images/chrysalis/change-layout/click-space.png b/docs/images/chrysalis/change-layout/click-space.png new file mode 100644 index 00000000..96ab2bb1 Binary files /dev/null and b/docs/images/chrysalis/change-layout/click-space.png differ diff --git a/docs/images/chrysalis/change-layout/connect.png b/docs/images/chrysalis/change-layout/connect.png new file mode 100644 index 00000000..349e9fc4 Binary files /dev/null and b/docs/images/chrysalis/change-layout/connect.png differ diff --git a/docs/images/chrysalis/change-layout/edit-kemap.png b/docs/images/chrysalis/change-layout/edit-kemap.png new file mode 100644 index 00000000..478233f3 Binary files /dev/null and b/docs/images/chrysalis/change-layout/edit-kemap.png differ diff --git a/docs/images/chrysalis/change-layout/save-changes.png b/docs/images/chrysalis/change-layout/save-changes.png new file mode 100644 index 00000000..7a952cd3 Binary files /dev/null and b/docs/images/chrysalis/change-layout/save-changes.png differ diff --git a/docs/images/chrysalis/change-layout/start-chrysalis.png b/docs/images/chrysalis/change-layout/start-chrysalis.png new file mode 100644 index 00000000..02008f4f Binary files /dev/null and b/docs/images/chrysalis/change-layout/start-chrysalis.png differ diff --git a/docs/images/chrysalis/flashing/01-click-connect.png b/docs/images/chrysalis/flashing/01-click-connect.png new file mode 100644 index 00000000..5a41b3d2 Binary files /dev/null and b/docs/images/chrysalis/flashing/01-click-connect.png differ diff --git a/docs/images/chrysalis/flashing/02-open-hamburger.png b/docs/images/chrysalis/flashing/02-open-hamburger.png new file mode 100644 index 00000000..3338ffe7 Binary files /dev/null and b/docs/images/chrysalis/flashing/02-open-hamburger.png differ diff --git a/docs/images/chrysalis/flashing/03-firmware-update.png b/docs/images/chrysalis/flashing/03-firmware-update.png new file mode 100644 index 00000000..9396ce68 Binary files /dev/null and b/docs/images/chrysalis/flashing/03-firmware-update.png differ diff --git a/docs/images/chrysalis/flashing/04-click-update.png b/docs/images/chrysalis/flashing/04-click-update.png new file mode 100644 index 00000000..a15dfb8a Binary files /dev/null and b/docs/images/chrysalis/flashing/04-click-update.png differ diff --git a/docs/images/chrysalis/flashing/04-press-prog.png b/docs/images/chrysalis/flashing/04-press-prog.png new file mode 100644 index 00000000..b58f9788 Binary files /dev/null and b/docs/images/chrysalis/flashing/04-press-prog.png differ diff --git a/docs/images/chrysalis/flashing/05-updating.png b/docs/images/chrysalis/flashing/05-updating.png new file mode 100644 index 00000000..3e47efa6 Binary files /dev/null and b/docs/images/chrysalis/flashing/05-updating.png differ diff --git a/docs/images/chrysalis/flashing/06-flashed-ok.png b/docs/images/chrysalis/flashing/06-flashed-ok.png new file mode 100644 index 00000000..85cd82ed Binary files /dev/null and b/docs/images/chrysalis/flashing/06-flashed-ok.png differ diff --git a/docs/images/chrysalis/flashing/07-failure.png b/docs/images/chrysalis/flashing/07-failure.png new file mode 100644 index 00000000..a60c1b6a Binary files /dev/null and b/docs/images/chrysalis/flashing/07-failure.png differ diff --git a/docs/images/colemak.png b/docs/images/colemak.png new file mode 100644 index 00000000..8fdaadb6 Binary files /dev/null and b/docs/images/colemak.png differ diff --git a/docs/images/community.png b/docs/images/community.png new file mode 100644 index 00000000..176ca768 Binary files /dev/null and b/docs/images/community.png differ diff --git a/docs/images/community2x.png b/docs/images/community2x.png new file mode 100644 index 00000000..3fcba31d Binary files /dev/null and b/docs/images/community2x.png differ diff --git a/docs/images/dvorak.png b/docs/images/dvorak.png new file mode 100644 index 00000000..410e9e3e Binary files /dev/null and b/docs/images/dvorak.png differ diff --git a/docs/images/icsp_model01_bottom.jpg b/docs/images/icsp_model01_bottom.jpg new file mode 100644 index 00000000..4c282a43 Binary files /dev/null and b/docs/images/icsp_model01_bottom.jpg differ diff --git a/docs/images/icsp_model01_top.jpg b/docs/images/icsp_model01_top.jpg new file mode 100644 index 00000000..bc66e519 Binary files /dev/null and b/docs/images/icsp_model01_top.jpg differ diff --git a/docs/images/keyboard-setup-1.png b/docs/images/keyboard-setup-1.png new file mode 100644 index 00000000..40b36d1c Binary files /dev/null and b/docs/images/keyboard-setup-1.png differ diff --git a/docs/images/keyboard-setup-2.png b/docs/images/keyboard-setup-2.png new file mode 100644 index 00000000..0922f62a Binary files /dev/null and b/docs/images/keyboard-setup-2.png differ diff --git a/docs/images/keyboard-setup-3.png b/docs/images/keyboard-setup-3.png new file mode 100644 index 00000000..3ec15138 Binary files /dev/null and b/docs/images/keyboard-setup-3.png differ diff --git a/docs/images/logo_orange_on_transparent.png b/docs/images/logo_orange_on_transparent.png new file mode 100644 index 00000000..ee2bb93d Binary files /dev/null and b/docs/images/logo_orange_on_transparent.png differ diff --git a/docs/images/noun_836336_cc.svg b/docs/images/noun_836336_cc.svg new file mode 100644 index 00000000..f1a5b290 --- /dev/null +++ b/docs/images/noun_836336_cc.svg @@ -0,0 +1,27 @@ + + + + + + + + + + +Created by Gonzalo Bravo +from the Noun Project + diff --git a/docs/images/preferences.png b/docs/images/preferences.png new file mode 100644 index 00000000..2c7d2d99 Binary files /dev/null and b/docs/images/preferences.png differ diff --git a/docs/images/preferences2x.png b/docs/images/preferences2x.png new file mode 100644 index 00000000..909433a7 Binary files /dev/null and b/docs/images/preferences2x.png differ diff --git a/docs/images/question.png b/docs/images/question.png new file mode 100644 index 00000000..6e89c111 Binary files /dev/null and b/docs/images/question.png differ diff --git a/docs/images/question2x.png b/docs/images/question2x.png new file mode 100644 index 00000000..3df459db Binary files /dev/null and b/docs/images/question2x.png differ diff --git a/docs/images/three-brackets.jpg b/docs/images/three-brackets.jpg new file mode 100644 index 00000000..91c919f6 Binary files /dev/null and b/docs/images/three-brackets.jpg differ diff --git a/docs/setup_toolchain.md b/docs/setup_toolchain.md index 6f5f9073..14b59678 100644 --- a/docs/setup_toolchain.md +++ b/docs/setup_toolchain.md @@ -1,50 +1,52 @@ -# Installing the Arduino IDE +# Setting up your development environment If you'd like to customize your keyboard's layout or functionality, the most robust and flexible option is to use the Arduino IDE. Arduino is one of the world's most widely used (and user friendly) platforms for programming "embedded" devices like the chip inside your keyboard. -The first step is to install the Arduino "Integrated development environment" or IDE: + +# Set up the Arduino IDE + +Arduino's designers made it to be accessible to people at all skill levels, and Kaleidoscope is built on top of the Arduino platform because we share that goal. The easiest way to customize your keyboard's firmware is to use the Arduino IDE. Even if you expect to use the command line to compile your firmware, you'll still need to install Arduino, as they provide the compilers and libraries Kaleidoscope needs to work. + +Using the IDE is 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. :-) + + +The right way to install Arduino is a little bit different depending on what operating system you use. * [Install Arduino on macOS](#Arduino-macOS) * [Install Arduino on Linux](#Arduino-Linux) -* [Install Arduino on Windows](#Arduino-Windows) +* [Install Arduino on Windows 10](#Arduino-Windows) * [Install Arduino on FreeBSD](#Arduino-FreeBSD) ## Install Arduino on macOS -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. Download the Arduino IDE install package from https://www.arduino.cc/en/Main/Software +1. Download the Arduino IDE install package from https://www.arduino.cc/en/Main/Software -As of this writing, the latest version is v1.8.8, which you can download from https://www.arduino.cc/download_handler.php?f=/arduino-1.8.8-macosx.zip +As of this writing, the latest version is v1.8.13, which you can download from https://www.arduino.cc/download_handler.php?f=/arduino-1.8.13-macosx.zip - 2. Double-click "arduino-1.8.x-macos.zip" to uncompress the Arduino IDE. +2. Double-click "arduino-1.8.13-macos.zip" to uncompress the Arduino IDE. - 3. Move Arduino.app from your `Downloads` folder to your Applications folder. +3. Move Arduino.app from your `Downloads` folder to your Applications folder. - 4. Double-click on Arduino.app to start it. +4. Double-click on Arduino.app to start it. -Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino) +Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino) # Install 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.8.8 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. +1. Install version 1.8.13 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: ```sh $ cd ~/Downloads - $ tar xvf arduino-1.8.8-linux64.tar.xz - $ sudo mv arduino-1.8.8 /usr/local/arduino + $ tar xvf arduino-1.8.13-linux64.tar.xz + $ sudo mv arduino-1.8.13 /usr/local/arduino $ cd /usr/local/arduino $ sudo ./install.sh ``` @@ -86,55 +88,44 @@ The Arduino system has been designed to be accessible to people at all skill lev export ARDUINO_PATH=/usr/local/arduino ``` -Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino) +Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino) -# Install on Windows +# Install on Windows 10 -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. :-) _**Note:** This tutorial has been written using Windows 10._ -

Prerequisite: Install USB Driver (Win 7, 8, & 8.1)

- -For Windows 7, 8, and 8.1, please follow the instructions on the [Installing USB Driver on Windows](Installing-USB-Driver-on-Windows) page before proceeding with the instructions on this page. - -

Step One: Set up the Arduino IDE

- 1. Download the Arduino IDE installation package from https://www.arduino.cc/en/Main/Software -As of this writing, the latest version is v1.8.8, which you can download from this URL: +As of this writing, the latest version is v1.8.13, which you can download from this URL: -https://www.arduino.cc/download_handler.php?f=/arduino-1.8.8-windows.exe +https://www.arduino.cc/download_handler.php?f=/arduino-1.8.13-windows.exe _**Note:** Some users have had difficulties with the Windows store version of the Arduino IDE. Please use the downloadable installation package._ 2. Open the installation package and follow the prompts to install the Arduino IDE. -Next step: [Add keyboard support to Arduino](Add-keyboard-support-to-Arduino) +Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino) ## Install on FreeBSD -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: installing support packages

- 1. Install the following packages required by the build system: `bash`, `gmake`, `perl5`, `avrdude`, and `arduino18`. ```sh $ sudo pkg install bash gmake perl5 avrdude arduino18 ``` -2. Flashing firmware as non-root. +### Flashing firmware as non-root. - a. If you want to flash your firmware as non-root, ensure your user has write access to the appropriate USB devices in devfs. By default, the devices are owned by `root`:`operator`, so put yourself in the `operator` group. You will also need to add yourself to the `dialer` group to use the modem device: +1. If you want to flash your firmware as non-root, ensure your user has write access to the appropriate USB devices in devfs. By default, the devices are owned by `root`:`operator`, so put yourself in the `operator` group. You will also need to add yourself to the `dialer` group to use the modem device: ```sh $ sudo pw groupmod operator -m $USER $ sudo pw groupmod dialer -m $USER ``` - b. Add devfs rules for write access for operator to USB devices: +1. Add devfs rules for write access for operator to USB devices: ```sh $ cat << EOM >> /etc/devfs.rules @@ -148,15 +139,19 @@ The Arduino system has been designed to be accessible to people at all skill lev EOM ``` - c. Update `/etc/rc.conf` to use the new devfs rule as the system rule: +1. Update `/etc/rc.conf` to use the new devfs rule as the system rule: ```sh $ sudo sysrc devfs_system_ruleset=operator_usb ``` - d. Restart devfs: +1. Restart devfs: ```sh $ sudo service devfs restart ``` +Next step: [Add keyboard support to Arduino](#Add-keyboard-support-to-Arduino) + + +# Add keyboard support to Arduino