Skip to content

Latest commit

 

History

History
239 lines (176 loc) · 7.9 KB

protocol.md

File metadata and controls

239 lines (176 loc) · 7.9 KB

ggtag protocol

ggtag is using the same data protocol for sound and USB programming. The protocol encodes a series of commands into binary stream which is prefixed by two bytes which specify the size of the stream. The entire payload has the following format:

[SIZE (2 bytes)] [CMD1] [CMD2] [CMD3] ... [CMDn]

The SIZE is encoded as a big-endian 16-bit unsigned integer. At most SIZE bytes follow which represent the commands.

Commands

Each command has the following format:

[CMD_CODE (4 bits)] [ARG1] [ARG2] ... [ARGn]
CMD_CODE Name Description
0000 TEXT_CMD Draw text
0001 RECT_CMD Draw rectangle
0010 FILL_RECT_CMD Draw filled rectangle
0011 CIRCLE_CMD Draw circle
0100 FILL_CIRCLE_CMD Draw filled circle
0101 LINE_CMD Draw line
0110 QRCODE_CMD Draw QR code
0111 IMAGE_CMD Draw image
1000 ICON_CMD Draw icon
1001 RFID_CMD Program RFID
1010 RLE_IMAGE_CMD Draw RLE image

The commands are executed in the order they are received. The display is cleared before the first command is executed.

TEXT_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Font size 3
4 Text length (N) 7
5 Char1 (7bit ASCII) 7
... ... ...
4+N CharN (7bit ASCII) 7

Example: Draw "ABC" at position (120,95) with fontSize=3

CMD_CODE ARG1 ARG2 ARG3 ARG4 ARG5 ARG6 ARG7
0000 001111000 01011111 010 0000011 1000001 1000010 1000011

RECT_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Width 9
4 Height 8

Example: Draw rectangle at position (50,30) with width=280 and height=170

CMD_CODE ARG1 ARG2 ARG3 ARG4
0001 000110010 00011110 100011000 10101010

FILL_RECT_CMD

Same as RECT_CMD.

CIRCLE_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Radius 7

Example: Draw circle at position (50,30) with radius=100

CMD_CODE ARG1 ARG2 ARG3
0011 000110010 00011110 1100100

FILL_CIRCLE_CMD

Same as CIRCLE_CMD.

LINE_CMD

ARG# Description Size (bits)
1 X1 coordinate 9
2 Y1 coordinate 8
3 X2 coordinate 9
4 Y2 coordinate 8

Example: Draw line from (50,30) to (280,170)

CMD_CODE ARG1 ARG2 ARG3 ARG4
0101 000110010 00011110 100011000 10101010

QRCODE_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Pixel width 2
4 Text length (N) 7
5 Char1 (7bit ASCII) 7
... ... ...
4+N CharN (7bit ASCII) 7

Example: Draw QR code at position (50,30) with pixel width=2 and text="ABC"

CMD_CODE ARG1 ARG2 ARG3 ARG4 ARG5 ARG6 ARG7
0110 000110010 00011110 10 0000011 1000001 1000010 1000011

IMAGE_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Image width (W) 9
4 Image height (H) 8
5 Bitmap W*H

Consider the following 7x9 image (* = black, . = white)

*******
*.....*
*.....*
*.***.*
*.....*
*.***.*
*.....*
*.....*
*******

Example: Draw the image above at position (50,30)

CMD_CODE ARG1 ARG2 ARG3 ARG4 ARG5
0111 000110010 00011110 000000111 00001001 111111110000011000001101110110000011011101100000110000011111111

ICON_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Icon height 8
4 Icon codepoint 16

Example: Draw the FontAwesome icon with codepoint 0xf552 at position (50,30) with height=40

CMD_CODE ARG1 ARG2 ARG3 ARG4
1000 000110010 00011110 00101000 1111010111010010

RFID_CMD

ARG# Description Size (bits)
1 Type (0=EM4102, 1=HID) 1
2 ID 45

If type is EM4102, the ID argument is interpreted in the following way:

| unused (5 bits) | manufacturer ID (8 bits) | unique ID (32 bits) |

If type is HID, the ID argument is interpreted in the following way:

| manufacturer code (20 bits) | site code (8 bits) | unique id (16 bits) | parity (1 bit) |

Example: Program RFID to be EM4102 with manufacturer ID=0x07 and unique ID=0xad30b1

CMD_CODE ARG1 ARG2
1001 0 000000000011100000000101011010011000010110001

RLE_IMAGE_CMD

ARG# Description Size (bits)
1 X coordinate 9
2 Y coordinate 8
3 Image width (W) 9
4 Image height (H) 8
5 RLE bitmap variable

The image is encoded using run-length encoding (RLE). The bitmap is interpreted as a sequence of black and white runs, left to right, top to bottom. Consider the following 7x9 image (* = black, . = white):

.......
.......
*******
****...
.......
.......
....***
*******
*******

We have 14 white pixels, 11 black pixels, 21 white pixels and 17 black pixels. We encode these numbers in base 3:

14 = 112(3)
11 = 102(3)
21 = 210(3)
17 = 122(3)

We use 2 bits to encode each digit in base 3, so 112(3) is encoded as 010110. We use 11 to separate the runs, and we always start with a white run. The image above is encoded as 010110 11 010010 11 100100 11 011010.

Example: Draw the image above at position (50,30)

CMD_CODE ARG1 ARG2 ARG3 ARG4 ARG5
1010 000110010 00011110 000000111 00001001 010110110100101110010011011010