Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
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. - 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.