ergodox-firmware/references.md

Electronics Stuff

• [Resistor Color Codes]

  (http://www.ladyada.net/wiki/lib/exe/fetch.php?hash=a2c6a9&w=501&h=785&media=http%3A%2F%2Fwww.ladyada.net%2Fimages%2Fmetertutorial%2Frescolorcode.jpg)

  image

  • from [the Multimeter Tutorial] (http://www.ladyada.net/learn/multimeter/resistance.html) (on http://ladyada.net/)

• [Schematic Symbols]

  (http://img.docstoccdn.com/thumb/orig/28066054.png)

  image

• [Vcc, Vdd, Vss, etc.] (http://encyclobeamia.solarbotics.net/articles/vxx.html)
  A neat little discussion of the symbols and where they came from.

• [Very Basic Circuits]

  (http://www.seattlerobotics.org/encoder/mar97/basics.html)

  column by Kevin Ross for Encoder
  Includes a short thing about pull-up resistors.

• [Powering Light Emitting Diodes (LEDs)] (http://wolfstone.halloweenhost.com/Lighting/litlpo_PoweringLEDs.html)
  Can you use one resistor for multiple parallel LEDs? No. Or, you can, but it's not the best idea.

  • can also be reached via http://thewolfstone.com/ -> [ENTER] ('http://thewolfstone.com/Welcome/Home.html) -> [Wolfstone's Haunted Halloween Page] (http://thewolfstone.com/_ar/Halloween.html) -> [technology] (http://wolfstone.halloweenhost.com/Navigation/TechBase.html) -> [powering LEDs] (http://wolfstone.halloweenhost.com/Lighting/litlpo_PoweringLEDs.html)

• [Notes on LEDs] (http://www.gizmology.net/LEDs.htm)
  Talks about different types of LEDs, mentioning typical brightnesses, voltages, and other intersting stuff.

• [All About Circuits : Reference] (http://www.allaboutcircuits.com/vol_5/index.html)
  Looks like a great collection of info; didn't get to read much of it.

• [Effects of Varying I2C Pull-Up Resistors] (http://dsscircuits.com/articles/effects-of-varying-i2c-pull-up-resistors.html) : article by Wayne Truchsess
  Great discussion on the topic, with oscilloscope graphs. The practical takeaway is that 4.7kΩ is a good value for 100kHz I²C, and 2.2kΩ is good for 400kHz.

C Stuff

• [comp.lang.c Frequently Asked Questions] (http://c-faq.com/index.html)
  Really good information, if they happen to address the question you have.

• [The C Preprocessor] (http://gcc.gnu.org/onlinedocs/gcc-2.95.3/cpp_1.html#SEC1) (on http://gcc.gnu.org/)
  One of my main references.

• [The GNU C Preprocessor] (http://tigcc.ticalc.org/doc/cpp.html#SEC27)
  A modified version on a different site. Has a few really useful things that I don't think I saw in the official documentation.

• [C Library Reference] (http://www.cplusplus.com/reference/) (on http://cplusplus.com)

• [C Operators/Expressions] (http://www.lix.polytechnique.fr/~liberti/public/computing/prog/c/C/CONCEPT/expressions.html) (on http://www.lix.polytechnique.fr/)

• [Bitwise Operators in C and C++: A Tutorial] (http://www.cprogramming.com/tutorial/bitwise_operators.html) (on http://cprogramming.com/)

• [AVR Tutorials - [TUT] [C] Bit manipulation (AKA "Programming 101")] (http://www.avrfreaks.net/index.php?name=PNphpBB2&file=printview&t=37871&start=0)

• [In C++ is "const" after type ID acceptable?] (http://stackoverflow.com/questions/988069/in-c-is-const-after-type-id-acceptable) (on http://stackoverflow.com/)

• [Arrays and pointers in C] (http://www.ibiblio.org/pub/languages/fortran/append-c.html) (on http://www.ibiblio.org/)

• [how to use array of function pointers?] (http://stackoverflow.com/questions/252748/how-to-use-array-of-function-pointers) (on http://stackoverflow.com/)

• [The Function Pointer Tutorials] (http://www.newty.de/fpt/index.html)

• [C preprocessor and concatenation] (http://stackoverflow.com/questions/1489932/c-preprocessor-and-concatenation) (on http://stackoverflow.com/)

• [The New C: Inline Functions] (http://drdobbs.com/184401540) by Randy Meyers (on http://drdobbs.com/)

• [gcc: why the -lm flag is needed to link the math library?] (http://stackoverflow.com/questions/4606301/gcc-why-the-lm-flag-is-needed-to-link-the-math-library) (on http://stackoverflow.com/)

For the AVR

• [AVR Newbie guide] (http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=70673) by stu_san (on http://www.avrfreaks.net/)
  Didn't read much of it, but it looks like a great collection of info.

• [AVR Libc Library Reference] (http://www.nongnu.org/avr-libc/user-manual/modules.html)
  One of my main references.

• [AVR : Data in Program Space] (http://www.nongnu.org/avr-libc/user-manual/pgmspace.html)
  How to use '<avr/pgmspace.h>'.

• [avr-libc/include/avr/iom32u4.h] (http://svn.savannah.nongnu.org/viewvc/trunk/avr-libc/include/avr/iom32u4.h?revision=2288&root=avr-libc&view=markup)
  List of registers and associated bit numbers for the ATmega32U4

• [A Brief Tutorial on Programming the AVR without Arduino] (https://www.mainframe.cx/~ckuethe/avr-c-tutorial/) by Chris Kuethe
  Goes over a bunch of stuff pretty generally. Useful to me because it was talking about exactly what I was trying to do (e.g. program the thing directly instead of messing around with gratuitous libraries).

• [Optimisations of AVR programs using avr-gcc] (http://www.tty1.net/blog/2008-04-29-avr-gcc-optimisations_en.html)
  About compiling and stuff.

• [Using the EEPROM memory in AVR-GCC]

  (http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=38417)

  tutorial by [Dean Camera] (http://fourwalledcubicle.com/AboutMe.php) (on http://www.avrfreaks.net/)
  The EEPROM is non-volatile data memory that can withstand 100,000 writes and is byte accessible from within the program. On the Teensy 2.0 there's only 1,024 bytes of it though (compared to 32,256 bytes of flash, and 2,560 bytes of RAM), so you have to use it sparingly. It's useful because flash (program) memory is not really something that's meant to be written to (it can only withstand 10,000 writes, and has to be written in pages using instructions meant for the bootloader), and RAM is volatile.

  • updated version available as a pdf at [Four Walled Cubicle : AVR Articles] (http://www.fourwalledcubicle.com/AVRArticles.php), along with a few other good articles on AVR programming

Protocol Stuff

I²C

• [Arduino I²C Expansion IO] (http://www.neufeld.newton.ks.us/electronics/?p=241) (from [Keith's Electronics Blog] (http://www.neufeld.newton.ks.us/electronics/))
  Didn't use this much, but it's nice (if you're using the Arduino 'Wire' library), and it has pictures.

• [Arduino Playground :: Wire Library, Explored] (http://arduino.cc/playground/Main/WireLibraryDetailedReference)
  More about the Wire library. If you're not using interrupts, I think you'll be better off looking throught the datasheet and writing your own trivial library in C. It really is trivial, almost all the code is in the datasheet (at least for the ATmega32U4), and it'll make more sense to you that way :) .

USB

• About Keyboard [Scan Codes] (http://geekhack.org/showwiki.php?title=Scan+Codes) (on http://geekhack.org/)
  Interesting discussion. For practical purposes, if you're just dealing with USB, you can skip this and go straight to the keyboard usage page in the HID Usage Tables (see below).

• [USB - boot mode, NKRO, compatibility, etc...]

  (http://geekhack.org/showthread.php?13162-USB-boot-mode-NKRO-compatibility-etc/page2)

  old thread by [Soarer] (http://geekhack.org/member.php?4274-Soarer) (on http://geekhack.org/)
  Discussion about getting NKRO to work over USB and still be compatible with various BIOSs.

• [USB 2.0 Specification]

  (http://www.usb.org/developers/docs/usb_20_101111.zip)

  zip (from http://www.usb.org/developers/docs/)

• [HID Device Class Definition]

  (http://www.usb.org/developers/devclass_docs/HID1_11.pdf)

  pdf (from http://www.usb.org/developers/hidpage)

  • HID = Human Interface Device

• [HID Usage Tables]

  (http://www.usb.org/developers/devclass_docs/Hut1_12v2.pdf)

  pdf (from http://www.usb.org/developers/hidpage)

Other People's Code

Keyboard Firmware

• zip: [Phantom Firmware from PrinsValium] (http://geekhack.org/attachment.php?attachmentid=38982&d=1327895092)
  Pretty basic (unless I'm missing nuances, which is entirely possible). Helped me a lot when I was learning how to initialize stuff on the Teensy.

  • mentioned in the [Building Phantom Hardware and Firmware Mods] (http://geekhack.org/showwiki.php?title=Island:26742) article (on http://geekhack.org/)

• github: [tmk / tmk_keyboard] (https://github.com/tmk/tmk_keyboard)
  Firmware by [hasu] (http://geekhack.org/member.php?3412-hasu) on geekhack. Supports NKRO and mouse movements.

  • forked by [Pyrolistical / tmk_keyboard] (https://github.com/Pyrolistical/tmk_keyboard/tree/master/fourway)

    • mentioned in the [KeyPoard] (http://geekhack.org/showwiki.php?title=Island:26845) article on http://geekhack.org/

  • forked by [riffautae / tmk_keyboard] (https://github.com/riffautae/tmk_keyboard)

    • mentioned on the [Teensy Keyboard Firmware Discussion] (http://geekhack.org/showthread.php?26730-Teensy-Keyboard-Firmware-Discussion/page2) thread on http://geekhack.org/

• github: [humblehacker / keyboard] (https://github.com/humblehacker/keyboard)
  Looks like it has some cool ideas, but I haven't read through it well enough to know what's going on.

  • mentioned on [the humblehacker keyboard website] (http://humblehacker.com/keyboard/)

  • mentioned on [the humblehacker geekhack page] (http://geekhack.org/showwiki.php?title=Island:6292)

  • mentioned on [the designer's blog] (http://humblehacker.com/blog/)

USB Libraries

• [LUFA (2012) (Lightweight USB Framework for AVRs)] (http://www.fourwalledcubicle.com/LUFA.php)
  Very well known USB library for AVRs. And it looks like it'd be really good too, but the documentation is hard to get into, and the examples don't seem to have enough explanation for me, since I don't have any background in what USB is doing in the first place.

• zip: [PJRC: usb_keyboard] (http://pjrc.com/teensy/usb_keyboard.zip)
  From the [LUFA Library : Alternative USB AVR Stacks] (http://www.fourwalledcubicle.com/files/LUFA/Doc/110528/html/_page__alternative_stacks.html) page: "Not so much a complete stack as a collection of USB enabled demos, this library is specifically designed for the PJRC Teensy line of USB AVRs, and thus may need to be modified for other USB AVR chips. These minimal code samples shows the inner workings of the USB controller, without all the abstraction present in most other USB AVR stacks."

  • mentioned on [the PJRC website] (http://pjrc.com/teensy/usb_keyboard.html)

• [V-USB] (http://vusb.wikidot.com/driver-api)
  From the [LUFA Library : Alternative USB AVR Stacks] (http://www.fourwalledcubicle.com/files/LUFA/Doc/110528/html/_page__alternative_stacks.html) page: "Well regarded and complete USB 1.1 software stack for several AVR models, implementing Low Speed HID. Used in many commercial and non-commercial designs, with user-submitted projects available for viewing on the company's website. Uses C language code mixed with assembly for time-critical sections."
  Also, it has really good documentation.

TWI Libraries

• github: [TWI library in C]

  (https://github.com/arduino/Arduino/tree/master/libraries/Wire/utility)

  (arduino / Arduino / libraries / Wire / utility)
  Well done (as far as I can tell) and complete (includes code for interrupt handling). Meant to be used through the Arduino 'Wire' library interface, but you can use it alone as well. The version on github pulls in a whole bunch of Arduino dependencies though, if you're just going to use the library look for an older version that doesn't (like the one included in the version of Arduino in the Ubuntu 11.10 repos).

• zip: [i2cmaster] (http://homepage.hispeed.ch/peterfleury/i2cmaster.zip) (by Peter Fleury, on [his homepage] (http://homepage.hispeed.ch/peterfleury/))
  Good I2C library. Includes stuff both in assembly and C (though, I didn't look at the assembly code). I still think you're better off writing your own, it's not that hard and you'll understand it better. Also, this library is under the GPL (from what it says on his site; couldn't find a licence in the code).

• forum: [Interfacing MCP23018 io expander via Arduino] (http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl?num=1282150189)
  Contains a quick MCP23017 library in C++. Didn't end up looking at it too hard.

• github: [maniacbug / Arduino / libraries / MCP23018] (https://github.com/maniacbug/Arduino/tree/master/libraries/MCP23018)
  Library in C++. Don't think I ended up looking through this one at all.

Other

• [Soarer's Converter (XT/AT/PS2/Terminal to USB Converter with NKRO)] (http://geekhack.org/showwiki.php?title=Island:17458)
  No code for the part that talks over USB though. Code only available for the tools that allow you to change the keymap and stuff, I think.

• zip: [PJRC: blinky] (http://pjrc.com/teensy/blinky.zip)
  Little baby example project for the Teensy. Quite nice.

  • mentioned on [the PJRC website] (http://pjrc.com/teensy/gcc.html)

Hardware Documentation

• [Microchip: Analog & Interface Product Selector Guide] (http://ww1.microchip.com/downloads/en/DeviceDoc/21060z.pdf)

  • from [the Microchip website (MCP23017 product listing page)] (http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en023499)

• [MCP23017 / MCP23S17 Data Sheet] (http://ww1.microchip.com/downloads/en/DeviceDoc/21952b.pdf)

  • from [the Microchip website] (http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en023499)

• [MCP23018 / MCP23S18 Data Sheet] (http://ww1.microchip.com/downloads/en/DeviceDoc/22103a.pdf)

  • from [the Microchip website] (http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en537375)

• [Teensy 2.0 (ATMEGA32U4) Data Sheet] (http://pjrc.com/teensy/atmega32u4.pdf)

  • from [the PJRC website] (http://pjrc.com/teensy/datasheets.html)

• [Teensy++ 2.0 (AT90USB1286) Data Sheet] (http://pjrc.com/teensy/at90usb1286.pdf)

  • from [the PJRC website] (http://pjrc.com/teensy/datasheets.html)

• [Teensy 2.0 Pin Assignments, Using C] (http://pjrc.com/teensy/card2a.pdf)

  • from [the PJRC website] (http://pjrc.com/teensy/datasheets.html)

• [Teensy 2.0 Pin Assignments, Using Arduino] (http://pjrc.com/teensy/card2b.pdf)

  • from [the PJRC website] (http://pjrc.com/teensy/datasheets.html)

• [Cherry MX Series Keyswitches : Specifications] (http://www.cherrycorp.com/english/switches/key/mx.htm)

Miscellaneous

Keyboard Testing Tools

• [Understanding Rollover] (http://gadzikowski.com/nkeyrollover.html)
  Includes 3 different tests (2 of which are web based) to see which keys are actually registering as pressed.

  • mentioned on the [Default:NKey Rollover] (http://geekhack.org/showwiki.php?title=NKey+Rollover+-+Overview+Testing+Methodology+and+Results) page (on http://geekhack.org/)

Typical Keyboard Information

• [Keyboard Scan Rates] (http://geekhack.org/showwiki.php?title=Keyboard+scan+rates) list (on http://geekhack.org/)
  Keyboards seem to typically scan at rates from a little below 100Hz to about 300Hz, with the most common values a little below 100Hz. The [PJRC usb_keyboard] (http://pjrc.com/teensy/usb_keyboard.html) example documentation has a limit of 1000 packets (so 500 presses -> releases) per second, but says that even that speed might overwhelm host software, which expects keystrokes to come much more slowly. And, a debounce time of 5ms (which is the spec'ed high value for Cherry MX switches) would give us a max scan rate of 200Hz.

Other Awesome Keyboard Projects

• [My DIY keyboard collection ( or how I became a KB-geek...)]

  (http://deskthority.net/workshop-f7/my-diy-keyboard-collection-or-how-i-became-a-kb-geek-t2534.html)

  post by [suka] (http://deskthority.net/suka-u434/) on http://deskthority.net/
  If I ever decide to do a keyboard completely by myself, I'm going back to this link and starting with this. Looks really well done.

  • linked to in [a post] (http://geekhack.org/showthread.php?22780-Interest-Check-Custom-split-ergo-keyboard&p=582593&viewfull=1#post582593) on the ergoDOX geekhack thread

Documentation and Design Tools

• [Markdown: Syntax] (http://daringfireball.net/projects/markdown/syntax)
  A necessity if your code is on github :) .

• [KiCAD Tutorial] (http://teholabs.com/knowledge/kicad.html) (on http://teholabs.com/)
  I like the tool. Didn't need the functionality just for a little circuit diagram though, so I forwent the learning curve and used Inkscape.

  • mentioned on the [circuit/block-diagram drawing] (http://stackoverflow.com/questions/6422603/circuit-block-diagram-drawing) question (on http://stackoverflow.com/)

• [TikZ and PGF]

  (http://www.texample.net/tikz/)

  a TeX graphics package
  This is really cool. And I wish i knew more about LaTeX (and all its variations) so that it would have been time effective for me to use it. If I ever need to do automatic diagram generation, I'm going to give this a more serious try.

  • mentioned on the [circuit/block-diagram drawing] (http://stackoverflow.com/questions/6422603/circuit-block-diagram-drawing) question (on http://stackoverflow.com/)

  • [Documentation (for version 2010-09-28)]

    (http://www.texample.net/media/pgf/builds/pgfmanualCVS2010-09-28.pdf)

    pdf

  • [Example: Block diagram line junctions] (http://www.texample.net/tikz/examples/line-junctions/)

• [Inkscape : Connector tool tutorial] (http://wiki.inkscape.org/wiki/index.php/UsingTheConnectorTool)
  The open source vector graphics tool. Not the best for diagrams (though, see the link; as that tool improves it will hopefully become much better), but it works and I like it :) .

---

Copyright © 2012 Ben Blazak benblazak.dev@gmail.com
Released under The MIT License (MIT) (see "license.md")
Project located at https://github.com/benblazak/ergodox-firmware