hughski/colorhug-als-firmware

		ColorHugALS Firmware README

Right, you're probably reading this file as you want to make a driver
for the ColorHugALS hardware.

If you came here for modifying, building and flashing the firmware
please have a look at the Makefiles.

This is the basics:

== General Device Information ==

The device is a tiny USB peripheral that connects to the host computer and takes
RGB ambient measurements.

The device has one LEDs that can either be switched on or off.

== Communication Protocol ==

The only way to contact the ColorHugALS is a HID 64 byte response-reply
format. The ColorHugALS never initiates any kind of data exchange and so
only needs one non-default endpoint.

To connect to the ColorHugALS, do the following:

 * Open USB device VID=0x273f, PID=0x1007
 * Set configuration #1
 * Claim interface #0 (unregister any kernel driver if present)

The ColorHugALS now will accept commands from the host.

To send a command you have to:

 * Do an interrupt transfer on endpoint 0x01 with a buffer size of 64 bytes

  - The buffer has to be in the following LE format:
        [1:cmd][63:data]
    ...where the cmd is a single byte that can be found in ColorHug.h

  - The [63:data] format is different for each command, and these formats
    can be found again in ColorHug.h. If less data is specified than 63
    bytes, then the remaining data is ignored by the device.

 * Then immediately do another interrupt transfer on endpoint 0x81 with again
   a 64 byte buffer size.

  - The returned buffer will be in the following LE format:
        [1:retval][1:cmd][62:data]
    where the command is a single byte command that was used to get the
    data and the retval is set to 0 for success, or any other error
    constant found in ColorHug.h

  - The [62:data] format is different for each command, and these formats
    can be found again in ColorHug.h.

The host has 400ms to read the interrupt transfer on endpoint 0x81
before the device re-enumerates on the USB bus.

== Getting RGB readings from the device ==

 * Set the multiplier to 100%
 * Set the integral time to 0xffff
 * Set the color select to white
 * Take reading
 * Set the multiplier to 0%

The multiplier enables the color sensor in the device and by setting it
to 100% enables all the inputs in the device. This uses power, and so
the multiplier is set back to 0% (sensor off) after all the samples have
been taken.

The integral time has been set to 0xffff here, which is the maximum
precision available (up to 98302 pulses counted per sample). A maximum
precision reading takes about 500ms, although accurate readings can be
still obtained using an integral time of 1/4 of this value.

The integral time and the time to take a reading is approximately linear,
although care should be taken when using the smaller integral times that
the display refresh has happened and that the new color is actually
showing on the monitor.

== Firmware versions ==

The user can easily load on new firmware images using the colorhug-flash
GUI program, or the 'colorhug' command line tool located in /usr/libexec.

The device will enter a bootloader if programming the device
failed or was interrupted, or if the device is soft-reset at runtime.

When the device is in bootloader mode the LEDs will flash in an
alternate pattern to advise the user that it is not fully functional.
When the device is in the bootloader some commands are available that
are not available to the firmware (for instance, ERASH_FLASH) and also
vice-versa, in that the bootloader cannot enable the color sensor and
take readings. Similarly, the SET_FLASH_SUCCESS command will accept
different values in bootloader and firmware modes.

In normal operation the device will not need to access the bootloader
mode and no other commands are required to get a reading.