<commit_before># S3G protocol (formerly RepRap Generation 3 Protocol Specification)

## Overview

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](http://github.com/makerbot/s3g), 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.

## Definitions

Here is some vocabulary, that should be used when talking about the protocol:

<table>
<tr>
 <th>Name</th>
 <th>Definition</th>
</tr>
<tr>
 <td>PC</td>
 <td>A computer, that is connected to the Host over the host network.</td>
</tr>
<tr>
 <td>Host</td>
 <td>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.</td>
</tr>
<tr>
 <td>Tool</td>
 <td>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.</td>
</tr>
<tr>
 <td>Host network</td>
 <td>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).</td>
</tr>
<tr>
 <td>Tool network</td>
 <td>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).</td>
</tr>
<tr>
 <td>Tool ID</td>
 <td>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.</td>
</tr>
<tr>
 <td>Query Command</td>
 <td>A query command is a command that should be evaluated and acknowledged immediately. They are used for things such as setting or reading temperatures.</td>
</tr>
<tr>
 <td>Buffered Command</td>
 <td>A buffered command should be acknowledge immediately, but the Host or Tool may choose to store in a buffer for later execution. These should be used for commands that could take a long time to execute, such as motion commands.
</tr>
</table>

# Architecture

An s3g system looks like this:

![block diagram of system architecture](https://github.com/makerbot/s3g/raw/master/doc/SystemArchitecture.png)

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._

## Normal communication

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:

![host command success](https://github.com/makerbot/s3g/raw/master/doc/HostCommandSuccess.png)

Communication over the tool network works similarly:

![tool command success](https://github.com/makerbot/s3g/raw/master/doc/ToolCommandSuccess.png)

Finally, a PC may communicate with a Tool by forwarding a packet through the Host:

![host tool command success](https://github.com/makerbot/s3g/raw/master/doc/HostToolCommandSuccess.png)

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._

## Handling Errors

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.

If a packet has timed out, the host or board should treat the entire packet transaction as void.  It should:

* Return its packet reception state machine to a ready state.
* Presume that no action has been taken on the transaction
* Attempt to resend the packet, if it was a host packet.

# Implementations

Firmware repositories:

* For Gen3 and Gen4 electronics (Cupcake, Thing-O-Matic, Reprap): [G3Firmware](http://github.com/makerbot/G3Firmware)
* For Mightyboard (Replicator): [MightyBoardFirmware](http://github.com/makerbot/MightyBoardFirmware)

Host software:

* [ReplicatorG](http://github.com/makerbot/ReplicatorG)
* [pyS3g](http://github.com/makerbot/s3g)

# Packet formats

## Packet Structure
All packets have the following structure:

<table>
<tr>
 <th>Index</th>
 <th>Name</th>
 <th>Details</th>
</tr>
<tr>
 <td>0</td>
 <td>Start Byte</td>
 <td>This byte always has the value 0xD5 and is used to ensure synchronization.</td>
</tr>
<tr>
 <td>1</td>
 <td>Length</td>
 <td>The length of the payload, in bytes</td>
</tr>
<tr>
 <td>2..(1+N)</td>
 <td>Payload</td>
 <td>The packet payload. The payload can be N bytes long (TODO: maximum length?).</td>
</tr>
<tr>
 <td>2+N</td>
 <td>CRC</td>
 <td>The [8-bit iButton/Maxim CRC](http://www.maxim-ic.com/app-notes/index.mvp/id/27) of the payload</td>
</tr>
</table>

## Host Network Payload Structure
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:

<table>
<tr>
 <th>Index</th>
 <th>Name</th>
 <th>Details</th>
</tr>
<tr>
 <td>0</td>
 <td>Host Command Code</td>
 <td>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.</td><commit_msg>Add descriptions of error conditions to s3g protocol.<commit_after># S3G protocol (formerly RepRap Generation 3 Protocol Specification)

## Overview

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](http://github.com/makerbot/s3g), 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.

## Implementations of this protocol

Firmware repositories:

* For Gen3 and Gen4 electronics (Cupcake, Thing-O-Matic, Reprap): [G3Firmware](http://github.com/makerbot/G3Firmware)
* For Mightyboard (Replicator): [MightyBoardFirmware](http://github.com/makerbot/MightyBoardFirmware)

Host software:

* [ReplicatorG](http://github.com/makerbot/ReplicatorG)
* [pyS3g](http://github.com/makerbot/s3g)

## Definitions

Here is some vocabulary, that should be used when talking about the protocol:

<table>
<tr>
 <th>Name</th>
 <th>Definition</th>
</tr>
<tr>
 <td>PC</td>
 <td>A computer, that is connected to the Host over the host network.</td>
</tr>
<tr>
 <td>Host</td>
 <td>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.</td>
</tr>
<tr>
 <td>Tool</td>
 <td>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.</td>
</tr>
<tr>
 <td>Host network</td>
 <td>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).</td>
</tr>
<tr>
 <td>Tool network</td>
 <td>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).</td>
</tr>
<tr>
 <td>Tool ID</td>
 <td>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.</td>
</tr>
<tr>
 <td>Query Command</td>
 <td>A query command is a command that should be evaluated and acknowledged immediately. They are used for things such as setting or reading temperatures.</td>
</tr>
<tr>
 <td>Buffered Command</td>
 <td>A buffered command should be acknowledge immediately, but the Host or Tool may choose to store in a buffer for later execution. These should be used for commands that could take a long time to execute, such as motion commands.
</tr>
</table>

# Architecture

An s3g system looks like this:

![block diagram of system architecture](https://github.com/makerbot/s3g/raw/master/doc/SystemArchitecture.png)

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._

## Normal communication

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:

![host command success](https://github.com/makerbot/s3g/raw/master/doc/HostCommandSuccess.png)

Communication over the tool network works similarly:

![tool command success](https://github.com/makerbot/s3g/raw/master/doc/ToolCommandSuccess.png)

Finally, a PC may communicate with a Tool by forwarding a packet through the Host:

![host tool command success](https://github.com/makerbot/s3g/raw/master/doc/HostToolCommandSuccess.png)

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._

## Handling Errors

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.

If the master sends a packet over the network and does not receive a response, then the transmission is considered a timeout and can be re-tried up to 5 times. If the master does receive a response packet but it is damaged (either due to an invalid header, length, or CRC check), then it is considered a decoder error, and can be retried. Finally, if the master receives a valid response packet, but the packets response code indicates that the slave encountered a buffer overflow or retry error, then the master should attempt retransmission of the packet.

Here is a reference implementation of a packet send state machine:

![SendCommand state machine diagram](https://github.com/makerbot/s3g/raw/master/doc/SendCommand.png)


# Packet formats

## Packet Structure
All packets have the following structure:

<table>
<tr>
 <th>Index</th>
 <th>Name</th>
 <th>Details</th>
</tr>
<tr>
 <td>0</td>
 <td>Start Byte</td>
 <td>This byte always has the value 0xD5 and is used to ensure synchronization.</td>
</tr>
<tr>
 <td>1</td>
 <td>Length</td>
 <td>The length of the payload, in bytes</td>
</tr>
<tr>
 <td>2..(1+N)</td>
 <td>Payload</td>
 <td>The packet payload. The payload can be N bytes long (TODO: maximum length?).</td>
</tr>
<tr>
 <td>2+N</td>
 <td>CRC</td>
 <td>The <a href="http://www.maxim-ic.com/app-notes/index.mvp/id/27">8-bit iButton/Maxim CRC</a> of the payload</td>
</tr>
</table>

## Host Network Payload Structure
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:

<table>
<tr>
 <th>Index</th>
 <th>Name</th>
 <th>Details</th>
</tr>
<tr>
 <td>0</td>
 <td>Host Command Code</td>
 <td>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.</td>
{'fraction_non_alphanumeric': 0.08271381689103208, 'fraction_numerical': 0.009845288326300985, 'mean_word_length': 4.473607038123167, 'pattern_counts': {'":': 0, '<': 233, '<?xml version=': 0, '>': 233, 'https://': 9, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6854831', 'n_tokens_mistral': 4327, 'n_tokens_neox': 4168, 'n_words': 2144}