|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220 |
- keybrd Library User's Guide
- ===========================
- keybrd is an open source library for creating custom-keyboard firmware.
- The resulting keyboard firmware is compatible with standard USB keyboard drivers.
-
- This guide shows how to
- * set up the Arduino development environment
- * install the keybrd library
- * compile and load keybrd firmware
-
- The Arduino development environment is free and simple as possible.
- Its easy for novice programmers to setup and learn.
-
- ## Who this guide is for
- This guide is for anyone who wants to use the keybrd library to develop custom-keyboard firmware.
-
- A reader with programming experience, but no C++ experience, would understand the tutorials well enough to modify existing keybrd sketches.
- An experienced C++ programmer would be able to write original sketches and classes from scratch.
-
- The library is written in the C++ language and uses pointers, objects, classes, static class variables, composition, inheritance, and enum.
-
- ## Microcontroller board requirements
- The keybrd library works with Teensy and Arduino boards.
-
- [Teensy LC](https://www.pjrc.com/teensy/teensyLC.html) has 8K RAM, which is more than enough memory for any keyboard.
-
- keybrd has been tested on the DodoHand keyboard with Teensy 2.0 and PCA9655E I/O expander using the DH_2565 sketch.
-
- Teensy LC is preferred over the older Teensy 2.0 for it's larger memory capacity and lower price.
-
- ## Getting started with Teensy, Arduino IDE, and keybrd
- The Arduino IDE is used to edit and compile sketches, and then load them on to the microcontroller.
-
- Teensyduino is a software add-on for the Arduino IDE that allows it to compile to Teensy.
-
- [Teensy Getting Started](http://www.pjrc.com/teensy/first_use.html) is a good way to familiarize yourself with Teensy.
- [Arduino Development Environment](http://arduino.cc/en/guide/Environment) is a brief description.
-
- The following steps create an Arduino development environment for keybrd sketches.
-
- ### Install Arduino IDE and Teensyduino
- Follow the install steps are modified from the [Teensyduino download page](https://www.pjrc.com/teensy/td_download.html)
-
- For Linux:
-
- 1. Download and extract the Arduino software.
- Move the extracted directory to /opt:
-
- $ sudo mv ~/Downloads/arduino-1.6.7 /opt/arduino-1.6.7
-
- 2. The "Linux udev rules" link is at top right of page.
- Save the teensy.rules file in /etc/udev/rules.d/
-
- 3. "Teensyduino Files" installer links are at top of page.
- Download the installer to your Downloads directory.
- Make the installer executable:
-
- $ chmod 755 teensyduino.64bit
-
- Run the teensyduino installer and fill the form fields:
-
- Arduino location to install Teensyduino: /usr/local/bin/arduino-1.x.x
- Libraries to Install: None
-
- 4. Launch Arduino IDE from /opt/arduino-1.x.x/arduino
-
- ### Setup Arduino IDE for compiling keybrd firmware
- From the Arduino IDE tool bar, select:
- * Tools > Board > Teensy LC (or whatever board you are using)
- * Tools > USB Type > Keyboard + Mouse + Joystick
-
- optional:
- * File > Preferences > Compiler warnings: All
- * File > Preferences > check: Use external editor
-
- A Sketchbook is a folder that the Arduino IDE uses to store sketches and libraries.
- The default location for [Arduino libraries](https://www.arduino.cc/en/Guide/Libraries) is in
-
- ~/Documents/Arduino/libraries/
-
- ### Download and unpack keybrd-master.zip into your Arduino directory
- todo update after testing Arduino library manager
- link from tutorial 7 ## Publishing
- https://www.arduino.cc/en/Guide/Libraries
- > Installing Additional Arduino Libraries
- > Using the Library Manager
-
- Down load keybrd-master.zip from the [Download ZIP](https://github.com/wolfv6/keybrd) button.
-
- Unpack keybrd-master.zip into your Arduino directory on your system (default location is ~/Documents/Arduino/).
-
- ### keybrd library and keybrd extension libraries
- todo update after testing Arduino library manager
-
- The keybrd library contains the foundation classes for creating a keyboard firmware.
- For emphasis, it is sometimes referred to as the "core keybrd library".
-
- keybrd extension libraries contain additional classes that extend the keyboard library.
- keybrd extension library names are prefixed by "keybrd_".
-
- The Arduino IDE looks for libraries in Arduino/libraries/.
- For example, the DodoHand keyboard requires that the core keybrd library and the keybrd_DH extension library be installed:
- * Arduino/libraries/keybrd/
- * Arduino/libraries/keybrd_DH/
-
- A keybrd extension library allows classes to be shared by multiple sketches without polluting the core keybrd library with classes that few other keyboards can use.
-
- ### Compile and load keybrd sketch
- If it isn't already plugged in, plug the USB cable into the computer and controller.
-
- > CAUTION: It is possible to loose control of your keyboard when running a keybrd sketch.
- > If the keybrd sketch has a mouse object, it is also possible to loose control of your mouse.
- > USB keyboard protocol is capable of spewing characters and mouse commands at up to 500 per second.
- > Take the following precautions before uploading an untested keybrd sketch to a controller:
- > * Save all files and close dangerous applications.
- > * Park the cursor in an editor opened to a test file.
- > That way you can immediately see if the controller starts spewing characters.
- > * Be prepared to turn off the controller:
- > turn off Teensy Loader's green "Auto" button and push Teensy's reset button
- > if that fails, unplug Teensy USB
-
- Compile and load workflow:
-
- 1. Open a keybrd sketch in the Arduino IDE (for example Arduino/keybrds/firmware/keybrd_single-layer/keybrd_single-layer_1221_bb/keybrd_single-layer_1221_bb.ino)
- 2. Prepare for loosing control of keyboard and mouse.
- 3. On the Arduino IDE, click the Upload button.
- 4. The Teensy boot loader window opens, you might need to press and release the tiny pushbutton on the Teensy circuit board.
-
- ## Example keybrd sketches
- Example keybrd sketches are in the keybrd_proj/keybrd/examples/ directory.
- Extension libraries have their example sketches similarly located.
-
- The example sketch names use the following conventions.
-
- keybrd_extension_feature_version.ino
-
- where
- * **keybrd** indicates a keybrd sketch
- * **extension** is the extension library name e.g. DH, DualMode
- * **feature** is distinguishing feature of keybrd sketch e.g. breadboard, LED, sound, Dvorak
- * **version** is version number
-
- The first two fields are mandatory, the remaining fields are optional.
-
- ## Diode orientation
- The physical martix rows and columns on a keyboard can be in any direction or shape.
- [diode](https://en.wikipedia.org/wiki/Diode) orientation is specified in [Matrix.h](todo)
-
- ![Diode](images/120px-Diode_pinout_en_fr.svg.png)
-
- Diagram is of typical through-the-hole diode in same alignment as diode symbol.
- Cross bar and band depict the cathode.
-
- ## Troubleshooting check list
- The following is a listing of items to check when a new keybrd sketch or keyboard is having trouble.
-
- Development-environment items to check:
- * If the keyboard has an I/O expander, power cycle (replug the USB) after loading the HEX file.
- * If the keybrd extension library directory name or location was changed, see section
- [Populate Arduino/libraries with keybrd library symlinks](todo link)
- * If compile error: 'KEY_A' was not declared in this scope
- From the Arduino IDE tool bar, select: Tools > USB Type > Keyboard + Mouse + Joystick
-
- Sketch items to check:
- * For each row, number of keys in Row should equal number of colPort pins.
- In this example, row_0 has six colPort pins in ptrsColPorts, and six keys in ptrsKeys_0:
- ```
- ColPort_AVR colPortB(DDRB, PORTB, PINB, 1<<0 | 1<<1 | 1<<2 | 1<<3 );
- ColPort_AVR colPortD(DDRD, PORTD, PIND, 1<<2 | 1<<3 );
-
- ColPort* const ptrsColPorts[] = { &colPortB, &colPortD };
- const uint8_t COL_PORT_COUNT = sizeof(ptrsColPorts)/sizeof(*ptrsColPorts);
-
- const Key* const ptrsKeys_0[] = { &k_00, &k_01, &k_02, &k_03, &k_04, &k_05 };
- Row row_0(ptrsKeys_0, &rowPortF, 1<<0, ptrsColPorts, COL_PORT_COUNT);
- ```
- * Some of the constructors take array-element-count arguments, make sure that the correct counts are passed to the constructors. Or use sizeof() like this example:
- ```
- Row* const ptrsRows[] = { &row0, &row1, &row2, &row3 };
- const uint8_t ROW_COUNT = sizeof(ptrsRows)/sizeof(*ptrsRows);
- Matrix matrix(ptrsRows, ROW_COUNT, 1);
- ```
- * For multi-layered keyboards, the number of codes in each Key_Layered should equal the number of layers.
-
- Hardware items to check:
- * Connections
- * Diode orientation
- * 5 volts across power and ground
- * To validate keyboard hardware, modify the simple single-layer keybrd sketch from the tutorial.
-
- ## Keybrd nomenclature
- **[scancode](http://en.wikipedia.org/wiki/Scancode)** -
- Is a 16-bit integer assigned to a key position on a keyboard.
- The keyboard sends a scancode to the computer for every key press and release.
-
- **[Layers](http://deskthority.net/wiki/Layer)** -
- are key bindings provided by the keyboard firmware.
- The standard [IBM PC keyboard](http://en.wikipedia.org/wiki/IBM_PC_keyboard) has one layer.
- Many compact keyboards have an additional [Fn layer](http://en.wikipedia.org/wiki/Fn_key).
- The [Neo layout](http://neo-layout.org/index_en.html) has 6 layers.
-
- **Layer code** - is an integer assigned to a layer.
-
- **Layer scheme** - is a system for changing layers while typing.
- A single-layer scheme does not change layers.
-
- **Layout** - is a grid of keys. Key caps are often labeled to show a keyboard's layout.
-
- **[Matrix](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/)** - is a collection of switches connected by rows and columns.
-
- **[bounce](http://en.wikipedia.org/wiki/Switch#Contact_bounce)** -
- Keyboard switches are made of moving contacts.
- When the contacts close, they bounce apart one or more times before making steady contact.
- A debouncer removes the bounce so that a key press is sent to the computer only once.
-
- **[Modifier key](http://en.wikipedia.org/wiki/Modifier_key)** - is a special key on a computer keyboard that temporarily modifies the normal action of another key when pressed together. By themselves, modifier keys usually do nothing; that is, pressing any of the Shift, Alt, or Ctrl keys alone does not trigger any action from the computer.
-
- **Sketch** - is the name that Arduino uses for a program
-
- **keybrd sketch** - is an Arduino sketch that uses the keybrd library to define a keyboard firmware.
|