This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
wiki:v2:protocol_reference [2018/10/10 17:03] pixycam [Pixy2 Serial Protocol - Packet Reference] |
wiki:v2:protocol_reference [2018/10/10 19:33] pixycam |
||
---|---|---|---|
Line 3: | Line 3: | ||
In case you need to implement your own client to talk to Pixy2 in a language or microcontroller we don't support, here is a handy reference of the Pixy2 serial protocol request and response packets. | In case you need to implement your own client to talk to Pixy2 in a language or microcontroller we don't support, here is a handy reference of the Pixy2 serial protocol request and response packets. | ||
- | (For reference, our [[wiki:v2:pixy2_full_api|Arduino Library]] implements all of what's below in the files TPixy2.h, Pixy2Line.h, Pixy2CCC.h, and Pixy2Video.h. For consistency, the function names listed here are the same as in that implementation.) | ||
- | All values exchanged through the protocol are integer quantities (no floating point values). Some quantities are 1-byte (8-bit), 2-byte (16-bit), or 4-byte (32-bit). | + | For reference, our [[wiki:v2:pixy2_full_api|Arduino Library]] implements all of what's below in the files TPixy2.h, Pixy2Line.h, Pixy2CCC.h, and Pixy2Video.h. For consistency, the function names listed here are the same as in that implementation. |
+ | |||
+ | |||
+ | All values exchanged through the protocol are integer quantities (no floating point values). All quantities are either 1-byte (8-bit), 2-byte (16-bit), or 4-byte (32-bit). Multi-byte values are sent using little-endian byte ordering -- that is, the least-significant-byte is sent first, followed by the next-least-significant-byte. The most-significant-byte is sent last. This [[https://thebittheories.com/little-endian-vs-big-endian-b4046c63e1f2|page]] does a good job explaining endianness. | ||
+ | |||
+ | |||
+ | Furthermore, all signed integer quantities are represented using two's complement representation. This [[https://chortle.ccsu.edu/AssemblyTutorial/Chapter-08/ass08_17.html|page]] describes two's complement representation. | ||
+ | |||
+ | |||
+ | It's not hugely important that you understand little-endian and two's complement representations -- 95% of all processors use little-endian and two's complement. So you basically read the bytes into memory and tell the processor there's an integer there, and it will happily interpret it correctly. But it's good to know, and required information for the protocol to work correctly. | ||
Original Pixy would constantly broadcast data about objects it was (or wasn’t) seeing. With Pixy2, we’ve moved to a request-response system. That means Pixy2 is silent unless you send it a properly formatted request packet, in which case it will respond in kind. | Original Pixy would constantly broadcast data about objects it was (or wasn’t) seeing. With Pixy2, we’ve moved to a request-response system. That means Pixy2 is silent unless you send it a properly formatted request packet, in which case it will respond in kind. | ||
Line 13: | Line 22: | ||
==== sendPacket / requests sent to Pixy2 ==== | ==== sendPacket / requests sent to Pixy2 ==== | ||
- | ^Byte ^Description ^ Value ^ | + | ^Byte ^Description ^ Value(s) ^ |
- | |0 - 1 |Sync (indicates whether to expect checksum) | 174, 193 | | + | |0 - 1 |16-bit sync | 174, 193 (0xc1ae) | |
|2 |Type of packet | (varies) | | |2 |Type of packet | (varies) | | ||
|3 |Length of payload in bytes (len) | (varies) | | |3 |Length of payload in bytes (len) | (varies) | | ||
- | |4 - len |Payload | (varies) | | + | |4 - len |Variable length payload | (varies) | |
==== recvPacket / responses received from Pixy2 ==== | ==== recvPacket / responses received from Pixy2 ==== | ||
- | ^Byte ^Description ^ Value ^ | + | ^Byte ^Description ^ Value(s) ^ |
- | |0 - 1 |Sync (indicates whether to expect checksum) | 175, 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af) | |
|2 |Type of packet | (varies) | | |2 |Type of packet | (varies) | | ||
|3 |Length of payload in bytes (len) | (varies) | | |3 |Length of payload in bytes (len) | (varies) | | ||
- | |4 - 5 |Checksum | sum of payload bytes | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - len |Payload | (varies) | | + | |6 - len |Variable length payload | (varies) | |
Line 35: | Line 44: | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |
|2 |Type of packet |14 | | |2 |Type of packet |14 | | ||
|3 |Length of payload |0 | | |3 |Length of payload |0 | | ||
Line 42: | Line 51: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |
|2 |Type of packet |15 | | |2 |Type of packet |15 | | ||
|3 |Length of payload |7 | | |3 |Length of payload |7 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 7 |Hardware version | (varies) | | + | |6 - 7 |16-bit hardware version | (varies) | |
|8 |Firmware version (major) | (varies) | | |8 |Firmware version (major) | (varies) | | ||
|9 |Firmware version (minor) | (varies) | | |9 |Firmware version (minor) | (varies) | | ||
- | |10 - 11 |Firmware build | (varies) | | + | |10 - 11 | 16-bit firmware build | (varies) | |
|12 |Firmware type (human readable string) | (varies) | | |12 |Firmware type (human readable string) | (varies) | | ||
Line 57: | Line 66: | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |
|2 |Type of packet |12 | | |2 |Type of packet |12 | | ||
|3 |Length of payload |1 | | |3 |Length of payload |1 | | ||
Line 65: | Line 74: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync| 175, 193 (0xc1af)| |
|2 |Type of packet |13 | | |2 |Type of packet |13 | | ||
|3 |Length of payload |2 | | |3 |Length of payload |2 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 7 |Frame width | 0 - 511 (little-endian) | | + | |6 - 7 |16-bit frame width | 0 - 511 | |
- | |8 - 9 |Frame height | 0 - 511 (little-endian) | | + | |8 - 9 |16-bit frame height | 0 - 511 | |
==== setCameraBrightness(brightness) ==== | ==== setCameraBrightness(brightness) ==== | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |Sync | 174, 193 (0xc1ae)| |
|2 |Type of packet |16 | | |2 |Type of packet |16 | | ||
|3 |Length of payload |1 | | |3 |Length of payload |1 | | ||
Line 83: | Line 92: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync| 175, 193 (0xc1af)| |
|2 |Type of packet |17 | | |2 |Type of packet |17 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 9 |Result |0 (???) | | + | |6 - 9 |32-bit result |result value | |
==== setServos(s0, s1) ==== | ==== setServos(s0, s1) ==== | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |
|2 |Type of packet |18 | | |2 |Type of packet |18 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |s0 - pan servo value |0 - 511 (little-endian)| | + | |4 - 5 |16-bit s0 - pan servo value |0 - 511 | |
- | |6 - 7 |s1 - tilt servo value |0 - 511 (little-endian)| | + | |6 - 7 |16-bit s1 - tilt servo value |0 - 511 | |
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |
|2 |Type of packet |19 | | |2 |Type of packet |19 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 9 |Result |0 (???) | | + | |6 - 9 |32-bit result/acknowledge |result value | |
==== setLED(r, g, b) ==== | ==== setLED(r, g, b) ==== | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |
|2 |Type of packet |20 | | |2 |Type of packet |20 | | ||
|3 |Length of payload |3 | | |3 |Length of payload |3 | | ||
Line 120: | Line 129: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |
|2 |Type of packet |21 | | |2 |Type of packet |21 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 9 |Result |0 (???) | | + | |6 - 9 |32-bit result/acknowledge | result value | |
==== setLamp(upper, lower) ==== | ==== setLamp(upper, lower) ==== | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |
|2 |Type of packet |22 | | |2 |Type of packet |22 | | ||
|3 |Length of payload |2 | | |3 |Length of payload |2 | | ||
Line 138: | Line 147: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |
|2 |Type of packet |23 | | |2 |Type of packet |23 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 9 |Result |0 (???) | | + | |6 - 9 |32-bit result/acknowledge | result value | |
==== getFPS() ==== | ==== getFPS() ==== | ||
=== Request: === | === Request: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 174 193 | | + | |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |
|2 |Type of packet |24 | | |2 |Type of packet |24 | | ||
|3 |Length of payload |0 | | |3 |Length of payload |0 | | ||
Line 155: | Line 164: | ||
=== Response: === | === Response: === | ||
- | ^Byte ^Description ^Value ^ | + | ^Byte ^Description ^Value(s) ^ |
- | |0 - 1 |Sync | 175 193 | | + | |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |
|2 |Type of packet |25 | | |2 |Type of packet |25 | | ||
|3 |Length of payload |4 | | |3 |Length of payload |4 | | ||
- | |4 - 5 |Checksum | | | + | |4 - 5 |16-bit checksum | sum of payload bytes | |
- | |6 - 9 |Result |0 (???) | | + | |6 - 9 |32-bit result | FPS | |
{{page>wiki:v2:ccc-packets&noindent}} | {{page>wiki:v2:ccc-packets&noindent}} | ||
{{page>wiki:v2:line-packets&noindent}} | {{page>wiki:v2:line-packets&noindent}} | ||
{{page>wiki:v2:video-packets&noindent}} | {{page>wiki:v2:video-packets&noindent}} |