MakerBot published the s3g protocol (formerly the RepRap Generation 3 protocol) in
its s3g repository, doc/s3gProtocol.md. An X3G file is
the stream of commands the printer would otherwise receive over USB, captured to a
file; this page lists every command the document defines that can appear in one.
All integers are little-endian.
The file
- The file is the command payloads one after another: a command byte followed by its fixed parameters. There is no file header, no length fields and no checksums; a reader must know each command’s size to find the next.
- Only buffered host commands (codes 128 to 255) appear. Query commands (0 to 127) need an answer and are only sent over the wire.
- A build normally begins with
157Stream version and153Build start, and ends with154Build end. The converter GPX can leave these out, and can also write the on-wire framing below into the file as an option; ordinary files hold plain payloads. - Positions are in motor steps, so a file is made for one printer’s steps per millimetre and will not print correctly on another.
On-wire framing
| Offset | Size | Meaning |
|---|---|---|
| 0 | 1 | Start byte, 0xD5 |
| 1 | 1 | Payload length N |
| 2 | N | Payload: command byte and parameters |
| 2 + N | 1 | CRC: the 8-bit Maxim (Dallas 1-Wire) CRC of the payload, polynomial x8 + x5 + x4 + 1 |
Data types
| Type | Size | Range |
|---|---|---|
| uint8 | 1 | 0 to 255 |
| uint16 | 2 | 0 to 65 535 |
| int16 | 2 | −32 768 to 32 767 |
| uint32 | 4 | 0 to 4 294 967 295 |
| int32 | 4 | −2 147 483 648 to 2 147 483 647 |
| float | 4 | IEEE 754 single precision (command 155 only) |
| Axes bitfield bit | Axis |
|---|---|
| 0 | X |
| 1 | Y |
| 2 | Z |
| 3 | A (first extruder) |
| 4 | B (second extruder) |
| 5–7 | Reserved, 0 |
Host commands
Size is the whole command including its first byte.
| Code | Command | Size | Parameters after the code byte |
|---|---|---|---|
| 131 (0x83) | Find axes minimums: home towards the minimum endstops | 8 | uint8 axes; uint32 feed rate in µs between steps of the longest axis (DDA); uint16 timeout, s |
| 132 (0x84) | Find axes maximums | 8 | As 131 |
| 133 (0x85) | Delay all motion | 5 | uint32 delay, ms |
| 134 (0x86) | Change tool | 2 | uint8 tool ID (applies the dual-head calibration offset) |
| 135 (0x87) | Wait for tool ready (temperature reached) | 6 | uint8 tool ID; uint16 query interval, ms (nominally 100); uint16 timeout, s (nominally 60) |
| 136 (0x88) | Tool action command | 4 + N | uint8 tool ID; uint8 tool command (see below); uint8 length N; N bytes of tool parameters |
| 137 (0x89) | Enable or disable steppers | 2 | uint8: bits 0–4 select X, Y, Z, A, B; bit 7 set enables, clear disables |
| 139 (0x8B) | Queue extended point (absolute, DDA) | 25 | int32 X, Y, Z, A, B in steps; uint32 feed rate, µs per step of the longest axis |
| 140 (0x8C) | Set extended position | 21 | int32 X, Y, Z, A, B in steps: redefine the current position |
| 141 (0x8D) | Wait for platform ready | 6 | uint8 tool ID of the platform; uint16 query interval, ms; uint16 timeout, s |
| 142 (0x8E) | Queue extended point, new style | 26 | int32 X, Y, Z, A, B in steps; uint32 duration, µs; uint8 axes that move relatively |
| 143 (0x8F) | Store home positions in EEPROM | 2 | uint8 axes |
| 144 (0x90) | Recall home positions from EEPROM | 2 | uint8 axes |
| 145 (0x91) | Set digital potentiometer (stepper current reference) | 3 | uint8 axis 0–4; uint8 value 0–127 |
| 146 (0x92) | Set RGB LED | 6 | uint8 red, green, blue (0–255); uint8 blink rate; uint8 reserved 0 |
| 147 (0x93) | Beep | 6 | uint16 frequency; uint16 length, ms; uint8 reserved 0 |
| 148 (0x94) | Wait for button | 5 | uint8 buttons; uint16 timeout, s (0 never); uint8 options |
| 149 (0x95) | Display message on the LCD | 6 + N | uint8 options; uint8 column (0–19); uint8 row (0–3); uint8 timeout, s (0 stays); ASCII text of N bytes and a terminating 0 |
| 150 (0x96) | Set build percentage | 3 | uint8 percent 0–100; uint8 reserved 0 |
| 151 (0x97) | Queue song | 2 | uint8 song: 0 error tone of 4 cycles, 1 done tone, 2 error tone of 2 cycles |
| 152 (0x98) | Reset to factory settings (except calibration, axis inversion, tool count) | 2 | uint8 reserved 0 |
| 153 (0x99) | Build start notification | 6 + N | uint32 reserved 0; build name, ASCII, N bytes and a terminating 0 |
| 154 (0x9A) | Build end notification | 2 | uint8 reserved 0 |
| 155 (0x9B) | Queue extended point x3g | 32 | int32 X, Y, Z, A, B in steps; uint32 DDA rate, steps/s; uint8 relative axes; float distance of the move, mm (XYZ length, or AB for extruder-only moves); uint16 feed rate in mm/s × 64 |
| 157 (0x9D) | Stream version | 21 | uint8 x3g version high; uint8 version low; uint8 unused; uint32 unused; uint16 bot type (0xD314 Replicator, 0xB015 Replicator 2); uint16 unused; uint32 unused; uint32 unused; uint8 unused |
Bit fields
| Field | Bits |
|---|---|
| 148 buttons | 0 centre, 1 right, 2 left, 3 down, 4 up, 5 reset |
| 148 options | 0 go to ready state on timeout, 1 reset the printer on timeout, 2 clear the screen on button press |
| 149 options | 0 clear existing message, 1 last message in group (show the buffer), 2 wait for button press |
Command 149 builds the screen in a buffer: text wraps at the end of a line,
\n starts a new line and \r is ignored; nothing appears
until a message with the “last message in group” bit arrives.
Tool commands (inside 136)
| Code | Command | Parameters (N bytes) |
|---|---|---|
| 1 | Initialise the tool to its boot state (targets 0, outputs off, servos detached) | none |
| 3 | Set extruder target temperature | int16 °C |
| 6 | Set motor speed | uint32 µs per revolution |
| 10 | Enable or disable motor | uint8: bit 0 enable, bit 1 clockwise |
| 12 | Fan on or off (the extruder fan waits until 50 °C) | uint8 1 on, 0 off |
| 13 | Extra output on or off | uint8 1 on, 0 off |
| 14 | Set servo 1 position | uint8 angle 0–180 |
| 23 | Pause or resume | none |
| 24 | Abort: stop heaters and motors | none |
| 31 | Set build platform target temperature | int16 °C |
Tool IDs are 0 to 126; 0 is the first extruder and 1 the second. Up to firmware 2.92, 255 was the broadcast address; from then on it is 127.
Worked example
| Bytes | Meaning |
|---|---|
88 00 03 02 DC 00 | Tool command to tool 0: set temperature (3), 2 bytes, 0x00DC = 220 °C |
87 00 64 00 3C 00 | Wait for tool 0, querying every 100 ms, giving up after 60 s |
85 E8 03 00 00 | Delay 1000 ms |
9A 00 | Build end |
What is not covered
Later firmwares such as Sailfish may accept commands that are not in MakerBot’s document (code 156, for one, is not defined there); they are not listed here. The query commands (0 to 127), tool query commands and response codes belong to the live connection and do not appear in files.