Table of Contents

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 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 page does a good job explaining endianness.

Furthermore, all signed integer quantities are represented using two's complement representation. This 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

Color Connected Components - Packet Reference

See Color Connected Components API for more details on sigmap, maxblocks, tracking index, etc.

getBlocks(sigmap, maxBlocks)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 32
3 Length of payload 2
4 Sigmap - indicate which signatures to receive data from 0 (none) - 255 (all)
5 Maximum blocks to return 0 (none) - 255 (all blocks)

Response:

Byte Description Value(s)
0 - 1 16-bit sync 175, 193 (0xc1af)
2 Type of packet 33
3 Length of payload 14
4 - 5 16-bit checksum sum of payload bytes
6 - 7 16-bit signature / Color code number 0 - 255
8 - 9 16-bit X (center) of block in pixels 0 - 315
10 - 11 16-bit Y (center) of block in pixels 0 - 207
12 - 13 16-bit Width of block in pixels 0 - 316
14 - 15 16-bit Height of block in pixels 0 - 208
16 - 17 16-bit Angle of color-code in degrees -180 - 180 (0 if not a color code)
18 Tracking index of block (see API for more info)0 - 255
19 Age - number of frames this block has been tracked 0 - 255 (stops incrementing at 255)
2018/09/28 22:35 · jfrench

Line Tracking - Packet Reference

Check out the Line tracking API for more details.

getMainFeatures(features, wait)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 48
3 Length of payload 2
4 Request type 0=main features, 1=all features
5 Features (bitmap) 7=vectors, intersections, barcodes

Response:

Byte Description Value(s)
0 - 1 16-bit sync 175, 193 (0xc1af)
2 Type of packet 49
3 Length of payload (varies)
4 - 5 16-bit checksum sum of payload bytes
6 Feature-type 1=Vector, 2=Intersection, 4=Barcode
7 Feature-length (varies)
8 - 8+feature-length Feature-data (varies)
Next feature-type (optional) (varies)
Next feature-length (optional) (varies)
Next feature-data (optinal) (varies)
Next feature-type (optional) (varies)
Next feature-length (optional) (varies)
Next feature-data (optinal) (varies)

Note, this response can have up to three different feature sections, one for vectors (if vector(s) exist), one for intersections (if intersection(s) exist) and one for barcodes (if barcode(s) exist) in the image. Each feature section begins with a feature-type. The feature-length is next, which indicates how many bytes are in the feature-data. The feature-data is last, which has the data associated with the feature. Sometimes the feature-data section will have more than one of the given feature type, for example, there may be three barcodes, in which case the three barcodes will be concatenated in the feature-data without any bytes between them.

For the specific feature data types and composition, please consult the Pixy2Line.h file.

setMode(mode)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 54
3 Length of payload 1
4 Mode (varies)

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 Response/acknowledge (varies)

setNextTurn(angle)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 58
3 Length of payload 2
4 - 5 16-bit angle (varies)

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 Response/acknowledge (varies)

setDefaultTurn(angle)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 60
3 Length of payload 2
4 - 5 16-bit angle (varies)

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 Response/acknowledge (varies)

setVector(angle)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 56
3 Length of payload 1
4 vector index (varies)

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 Response/acknowledge (varies)

reverseVector(angle)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 62
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 Response/acknowledge (varies)
2018/09/28 22:35 · jfrench

Video - Packet Reference

Check out the Video API for more details.

getRGB(x,y,r,g,b,saturate)

Request:

Bit Description Value(s)
0 - 1 16-bit sync 174, 193 (0xc1ae)
2 Type of packet 112
3 Length of payload 5
4 - 5 16-bit x value 0 - 315
6 - 7 16-bit y value 0 - 207
8 Saturate flag 0=don't saturate, 1=saturate

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 blue value (varies)
7 green value (varies
8 red value (varies)
2018/09/28 22:51 · jfrench