Project update 7 of 8
Extending and Customizing GGtag
by Radoslav GerganovGreetings, everyone!
In this week’s update, we will dive into a bit of how GGtag works and how you can extend it for your own needs.
Project Structure
The project is split into several directories:
- target - contains device-only source code
- shared - contains shared source code between the device and the host library
- host - contains the host library
- docs - contains the web interface
- python - contains Python bindings for the host library
Component Diagram
Notice how we reuse the same source code for the device and the web interface. This is possible thanks to the Emscripten compiler which allows us to compile C code into WebAssembly and JavaScript.
Data Protocol
GGtag uses 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.
You can find the full protocol documentation in our GitHub repo.
Extending the Protocol
Let’s say we want to add a new command for drawing an ellipse. It will have CMD_CODE=11 (or 1011 in binary) and the following arguments:
| ARG# | Description | Size (bits) |
|---|---|---|
| 1 | center X coordinate | 9 |
| 2 | center Y coordinate | 8 |
| 3 | X Radius | 7 |
| 4 | Y Radius | 7 |
The complete implementation of this new command is less than 150 lines of code. You can find it in the ellipse branch of the repository. Here is a short summary of the changes:
docs/...- trivial changes to the web interfacehost/src/ggtag.cpp- parsing the text command into the binary protocolshared/include/protocol.h- adding the new commandshared/src/GUI_Paint.c- drawing an ellipseshared/src/protocol.cpp- parsing the binary protocol
Finally, you’ll need to rebuild everything by following the instructions in the README and flashing the new firmware to the device.
Happy hacking!
Should you have any questions, please feel free to reach out to us using the "Ask a technical question" link on our campaign page or participate in our GitHub discussions! And, if you haven’t claimed your own GGtag yet, there’s still time while our campaign is live!
Until next time!
- GGtag team