Prusa Research publishes the binary G-code specification with its reference library, libbgcode. This page follows that specification (version 1) and the library. All integers are little-endian.
Block order
- File header
- File metadata block (optional)
- Printer metadata block
- Thumbnail blocks (optional, one per image)
- Print metadata block
- Slicer metadata block
- G-code blocks
File header
| Offset | Size | Type | Name | Meaning |
|---|---|---|---|---|
| 0 | 4 | char[4] | Magic number | GCDE (47 43 44 45) |
| 4 | 4 | uint32 | Version | 1 |
| 8 | 2 | uint16 | Checksum type | 0 none, 1 CRC-32 |
Blocks
Every block is a header, parameters, data and, when the file uses checksums, a checksum.
| Offset | Size | Type | Name | Meaning |
|---|---|---|---|---|
| 0 | 2 | uint16 | Type | Block type; see below |
| 2 | 2 | uint16 | Compression | See below |
| 4 | 4 | uint32 | Uncompressed size | Size of the data when uncompressed |
| 8 | 4 | uint32 | Compressed size | Size of the stored data; present only when Compression is not 0 |
So the header is 8 bytes when the data is uncompressed and 12 bytes otherwise. The
stored data is Uncompressed size bytes long when Compression is 0, and
Compressed size bytes otherwise. With CRC-32 checksums, 4 bytes follow
the data: the CRC-32 of the block header, parameters and stored data.
Block types
| Type | Block | Parameters | Data |
|---|---|---|---|
| 0 | File metadata | uint16 encoding | Key-value pairs about the file, such as the producing software |
| 1 | G-code | uint16 encoding | A part of the G-code program |
| 2 | Slicer metadata | uint16 encoding | Key-value pairs made and used by the slicer, such as its settings |
| 3 | Printer metadata | uint16 encoding | Key-value pairs used by the printer, such as printer model and nozzle diameter |
| 4 | Print metadata | uint16 encoding | Key-value pairs about the print, such as print time and material used |
| 5 | Thumbnail | uint16 format, uint16 width, uint16 height | One preview image |
Compression
| Value | Meaning |
|---|---|
| 0 | None |
| 1 | Deflate |
| 2 | Heatshrink, window size 11, lookahead 4 |
| 3 | Heatshrink, window size 12, lookahead 4 |
Encodings
| Blocks | Value | Meaning |
|---|---|---|
| Metadata blocks | 0 | INI: lines of key=value |
| G-code blocks | 0 | Plain G-code text |
| G-code blocks | 1 | MeatPack, with comments removed |
| G-code blocks | 2 | MeatPack, keeping comment lines |
Thumbnail formats
| Value | Format |
|---|---|
| 0 | PNG |
| 1 | JPEG |
| 2 | QOI |
MeatPack
MeatPack packs the most common G-code characters into 4 bits each, two to a byte: the first character in the low four bits, the second in the high four bits.
| Bits | Character |
|---|---|
| 0000 to 1001 | 0 to 9 |
| 1010 | . |
| 1011 | Space, or E in no-spaces mode |
| 1100 | Line feed |
| 1101 | G |
| 1110 | X |
| 1111 | The character is not packed: a full byte with it follows |
If the first character is a line feed, the high four bits are not used. Commands are
sent as two FF bytes followed by a command byte:
| Command | Meaning |
|---|---|
| 251 | Enable packing |
| 250 | Disable packing; bytes are copied as they are |
| 249 | Reset all (packing off) |
| 248 | Query configuration |
| 247 | Enable no-spaces mode |
| 246 | Disable no-spaces mode |
libbgcode’s encoder turns packing and no-spaces mode on at the start, writes
lower-case e as E, and leaves out the spaces between a
command and its parameters. Its decoder puts a space back before each parameter
letter on lines that start with G.
Worked example: G1 X10 in no-spaces mode is the characters
G, 1, X, 1, 0, line
feed, which pack as 1D (G then 1), 1E (X then 1) and
C0 (0 then line feed).