Captain Unlikely's LittleBits-USB interface - version 0.3

A simple circuit, firmware and software library for a device which will
interface between the "LittleBits" parts available from http://littlebits.cc
and computer (via USB). The board can act as an "input" for previous devices
(so it can report on a button being pressed, for example) and/or an "output"
for subsequent devices (so it can turn on or off a LED, for example). It also
supplies power to the circuit and has an on-board LED which can be controlled.

Software has been developed and tested on Linux and Mac OS X, Windows is
unsupported (but surely could be made to work with some effort).

Package contents
================
* eagle - contains the Eagle schematic and circuit board layout.

  The hardware is all surface-mount (SMT) and the parts required are:
  
  1 x Atmel ATtiny 85 or 45, 8 pin SOIC. Be careful to orientate correctly!
  1 x USB mini-B plug (any should be OK, I use uk.farnell.com product 2112367)
  1 x Dual 3.6V Zener, common anode, SOT23 package (eg uk.farnel.com 1773557)
  2 x 68ohm 0603 SMT resistor
  1 x 10kohm 0603 SMT resistor
  1 x 100nF 0603 SMT capacitor
  2 x 570ohm 0603 SMT resistor (or swap for 330 to 1K, to alter LED intensity)
  2 x 0603 SMT LED, any colors you like. Arrow on the part matches the arrow on
      the board. One is user-switchable, the other is on when power is supplied.
  1 x circuit board, which you can order from the excellent http://oshpark.com.
  2 x LittleBit connectors, one of each polarity, scavenged from an official
      LittleBits part as they don't sell them. When installing ensure the arrows
      on the board match the arrows on the board you took the connectors from.

  The processor is an Atmel attiny85, which will need to be flashed with the
  firmware. Personally I use a Teensy 2.0 running with an "avrisp" program, and
  I use a programming/test clip. For soldering I use a hotplate, a syringe of
  solder paster and a steady hand. The blog at http://captainunlikely.com has
  more details on using the Teensy as a programmer and SMT soldering, and there
  are many other sites on the web covering it as well. It's not difficult!

  Note: if you are designing your own board, the eagle components for the
  LittleBits connectors are NOT the same as those from the LittleBits github
  circuits, which don't fit - I presume they were for an older design. I have
  included the modified designs in the library in the "eagle" folder.


* firmware - the firmware for the Atmel attiny85 chip. Include the USB stack
  from vusb. The firmware needs to be compiled with the avg-gcc toolkit and
  flashed onto the device using avrdude - depending on your setup this may
  require modifications to the Makefile.


* software - this has been tested on OS X and Linux. It requires the libusb-1.0
  library, so for Linux it's
    * apt-get install libusb-1.0-0-dev libusb-1.0-0 pkg-config.
  Mac the packages can be installed from
    * http://code.google.com/p/rudix/wiki/libusb
    * http://code.google.com/p/rudix/wiki/pkg_config

  If the the "libusb" package is older than 1.0.9 the compile will fail with
  "undefined reference to `libusb_error_name'". In this case comment out the
  HAS_USB_ERROR_NAME in the Makefile.

  The "littleclient" is a basic example which can be run from the command line:
  example use would be "littleclient list" to list devices, "littleclient on"
  to turn on the output signal, or "littleclient poll" to listen for state
  changes on the input signal and print them to stdout. The "littlelib.h"
  describes the API in the littlelib.c library, which can be included in your
  own projects.


Scratch integration
===================
  You can also integrate the "littleclient" with MIT's "Scratch" software - see
  http://scratch.mit.edu.  Run the client as "littleclient scratch". By default
  it will connect to scratch running on the local machine, although that can be
  changed on the command line. If no device is connected or no scratch is running,
  it will sleep until both those requirements are met.

  Scratch needs to be listening for remote sensors - to do this, open the list of
  "sensing" options, right click on the "slider sensor value" or "sensor button
  pressed" entries down the bottom and select "enable remote sensor connections".
  The client communicates with Scratch via broadcast messages, namely:

  littlebit-input-on    sent from the client to Scratch when input turns on
  littlebit-input-off   sent from the client to Scratch when input turns off
  littlebit-output-on   send from Scratch to client to turn the output on
  littlebit-output-off  send from Scratch to client to turn the output off
  littlebit-output-flip send from Scratch to client to toggle the output
  littlebit-led-on      send from Scratch to client to turn the LED on
  littlebit-led-off     send from Scratch to client to turn the LED off
  littlebit-led-flip    send from Scratch to client to toggle the LED

  For example, a rule "when space key pressed, broadcast littlebit-output-flip"
  will toggle the output when the space bar is pressed in Scratch.


Finally, note that LittleBits are a trademark of "littleBits Electronics Inc"
and you use all of the above at your own risk.

                                                                     2013-09-05
                                                     http://captainunlikely.com
