Firmware for the ColorHug2 device
C Makefile
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
18F46J50.lkr
COPYING
ColorHug.h
HardwareProfile.h
Makefile
README
bootloader.c
ch-common.c
ch-common.h
ch-flash.c
ch-flash.h
ch-math.c
ch-math.h
ch-mcdc04.c
ch-mcdc04.h
ch-sram.c
ch-sram.h Add commands to read and write from the SRAM Jun 6, 2014
ch-temp.c
ch-temp.h Add support for the Microchip TCN75A to get the ambient temperature Jun 6, 2014
firmware.c
firmware.metainfo.xml
usb_config.h
usb_descriptors.c

README

		ColorHug2 Firmware README

Right, you're probably reading this file as you want to make a driver
for the ColorHug2 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 small USB peripheral that connects to the host computer
and takes XYZ measurements of a specified accuracy. Longer measurements
lead to a more accurate result, but take more time.

The device has two LEDs that can either be switched on or off, or be
programmed to do a repeated flashing with specified on and off durations.

The device supports up to 64 calibration matrices, and by default 3 are
provided which are mapped to lcd, crt and projector, with 3 additonal
reserved types.

== Communication Protocol ==

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

To connect to the ColorHug, do the following:

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

The ColorHug 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, but
   this time the buffer size has to be the exact number of bytes you are
   expecting from the command[2].

  - 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.
    If the error is non-zero, then the data will only be two bytes long.

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

== Getting XYZ readings from the device ==

 * Take reading #1 with matrix m
 * Take reading #2 with matrix m
 * Take reading #n with matrix m

The matrix 'm' is specified at sample time. Different values of 'm'
specify different calibration matrices in the device, of which there are
three default matrices available. By specifying a value of 'm' < 64 an
explicit matrix is used, but by specifying a map index the default matrix
for that type will be chosen.

The map index values are as follows:
    m=64        LCD
    m=65        CRT
    m=66        Projector
    m=67        LED
    m=68-69     Reserved for future use

The user can change the default LCD, CRT and projector mappings and also
load on new CCMX matrices using the provided colorhug-ccmx GUI tool.

== Floating point format ==

The device returns non-trivial numbers as packed floats. This means the
number is returned as a 64 bit signed number, with the offset set at
32 bits. This leads to the largest and smallest number being acceptable
as being +/-32768 with a precision of at least 0.0001.

To convert a number to a packed float, simply multiply it by 0x10000
ensuring the temporary and final result has sufficient clearance for a
64 bit number.

== 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 firmware version will be 0.x.x for the bootloader, and 1.x.x for the
firmware. 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 an XYZ reading.