Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
Fadecandy: USB Protocol
=======================
To achieve the best CPU efficiency, Fadecandy uses a custom packet-oriented USB protocol rather than emulating a USB serial device. This simple USB protocol is easy to speak using cross-platform libraries like [libusb](http://www.libusb.org) and [PyUSB](http://pyusb.sourceforge.net/). Examples are included.
If you use the included `fcserver` daemon, you need not worry about the USB protocol at all.
Device Information
------------------
Attribute | Value
--------------- | -----
Vendor ID | 0x1d50
Product ID | 0x607a
Manufacturer | "scanlime"
Product | "Fadecandy"
Serial | Unique ID string
Device Class | Vendor-specific
Configurations | 1
Endpoints | 1
Endpoint 1 | Bulk OUT (Host to Device), 64-byte packets
Bulk Endpoint
-------------
The device has a single Bulk OUT endpoint which expects packets of up to 64 bytes. Multiple packets may be transmitted in one LibUSB "write" operation, as long as the buffer you provide is a multiple of 64 bytes in length.
Each packet begins with an 8-bit control byte, which is divided into three bit-fields:
Bits 7..6 | Bit 5 | Bits 4..0
---------- | ----------- | ------------
Type code | 'Final' bit | Packet index
* The 'type' code indicates what kind of packet this is.
* The 'final' bit, if set, causes the most recent group of packets to take effect
* The packet index is used to sequence packets within a particular type code
The following packet types are recognized:
Type code | Meaning of 'final' bit | Index range | Packet contents
--------- | ------------------------------- | ----------- | -------------------------------------
0 | Interpolate to new video frame | 0 … 24 | Up to 21 pixels, 24-bit RGB
1 | Instantly apply new color LUT | 0 … 24 | Up to 31 16-bit lookup table entries
2 | (reserved) | 0 | Set configuration data
3 | | | (reserved)
Video Packets
-------------
In a type 0 packet, the USB packet contains up to 21 pixels of 24-bit RGB color data. The last packet (index 24) only needs to contain 8 valid pixels. Pixels 9-20 in these packets are ignored.
Byte Offset | Description
------------- | ------------
0 | Control byte
1 | Pixel 0, Red
2 | Pixel 0, Green
3 | Pixel 0, Blue
4 | Pixel 1, Red
5 | Pixel 1, Green
6 | Pixel 1, Blue
… | …
61 | Pixel 20, Red
62 | Pixel 20, Green
63 | Pixel 20, Blue
Color LUT Packets
-----------------
In a type 1 packet, the USB packet contains up to 31 lookup-table entries. The lookup table is structured as three arrays of 257 entries, starting with the entire red-channel LUT, then the green-channel LUT, then the blue-channel LUT. Each packet is structured as follows:
Byte Offset | Description
------------- | ------------
0 | Control byte
1 | Reserved (0)
2 | LUT entry #0, low byte
3 | LUT entry #0, high byte
4 | LUT entry #1, low byte
5 | LUT entry #1, high byte
… | …
62 | LUT entry #30, low byte
63 | LUT entry #30, high byte
Configuration Packet
--------------------
A type 2 packet sets optional device-wide configuration settings:
Byte Offset | Bits | Description
----------- | ------ | ------------
0 | 7 … 0 | Control byte
1 | 7 … 2 | (reserved)
1 | 3 | Manual LED control bit
1 | 2 | 0 = LED shows USB activity, 1 = LED under manual control
1 | 1 | Disable keyframe interpolation
1 | 0 | Disable dithering
2 … 63 | 7 … 0 | (reserved)
Control Requests
----------------
In addition to the OUT endpoint, the device also supports vendor-specific control requests:
bmRequestType | bRequest | wValue | wIndex | wLength | Description
------------- | -------- | ------ | ------ | ------- | ---------------------------------------------
0xC0 | 0x01 | 0 | 0 | 4 | Read rendered frame counter (32-bit, little endian)
0xC0 | 0x01 | 0 | 1 | 4 | Read received keyframe counter (32-bit, little endian)
0xC0 | 0x7E | x | 4 | x | Read Microsoft WCID descriptor
0xC0 | 0x7E | x | 5 | x | Read Microsoft Extended Properties descriptor