Debian Codegraph @

lib/colorhug/ch-common.h

raw
1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
2 *
3 * Copyright (C) 2011-2015 Richard Hughes <[email protected]>
4 *
5 * Licensed under the GNU General Public License Version 2
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20 */
21
22 #if !defined (__COLORHUG_H_INSIDE__) && !defined (CD_COMPILATION)
23 #error "Only <colorhug.h> can be included directly."
24 #endif
25
26 #ifndef CH_COMMON_H
27 #define CH_COMMON_H
28
29 #include <glib.h>
30 #include <gusb.h>
31
32 G_BEGIN_DECLS
33
34 /* device constants */
35 #define CH_USB_VID 0x273f
36 #define CH_USB_PID_BOOTLOADER 0x1000
37 #define CH_USB_PID_BOOTLOADER_DFU 0x100a
38 #define CH_USB_PID_BOOTLOADER2 0x1005
39 #define CH_USB_PID_BOOTLOADER_ALS 0x1006 /* since 1.2.9 */
40 #define CH_USB_PID_BOOTLOADER_PLUS 0x1003
41 #define CH_USB_PID_FIRMWARE 0x1001
42 #define CH_USB_PID_FIRMWARE_DFU 0x1009
43 #define CH_USB_PID_FIRMWARE2 0x1004
44 #define CH_USB_PID_FIRMWARE_ALS 0x1007 /* since 1.2.9 */
45 #define CH_USB_PID_FIRMWARE_ALS_SENSOR_HID 0x1008 /* since 1.2.11 */
46 #define CH_USB_PID_FIRMWARE_PLUS 0x1002
47 #define CH_USB_CONFIG 0x0001
48 #define CH_USB_INTERFACE 0x0000
49 #define CH_USB_HID_EP 0x01
50 #define CH_USB_HID_EP_IN (CH_USB_HID_EP | 0x80)
51 #define CH_USB_HID_EP_OUT (CH_USB_HID_EP | 0x00)
52 #define CH_USB_HID_EP_SIZE 64
53
54 /* old device constants */
55 #define CH_USB_VID_LEGACY 0x04d8
56 #define CH_USB_PID_LEGACY 0xf8da
57
58 /* the default timeout in client tools */
59 #define CH_DEVICE_USB_TIMEOUT 10000 /* ms */
60
61 /* constants for ownership tags */
62 #define CH_OWNER_LENGTH_MAX 60
63
64 /**
65 * CH_CMD_GET_COLOR_SELECT:
66 *
67 * Get the color select state.
68 *
69 * IN: [1:cmd]
70 * OUT: [1:retval][1:cmd][1:color_select]
71 *
72 * This command is available under these conditions:
73 *
74 * | Bootloader | Firmware
75 * ---------------+--------------+-----------
76 * ColorHug | × | ✓
77 * ColorHug2 | × | ×
78 * ColorHug+ | × | ×
79 * ColorHugALS | × | ✓
80 *
81 * Since: 0.1.29
82 **/
83 #define CH_CMD_GET_COLOR_SELECT 0x01
84
85 /**
86 * CH_CMD_SET_COLOR_SELECT:
87 *
88 * Set the color select state.
89 *
90 * IN: [1:cmd][1:color_select]
91 * OUT: [1:retval][1:cmd]
92 *
93 * This command is available under these conditions:
94 *
95 * | Bootloader | Firmware
96 * ---------------+--------------+-----------
97 * ColorHug | × | ✓
98 * ColorHug2 | × | ×
99 * ColorHug+ | × | ×
100 * ColorHugALS | × | ✓
101 *
102 * Since: 0.1.29
103 **/
104 #define CH_CMD_SET_COLOR_SELECT 0x02
105
106 /**
107 * CH_CMD_GET_MULTIPLIER:
108 *
109 * Gets the multiplier value.
110 *
111 * IN: [1:cmd]
112 * OUT: [1:retval][1:cmd][1:multiplier_value]
113 *
114 * This command is available under these conditions:
115 *
116 * | Bootloader | Firmware
117 * ---------------+--------------+-----------
118 * ColorHug | × | ✓
119 * ColorHug2 | × | ×
120 * ColorHug+ | × | ×
121 * ColorHugALS | × | ✓
122 *
123 * Since: 0.1.29
124 **/
125 #define CH_CMD_GET_MULTIPLIER 0x03
126
127 /**
128 * CH_CMD_SET_MULTIPLIER:
129 *
130 * Sets the multiplier value.
131 *
132 * IN: [1:cmd][1:multiplier_value]
133 * OUT: [1:retval][1:cmd]
134 *
135 * This command is available under these conditions:
136 *
137 * | Bootloader | Firmware
138 * ---------------+--------------+-----------
139 * ColorHug | × | ✓
140 * ColorHug2 | × | ×
141 * ColorHug+ | × | ×
142 * ColorHugALS | × | ✓
143 *
144 * Since: 0.1.29
145 **/
146 #define CH_CMD_SET_MULTIPLIER 0x04
147
148 /**
149 * CH_CMD_GET_INTEGRAL_TIME:
150 *
151 * Gets the integral time.
152 *
153 * IN: [1:cmd]
154 * OUT: [1:retval][1:cmd][2:integral_time]
155 *
156 * This command is available under these conditions:
157 *
158 * | Bootloader | Firmware
159 * ---------------+--------------+-----------
160 * ColorHug | × | ✓
161 * ColorHug2 | × | ×
162 * ColorHug+ | × | ✓
163 * ColorHugALS | × | ✓
164 *
165 * Since: 0.1.29
166 **/
167 #define CH_CMD_GET_INTEGRAL_TIME 0x05
168
169 /**
170 * CH_CMD_SET_INTEGRAL_TIME:
171 *
172 * Sets the integral time.
173 *
174 * IN: [1:cmd][2:integral_time]
175 * OUT: [1:retval][1:cmd]
176 *
177 * This command is available under these conditions:
178 *
179 * | Bootloader | Firmware
180 * ---------------+--------------+-----------
181 * ColorHug | × | ✓
182 * ColorHug2 | × | ×
183 * ColorHug+ | × | ✓
184 * ColorHugALS | × | ✓
185 *
186 * Since: 0.1.29
187 **/
188 #define CH_CMD_SET_INTEGRAL_TIME 0x06
189
190 /**
191 * CH_CMD_GET_FIRMWARE_VERSION:
192 *
193 * Gets the firmware version.
194 *
195 * IN: [1:cmd]
196 * OUT: [1:retval][1:cmd][2:major][2:minor][2:micro]
197 *
198 * This command is available under these conditions:
199 *
200 * | Bootloader | Firmware
201 * ---------------+--------------+-----------
202 * ColorHug | ✓ | ✓
203 * ColorHug2 | ✓ | ✓
204 * ColorHug+ | ✓ | ✓
205 * ColorHugALS | ✓ | ✓
206 *
207 * Since: 0.1.29
208 **/
209 #define CH_CMD_GET_FIRMWARE_VERSION 0x07
210
211 /**
212 * CH_CMD_GET_CALIBRATION:
213 *
214 * Gets the calibration matrix. The description does not have to be NULL
215 * terminated.
216 *
217 * @types is a bitmask which corresponds to:
218 *
219 * bit:
220 * 0 Can be used with LCD panels
221 * 1 Can be used with CRT monitors
222 * 2 Can be used with projectors
223 * 3 Can be used with LED panels
224 * 4-7 Reserved for future use
225 *
226 * IN: [1:cmd][2:index]
227 * OUT: [1:retval][1:cmd][2*9:matrix_value][1:types][23:description]
228 *
229 * This command is available under these conditions:
230 *
231 * | Bootloader | Firmware
232 * ---------------+--------------+-----------
233 * ColorHug | × | ✓
234 * ColorHug2 | × | ✓
235 * ColorHug+ | × | ×
236 * ColorHugALS | × | ×
237 *
238 * Since: 0.1.29
239 **/
240 #define CH_CMD_GET_CALIBRATION 0x09
241
242 /**
243 * CH_CMD_SET_CALIBRATION:
244 *
245 * Sets the calibration matrix.
246 *
247 * IN: [1:cmd][2:index][4*9:matrix_value][1:types][23:description]
248 * OUT: [1:retval][1:cmd]
249 *
250 * This command is available under these conditions:
251 *
252 * | Bootloader | Firmware
253 * ---------------+--------------+-----------
254 * ColorHug | × | ✓
255 * ColorHug2 | × | ✓
256 * ColorHug+ | × | ×
257 * ColorHugALS | × | ×
258 *
259 * Since: 0.1.29
260 **/
261 #define CH_CMD_SET_CALIBRATION 0x0a
262
263 /**
264 * CH_CMD_GET_SERIAL_NUMBER:
265 *
266 * Gets the device serial number.
267 *
268 * IN: [1:cmd]
269 * OUT: [1:retval][1:cmd][4:serial_number]
270 *
271 * This command is available under these conditions:
272 *
273 * | Bootloader | Firmware
274 * ---------------+--------------+-----------
275 * ColorHug | × | ✓
276 * ColorHug2 | × | ✓
277 * ColorHug+ | × | ✓
278 * ColorHugALS | × | ✓
279 *
280 * Since: 0.1.29
281 **/
282 #define CH_CMD_GET_SERIAL_NUMBER 0x0b
283
284 /**
285 * CH_CMD_SET_SERIAL_NUMBER:
286 *
287 * Sets the device serial number.
288 *
289 * IN: [1:cmd][4:serial_number]
290 * OUT: [1:retval][1:cmd]
291 *
292 * This command is available under these conditions:
293 *
294 * | Bootloader | Firmware
295 * ---------------+--------------+-----------
296 * ColorHug | × | ✓
297 * ColorHug2 | × | ✓
298 * ColorHug+ | × | ✓
299 * ColorHugALS | × | ×
300 *
301 * Since: 0.1.29
302 **/
303 #define CH_CMD_SET_SERIAL_NUMBER 0x0c
304
305 /**
306 * CH_CMD_GET_LEDS:
307 *
308 * Get the LED state.
309 *
310 * IN: [1:cmd]
311 * OUT: [1:retval][1:cmd][1:led_state]
312 *
313 * This command is available under these conditions:
314 *
315 * | Bootloader | Firmware
316 * ---------------+--------------+-----------
317 * ColorHug | × | ✓
318 * ColorHug2 | × | ✓
319 * ColorHug+ | × | ✓
320 * ColorHugALS | ✓ | ✓
321 *
322 * Since: 0.1.29
323 **/
324 #define CH_CMD_GET_LEDS 0x0d
325
326 /**
327 * CH_CMD_SET_LEDS:
328 *
329 * Set the LED state. Using a @repeat value of anything other than
330 * 0 will block the processor for the duration of the command.
331 *
332 * If @repeat is not 0, then the LEDs are reset to all off at the end
333 * of the sequence.
334 *
335 * IN: [1:cmd][1:led_state][1:repeat][1:on-time][1:off-time]
336 * OUT: [1:retval][1:cmd]
337 *
338 * This command is available under these conditions:
339 *
340 * | Bootloader | Firmware
341 * ---------------+--------------+-----------
342 * ColorHug | × | ✓
343 * ColorHug2 | × | ✓
344 * ColorHug+ | × | ✓
345 * ColorHugALS | × | ✓
346 *
347 * Since: 0.1.29
348 **/
349 #define CH_CMD_SET_LEDS 0x0e
350
351 /**
352 * CH_CMD_GET_ILLUMINANTS:
353 *
354 * Get the illuminant state.
355 *
356 * IN: [1:cmd]
357 * OUT: [1:retval][1:cmd][1:illuminants]
358 *
359 * This command is available under these conditions:
360 *
361 * | Bootloader | Firmware
362 * ---------------+--------------+-----------
363 * ColorHug | × | ×
364 * ColorHug2 | × | ×
365 * ColorHug+ | × | ✓
366 * ColorHugALS | × | ×
367 *
368 * Since: 1.3.4
369 **/
370 #define CH_CMD_GET_ILLUMINANTS 0x15
371
372 /**
373 * CH_CMD_SET_ILLUMINANTS:
374 *
375 * Set the illuminants.
376 *
377 * IN: [1:cmd][1:illuminant]
378 * OUT: [1:retval][1:cmd]
379 *
380 * This command is available under these conditions:
381 *
382 * | Bootloader | Firmware
383 * ---------------+--------------+-----------
384 * ColorHug | × | ×
385 * ColorHug2 | × | ×
386 * ColorHug+ | × | ✓
387 * ColorHugALS | × | ×
388 *
389 * Since: 1.3.4
390 **/
391 #define CH_CMD_SET_ILLUMINANTS 0x16
392
393 /**
394 * CH_CMD_GET_DARK_OFFSETS:
395 *
396 * Get the dark offsets.
397 *
398 * IN: [1:cmd]
399 * OUT: [1:retval][1:cmd][2:red][2:green][2:blue]
400 *
401 * This command is available under these conditions:
402 *
403 * | Bootloader | Firmware
404 * ---------------+--------------+-----------
405 * ColorHug | × | ✓
406 * ColorHug2 | × | ×
407 * ColorHug+ | × | ✓
408 * ColorHugALS | × | ×
409 *
410 * Since: 0.1.29
411 **/
412 #define CH_CMD_GET_DARK_OFFSETS 0x0f
413
414 /**
415 * CH_CMD_SET_DARK_OFFSETS:
416 *
417 * Set the dark offsets for use when taking samples when the measure
418 * mode is FREQUENCY. When the measure mode is DURATION these values
419 * have no effect.
420 *
421 * IN: [1:cmd][2:red][2:green][2:blue]
422 * OUT: [1:retval][1:cmd]
423 *
424 * This command is available under these conditions:
425 *
426 * | Bootloader | Firmware
427 * ---------------+--------------+-----------
428 * ColorHug | × | ✓
429 * ColorHug2 | × | ×
430 * ColorHug+ | × | ✓
431 * ColorHugALS | × | ×
432 *
433 * Since: 0.1.29
434 **/
435 #define CH_CMD_SET_DARK_OFFSETS 0x10
436
437 /**
438 * CH_CMD_GET_OWNER_NAME:
439 *
440 * Get User's Name
441 *
442 * IN: [1:cmd]
443 * OUT: [1:retval][1:cmd][60:owner-name]
444 *
445 * This command is available under these conditions:
446 *
447 * | Bootloader | Firmware
448 * ---------------+--------------+-----------
449 * ColorHug | × | ✓
450 * ColorHug2 | × | ✓
451 * ColorHug+ | × | ✓
452 * ColorHugALS | × | ×
453 *
454 * Since: 0.1.29
455 **/
456 #define CH_CMD_GET_OWNER_NAME 0x11
457
458 /**
459 * CH_CMD_SET_OWNER_NAME:
460 *
461 * Set User's Name
462 *
463 * IN: [1:cmd][60:owner-name]
464 * OUT: [1:retval][1:cmd]
465 *
466 * This command is available under these conditions:
467 *
468 * | Bootloader | Firmware
469 * ---------------+--------------+-----------
470 * ColorHug | × | ✓
471 * ColorHug2 | × | ✓
472 * ColorHug+ | × | ✓
473 * ColorHugALS | × | ×
474 *
475 * Since: 0.1.29
476 **/
477 #define CH_CMD_SET_OWNER_NAME 0x12
478
479 /**
480 * CH_CMD_GET_OWNER_EMAIL:
481 *
482 * Get User's Email Address
483 *
484 * IN: [1:cmd]
485 * OUT: [1:retval][1:cmd][60:owner-email]
486 *
487 * This command is available under these conditions:
488 *
489 * | Bootloader | Firmware
490 * ---------------+--------------+-----------
491 * ColorHug | × | ✓
492 * ColorHug2 | × | ✓
493 * ColorHug+ | × | ✓
494 * ColorHugALS | × | ×
495 *
496 * Since: 0.1.29
497 **/
498 #define CH_CMD_GET_OWNER_EMAIL 0x13
499
500 /**
501 * CH_CMD_SET_OWNER_EMAIL:
502 *
503 * Set User's Email Address
504 *
505 * IN: [1:cmd][60:owner-email]
506 * OUT: [1:retval][1:cmd]
507 *
508 * This command is available under these conditions:
509 *
510 * | Bootloader | Firmware
511 * ---------------+--------------+-----------
512 * ColorHug | × | ✓
513 * ColorHug2 | × | ✓
514 * ColorHug+ | × | ✓
515 * ColorHugALS | × | ×
516 *
517 * Since: 0.1.29
518 **/
519 #define CH_CMD_SET_OWNER_EMAIL 0x14
520
521 /**
522 * CH_CMD_WRITE_EEPROM:
523 *
524 * Write values to EEPROM.
525 *
526 * IN: [1:cmd][8:eeprom_magic]
527 * OUT: [1:retval][1:cmd]
528 *
529 * This command is available under these conditions:
530 *
531 * | Bootloader | Firmware
532 * ---------------+--------------+-----------
533 * ColorHug | × | ✓
534 * ColorHug2 | × | ✓
535 * ColorHug+ | × | ✓
536 * ColorHugALS | × | ×
537 *
538 * Since: 0.1.29
539 **/
540 #define CH_CMD_WRITE_EEPROM 0x20
541
542 /**
543 * CH_CMD_TAKE_READING_RAW:
544 *
545 * Take a raw reading.
546 *
547 * IN: [1:cmd]
548 * OUT: [1:retval][1:cmd][4:count]
549 *
550 * This command is available under these conditions:
551 *
552 * | Bootloader | Firmware
553 * ---------------+--------------+-----------
554 * ColorHug | × | ✓
555 * ColorHug2 | × | ×
556 * ColorHug+ | × | ✓
557 * ColorHugALS | × | ✓
558 *
559 * Since: 0.1.29
560 **/
561 #define CH_CMD_TAKE_READING_RAW 0x21
562
563 /**
564 * CH_CMD_TAKE_READINGS:
565 *
566 * Take a reading taking into account just dark offsets.
567 * All of @red, @green and @blue are packed float values.
568 *
569 * This command is useful if you want to do an ambient reading.
570 *
571 * IN: [1:cmd]
572 * OUT: [1:retval][1:cmd][4:red][4:green][4:blue]
573 *
574 * This command is available under these conditions:
575 *
576 * | Bootloader | Firmware
577 * ---------------+--------------+-----------
578 * ColorHug | × | ✓
579 * ColorHug2 | × | ✓
580 * ColorHug+ | × | ✓
581 * ColorHugALS | × | ×
582 *
583 * Since: 0.1.29
584 **/
585 #define CH_CMD_TAKE_READINGS 0x22
586
587 /**
588 * CH_CMD_TAKE_READING_XYZ:
589 *
590 * Take a reading taking into account:
591 * 1. dark offsets
592 * 2. the calibration matrix
593 *
594 * If the calibration index > %CH_CALIBRATION_MAX then the calibration
595 * map is used to find the default calibration index to use.
596 *
597 * If the calibration index is set to %CH_CALIBRATION_SPECTRAL then the
598 * spectral hardware is used if it is available. The CIE 1931 luminosity
599 * function data is used by default.
600 *
601 * IN: [1:cmd][2:calibration-index]
602 * OUT: [1:retval][1:cmd][4:red][4:green][4:blue]
603 *
604 * This command is available under these conditions:
605 *
606 * | Bootloader | Firmware
607 * ---------------+--------------+-----------
608 * ColorHug | × | ✓
609 * ColorHug2 | × | ✓
610 * ColorHug+ | × | ✓
611 * ColorHugALS | × | ×
612 *
613 * Since: 0.1.29
614 **/
615 #define CH_CMD_TAKE_READING_XYZ 0x23
616
617 /**
618 * CH_CMD_TAKE_READING_SPECTRAL:
619 *
620 * Takes a spectral reading putting %CH_CCD_SPECTRAL_RESOLUTION uint16_t values
621 * (typically 7296 bytes) in SRAM.
622 * The values are scaled from 0x0000 to 0x03ff and correspond to the actual
623 * signal amplitude once Vref- and Vref+ have been taken into account.
624 *
625 * IN: [1:cmd]
626 * OUT: [1:retval][1:cmd][4:addr]
627 *
628 * This command is available under these conditions:
629 *
630 * | Bootloader | Firmware
631 * ---------------+--------------+-----------
632 * ColorHug | × | ×
633 * ColorHug2 | × | ×
634 * ColorHug+ | × | ✓
635 * ColorHugALS | × | ×
636 *
637 * Since: 0.1.31
638 **/
639 #define CH_CMD_TAKE_READING_SPECTRAL 0x55
640
641 /**
642 * CH_CMD_GET_ADC_CALIBRATION_POS:
643 *
644 * Gets the value of the Vref+ ADC adjustment.
645 * @vref is a packed float.
646 *
647 * IN: [1:cmd]
648 * OUT: [1:retval][1:cmd][4:vref]
649 *
650 * This command is available under these conditions:
651 *
652 * | Bootloader | Firmware
653 * ---------------+--------------+-----------
654 * ColorHug | × | ×
655 * ColorHug2 | × | ×
656 * ColorHug+ | × | ✓
657 * ColorHugALS | × | ×
658 *
659 * Since: 0.1.31
660 **/
661 #define CH_CMD_GET_ADC_CALIBRATION_POS 0x51
662
663 /**
664 * CH_CMD_GET_ADC_CALIBRATION_NEG:
665 *
666 * Gets the value of the Vref- ADC adjustment.
667 * @vref is a packed float.
668 *
669 * IN: [1:cmd]
670 * OUT: [1:retval][1:cmd][4:vref]
671 *
672 * This command is available under these conditions:
673 *
674 * | Bootloader | Firmware
675 * ---------------+--------------+-----------
676 * ColorHug | × | ×
677 * ColorHug2 | × | ×
678 * ColorHug+ | × | ✓
679 * ColorHugALS | × | ×
680 *
681 * Since: 0.1.31
682 **/
683 #define CH_CMD_GET_ADC_CALIBRATION_NEG 0x52
684
685 /**
686 * CH_CMD_GET_CCD_CALIBRATION:
687 *
688 * Gets the spectral indexes for the RGB calibration which are values between 0
689 * and %CH_CCD_SPECTRAL_RESOLUTION pointing to the dominant peak for the color.
690 * Red is nominally 625nm, green 520nm and blue 465nm.
691 *
692 * IN: [1:cmd]
693 * OUT: [1:retval][1:cmd][2:red-idx][2:green-idx][2:blue-idx]
694 *
695 * This command is available under these conditions:
696 *
697 * | Bootloader | Firmware
698 * ---------------+--------------+-----------
699 * ColorHug | × | ×
700 * ColorHug2 | × | ×
701 * ColorHug+ | × | ✓
702 * ColorHugALS | × | ×
703 *
704 * Since: 0.1.31
705 **/
706 #define CH_CMD_GET_CCD_CALIBRATION 0x53
707
708 /**
709 * CH_CMD_SET_CCD_CALIBRATION:
710 *
711 * Sets the spectral indexes for the RGB calibration.
712 *
713 * IN: [1:cmd][2:red-idx][2:green-idx][2:blue-idx]
714 * OUT: [1:retval][1:cmd]
715 *
716 * This command is available under these conditions:
717 *
718 * | Bootloader | Firmware
719 * ---------------+--------------+-----------
720 * ColorHug | × | ×
721 * ColorHug2 | × | ×
722 * ColorHug+ | × | ✓
723 * ColorHugALS | × | ×
724 *
725 * Since: 0.1.31
726 **/
727 #define CH_CMD_SET_CCD_CALIBRATION 0x54
728
729 /**
730 * CH_CMD_RESET:
731 *
732 * Reset the processor.
733 *
734 * IN: [1:cmd]
735 * OUT: [1:retval][1:cmd] (but with success the device will disconnect)
736 *
737 * This command is available under these conditions:
738 *
739 * | Bootloader | Firmware
740 * ---------------+--------------+-----------
741 * ColorHug | ✓ | ✓
742 * ColorHug2 | ✓ | ✓
743 * ColorHug+ | ✓ | ✓
744 * ColorHugALS | ✓ | ✓
745 *
746 * Since: 0.1.29
747 **/
748 #define CH_CMD_RESET 0x24
749
750 /**
751 * CH_CMD_READ_FLASH:
752 *
753 * Read in raw data from the flash memory.
754 *
755 * IN: [1:cmd][2:address][1:length]
756 * OUT: [1:retval][1:cmd][1:checksum][1-60:data]
757 *
758 * This command is available under these conditions:
759 *
760 * | Bootloader | Firmware
761 * ---------------+--------------+-----------
762 * ColorHug | ✓ | ×
763 * ColorHug2 | ✓ | ×
764 * ColorHug+ | ✓ | ×
765 * ColorHugALS | ✓ | ×
766 *
767 * Since: 0.1.29
768 **/
769 #define CH_CMD_READ_FLASH 0x25
770
771 /**
772 * CH_CMD_ERASE_FLASH:
773 *
774 * Erases flash memory before a write is done.
775 * Erasing flash can only be done in 1k byte chunks and should be
776 * aligned to 1k.
777 *
778 * IN: [1:cmd][2:address][2:length]
779 * OUT: [1:retval][1:cmd]
780 *
781 * This command is available under these conditions:
782 *
783 * | Bootloader | Firmware
784 * ---------------+--------------+-----------
785 * ColorHug | ✓ | ×
786 * ColorHug2 | ✓ | ×
787 * ColorHug+ | ✓ | ×
788 * ColorHugALS | ✓ | ×
789 *
790 * Since: 0.1.29
791 **/
792 #define CH_CMD_ERASE_FLASH 0x29
793
794 /**
795 * CH_CMD_WRITE_FLASH:
796 *
797 * Write raw data to the flash memory. You can only write aligned to
798 * a 32 byte boundary, and you must flush any incomplete 64 byte block.
799 *
800 * IN: [1:cmd][2:address][1:length][1:checksum][1-32:data]
801 * OUT: [1:retval][1:cmd]
802 *
803 * This command is available under these conditions:
804 *
805 * | Bootloader | Firmware
806 * ---------------+--------------+-----------
807 * ColorHug | ✓ | ×
808 * ColorHug2 | ✓ | ×
809 * ColorHug+ | ✓ | ×
810 * ColorHugALS | ✓ | ×
811 *
812 * Since: 0.1.29
813 **/
814 #define CH_CMD_WRITE_FLASH 0x26
815
816 /**
817 * CH_CMD_BOOT_FLASH:
818 *
819 * Boot into to the flash memory.
820 *
821 * IN: [1:cmd]
822 * OUT: [1:retval][1:cmd]
823 *
824 * This command is available under these conditions:
825 *
826 * | Bootloader | Firmware
827 * ---------------+--------------+-----------
828 * ColorHug | ✓ | ×
829 * ColorHug2 | ✓ | ×
830 * ColorHug+ | ✓ | ×
831 * ColorHugALS | ✓ | ×
832 *
833 * Since: 0.1.29
834 **/
835 #define CH_CMD_BOOT_FLASH 0x27
836
837 /**
838 * CH_CMD_SET_FLASH_SUCCESS:
839 *
840 * Sets the result of the firmware flashing. The idea of this command
841 * is that the flashing interaction is thus:
842 *
843 * 1. Reset() device goes to bootloader mode
844 * 2. SetFlashSuccess(FALSE)
845 * 3. WriteFlash($data)
846 * 4. ReadFlash($data) to verify
847 * 5. BootFlash() switch to program mode
848 * 6. SetFlashSuccess(TRUE)
849 *
850 * The idea is that we only set the success FALSE from the bootoloader
851 * to indicate that on booting we should not boot into the program.
852 * We can only set the success true from the *new* program code so as
853 * to verify that the new program boots, and can accept HID commands.
854 *
855 * IN: [1:cmd][1:success]
856 * OUT: [1:retval][1:cmd]
857 *
858 * This command is available under these conditions:
859 *
860 * | Bootloader | Firmware
861 * ---------------+--------------+-----------
862 * ColorHug | ✓ | ✓
863 * ColorHug2 | ✓ | ✓
864 * ColorHug+ | ✓ | ✓
865 * ColorHugALS | ✓ | ✓
866 *
867 * Different values of @success are permitted in each mode.
868 *
869 * Since: 0.1.29
870 **/
871 #define CH_CMD_SET_FLASH_SUCCESS 0x28
872
873 /**
874 * CH_CMD_GET_PRE_SCALE:
875 *
876 * Get the pre XYZ scaling constant. @scale is a packed float.
877 *
878 * IN: [1:cmd]
879 * OUT: [1:retval][1:cmd][4:scale]
880 *
881 * This command is available under these conditions:
882 *
883 * | Bootloader | Firmware
884 * ---------------+--------------+-----------
885 * ColorHug | × | ✓
886 * ColorHug2 | × | ×
887 * ColorHug+ | × | ×
888 * ColorHugALS | × | ×
889 *
890 * Since: 0.1.29
891 **/
892 #define CH_CMD_GET_PRE_SCALE 0x2c
893
894 /**
895 * CH_CMD_SET_PRE_SCALE:
896 *
897 * Set the pre XYZ scaling constant. @scale is a packed float.
898 *
899 * IN: [1:cmd][4:scale]
900 * OUT: [1:retval][1:cmd]
901 *
902 * This command is available under these conditions:
903 *
904 * | Bootloader | Firmware
905 * ---------------+--------------+-----------
906 * ColorHug | × | ✓
907 * ColorHug2 | × | ×
908 * ColorHug+ | × | ×
909 * ColorHugALS | × | ×
910 *
911 * Since: 0.1.29
912 **/
913 #define CH_CMD_SET_PRE_SCALE 0x2d
914
915 /**
916 * CH_CMD_GET_POST_SCALE:
917 *
918 * Get the post XYZ scaling constant. @scale is a packed float.
919 *
920 * IN: [1:cmd]
921 * OUT: [1:retval][1:cmd][4:scale]
922 *
923 * This command is available under these conditions:
924 *
925 * | Bootloader | Firmware
926 * ---------------+--------------+-----------
927 * ColorHug | × | ✓
928 * ColorHug2 | × | ×
929 * ColorHug+ | × | ×
930 * ColorHugALS | × | ×
931 *
932 * Since: 0.1.29
933 **/
934 #define CH_CMD_GET_POST_SCALE 0x2a
935
936 /**
937 * CH_CMD_SET_POST_SCALE:
938 *
939 * Set the post XYZ scaling constant. @scale is a packed float.
940 *
941 * IN: [1:cmd][4:scale]
942 * OUT: [1:retval][1:cmd]
943 *
944 * This command is available under these conditions:
945 *
946 * | Bootloader | Firmware
947 * ---------------+--------------+-----------
948 * ColorHug | × | ✓
949 * ColorHug2 | × | ×
950 * ColorHug+ | × | ×
951 * ColorHugALS | × | ×
952 *
953 * Since: 0.1.29
954 **/
955 #define CH_CMD_SET_POST_SCALE 0x2b
956
957 /**
958 * CH_CMD_GET_CALIBRATION_MAP:
959 *
960 * Get the mappings from default calibration type to calibration
961 * indexes.
962 *
963 * The calibration types are as follows:
964 * LCD = 0
965 * CRT = 1
966 * Projector = 2
967 * LED = 3
968 * Custom1 = 4
969 * Custom2 = 5
970 *
971 * In the future CustomX may be renamed to another display technology,
972 * e.g. e-ink.
973 *
974 * IN: [1:cmd]
975 * OUT: [1:retval][1:cmd][6*2:types]
976 *
977 * This command is available under these conditions:
978 *
979 * | Bootloader | Firmware
980 * ---------------+--------------+-----------
981 * ColorHug | × | ✓
982 * ColorHug2 | × | ✓
983 * ColorHug+ | × | ×
984 * ColorHugALS | × | ×
985 *
986 * Since: 0.1.29
987 **/
988 #define CH_CMD_GET_CALIBRATION_MAP 0x2e
989
990 /**
991 * CH_CMD_SET_CALIBRATION_MAP:
992 *
993 * Set the calibration type to index map.
994 *
995 * IN: [1:cmd][6*2:types]
996 * OUT: [1:retval][1:cmd]
997 *
998 * This command is available under these conditions:
999 *
1000 * | Bootloader | Firmware
1001 * ---------------+--------------+-----------
1002 * ColorHug | × | ✓
1003 * ColorHug2 | × | ✓
1004 * ColorHug+ | × | ×
1005 * ColorHugALS | × | ×
1006 *
1007 * Since: 0.1.29
1008 **/
1009 #define CH_CMD_SET_CALIBRATION_MAP 0x2f
1010
1011 /**
1012 * CH_CMD_GET_HARDWARE_VERSION:
1013 *
1014 * Get the hardware version.
1015 *
1016 * The hardware versions are as follows:
1017 * 0x00 = Pre-production hardware
1018 * 0x01 = ColorHug
1019 * 0x02 = ColorHug2
1020 * 0x03 = ColorHug+
1021 * 0x04 = ColorHugALS
1022 * 0x05-0x0f = Reserved for future use
1023 *
1024 * IN: [1:cmd]
1025 * OUT: [1:retval][1:cmd][1:hw_version]
1026 *
1027 * This command is available under these conditions:
1028 *
1029 * | Bootloader | Firmware
1030 * ---------------+--------------+-----------
1031 * ColorHug | ✓ | ✓
1032 * ColorHug2 | ✓ | ✓
1033 * ColorHug+ | ✓ | ✓
1034 * ColorHugALS | ✓ | ✓
1035 *
1036 * Since: 0.1.29
1037 **/
1038 #define CH_CMD_GET_HARDWARE_VERSION 0x30
1039
1040 /**
1041 * CH_CMD_TAKE_READING_ARRAY:
1042 *
1043 * Takes 30 raw samples and returns them in an array.
1044 *
1045 * This command can be used to find the optimum delay between patches
1046 * by showing a black sample area, then white, and then using this
1047 * command to find out how long the actual hardware delay is.
1048 *
1049 * It can also be used to find out how stable the device or output is
1050 * over a small amount of time, typically ~2.5 seconds for the maximum
1051 * integral time.
1052 *
1053 * IN: [1:cmd]
1054 * OUT: [1:retval][1:cmd][30:reading_array]
1055 *
1056 * This command is available under these conditions:
1057 *
1058 * | Bootloader | Firmware
1059 * ---------------+--------------+-----------
1060 * ColorHug | × | ✓
1061 * ColorHug2 | × | ×
1062 * ColorHug+ | × | ×
1063 * ColorHugALS | × | ×
1064 *
1065 * Since: 0.1.29
1066 **/
1067 #define CH_CMD_TAKE_READING_ARRAY 0x31
1068
1069 /**
1070 * CH_CMD_SET_PCB_ERRATA:
1071 *
1072 * Sets the board errata value. Board errata is used to correct swapped
1073 * LEDs and any future problems discovered that only affect some batches
1074 * of hardware version 1.
1075 *
1076 * The errata bitmask is as follows:
1077 * 0x00 = No errata for this PCB
1078 * 0x01 = Leds are swapped
1079 * 0x02-0xffff = Reserved for future use
1080 *
1081 * IN: [1:cmd][2:pcb_errata]
1082 * OUT: [1:retval][1:cmd]
1083 *
1084 * This command is available under these conditions:
1085 *
1086 * | Bootloader | Firmware
1087 * ---------------+--------------+-----------
1088 * ColorHug | × | ✓
1089 * ColorHug2 | × | ✓
1090 * ColorHug+ | × | ✓
1091 * ColorHugALS | × | ×
1092 *
1093 * Since: 0.1.29
1094 **/
1095 #define CH_CMD_SET_PCB_ERRATA 0x32
1096
1097 /**
1098 * CH_CMD_GET_PCB_ERRATA:
1099 *
1100 * Gets the board errata value.
1101 *
1102 * IN: [1:cmd]
1103 * OUT: [1:retval][1:cmd][2:pcb_errata]
1104 *
1105 * This command is available under these conditions:
1106 *
1107 * | Bootloader | Firmware
1108 * ---------------+--------------+-----------
1109 * ColorHug | × | ✓
1110 * ColorHug2 | × | ✓
1111 * ColorHug+ | × | ✓
1112 * ColorHugALS | × | ×
1113 *
1114 * Since: 0.1.29
1115 **/
1116 #define CH_CMD_GET_PCB_ERRATA 0x33
1117
1118 /**
1119 * CH_CMD_SET_REMOTE_HASH:
1120 *
1121 * Sets the remote SHA1 hash of the profile. This is designed to
1122 * be used by the calibration program to indicate the key which allows
1123 * the completed profile to be found from a public web service.
1124 *
1125 * IN: [1:cmd][20:sha1_hash]
1126 * OUT: [1:retval][1:cmd]
1127 *
1128 * This command is available under these conditions:
1129 *
1130 * | Bootloader | Firmware
1131 * ---------------+--------------+-----------
1132 * ColorHug | × | ✓
1133 * ColorHug2 | × | ✓
1134 * ColorHug+ | × | ✓
1135 * ColorHugALS | × | ×
1136 *
1137 * Since: 0.1.29
1138 **/
1139 #define CH_CMD_SET_REMOTE_HASH 0x34
1140
1141 /**
1142 * CH_CMD_GET_REMOTE_HASH:
1143 *
1144 * Gets the remote hash which is used to get the last profile saved
1145 * to a public web service.
1146 *
1147 * IN: [1:cmd]
1148 * OUT: [1:retval][1:cmd][20:sha1_hash]
1149 *
1150 * This command is available under these conditions:
1151 *
1152 * | Bootloader | Firmware
1153 * ---------------+--------------+-----------
1154 * ColorHug | × | ✓
1155 * ColorHug2 | × | ✓
1156 * ColorHug+ | × | ✓
1157 * ColorHugALS | × | ×
1158 *
1159 * Since: 0.1.29
1160 **/
1161 #define CH_CMD_GET_REMOTE_HASH 0x35
1162
1163 /**
1164 * CH_CMD_SET_MEASURE_MODE:
1165 *
1166 * Sets the measurement mode. The mode can either be frequency or pulse
1167 * duration. The former is well tested, but the latter is much more
1168 * precise.
1169 *
1170 * IN: [1:cmd][1:measure_mode]
1171 * OUT: [1:retval][1:cmd]
1172 *
1173 * This command is available under these conditions:
1174 *
1175 * | Bootloader | Firmware
1176 * ---------------+--------------+-----------
1177 * ColorHug | × | ✓
1178 * ColorHug2 | × | ×
1179 * ColorHug+ | × | ×
1180 * ColorHugALS | × | ×
1181 *
1182 * Since: 0.1.29
1183 **/
1184 #define CH_CMD_SET_MEASURE_MODE 0x36
1185
1186 /**
1187 * CH_CMD_GET_MEASURE_MODE:
1188 *
1189 * Gets the measurement mode.
1190 *
1191 * IN: [1:cmd]
1192 * OUT: [1:retval][1:cmd][1:measure_mode]
1193 *
1194 * This command is available under these conditions:
1195 *
1196 * | Bootloader | Firmware
1197 * ---------------+--------------+-----------
1198 * ColorHug | × | ✓
1199 * ColorHug2 | × | ×
1200 * ColorHug+ | × | ×
1201 * ColorHugALS | × | ×
1202 *
1203 * Since: 0.1.29
1204 **/
1205 #define CH_CMD_GET_MEASURE_MODE 0x37
1206
1207 /**
1208 * CH_CMD_READ_SRAM:
1209 *
1210 * Read in raw data from the SRAM memory.
1211 *
1212 * PROTOCOLv1:
1213 * IN: [1:cmd][2:address][1:length]
1214 * OUT: [1:retval][1:cmd][1-60:data]
1215 *
1216 * PROTOCOLv2:
1217 * bRequest: [cmd]
1218 * wValue: [address-index/64]
1219 * wIndex: interface
1220 * wLength: 0x64
1221 * Direction: DEVICE->HOST
1222 * Data: [64:DATA]
1223 *
1224 * This command is available under these conditions:
1225 *
1226 * | Bootloader | Firmware
1227 * ---------------+--------------+-----------
1228 * ColorHug | × | ×
1229 * ColorHug2 | × | ✓
1230 * ColorHug+ | × | ✓
1231 * ColorHugALS | × | ×
1232 *
1233 * Since: 0.1.29
1234 **/
1235 #define CH_CMD_READ_SRAM 0x38
1236
1237 /**
1238 * CH_CMD_WRITE_SRAM:
1239 *
1240 * Write raw data to the SRAM memory.
1241 *
1242 * IN: [1:cmd][2:address][1:length][1-60:data]
1243 * OUT: [1:retval][1:cmd]
1244 *
1245 * This command is available under these conditions:
1246 *
1247 * | Bootloader | Firmware
1248 * ---------------+--------------+-----------
1249 * ColorHug | × | ×
1250 * ColorHug2 | × | ✓
1251 * ColorHug+ | × | ✓
1252 * ColorHugALS | × | ×
1253 *
1254 * Since: 0.1.29
1255 **/
1256 #define CH_CMD_WRITE_SRAM 0x39
1257
1258 /**
1259 * CH_CMD_GET_TEMPERATURE:
1260 *
1261 * Gets the temperature of the sensor in degrees celsius
1262 *
1263 * IN: [1:cmd]
1264 * OUT: [1:retval][1:cmd][4:temperature]
1265 *
1266 * This command is available under these conditions:
1267 *
1268 * | Bootloader | Firmware
1269 * ---------------+--------------+-----------
1270 * ColorHug | × | ×
1271 * ColorHug2 | × | ✓
1272 * ColorHug+ | × | ✓
1273 * ColorHugALS | × | ×
1274 *
1275 * Since: 0.1.29
1276 **/
1277 #define CH_CMD_GET_TEMPERATURE 0x3b
1278
1279 /**
1280 * CH_CMD_GET_DAC_VALUE:
1281 *
1282 * Get the DAC value. @scale is a packed float, where 1.0f is 3.3V
1283 *
1284 * IN: [1:cmd]
1285 * OUT: [1:retval][1:cmd][4:value]
1286 *
1287 * This command is available under these conditions:
1288 *
1289 * | Bootloader | Firmware
1290 * ---------------+--------------+-----------
1291 * ColorHug | × | ×
1292 * ColorHug2 | × | ×
1293 * ColorHug+ | × | ✓
1294 * ColorHugALS | × | ×
1295 *
1296 * Since: 1.1.6
1297 **/
1298 #define CH_CMD_GET_DAC_VALUE 0x3c
1299
1300 /**
1301 * CH_CMD_SET_DAC_VALUE:
1302 *
1303 * Set the DAC value. @scale is a packed float, where 1.0f is 3.3V
1304 *
1305 * IN: [1:cmd][4:value]
1306 * OUT: [1:retval][1:cmd]
1307 *
1308 * This command is available under these conditions:
1309 *
1310 * | Bootloader | Firmware
1311 * ---------------+--------------+-----------
1312 * ColorHug | × | ×
1313 * ColorHug2 | × | ×
1314 * ColorHug+ | × | ✓
1315 * ColorHugALS | × | ×
1316 *
1317 * Since: 1.1.6
1318 **/
1319 #define CH_CMD_SET_DAC_VALUE 0x3d
1320
1321 /**
1322 * CH_CMD_SELF_TEST:
1323 *
1324 * Tests the device by trying to get a non-zero reading from each
1325 * color channel.
1326 *
1327 * IN: [1:cmd]
1328 * OUT: [1:retval][1:cmd]
1329 *
1330 * This command is available under these conditions:
1331 *
1332 * | Bootloader | Firmware
1333 * ---------------+--------------+-----------
1334 * ColorHug | ✓ | ✓
1335 * ColorHug2 | ✓ | ✓
1336 * ColorHug+ | ✓ | ✓
1337 * ColorHugALS | ✓ | ×
1338 *
1339 * Since: 0.1.29
1340 **/
1341 #define CH_CMD_SELF_TEST 0x40
1342
1343 /**
1344 * CH_CMD_LOAD_SRAM:
1345 *
1346 * Load the SRAM from the EEPROM.
1347 *
1348 * PROTOCOLv2:
1349 * bRequest: [cmd]
1350 * wValue: 0x00
1351 * wIndex: interface
1352 * wLength: 0x00
1353 * Direction: DEVICE->HOST
1354 * Data: [1:error][1:cmd]
1355 *
1356 * This command is available under these conditions:
1357 *
1358 * | Bootloader | Firmware
1359 * ---------------+--------------+-----------
1360 * ColorHug | × | ×
1361 * ColorHug2 | × | ×
1362 * ColorHug+ | × | ✓
1363 * ColorHugALS | × | ×
1364 *
1365 * Since: 0.1.29
1366 **/
1367 #define CH_CMD_LOAD_SRAM 0x41
1368
1369 /**
1370 * CH_CMD_SAVE_SRAM:
1371 *
1372 * Save the SRAM to the EEPROM.
1373 *
1374 * PROTOCOLv2:
1375 * bRequest: [cmd]
1376 * wValue: 0x00
1377 * wIndex: interface
1378 * wLength: 0x00
1379 * Direction: DEVICE->HOST
1380 * Data: [1:error][1:cmd]
1381 *
1382 * This command is available under these conditions:
1383 *
1384 * | Bootloader | Firmware
1385 * ---------------+--------------+-----------
1386 * ColorHug | × | ×
1387 * ColorHug2 | × | ×
1388 * ColorHug+ | × | ✓
1389 * ColorHugALS | × | ×
1390 *
1391 * Since: 0.1.29
1392 **/
1393 #define CH_CMD_SAVE_SRAM 0x42
1394
1395 /**
1396 * CH_CMD_GET_ERROR:
1397 *
1398 * Gets any recorded error from the device.
1399 *
1400 * PROTOCOLv2:
1401 * bRequest: [cmd]
1402 * wValue: 0x00
1403 * wIndex: interface
1404 * wLength: 0x00
1405 * Direction: DEVICE->HOST
1406 * Data: [1:error][1:cmd]
1407 *
1408 * This command is available under these conditions:
1409 *
1410 * | Bootloader | Firmware
1411 * ---------------+--------------+-----------
1412 * ColorHug | × | ×
1413 * ColorHug2 | × | ×
1414 * ColorHug+ | × | ✓
1415 * ColorHugALS | × | ×
1416 *
1417 * Since: 1.3.1
1418 **/
1419 #define CH_CMD_GET_ERROR 0x60
1420
1421 /**
1422 * CH_CMD_CLEAR_ERROR:
1423 *
1424 * Clears any recorded error on the device.
1425 *
1426 * PROTOCOLv2:
1427 * bRequest: [cmd]
1428 * wValue: 0x00
1429 * wIndex: interface
1430 * wLength: 0x00
1431 * Direction: DEVICE->HOST
1432 * Data: []
1433 *
1434 * This command is available under these conditions:
1435 *
1436 * | Bootloader | Firmware
1437 * ---------------+--------------+-----------
1438 * ColorHug | × | ×
1439 * ColorHug2 | × | ×
1440 * ColorHug+ | × | ✓
1441 * ColorHugALS | × | ×
1442 *
1443 * Since: 1.3.1
1444 **/
1445 #define CH_CMD_CLEAR_ERROR 0x61
1446
1447 /**
1448 * CH_CMD_SET_CRYPTO_KEY:
1449 *
1450 * Sets the 128 bit encryption key for the device.
1451 *
1452 * PROTOCOLv2:
1453 * bRequest: [cmd]
1454 * wValue: 0x00
1455 * wIndex: interface
1456 * wLength: 0x00
1457 * Direction: DEVICE->HOST
1458 * Data: [4:key0][4:key1][4:key2][4:key3]
1459 *
1460 * This command is available under these conditions:
1461 *
1462 * | Bootloader | Firmware
1463 * ---------------+--------------+-----------
1464 * ColorHug | × | ×
1465 * ColorHug2 | × | ×
1466 * ColorHug+ | × | ✓
1467 * ColorHugALS | × | ×
1468 *
1469 * Since: 1.3.1
1470 **/
1471 #define CH_CMD_SET_CRYPTO_KEY 0x70
1472
1473 /* the values here are not really API */
1474 #define CH_EP0_TRANSFER_SIZE 64
1475 #define CH_EP0_TRANSFER_SIZE_V2 0x400 /* since 1.3.4 */
1476
1477 /* secret code */
1478 #define CH_WRITE_EEPROM_MAGIC "Un1c0rn2"
1479 #define CH_FIRMWARE_ID_TOKEN1 "40338ceb"
1480 #define CH_FIRMWARE_ID_TOKEN2 "2082b5e0"
1481 #define CH_FIRMWARE_ID_TOKEN_ALS "84f40464" /* since 1.2.9 */
1482 #define CH_FIRMWARE_ID_TOKEN_PLUS "6d6f05a9"
1483
1484 #define CH_DEVICE_GUID_COLORHUG "40338ceb-b966-4eae-adae-9c32edfcc484" /* since 1.2.9 */
1485 #define CH_DEVICE_GUID_COLORHUG2 "2082b5e0-7a64-478a-b1b2-e3404fab6dad" /* since 1.2.9 */
1486 #define CH_DEVICE_GUID_COLORHUG_ALS "84f40464-9272-4ef7-9399-cd95f12da696" /* since 1.2.9 */
1487 #define CH_DEVICE_GUID_COLORHUG_PLUS "6d6f05a9-3ecb-43a2-bcbb-3844f1825366" /* since 1.2.9 */
1488
1489 /* input and output buffer offsets */
1490 #define CH_BUFFER_INPUT_CMD 0x00
1491 #define CH_BUFFER_INPUT_DATA 0x01
1492 #define CH_BUFFER_OUTPUT_RETVAL 0x00
1493 #define CH_BUFFER_OUTPUT_CMD 0x01
1494 #define CH_BUFFER_OUTPUT_DATA 0x02
1495
1496 /* where the custom firmware is stored */
1497 #define CH_EEPROM_ADDR_RUNCODE 0x4000
1498 #define CH_EEPROM_ADDR_RUNCODE_ALS 0x2000 /* since 1.2.9 */
1499
1500 /* the number of useful samples from the the CCD */
1501 #define CH_CCD_SPECTRAL_RESOLUTION 1024
1502
1503 /* although each calibration can be stored in 60 bytes,
1504 * we use a full 64 byte block */
1505 #define CH_CALIBRATION_MAX 64 /* so finishes at device params */
1506 #define CH_CALIBRATION_SPECTRAL 0xffff
1507 #define CH_CALIBRATION_DESCRIPTION_LEN 23 /* 60 - (9*4) - 1 */
1508
1509 /* the supported calibration types bitfield */
1510 #define CH_CALIBRATION_TYPE_LCD 0x01
1511 #define CH_CALIBRATION_TYPE_CRT 0x02
1512 #define CH_CALIBRATION_TYPE_PROJECTOR 0x04
1513 #define CH_CALIBRATION_TYPE_LED 0x08
1514 #define CH_CALIBRATION_TYPE_ALL 0xff
1515
1516 /* approximate sample times */
1517 #define CH_INTEGRAL_TIME_VALUE_5MS 0x0300
1518 #define CH_INTEGRAL_TIME_VALUE_50MS 0x1f00
1519 #define CH_INTEGRAL_TIME_VALUE_100MS 0x3a00
1520 #define CH_INTEGRAL_TIME_VALUE_200MS 0x7500
1521 #define CH_INTEGRAL_TIME_VALUE_MAX 0xffff
1522
1523 /* flash constants */
1524 #define CH_FLASH_ERASE_BLOCK_SIZE 0x400 /* 1024 */
1525 #define CH_FLASH_WRITE_BLOCK_SIZE 0x040 /* 64 */
1526 #define CH_FLASH_TRANSFER_BLOCK_SIZE 0x020 /* 32 */
1527 #define CH_FLASH_RECONNECT_TIMEOUT 5000 /* ms */
1528
1529 /* calibration remapping contants */
1530 #define CH_CALIBRATION_INDEX_FACTORY_ONLY 0x00
1531 #define CH_CALIBRATION_INDEX_LCD (CH_CALIBRATION_MAX + 0)
1532 #define CH_CALIBRATION_INDEX_CRT (CH_CALIBRATION_MAX + 1)
1533 #define CH_CALIBRATION_INDEX_PROJECTOR (CH_CALIBRATION_MAX + 2)
1534 #define CH_CALIBRATION_INDEX_LED (CH_CALIBRATION_MAX + 3)
1535 #define CH_CALIBRATION_INDEX_MAX 0x06
1536
1537 /* which color to select */
1538 typedef enum {
1539 CH_COLOR_SELECT_RED,
1540 CH_COLOR_SELECT_WHITE,
1541 CH_COLOR_SELECT_BLUE,
1542 CH_COLOR_SELECT_GREEN
1543 } ChColorSelect;
1544
1545 /* Led colors: possible bitfield values */
1546 typedef enum {
1547 CH_STATUS_LED_GREEN = 1 << 0,
1548 CH_STATUS_LED_RED = 1 << 1,
1549 CH_STATUS_LED_BLUE = 1 << 2 /* Since: 0.1.29 */
1550 } ChStatusLed;
1551
1552 /* Illuminants: possible bitfield values */
1553 typedef enum {
1554 CH_ILLUMINANT_NONE = 0, /* Since: 1.3.4 */
1555 CH_ILLUMINANT_A = 1 << 0, /* Since: 1.3.4 */
1556 CH_ILLUMINANT_UV = 1 << 1, /* Since: 1.3.4 */
1557 /*< private >*/
1558 CH_ILLUMINANT_LAST
1559 } ChIlluminant;
1560
1561 /* what frequency divider to use */
1562 typedef enum {
1563 CH_FREQ_SCALE_0,
1564 CH_FREQ_SCALE_20,
1565 CH_FREQ_SCALE_2,
1566 CH_FREQ_SCALE_100
1567 } ChFreqScale;
1568
1569 /* fatal error morse code */
1570 typedef enum {
1571 CH_ERROR_NONE,
1572 CH_ERROR_UNKNOWN_CMD,
1573 CH_ERROR_WRONG_UNLOCK_CODE,
1574 CH_ERROR_NOT_IMPLEMENTED,
1575 CH_ERROR_UNDERFLOW_SENSOR,
1576 CH_ERROR_NO_SERIAL,
1577 CH_ERROR_WATCHDOG,
1578 CH_ERROR_INVALID_ADDRESS,
1579 CH_ERROR_INVALID_LENGTH,
1580 CH_ERROR_INVALID_CHECKSUM,
1581 CH_ERROR_INVALID_VALUE,
1582 CH_ERROR_UNKNOWN_CMD_FOR_BOOTLOADER,
1583 CH_ERROR_NO_CALIBRATION,
1584 CH_ERROR_OVERFLOW_MULTIPLY,
1585 CH_ERROR_OVERFLOW_ADDITION,
1586 CH_ERROR_OVERFLOW_SENSOR,
1587 CH_ERROR_OVERFLOW_STACK,
1588 CH_ERROR_DEVICE_DEACTIVATED,
1589 CH_ERROR_INCOMPLETE_REQUEST,
1590 CH_ERROR_SELF_TEST_SENSOR,
1591 CH_ERROR_SELF_TEST_RED,
1592 CH_ERROR_SELF_TEST_GREEN,
1593 CH_ERROR_SELF_TEST_BLUE,
1594 CH_ERROR_SELF_TEST_COLOR_SELECT,
1595 CH_ERROR_SELF_TEST_MULTIPLIER,
1596 CH_ERROR_INVALID_CALIBRATION,
1597 CH_ERROR_SRAM_FAILED,
1598 CH_ERROR_OUT_OF_MEMORY,
1599 CH_ERROR_SELF_TEST_TEMPERATURE,
1600 CH_ERROR_SELF_TEST_I2C,
1601 CH_ERROR_SELF_TEST_ADC_VDD,
1602 CH_ERROR_SELF_TEST_ADC_VSS,
1603 CH_ERROR_SELF_TEST_ADC_VREF,
1604 CH_ERROR_I2C_SLAVE_ADDRESS,
1605 CH_ERROR_I2C_SLAVE_CONFIG,
1606 CH_ERROR_SELF_TEST_EEPROM, /* since 1.2.9 */
1607 /*< private >*/
1608 CH_ERROR_LAST
1609 } ChError;
1610
1611 /* the measure mode */
1612 typedef enum {
1613 CH_MEASURE_MODE_FREQUENCY,
1614 CH_MEASURE_MODE_DURATION
1615 } ChMeasureMode;
1616
1617 /* any problems with the PCB */
1618 typedef enum {
1619 CH_PCB_ERRATA_NONE = 0,
1620 CH_PCB_ERRATA_SWAPPED_LEDS = 1 << 0,
1621 CH_PCB_ERRATA_NO_WELCOME = 1 << 1,
1622 /*< private >*/
1623 CH_PCB_ERRATA_LAST = 1 << 2
1624 } ChPcbErrata;
1625
1626 typedef enum {
1627 CH_DEVICE_MODE_UNKNOWN,
1628 CH_DEVICE_MODE_LEGACY,
1629 CH_DEVICE_MODE_BOOTLOADER,
1630 CH_DEVICE_MODE_FIRMWARE,
1631 CH_DEVICE_MODE_BOOTLOADER_PLUS,
1632 CH_DEVICE_MODE_FIRMWARE_PLUS,
1633 CH_DEVICE_MODE_FIRMWARE2, /* since 1.2.2 */
1634 CH_DEVICE_MODE_BOOTLOADER2, /* since 1.2.3 */
1635 CH_DEVICE_MODE_BOOTLOADER_ALS, /* since 1.2.9 */
1636 CH_DEVICE_MODE_FIRMWARE_ALS, /* since 1.2.9 */
1637 /*< private >*/
1638 CH_DEVICE_MODE_LAST
1639 } ChDeviceMode;
1640
1641 typedef enum {
1642 CH_SPECTRUM_KIND_RAW = 0x00, /* since 1.3.4 */
1643 CH_SPECTRUM_KIND_DARK_CAL = 0x01, /* since 1.3.4 */
1644 CH_SPECTRUM_KIND_TEMP_CAL = 0x02, /* since 1.3.4 */
1645 CH_SPECTRUM_KIND_IRRADIANCE_CAL = 0x03, /* since 1.3.4 */
1646 CH_SPECTRUM_KIND_LAST
1647 } ChSpectrumKind;
1648
1649 typedef guint8 ChCmd;
1650
1651 /* prototypes */
1652 const gchar *ch_strerror (ChError error_enum);
1653 const gchar *ch_command_to_string (ChCmd cmd);
1654 const gchar *ch_multiplier_to_string (ChFreqScale multiplier);
1655 const gchar *ch_color_select_to_string (ChColorSelect color_select);
1656 const gchar *ch_measure_mode_to_string (ChMeasureMode measure_mode);
1657 const gchar *ch_device_mode_to_string (ChDeviceMode device_mode);
1658 ChDeviceMode ch_device_mode_from_firmware (const guint8 *data,
1659 gsize data_len);
1660
1661 G_END_DECLS
1662
1663 #endif