====== Pixy2 Serial Protocol - Packet Reference ====== 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). 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. ===== General Format ====== ==== sendPacket / requests sent to Pixy2 ==== ^Byte ^Description ^ Value(s) ^ |0 - 1 |16-bit sync | 174, 193 (0xc1ae) | |2 |Type of packet | (varies) | |3 |Length of payload in bytes (len) | (varies) | |4 - len |Variable length payload | (varies) | ==== recvPacket / responses received from Pixy2 ==== ^Byte ^Description ^ Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af) | |2 |Type of packet | (varies) | |3 |Length of payload in bytes (len) | (varies) | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - len |Variable length payload | (varies) | ===== Specifics: ===== ==== getVersion() ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |2 |Type of packet |14 | |3 |Length of payload |0 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |2 |Type of packet |15 | |3 |Length of payload |16 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 7 |16-bit hardware version | (varies) | |8 |Firmware version (major) | (varies) | |9 |Firmware version (minor) | (varies) | |10 - 11 | 16-bit firmware build | (varies) | |12 |Firmware type (human readable string) | (varies) | ==== getResolution() ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |2 |Type of packet |12 | |3 |Length of payload |1 | |4 |Type (unused - reserved for future versions) | 0 - 255 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync| 175, 193 (0xc1af)| |2 |Type of packet |13 | |3 |Length of payload |2 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 7 |16-bit frame width | 0 - 511 | |8 - 9 |16-bit frame height | 0 - 511 | ==== setCameraBrightness(brightness) ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |Sync | 174, 193 (0xc1ae)| |2 |Type of packet |16 | |3 |Length of payload |1 | |4 |Brightness |0 - 255 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync| 175, 193 (0xc1af)| |2 |Type of packet |1 | |3 |Length of payload |4 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 9 |32-bit result |result value | ==== setServos(s0, s1) ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync| 174, 193 (0xc1ae)| |2 |Type of packet |18 | |3 |Length of payload |4 | |4 - 5 |16-bit s0 - pan servo value |0 - 511 | |6 - 7 |16-bit s1 - tilt servo value |0 - 511 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |2 |Type of packet |1 | |3 |Length of payload |4 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 9 |32-bit result/acknowledge |result value | ==== setLED(r, g, b) ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |2 |Type of packet |20 | |3 |Length of payload |3 | |4 |r - Red value |0 - 255 | |5 |g - Green value |0 - 255 | |6 |b - Blue value |0 - 255 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |2 |Type of packet |1 | |3 |Length of payload |4 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 9 |32-bit result/acknowledge | result value | ==== setLamp(upper, lower) ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |2 |Type of packet |22 | |3 |Length of payload |2 | |4 |Upper - turn on the two white LEDs along Pixy2 top edge | 0 (off) or 1 (on) | |5 |Lower - turn on all channels of lower RGB LED |0 (off) or 1 (on) | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |2 |Type of packet |1 | |3 |Length of payload |4 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 9 |32-bit result/acknowledge | result value | ==== getFPS() ==== === Request: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 174, 193 (0xc1ae)| |2 |Type of packet |24 | |3 |Length of payload |0 | === Response: === ^Byte ^Description ^Value(s) ^ |0 - 1 |16-bit sync | 175, 193 (0xc1af)| |2 |Type of packet |1 | |3 |Length of payload |4 | |4 - 5 |16-bit checksum | sum of payload bytes | |6 - 9 |32-bit result | frames-per-second | {{page>wiki:v2:ccc-packets&noindent}} {{page>wiki:v2:line-packets&noindent}} {{page>wiki:v2:video-packets&noindent}}