This document describes the s3g protocol, which is used to communicate with Makerbots and similar CNC machines. It is intended to help developers who wish to communicate with a machine directly, or create their own devices that speak over the protocol. If all you want to do is control a machine, we recommend using the s3g library, which is a Python implementation of the protocol.
The first part of the document covers some definitions that are used to describe this system. We recommend you at least skim through them, so we can be sure we are talking about the same things.
The second part of the document talks about the architecture that the s3g protocol was designed for. It's useful for understanding how the different pieces of hardware are connected, and what each part does.
The third part of the document talks about the fine details of how commands are routed through the system, and what happens if there is an error when sending one. It's useful for understanding how to make your own
The final portion of the document is a catalog of all of the commands that the Host and Tools can implement.
Firmware repositories:
- For Gen3 and Gen4 electronics (Cupcake, Thing-O-Matic, Reprap): G3Firmware
- For Mightyboard (Replicator): MightyBoardFirmware
Host software:
Here is some vocabulary that should be used when talking about the protocol:
| Name | Definition |
|---|---|
| PC | A computer, that is connected to the Host over the host network. |
| Host | The motherboard on the machine. This communicates with the PC over the host network, and with 0 or more tools over the tool network. The host can control 3-5 stepper motors, read endstops, read and write to an SD card, and control an interface board. |
| Tool | An auxiliary motherboard on the machine, This communicates with the Host over the tool network, and controls one toolhead (extruder). The Tool can have a toolhead heater, platform heater, fan, extruder motor, and other things attached to it. On the Mightyboard, the Tool is simulated inside of the motherboard, and doesn't exist as a separate piece. |
| Host network | The host network is the serial connection between the PC and the Host. The physical bus is RS232 (using a USB<->serial adaptor), running at 115200 baud (Gen4, MightyBoard) or 38400 baud (Gen3). |
| Tool network | The tool network is the serial connection between the Host and 0 or more Tools. The physical bus is RS485, half-duplex, running at xxx baud (Gen3, Gen4), or virtual (MightyBoard). |
| Tool ID | A unique address that is assigned to each Tool, that allows it to be addressed individually by the Host. Valid Tool IDs are 0-126. It is recommended to use 0 for the first Tool, and 1 for the second Tool. |
| Query Command | A query command is a command that should be evaluated and acknowledged immediately. They are used for things such as setting or reading temperatures. |
| Buffered Command | A buffered command should be acknowledged immediately, but the Host or Tool may choose to store it in a buffer for later execution. These should be used for commands that could take a long time to execute, such as motion commands. |
An s3g system looks like this:
There are two networks, the host network and the tool network. Both networks (host, tool) have a single network master. On the host network, this is a PC, and on the tool network, this is the Host. The host network must have one slave device (the Host), and the tool network can have one or more slave devices (Tool N).
Note: On the MightyBoard, the tool bus is emulated in software in order to be backwards compatible.
All communication is initiated by the network master sending a single packet over the network, which contains either a query command or buffered command. If the slave device receives the packet, it must respond with a single packet, containing a response code and any response data.
This is what a normal communication over the host network looks like:
Communication over the tool network works similarly:
Finally, a PC may communicate with a Tool by forwarding a packet through the Host:
The slave device is expected to begin responding to a master command within 40ms of receiving it. This is currently broken for a number of commands in actual systems. If a slave takes too long to respond to a command, then the trasmission is to be considered a timeout. Note: Many commands in the current implementation break this requirement, and no known PC implementation enforces it.
Of course, communication is not always so rosy. There are a number of things that could prevent a successful transmission, such as electrical noise or busy firmware. The protocol uses two methods to protect against this: a CRC check at the end of every packet, and a timeout counter while receiving data.
The master is allowed to attemt re-transmission if and only if it receives two specific types of errors. The first type of error is the Retryable error. If the master receives a Retryable Error, it may retry sending the current packet up to 5 times. Several types of errors are considered "Retryable": transmission timeouts, Packet Decode errors (indicative of a malformed packet), CRC Errors indicating a discrepency between master and machine, and Generic Machine errors all inherit from Retryable Error. After 5 Retryable Errors are raised, s3g throws a Transmission Error and terminates. The second type of error that allows for re-transmission is the BufferOverflowError. There is no limit to the number of Buffer Overflow Errors a machine can receive.
Here is a reference implementation of a packet send state machine:
All packets have the following structure:
| Index | Name | Details |
|---|---|---|
| 0 | Start Byte | This byte always has the value 0xD5 and is used to ensure synchronization. |
| 1 | Length | The length of the payload, in bytes |
| 2..(1+N) | Payload | The packet payload. The payload can be N bytes long (TODO: maximum length?). |
| 2+N | CRC | The 8-bit iButton/Maxim CRC of the payload |
The payload of a packet sent over the master network contains one command. Each command consists of a command code, and 0 or more arguments:
| Index | Name | Details |
|---|---|---|
| 0 | Host Command Code | A byte representing the host command to be executed. Codes with a value from 0-127 are considered query commands, and codes with a value from 128-255 are considered action commands. |
| 1..(1+N) | Arguments | (optional) Command arguments, such as a position to move to, or a flag to set. Command specific. |
The payload of a packet sent over the tool network contains one command. Each command consists of a Tool ID, a command code, and 0 or more arguments:
| Index | Name | Details |
|---|---|---|
| 0 | Tool ID | The ID of the tool device being addressed (see below) |
| 1 | Command Code | A byte representing the command to be executed. Unlike host commands, tool command values have no special meaning. |
| 2..(2+N) | Arguments | (Optional) Command arguments, such as a position to move to, or a flag to set. Command specific. |
A note about Tool IDs:
The tool ID is the ID number of a toolhead. A toolhead may only respond to commands that are directed at its ID. If the packet is corrupt, the tool should not respond with an error message to avoid collisions.
The exception to this is the tool ID 127. This represents any listening device. The address 127 should only be used when setting the ID of a tool.
Note: Before firmware version 2.92, the broadcast address was 255.
The response payload contains the response to a single command:
| Index | Name | Details |
|---|---|---|
| 0 | Response Code | A byte representing the completion status of the command (see below) |
| 1..(1+N) | Arguments | (Optional) Response arguments, such as current machine position or toolhead temperature. Command specific. |
Response code values can be as follows:
| Response Code | Details | Can be retried? |
|---|---|---|
| 0x80 | Generic Packet error, packet discarded | Yes |
| 0x81 | Success | No |
| 0x82 | Action buffer overflow, entire packet discarded | No |
| 0x83 | CRC mismatch, packet discarded. | Yes |
| 0x84 | Query packet too big, packet discarded | No |
| 0x85 | Command not supported/recognized | No |
| 0x87 | Downstream timeout | No |
| 0x88 | Tool lock timeout | Yes |
| 0x89 | Cancel build | Yes |
| 0x8A | Bot is Building from SD | No |
| 0x8B | Bot is shutdown due to Overheat | No |
| 0x8C | Packet timeout error, packet discarded | Yes |
Historical note: Firmware versions prior to 2.9 did not have the high bit set for error codes. This was changed to avoid having the response code conflict with tool indexes on the tool network
Integers represent numbers. All integers are in little endian format.
| Type | Size | Range |
|---|---|---|
| uint8 | 1 byte | 0 to 255 |
| uint16 | 2 bytes | 0 to 65535 |
| int16 | 2 bytes | -32768 to 32767 |
| uint32 | 4 bytes | 0 to 4294967296 |
| int32 | 4 bytes | -−2147483648 to 2147483647 |
An axes bitfield structure is used to represent a selection of axes.
| Bit | Name |
|---|---|
| 7 | 0 (reserved for future use) |
| 6 | 0 (reserved for future use) |
| 5 | 0 (reserved for future use) |
| 4 | B axis |
| 3 | A axis |
| 2 | Z axis |
| 1 | Y axis |
| 0 | X axis |
| Response Code | Details |
|---|---|
| 0x00 | Operation successful |
| 0x01 | SD Card not present |
| 0x02 | SD Card initialization failed |
| 0x03 | Partition table could not be read |
| 0x04 | Filesystem could not be opened |
| 0x05 | Root directory could not be opened |
| 0x06 | SD Card is locked |
This command allows the host and firmware to exchange version numbers. It also allows for automated discovery of the firmware. Version numbers will always be stored as a single number, Arduino / Processing style. If the returned version number is greater than 5.5, the host has the option of requesting advanced version information with command #27
Payload
uint16: Host Version
Response
uint16: Firmware Version
Initialization consists of:
* Resetting all axes positions to 0
* Clearing command buffer
Payload (0 bytes)
Response (0 bytes)
This command will let us know how much buffer space we have available for action commands. It can be used to determine if and when the buffer is available for writing. If we are writing to the SD card, it will generally always report the maximum number of bytes available.
Payload (0 bytes)
Response
uint32: Number of bytes availabe in the command buffer
This command will empty our buffer, and reset all pointers, etc to the beginning of the buffer. If writing to an SD card, it will reset the file pointer back to the beginning of the currently open file. Obviously, it should halt all execution of action commands as well.
Payload (0 bytes)
Response (0 bytes)
This function is intended to be used to terminate a print during printing. Disables steppers, heaters, and any toolheads, and clears all command buffers.
Payload (0 bytes)
Response (0 bytes)
This function is inteded to be called infrequently by the end user in order to make build-time adjustments during a print. It differs from 'Abort Immediately', in that the command buffers and heaters are not disabled.
On pause, it stops all stepper movement and halts extrusion. On Resume, it restarts extrusion and resumes movement.
Payload (0 bytes)
Response (0 bytes)
This command is for sending a query command to the tool. The host firmware will then pass the query along to the appropriate tool, wait for a response from the tool, and pass the response back to the host. TODO: Does the master handle retries?
Payload
uint8: Tool index
0-N bytes: Payload containing the query command to send to the tool.
Response
0-N bytes: Response payload from the tool query command, if any.
This command queries the machine to determine if it currently executing commands from a command queue.
Payload (0 bytes)
Response
uint8: 0 if busy, 1 if finished.
Read the specified number of bytes from the given offset in the EEPROM, and return them in a response packet. The maximum read size is 31 bytes.
Payload
uint16: EEPROM memory offset to begin reading from
uint8: Number of bytes to read, N.
Response
N bytes: Data read from the EEPROM
Write the given bytes to the EEPROM, starting at the given offset.
Payload
uint16: EEPROM memory offset to begin writing to
uint8: Number of bytes to write
N bytes: Data to write to EEPROM
Response
uint8: Number of bytes successfully written to the EEPROM
Capture all subsequent commands up to the 'end capture' command to a file with the given name on the SD card. The file will be stored in the root of the fat16 filesystem on the SD card. The maximum file name length permitted is 12 characters, including the '.' and file name extension.
Payload
1+N bytes: Filename to write to, in ASCII, terminated with a null character. N can be 1-12 bytes long, not including the null character.
Response
uint8: SD response code
Complete an ongoing file capture by closing the file, and return to regular operation.
Payload (0 bytes)
Response
uint32: Number of bytes captured to file.
Play back a file containing a stream of captured commands. While the macine is in playback mode, it will only respond to pause, unpause, and stop commands.
Payload
1+N bytes: Filename to play back, in ASCII, terminated with a null character. N can be 1-12 bytes long, not including the null character.
Response
uint8: SD response code
Call a soft reset. This calls all reset functions on the bot. Same as abort.
Payload (0 bytes)
Response (0 bytes)
Retrieve the volume name of the SD card or the next valid filename from the SD card. If a non-zero value is passed to the 'restart' parameter, the file list will begin again from the start of the directory. The file list state will be reset if any other SD operations are performed. If all the filenames have been retrieved, an empty string is returned.
Payload
uint8: 0 if file listing should continue, 1 to restart listing.
Response
uint8: SD Response code
1+N bytes: Name of the next file, in ASCII, terminated with a null character. If the operation was unsuccessful, this will be a null character.
Retrieve the name of the file currently being built. If the machine is not currently printing, a null terminated string of length 0 is returned. If the bot has finished a print and has not been reset (hard or soft), it will return the name of the last file built.
Payload (0 bytes)
Response
1+N bytes: A null terminated string representing the filename of the current build.
Retrieve the curent position of all axes that the machine supports. Unsupported axes will return 0
Payload (0 bytes)
Response
int32: X position, in steps
int32: Y position, in steps
int32: Z position, in steps
int32: A position, in steps
int32: B position, in steps
uint16: bitfield corresponding to the endstop status:
| Bit | Name |
|---|---|
| 15 | 0 (reserved for future use) |
| 14 | 0 (reserved for future use) |
| 13 | 0 (reserved for future use) |
| 12 | 0 (reserved for future use) |
| 11 | 0 (reserved for future use) |
| 10 | 0 (reserved for future use) |
| 9 | B min switch pressed |
| 8 | B max switch pressed |
| 7 | A max switch pressed |
| 6 | A min switch pressed |
| 5 | Z max switch pressed |
| 4 | Z min switch pressed |
| 3 | Y max switch pressed |
| 2 | Y min switch pressed |
| 1 | X max switch pressed |
| 0 | X min switch pressed |
Stop the stepper motor motion and/or reset the command buffer. This differs from the reset and abort commands in that a soft reset of all functions is not called
Payload
uint8: Bitfield indicating which subsystems to shut down. If bit 0 is set, halt all stepper motion. If bit 1 is set, clear the command queue.
Response
int8: 0 (reserved for future use)
Retrieve some status information from the motherboard
Payload (0 bytes)
Response
uint8: Bitfield containing status information (see below)
| Bit | Name | Details |
|---|---|---|
| 7 | POWER_ERRPR | An error was detected with the system power. For Gen4 electronics, this means ATX_5V is not present |
| 6 | HEAT_SHUTDOWN | Heaters were shutdown after 30 minutes of inactivity |
| 5 | BUILD_CANCELLING | Watchdog reset flag was set at restart |
| 4 | WAIT_FOR_BUTTON | BotUI is waiting for button push by user |
| 3 | ONBOARD_PROCESS | Bot is running an onboard process (the difference between an onboard script and an onboard process is important to the bot, but is not important to the s3g host) |
| 2 | ONBOARD_SCRIPT | Bot is running an onboard script |
| 1 | MANUAL_MODE | Manual move mode active |
| 0 | PREHEAT | Onboard preheat active |
Gathers statistics about the currently building print if a build is active, or the last print if there is no active build
Payload (1 byte)
Response
uint8 : Build State (paused, running, finished_normally, canceled, none)
uint8 : Hours elapsed on print
uint8 : Minutes elapsed on print (add hours for total time)
uint32: Line Number (number of commands processed)
uint32: Reserved for Future Use
Build State Return Values are as follows
| 0 | no build initialized (boot up state) |
| 1 | build running |
| 2 | build finished normally |
| 3 | build paused |
| 4 | build cancelled |
| 5 | build sleeping |
Gathers statistics about communication over the tool network. This was intended for use while troubleshooting Gen3/4 machines.
Payload (0 bytes)
Response
uint32: Packets received from the host network
uint32: Packets sent over the tool network
uint32: Number of packets sent over the tool network that were not repsonded to
uint32: Number of packet retries on the tool network
uint32: Number of bytes received over the tool network that were discarded as noise
returns the main version numbers along with an internal version number
Payload
uint16: Host Version
Response
uint16_t Firmware Version
uint16_t Internal Version
uint8_t Software Variant, see software variant table for valid IDs
uint8_t Reserved for future use
uint16_t Reserved for future use
Sofware Variant IDs are as follows
| 0x00 | unknown |
| 0x01 | MBI Official |
| 0x02-0x7F | reserved |
| 0x80 | Sailfish |
| 0x81-0xBF | unassigned variants |
| 0xC0-0xFF | reserved |
131 - Find axes minimums: Move specified axes in the negative direction until their limit switch is triggered.
This function will find the minimum position that the hardware can travel to, then stop. Note that all axes are moved syncronously. If one of the axes (Z, for example) should be moved separately, then a seperate command should be sent to move that axis. Note that a minimum endstop is required for each axis that is to be moved.
Payload
uint8: Axes bitfield. Axes whose bits are set will be moved.
uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
uint16: Timeout, in seconds.
Response (0 bytes)
132 - Find axes maximums: Move specified axes in the positive direction until their limit switch is triggered.
This function will find the maximum position that the hardware can travel to, then stop. Note that all axes are moved syncronously. If one of the axes (Z, for example) should be moved separately, then a seperate command should be sent to move that axis. Note that a maximum endstop is required for each axis that is to be moved.
Payload
uint8: Axes bitfield. Axes whose bits are set will be moved.
uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
uint16: Timeout, in seconds.
Response (0 bytes)
Halt all motion for the specified amount of time.
Payload
uint32: delay, in milliseconds
Response (0 bytes)
Instruct the host to select the given tool as active
Note: This is important to use on dual-head Replicators, because the machine needs to know the current toolhead in order to apply a calibration offset.
Payload
uint8: Tool ID of the tool to switch to
Response (0 bytes)
This command halts machine motion until the specified toolhead reaches a ready state. A tool is ready when its temperature is within range of the setpoint.
Payload
uint8: Tool ID of the tool to wait for
uint16: delay between query packets sent to the tool, in ms (nominally 100 ms)
uint16: Timeout before continuing without tool ready, in seconds (nominally 1 minute)
Response (0 bytes)
This command is for sending an action command to the tool. The host firmware will then pass the query along to the appropriate tool, wait for a response from the tool, and pass the response back to the host. TODO: Does the master handle retries?
Payload
uint8: Tool ID of the tool to query
uint8: Action command to send to the tool
uint8: Length of the tool command payload (N)
N bytes: Tool command payload, 0-? bytes.
Response (0 bytes)
This command is used to explicitly power steppers on or off. Generally, it is used to shut down the steppers after a build to save power and avoid generating excessive heat.
Payload
uint8: Bitfield codifying the command (see below)
Response (0 bytes)
| Bit | Details |
|---|---|
| 7 | If set to 1, enable all selected axes. Otherwise, disable all selected axes. |
| 6 | 0 (reserved for future use) |
| 5 | 0 (reserved for future use) |
| 4 | B axis select |
| 3 | A axis select |
| 2 | Z axis select |
| 1 | Y axis select |
| 0 | X axis select |
This queues an absolute point to move to.
Historical note: This implementation is much more wordy than an incremental solution, which likely impacts processing time and buffer sizes on the resource-constrained firmware
Payload
int32: X coordinate, in steps
int32: Y coordinate, in steps
int32: Z coordinate, in steps
int32: A coordinate, in steps
int32: B coordinate, in steps
uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
Response (0 bytes)
reset the current position of the axes to the given values.
Payload
int32: X position, in steps
int32: Y position, in steps
int32: Z position, in steps
int32: A position, in steps
int32: B position, in steps
Response (0 bytes)
This command halts machine motion until the specified tool device reaches a ready state. A build platform is ready when it's temperature is within range of the setpoint.
Payload
uint8: Tool ID of the build platform to wait for
uint16: delay between query packets sent to the tool, in ms (nominally 100 ms)
uint16: Timeout before continuing without tool ready, in seconds (nominally 1 minute)
Response (0 bytes)
This queues a point to move to.
Historical note: It differs from old-style point queues (see command 139 et. al.) in that it no longer uses the DDA abstraction and instead specifies the total move time in microseconds. Additionally, each axis can be specified as relative or absolute. If the 'relative' bit is set on an axis, then the motion is considered to be relative; otherwise, it is absolute.
Payload
int32: X coordinate, in steps
int32: Y coordinate, in steps
int32: Z coordinate, in steps
int32: A coordinate, in steps
int32: B coordinate, in steps
uint32: Duration of the movement, in microseconds
uint8: Axes bitfield to specify which axes are relative. Any axis with a bit set should make a relative movement.
Response (0 bytes)
Record the positions of the selected axes to device EEPROM
Payload
uint8: Axes bitfield to specify which axes' positions to store. Any axis with a bit set should have its position stored.
Response (0 bytes)
Recall the positions of the selected axes from device EEPROM
Payload
uint8: Axes bitfield to specify which axes' positions to recall. Any axis with a bit set should have its position recalled.
Response (0 bytes)
Set the value of the digital potentiometers that control the voltage reference for the botsteps
Payload
uint8: axis value (valid range 0-4) which axis pot to set
uint8: value (valid range 0-127), values over max will be capped at max
Response (0 bytes)
Set Brightness levels for RGB led strip
Payload
uint8: red value (all pix are 0-255)
uint8: green
uint8: blue
uint8: blink rate (0-255 valid)
uint8: 0 (reserved for future use)
Response (0 bytes)
Set a buzzer frequency and buzz time
Payload
uint16: frequency
uint16: buzz length in ms
uint8: 0 (reserved for future use)
Response (0 bytes)
Wait until either a user presses a button on the interface board, or a timeout occurs.
Payload
uint8: Bit field of buttons to wait for (see below)
uint16: Timeout, in seconds. A value of 0 indicates that the command should not time out.
uint8: Options bitfield (see below)
Response (0 bytes)
Button field
| Bit | Name |
|---|---|
| 7 | 0 (reserved for future use) |
| 6 | 0 (reserved for future use) |
| 5 | RESET |
| 4 | UP |
| 3 | DOWN |
| 2 | LEFT |
| 1 | RIGHT |
| 0 | CENTER |
Options Field
| Bit | Name |
|---|---|
| 7 | 0 (reserved for future use) |
| 6 | 0 (reserved for future use) |
| 5 | 0 (reserved for future use) |
| 4 | 0 (reserved for future use) |
| 3 | 0 (reserved for future use) |
| 2 | clear screen on button press |
| 1 | reset bot on timeout |
| 0 | change to ready state on timeout |
This command is used to display a message to the LCD board. The maximum buffer size is larger than the maximum package size, so a full screen cannot be written with one command. Messages are stored in a buffer and the full buffer is displayed when the "last message in group" flag is 1. If the "last message in group" is not sent, the message will never be displayed
if the "clear message" flag is 0, the message buffer will be cleared and any existing timeout out will be cleared.
If the "wait on button" flag is 1, the message screen will not clear after a users presses the center button. The display will linger until something else is drawn. The timeout field is still relevant if the button press is never received.
Text will auto-wrap at end of line. \n is recognized as new line start. \r is ignored.
Payload
uint8: Options bitfield (see below)
uint8: Horizontal position to display the message at (commonly 0-19)
uint8: Vertical position to display the message at (commonly 0-3)
uint8: Timeout, in seconds. If 0, this message will left on the screen
1+N bytes: Message to write to the screen, in ASCII, terminated with a null character.
Response (0 bytes)
Options Field
| Bit | Name |
|---|---|
| 7 | 0 (reserved for future use) |
| 6 | 0 (reserved for future use) |
| 5 | 0 (reserved for future use) |
| 4 | 0 (reserved for future use) |
| 3 | 0 (reserved for future use) |
| 2 | wait for button press |
| 1 | last message in group |
| 0 | clear existing message |
Set the percent done for the current build. This value will be displayed on the Monitor screen
Payload
uint8: percent (0-100)
uint8: 0 (reserved for future use) (reserved for future use)
Response (0 bytes)
Play predefined songs on the piezo buzzer
Payload
uint8: songID: select from a predefined list of songs
Response (0 bytes)
song ID 0: error tone with 4 cycles
song ID 1: done tone
song ID 2: error tone with 2 cycles
Calls a factory reset on the eeprom. Resets all values to their "factory" settings. A soft reset of the board is also called.
This function resets all eeprom values to defaults except those that are considered "Factory" settings. Factory settings are:
Toolhead Calibration Settings
Axis Inversion Settings
Tool Count (single or dual)
These settings will not be cleared by reset to Factory. A full eeprom reset must be called to clear these settings.
Payload
uint8: 0 (reserved for future use)
Response (0 bytes)
Tells the motherboard that a build is starting. This allows the motherboard to be state aware and to display and track build statistics. Builds that do not include this command will not have the full mightyboard feature set enabled.
Payload
uint32: 0 (reserved for future use)
1+N bytes: Name of the build, in ASCII, null terminated
Response (0 bytes)
Tells the motherboard that a build has been completed or aborted.
Payload (1 byte)
uint8: 0 (reserved for future use)
Response (0 bytes)
This queues an absolute point to move to.
Payload
int32: X coordinate, in steps
int32: Y coordinate, in steps
int32: Z coordinate, in steps
int32: A coordinate, in steps
int32: B coordinate, in steps
uint32: DDA Feedrate, in steps/s
uint8: Axes bitfield to specify which axes are relative. Any axis with a bit set should make a relative movement.
float (single precision, 32 bit): mm distance for this move. normal of XYZ if any of these axes are active, and AB for extruder only moves
uint16: feedrate in mm/s, multiplied by 64 to assist fixed point calculation on the bot
Response (0 bytes)
Used at the start of a build to tell the bot the active x3g version. The bot can use this information to provide feedback on compatibility to the user.
Payload
uint8: x3g version high byte
uint8: x3g version low byte
uint8: not implemented
uint32: not implemented
uint16: bot type: PID for the intended bot is sent
| Bot Type | PID |
|---|---|
| Replicator | 0xD314 |
| Repliator 2 | 0xB015 |
Response (0 bytes)
This command allows the host and firmware to exchange version numbers. It also allows for automated discovery of the firmware. Version numbers will always be stored as a single number, Arduino / Processing style.
Payload
uint16: Host Version
Response
uint16: Firmware Version
This returns the last recorded temperature of the toolhead. It's important for speed purposes that it does not actually trigger a temperature reading, but rather returns the last reading. The tool firmware should be constantly monitoring its temperature and keeping track of the latest readings.
Payload (0 bytes)
Response
int16: Current temperature, in Celsius
Payload (0 bytes)
Response
uint32: Duration of each rotation, in microseconds
Query the tool to determine if it has reached target temperature. Note that this only queries the toolhead, not the build platform.
Payload (0 bytes)
Response
uint8: 1 if the tool is ready, 0 otherwise.
Read the specified number of bytes from the given offset in the EEPROM, and return them in a response packet. The maximum read size is 31 bytes.
Payload
uint16: EEPROM memory offset to begin reading from
uint8: Number of bytes to read, N.
Response
N bytes: Data read from the EEPROM
Write the given bytes to the EEPROM, starting at the given offset.
Payload
uint16: EEPROM memory offset to begin writing to
uint8: Number of bytes to write
N bytes: Data to write to EEPROM
Response
uint8: Number of bytes successfully written to the EEPROM
This returns the last recorded temperature of the build platform. It's important for speed purposes that it does not actually trigger a temperature reading, but rather returns the last reading. The tool firmware should be constantly monitoring its temperature and keeping track of the latest readings.
Payload (0 bytes)
Response
int16: Current temperature, in Celsius
This returns the target temperature (setpoint) of the toolhead.
Payload (0 bytes)
Response
int16: Target temperature, in Celsius
This returns the target temperature (setpoint) of the build platform.
Payload (0 bytes)
Response
int16: Target temperature, in Celsius
Query the build platform to determine if it has reached target temperature. Note that this only queries the build platform, not the toolhead.
Payload (0 bytes)
Response
uint8: 1 if the tool is ready, 0 otherwise.
Retrieve some status information from the tool
Payload (0 bytes)
Response
uint8: Bitfield containing status information (see below)
DEPRECATED BITFIELD TABLE
| Bit | Name | Details |
|---|---|---|
| 7 | EXTRUDER_ERROR | An error was detected with the extruder heater (if the tool supports one). The extruder heater will fail if an error is detected with the sensor (thermocouple) or if the temperature reading appears to be unreasonable. |
| 6 | PLATFORM_ERROR | An error was detected with the platform heater (if the tool supports one). The platform heater will fail if an error is detected with the sensor (thermocouple) or if the temperature reading appears to be unreasonable. |
| 5 | WDRF *Deprecated* | Watchdog reset flag was set at restart |
| 4 | BORF *Deprecated* | Brownout reset flag was set at restart |
| 3 | EXTRF *Deprecated* | External reset flag was set at restart |
| 2 | PORF *Deprecated* | Power-on reset flag was set at restart |
| 1 | 0 (reserved for future use) | |
| 0 | EXTRUDER_READY | The extruder has reached target temperature |
NEW BITFIELD TABLE
| Bit | Name | Details |
|---|---|---|
| 7 | EXTRUDER_ERROR | An error was detected with the extruder heater (if the tool supports one). The extruder heater will fail if an error is detected with the sensor (thermocouple) or if the temperature reading appears to be unreasonable. |
| 6 | PLATFORM_ERROR | An error was detected with the platform heater (if the tool supports one). The platform heater will fail if an error is detected with the sensor (thermocouple) or if the temperature reading appears to be unreasonable. |
| 5 | 0 (reserved for future use)> | |
| 4 | Temperature Dropping | Heater reached temperature but temperature subsequently dropped 30 degrees below target temp. |
| 3 | Not Heating | Heater is not heating up as expected, flagged if improper after heating for 40 seconds. |
| 2 | Software Cutoff | Temperature was recorded above maximum allowable. Heater shutdown for safety. |
| 1 | Not Plugged In | The tool or platform is not plugged in. |
| 0 | EXTRUDER_READY | The extruder has reached target temperature |
Retrieve the state variables of the PID controller. This is intended for tuning the PID constants.
Payload (0 bytes)
Response
int16: Extruder heater error term
int16: Extruder heater delta term
int16: Extruder heater last output
int16: Platform heater error term
int16: Platform heater delta term
int16: Platform heater last output
Initialization resets the toolhead and all processes it controls to the boot state. some examples of processes that will be reset are:
* Resetting target temperatures to 0
* Turning off all outputs (fan, motor, etc)
* Detaching all servo devices
* Resetting motor speed to 0
Payload (0 bytes)
Response (0 bytes)
This sets the desired temperature for the heating element. The tool firmware will then attempt to maintain this temperature as closely as possible.
Payload
int16: Desired target temperature, in Celsius
Response (0 bytes)
This sets the motor speed as an RPM value, but does not enable/disable it.
Payload
uint32: Duration of each rotation, in microseconds
Response (0 bytes)
This command can be used to turn the motor on or off. The motor direction must be specified when enabling the motor.
Payload
uint8: Bitfield codifying the command (see below)
Response (0 bytes)
| Bit | Name | Details |
|---|---|---|
| 7 | 0 (reserved for future use) | |
| 6 | 0 (reserved for future use) | |
| 5 | 0 (reserved for future use) | |
| 4 | 0 (reserved for future use) | |
| 3 | 0 (reserved for future use) | |
| 2 | 0 (reserved for future use) | |
| 1 | DIR | If set, motor should be turned in a clockwise direciton. Otherwise, it should be turned in a counterclockwise direction |
| 0 | ENABLE | If set, enable the motor. If unset, disable the motor |
Turn the fan output on or off. Note that the extruder fan does not turn on until a temperature threshold is reached (currently set to 50C).
Payload
uint8: 1 to enable, 0 to disable.
Response (0 bytes)
Turn the extra output attached to a toolhead on or off
Payload
uint8: 1 to enable, 0 to disable.
Response (0 bytes)
Set the position of a servo connected to the first servo output.
Payload
uint8: Desired angle, from 0 - 180
Response (0 bytes)
This function is inteded to be called infrequently by the end user in order to make build-time adjustments during a print.
Payload (0 bytes)
Response (0 bytes)
This function is intended to be used to terminate a print during printing. Disables any engaged heaters and motors.
Payload (0 bytes)
Response (0 bytes)
This sets the desired temperature for the build platform. The tool firmware will then attempt to maintain this temperature as closely as possible.
Payload
int16: Desired target temperature, in Celsius
Response (0 bytes)