Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 1667 lines (1297 sloc) 45.634 kB
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
1 # S3G protocol (formerly RepRap Generation 3 Protocol Specification)
2
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
3 ## Overview
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
4
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
5 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
6
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
7 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.
8
9 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.
10
11 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
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
12
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
13 The final portion of the document is a catalog of all of the commands that the Host and Tools can implement.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
14
040f3a9 Add descriptions of error conditions to s3g protocol.
matt.mets@makerbot.com authored
15 ## Implementations of this protocol
16
17 Firmware repositories:
18
19 * For Gen3 and Gen4 electronics (Cupcake, Thing-O-Matic, Reprap): [G3Firmware](http://github.com/makerbot/G3Firmware)
20 * For Mightyboard (Replicator): [MightyBoardFirmware](http://github.com/makerbot/MightyBoardFirmware)
21
22 Host software:
23
24 * [ReplicatorG](http://github.com/makerbot/ReplicatorG)
25 * [pyS3g](http://github.com/makerbot/s3g)
26
dc023c8 @cibomahto Update documentation.
cibomahto authored
27 ## Definitions
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
28
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
29 Here is some vocabulary that should be used when talking about the protocol:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
30
dc023c8 @cibomahto Update documentation.
cibomahto authored
31 <table>
32 <tr>
33 <th>Name</th>
34 <th>Definition</th>
35 </tr>
36 <tr>
37 <td>PC</td>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
38 <td>A computer, that is connected to the Host over the host network.</td>
dc023c8 @cibomahto Update documentation.
cibomahto authored
39 </tr>
40 <tr>
41 <td>Host</td>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
42 <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>
dc023c8 @cibomahto Update documentation.
cibomahto authored
43 </tr>
44 <tr>
45 <td>Tool</td>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
46 <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>
dc023c8 @cibomahto Update documentation.
cibomahto authored
47 </tr>
48 <tr>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
49 <td>Host network</td>
50 <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>
dc023c8 @cibomahto Update documentation.
cibomahto authored
51 </tr>
52 <tr>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
53 <td>Tool network</td>
54 <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>
dc023c8 @cibomahto Update documentation.
cibomahto authored
55 </tr>
56 <tr>
57 <td>Tool ID</td>
58 <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>
59 </tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
60 <tr>
61 <td>Query Command</td>
330d582 add normal packet transmit diagram
matt.mets@makerbot.com authored
62 <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>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
63 </tr>
64 <tr>
65 <td>Buffered Command</td>
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
66 <td>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.
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
67 </tr>
dc023c8 @cibomahto Update documentation.
cibomahto authored
68 </table>
69
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
70 # Architecture
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
71
dc023c8 @cibomahto Update documentation.
cibomahto authored
72 An s3g system looks like this:
73
04cf9cb @cibomahto Attempt to get image to show up correctly in github.
cibomahto authored
74 ![block diagram of system architecture](https://github.com/makerbot/s3g/raw/master/doc/SystemArchitecture.png)
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
75
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
76 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).
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
77
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
78 _Note: On the MightyBoard, the tool bus is emulated in software in order to be backwards compatible._
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
79
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
80 ## Normal communication
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
81
330d582 add normal packet transmit diagram
matt.mets@makerbot.com authored
82 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
83
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
84 This is what a normal communication over the host network looks like:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
85
330d582 add normal packet transmit diagram
matt.mets@makerbot.com authored
86 ![host command success](https://github.com/makerbot/s3g/raw/master/doc/HostCommandSuccess.png)
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
87
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
88 Communication over the tool network works similarly:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
89
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
90 ![tool command success](https://github.com/makerbot/s3g/raw/master/doc/ToolCommandSuccess.png)
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
91
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
92 Finally, a PC may communicate with a Tool by forwarding a packet through the Host:
330d582 add normal packet transmit diagram
matt.mets@makerbot.com authored
93
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
94 ![host tool command success](https://github.com/makerbot/s3g/raw/master/doc/HostToolCommandSuccess.png)
95
96 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._
97
98 ## Handling Errors
99
040f3a9 Add descriptions of error conditions to s3g protocol.
matt.mets@makerbot.com authored
100 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
101
fa06f58 @dgs3 Updated docs, moved UnknownResponse to ProtocolError.
dgs3 authored
102 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.
dc023c8 @cibomahto Update documentation.
cibomahto authored
103
040f3a9 Add descriptions of error conditions to s3g protocol.
matt.mets@makerbot.com authored
104 Here is a reference implementation of a packet send state machine:
dc023c8 @cibomahto Update documentation.
cibomahto authored
105
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
106 ![send_command state machine diagram](https://github.com/makerbot/s3g/raw/master/doc/send_command.png)
dc023c8 @cibomahto Update documentation.
cibomahto authored
107
108
109 # Packet formats
110
111 ## Packet Structure
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
112 All packets have the following structure:
113
114 <table>
115 <tr>
116 <th>Index</th>
117 <th>Name</th>
118 <th>Details</th>
119 </tr>
120 <tr>
121 <td>0</td>
122 <td>Start Byte</td>
123 <td>This byte always has the value 0xD5 and is used to ensure synchronization.</td>
124 </tr>
125 <tr>
126 <td>1</td>
127 <td>Length</td>
dee45aa @cibomahto Add read/write EEPROM commands, for host and slave targets. Add get v…
cibomahto authored
128 <td>The length of the payload, in bytes</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
129 </tr>
130 <tr>
131 <td>2..(1+N)</td>
132 <td>Payload</td>
4fc2731 @cibomahto Formatting fixes.
cibomahto authored
133 <td>The packet payload. The payload can be N bytes long (TODO: maximum length?).</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
134 </tr>
135 <tr>
136 <td>2+N</td>
137 <td>CRC</td>
040f3a9 Add descriptions of error conditions to s3g protocol.
matt.mets@makerbot.com authored
138 <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>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
139 </tr>
140 </table>
141
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
142 ## Host Network Payload Structure
143 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:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
144
145 <table>
146 <tr>
147 <th>Index</th>
148 <th>Name</th>
149 <th>Details</th>
150 </tr>
151 <tr>
152 <td>0</td>
153 <td>Host Command Code</td>
154 <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>
155 </tr>
156 <tr>
157 <td>1..(1+N)</td>
158 <td>Arguments</td>
159 <td>(optional) Command arguments, such as a position to move to, or a flag to set. Command specific.</td>
160 </tr>
161 </table>
162
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
163 ## Tool Network Payload Structure
164 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:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
165
166 <table>
167 <tr>
168 <th>Index</th>
169 <th>Name</th>
170 <th>Details</th>
171 </tr>
172 <tr>
173 <td>0</td>
dc023c8 @cibomahto Update documentation.
cibomahto authored
174 <td>Tool ID</td>
175 <td>The ID of the tool device being addressed (see below)</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
176 </tr>
177 <tr>
178 <td>1</td>
179 <td>Command Code</td>
dc023c8 @cibomahto Update documentation.
cibomahto authored
180 <td>A byte representing the command to be executed. Unlike host commands, tool command values have no special meaning.</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
181 </tr>
182 <tr>
183 <td>2..(2+N)</td>
184 <td>Arguments</td>
185 <td>(Optional) Command arguments, such as a position to move to, or a flag to set. Command specific.</td>
186 </tr>
187 </table>
188
dc023c8 @cibomahto Update documentation.
cibomahto authored
189 A note about Tool IDs:
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
190
dc023c8 @cibomahto Update documentation.
cibomahto authored
191 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
192
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
193 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.
194
195 _Note: Before firmware version 2.92, the broadcast address was 255._
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
196
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
197 ## Response Packet Structure (both Host and Tool Networks)
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
198 The response payload contains the response to a single command:
199
200 <table>
201 <tr>
202 <th>Index</th>
203 <th>Name</th>
204 <th>Details</th>
205 </tr>
206 <tr>
207 <td>0</td>
208 <td>Response Code</td>
209 <td>A byte representing the completion status of the command (see below)
210 </tr>
211 <tr>
212 <td>1..(1+N)</td>
213 <td>Arguments</td>
214 <td>(Optional) Response arguments, such as current machine position or toolhead temperature. Command specific.</td>
215 </tr>
216 </table>
217
218 Response code values can be as follows:
219
220 <table>
221 <tr>
222 <th>Response Code</th>
223 <th>Details</th>
224 <th>Can be retried?</th>
225 </tr>
226 <tr>
227 <td>0x80</td>
0cf7264 @aleonard updated bot error response codes
aleonard authored
228 <td>Generic Packet error, packet discarded</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
229 <td>Yes</td>
230 </tr>
231 <tr>
232 <td>0x81</td>
233 <td>Success</td>
234 <td>No</td>
235 </tr>
236 <tr>
237 <td>0x82</td>
238 <td>Action buffer overflow, entire packet discarded</td>
239 <td>No</td>
240 </tr>
241 <tr>
242 <td>0x83</td>
243 <td>CRC mismatch, packet discarded.</td>
244 <td>Yes</td>
245 </tr>
246 <tr>
247 <td>0x84</td>
0cf7264 @aleonard updated bot error response codes
aleonard authored
248 <td>Query packet too big, packet discarded </td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
249 <td>No</td>
250 </tr>
251 <tr>
252 <td>0x85</td>
253 <td>Command not supported/recognized</td>
254 <td>No</td>
255 </tr>
256 <tr>
257 <td>0x87</td>
258 <td>Downstream timeout</td>
486f76b @cibomahto Rework tool response code handling, update docs, not fully tested.
cibomahto authored
259 <td>No</td>
260 </tr>
261 <tr>
262 <td>0x88</td>
263 <td>Tool lock timeout</td>
264 <td>Yes</td>
265 </tr>
266 <tr>
267 <td>0x89</td>
268 <td>Cancel build</td>
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
269 <td>Yes</td>
270 </tr>
1faba7b @aleonard beginning to update docs
aleonard authored
271 <tr>
272 <td>0x8A</td>
273 <td>Bot is Building from SD</td>
274 <td>No</td>
275 </tr>
276 <tr>
277 <td>0x8B</td>
278 <td>Bot is shutdown due to Overheat</td>
279 <td>No</td>
280 </tr>
0cf7264 @aleonard updated bot error response codes
aleonard authored
281 <tr>
282 <td>0x8C</td>
283 <td>Packet timeout error, packet discarded</td>
284 <td>Yes</td>
285 </tr>
286
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
287 </table>
288
e26df9b @cibomahto Documentation cleanup
cibomahto authored
289 _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_
290
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
291 # Data formats
292
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
293 ## Integer
294 Integers represent numbers. All integers are in little endian format.
295
296 <table>
297 <tr>
298 <th>Type</th>
299 <th>Size</th>
300 <th>Range</th>
301 </tr>
302 <tr>
303 <td>uint8</td>
304 <td>1 byte</td>
305 <td>0 to 255</td>
306 </tr>
307 <tr>
308 <td>uint16</td>
309 <td>2 bytes</td>
310 <td>0 to 65535</td>
311 </tr>
312 <tr>
313 <td>int16</td>
314 <td>2 bytes</td>
315 <td>-32768 to 32767</td>
316 </tr>
317 <tr>
318 <td>uint32</td>
319 <td>4 bytes</td>
320 <td>0 to 4294967296</td>
321 </tr>
322 <tr>
323 <td>int32</td>
324 <td>4 bytes</td>
325 <td>-−2147483648 to 2147483647</td>
326 </tr>
327 </table>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
328
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
329 ## Axes bitfield
330 An axes bitfield structure is used to represent a selection of axes.
331
332 <table>
333 <tr>
334 <th>Bit</th>
335 <th>Name</th>
336 </tr>
337 <tr>
338 <td>7</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
339 <td>0 (reserved for future use)</td>
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
340 </tr>
341 <tr>
342 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
343 <td>0 (reserved for future use)</td>
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
344 </tr>
345 <tr>
346 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
347 <td>0 (reserved for future use)</td>
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
348 </tr>
349 <tr>
350 <td>4</td>
351 <td>B axis</td>
352 </tr>
353 <tr>
354 <td>3</td>
355 <td>A axis</td>
356 </tr>
357 <tr>
358 <td>2</td>
359 <td>Z axis</td>
360 </tr>
361 <tr>
362 <td>1</td>
363 <td>Y axis</td>
364 </tr>
365 <tr>
366 <td>0</td>
367 <td>X axis</td>
368 </tr>
369 </table>
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
370
371 ## SD Response codes
372 <table>
373 <tr>
374 <th>Response Code</th>
375 <th>Details</th>
376 </tr>
377 <tr>
378 <td>0x00</td>
379 <td>Operation successful</td>
380 </tr>
381 <tr>
382 <td>0x01</td>
383 <td>SD Card not present</td>
384 </tr>
385 <tr>
386 <td>0x02</td>
387 <td>SD Card initialization failed</td>
388 </tr>
389 <tr>
390 <td>0x03</td>
391 <td>Partition table could not be read</td>
392 </tr>
393 <tr>
394 <td>0x04</td>
395 <td>Filesystem could not be opened</td>
396 </tr>
397 <tr>
398 <td>0x05</td>
399 <td>Root directory could not be opened</td>
400 </tr>
401 <tr>
402 <td>0x06</td>
403 <td>SD Card is locked</td>
404 </tr>
405 </table>
406
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
407 # Host Query Commands
408
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
409 ## 00 - Get version: Query firmware for version information
076fa69 @aleonard get_advanced_version and get_build_stats commands
aleonard authored
410 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
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
411
412 Payload
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
413
414 uint16: Host Version
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
415
416 Response
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
417
418 uint16: Firmware Version
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
419
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
420 ## 01 - init: Initialize firmware to boot state
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
421 Initialization consists of:
422
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
423 * Resetting all axes positions to 0
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
424 * Clearing command buffer
425
426 Payload (0 bytes)
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
427
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
428 Response (0 bytes)
429
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
430 ## 02 - Get available buffer size: Determine how much free memory is available for buffering commands
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
431 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
432
433 Payload (0 bytes)
434
435 Response
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
436
437 uint32: Number of bytes availabe in the command buffer
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
438
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
439 ## 03 - Clear buffer: Empty the command buffer
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
440 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.
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
441
442 Payload (0 bytes)
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
443
935ff2f @cibomahto First part of the s3g protocol, converted to markdown.
cibomahto authored
444 Response (0 bytes)
445
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
446 ## 07 - Abort immediately: Stop machine, shut down job permanently
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
447 This function is intended to be used to terminate a print during printing. Disables steppers, heaters, and any toolheads, and clears all command buffers.
448
449 Payload (0 bytes)
450
451 Response (0 bytes)
452
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
453 ## 08 - pause/resume: Halt execution temporarily
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
454 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
455
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
456 On pause, it stops all stepper movement and halts extrusion.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
457 On Resume, it restarts extrusion and resumes movement.
458
459 Payload (0 bytes)
460
461 Response (0 bytes)
462
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
463 ## 10 - Tool query: Query a tool for information
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
464 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?
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
465
466 Payload
467
dc023c8 @cibomahto Update documentation.
cibomahto authored
468 uint8: Tool index
469 0-N bytes: Payload containing the query command to send to the tool.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
470
471 Response
472
dc023c8 @cibomahto Update documentation.
cibomahto authored
473 0-N bytes: Response payload from the tool query command, if any.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
474
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
475 ## 11 - Is finished: See if the machine is currently busy
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
476 This command queries the machine to determine if it currently executing commands from a command queue.
477
478 Payload (0 bytes)
479
480 Response
481
482 uint8: 0 if busy, 1 if finished.
483
484 ## 12 - Read from EEPROM
dee45aa @cibomahto Add read/write EEPROM commands, for host and slave targets. Add get v…
cibomahto authored
485 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
486
487 Payload
488
489 uint16: EEPROM memory offset to begin reading from
490 uint8: Number of bytes to read, N.
491
492 Response
493
494 N bytes: Data read from the EEPROM
495
496 ## 13 - Write to EEPROM
497 Write the given bytes to the EEPROM, starting at the given offset.
498
499 Payload
500
501 uint16: EEPROM memory offset to begin writing to
502 uint8: Number of bytes to write
503 N bytes: Data to write to EEPROM
504
505 Response
506
507 uint8: Number of bytes successfully written to the EEPROM
508
509 ## 14 - Capture to file
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
510 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
511
512 Payload
513
514 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.
515
516 Response
517
518 uint8: SD response code
519
520 ## 15 - End capture to file
521 Complete an ongoing file capture by closing the file, and return to regular operation.
522
523 Payload (0 bytes)
524
525 Response
526
527 uint32: Number of bytes captured to file.
528
529 ## 16 - Play back capture
530 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.
531
532 Payload
533
534 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.
535
536 Response
537
538 uint8: SD response code
539
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
540 ## 17 - reset
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
541 Call a soft reset. This calls all reset functions on the bot. Same as abort.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
542
543 Payload (0 bytes)
544
545 Response (0 bytes)
546
547 ## 18 - Get next filename
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
548 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
549 If all the filenames have been retrieved, an empty string is returned.
550
551 Payload
552
553 uint8: 0 if file listing should continue, 1 to restart listing.
554
555 Response
556
557 uint8: SD Response code
558 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.
559
560 ## 20 - Get build name
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
561 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
562
563 Payload (0 bytes)
564
565 Response
566
567 1+N bytes: A null terminated string representing the filename of the current build.
568
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
569 ## 21 - Get extended position: Get the current
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
570 Retrieve the curent position of all axes that the machine supports. Unsupported axes will return 0
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
571
572 Payload (0 bytes)
573
574 Response
575
a3d8b17 @cibomahto Update doc/s3g_protocol.markdown
cibomahto authored
576 int32: X position, in steps
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
577 int32: Y position, in steps
578 int32: Z position, in steps
579 int32: A position, in steps
580 int32: B position, in steps
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
581 uint16: bitfield corresponding to the endstop status:
582
583 <table>
584 <tr>
585 <th>Bit</th>
586 <th>Name</th>
587 </tr>
588 <tr>
589 <td>15</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
590 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
591 </tr>
592 <tr>
593 <td>14</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
594 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
595 </tr>
596 <tr>
597 <td>13</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
598 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
599 </tr>
600 <tr>
601 <td>12</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
602 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
603 </tr>
604 <tr>
605 <td>11</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
606 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
607 </tr>
608 <tr>
609 <td>10</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
610 <td>0 (reserved for future use)</td>
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
611 </tr>
612 <tr>
613 <td>9</td>
614 <td>B min switch pressed</td>
615 </tr>
616 <tr>
617 <td>8</td>
618 <td>B max switch pressed</td>
619 </tr>
620 <tr>
621 <td>7</td>
622 <td>A max switch pressed</td>
623 </tr>
624 <tr>
625 <td>6</td>
626 <td>A min switch pressed</td>
627 </tr>
628 <tr>
629 <td>5</td>
630 <td>Z max switch pressed</td>
631 </tr>
632 <tr>
633 <td>4</td>
634 <td>Z min switch pressed</td>
635 </tr>
636 <tr>
637 <td>3</td>
638 <td>Y max switch pressed</td>
639 </tr>
640 <tr>
641 <td>2</td>
642 <td>Y min switch pressed</td>
643 </tr>
644 <tr>
645 <td>1</td>
646 <td>X max switch pressed</td>
647 </tr>
648 <tr>
649 <td>0</td>
650 <td>X min switch pressed</td>
651 </tr>
652 </table>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
653
654 ## 22 - Extended stop: Stop a subset of systems
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
655 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
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
656
657 Payload
658
659 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.
660
661 Response
662
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
663 int8: 0 (reserved for future use)
664
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
665
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
666 ## 23 - Get motherboard status
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
667 Retrieve some status information from the motherboard
668
669 Payload (0 bytes)
670
671 Response
672
673 uint8: Bitfield containing status information (see below)
674
675 <table>
676 <tr>
677 <th>Bit</th>
678 <th>Name</th>
679 <th>Details</th>
680 </tr>
681 <tr>
682 <td>7</td>
683 <td>POWER_ERRPR</td>
684 <td>An error was detected with the system power. For Gen4 electronics, this means ATX_5V is not present</td>
685 </tr>
686 <tr>
687 <td>6</td>
1d13273 @aleonard updated tool and motherboard status commmands, tests and documentation
aleonard authored
688 <td>HEAT_SHUTDOWN</td>
e35860e @aleonard doc update
aleonard authored
689 <td>Heaters were shutdown after 30 minutes of inactivity</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
690 </tr>
691 <tr>
692 <td>5</td>
372aca0 @aleonard add another status byte to s3gProtocol
aleonard authored
693 <td>BUILD_CANCELLING</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
694 <td>Watchdog reset flag was set at restart</td>
695 </tr>
696 <tr>
697 <td>4</td>
7d3bf26 @aleonard updated motherboard status command doc and eeprom map for firmwarev6.1
aleonard authored
698 <td>WAIT_FOR_BUTTON</td>
699 <td>BotUI is waiting for button push by user</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
700 </tr>
701 <tr>
702 <td>3</td>
b24164d @aleonard minor document updates
aleonard authored
703 <td>ONBOARD_PROCESS</td>
704 <td>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)</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
705 </tr>
706 <tr>
707 <td>2</td>
a49ff19 @aleonard update motherboard status query
aleonard authored
708 <td>ONBOARD_SCRIPT</td>
709 <td>Bot is running an onboard script</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
710 </tr>
711 <tr>
712 <td>1</td>
a49ff19 @aleonard update motherboard status query
aleonard authored
713 <td>MANUAL_MODE</td>
714 <td>Manual move mode active</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
715 </tr>
716 <tr>
717 <td>0</td>
a49ff19 @aleonard update motherboard status query
aleonard authored
718 <td>PREHEAT</td>
719 <td>Onboard preheat active</td>
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
720 </tr>
721 </table>
722
076fa69 @aleonard get_advanced_version and get_build_stats commands
aleonard authored
723 ## 24 - Get build statistics
1faba7b @aleonard beginning to update docs
aleonard authored
724 Gathers statistics about the currently building print if a build is active, or the last print if there is no active build
725
076fa69 @aleonard get_advanced_version and get_build_stats commands
aleonard authored
726 Payload (1 byte)
1faba7b @aleonard beginning to update docs
aleonard authored
727
728 Response
729
730 uint8 : Build State (paused, running, finished_normally, canceled, none)
731 uint8 : Hours elapsed on print
732 uint8 : Minutes elapsed on print (add hours for total time)
733 uint32: Line Number (number of commands processed)
734 uint32: Reserved for Future Use
735
e35860e @aleonard doc update
aleonard authored
736 Build State Return Values are as follows
737 <table>
738 <tr>
739 <td>0</td>
740 <td>no build initialized (boot up state)</td>
741 </tr>
742 <tr>
743 <td>1</td>
744 <td>build running</td>
745 </tr>
746 <tr>
747 <td>2</td>
748 <td>build finished normally</td>
749 </tr>
750 <tr>
751 <td>3</td>
752 <td>build paused</td>
753 </tr>
754 <tr>
755 <td>4</td>
756 <td>build cancelled</td>
757 </tr>
b24164d @aleonard minor document updates
aleonard authored
758 <tr>
759 <td>5</td>
760 <td>build sleeping</td>
761 </tr>
e35860e @aleonard doc update
aleonard authored
762 </table>
763
03959cf @aleonard update fileReaderContants.py and tool communication stats number
aleonard authored
764 ## 25 - Get communication statistics
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
765 Gathers statistics about communication over the tool network. This was intended for use while troubleshooting Gen3/4 machines.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
766
767 Payload (0 bytes)
768
769 Response
770
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
771 uint32: Packets received from the host network
772 uint32: Packets sent over the tool network
773 uint32: Number of packets sent over the tool network that were not repsonded to
774 uint32: Number of packet retries on the tool network
775 uint32: Number of bytes received over the tool network that were discarded as noise
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
776
4c1df84 @aleonard updating protocol doc
aleonard authored
777 ## 27 - Get advanced version number
778 returns the main version numbers along with an internal version number
779
076fa69 @aleonard get_advanced_version and get_build_stats commands
aleonard authored
780 Payload
781
782 uint16: Host Version
4c1df84 @aleonard updating protocol doc
aleonard authored
783
784 Response
785
786 uint16_t Firmware Version
787 uint16_t Internal Version
53673ef @aleonard update advanced version command documentation
aleonard authored
788 uint8_t Software Variant, see software variant table for valid IDs
d51f8dd @aleonard Software Variant support added to advanced version command, s3g,x3g d…
aleonard authored
789 uint8_t Reserved for future use
b0f4e81 @aleonard protocol doc updated
aleonard authored
790 uint16_t Reserved for future use
4c1df84 @aleonard updating protocol doc
aleonard authored
791
53673ef @aleonard update advanced version command documentation
aleonard authored
792 Sofware Variant IDs are as follows
793 <table>
794 <tr>
795 <td>0x00</td>
796 <td>unknown</td>
797 </tr>
798 <tr>
799 <td>0x01</td>
800 <td>MBI Official</td>
801 </tr>
802 <tr>
803 <td>0x02-0x7F</td>
804 <td>reserved</td>
805 </tr>
806 <tr>
807 <td>0x80</td>
808 <td>Sailfish</td>
809 </tr>
810 <tr>
811 <td>0x81-0xBF</td>
812 <td>unassigned variants</td>
813 </tr>
814 <tr>
815 <td>0xC0-0xFF</td>
816 <td>reserved</td>
817 </tr>
818 </table>
819
820
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
821 # Host Buffered Commands
822
823 ## 131 - Find axes minimums: Move specified axes in the negative direction until their limit switch is triggered.
824 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.
825
826 Payload
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
827
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
828 uint8: Axes bitfield. Axes whose bits are set will be moved.
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
829 uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
830 uint16: Timeout, in seconds.
831
a799946 Filled in blank responses for the spec
Dave Sayles authored
832 Response (0 bytes)
833
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
834 ## 132 - Find axes maximums: Move specified axes in the positive direction until their limit switch is triggered.
835 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.
836
837 Payload
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
838
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
839 uint8: Axes bitfield. Axes whose bits are set will be moved.
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
840 uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
841 uint16: Timeout, in seconds.
842
a799946 Filled in blank responses for the spec
Dave Sayles authored
843 Response (0 bytes)
844
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
845 ## 133 - delay: pause all motion for the specified time
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
846 Halt all motion for the specified amount of time.
847
848 Payload
849
4c1df84 @aleonard updating protocol doc
aleonard authored
850 uint32: delay, in milliseconds
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
851
a799946 Filled in blank responses for the spec
Dave Sayles authored
852 Response (0 bytes)
853
9c08978 @cibomahto Add Change Tool command
cibomahto authored
854 ## 134 - Change Tool
855 Instruct the host to select the given tool as active
856
857 _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._
858
859 Payload
860
861 uint8: Tool ID of the tool to switch to
862
863 Response (0 bytes)
864
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
865 ## 135 - Wait for tool ready: Wait until a tool is ready before proceeding
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
866 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
867
868 Payload
869
dc023c8 @cibomahto Update documentation.
cibomahto authored
870 uint8: Tool ID of the tool to wait for
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
871 uint16: delay between query packets sent to the tool, in ms (nominally 100 ms)
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
872 uint16: Timeout before continuing without tool ready, in seconds (nominally 1 minute)
873
a799946 Filled in blank responses for the spec
Dave Sayles authored
874 Response (0 bytes)
875
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
876 ## 136 - Tool action command: Send an action command to a tool for execution
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
877 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?
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
878
879 Payload
880
dc023c8 @cibomahto Update documentation.
cibomahto authored
881 uint8: Tool ID of the tool to query
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
882 uint8: Action command to send to the tool
883 uint8: Length of the tool command payload (N)
884 N bytes: Tool command payload, 0-? bytes.
885
a799946 Filled in blank responses for the spec
Dave Sayles authored
886 Response (0 bytes)
887
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
888 ## 137 - Enable/disable axes: Explicitly enable or disable stepper motor controllers
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
889 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.
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
890
891 Payload
892
893 uint8: Bitfield codifying the command (see below)
894
a799946 Filled in blank responses for the spec
Dave Sayles authored
895 Response (0 bytes)
896
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
897 <table>
898 <tr>
899 <th>Bit</th>
900 <th>Details</th>
901 </tr>
902 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
903 <td>7</td>
904 <td>If set to 1, enable all selected axes. Otherwise, disable all selected axes.</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
905 </tr>
906 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
907 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
908 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
909 </tr>
910 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
911 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
912 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
913 </tr>
914 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
915 <td>4</td>
916 <td>B axis select</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
917 </tr>
918 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
919 <td>3</td>
920 <td>A axis select</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
921 </tr>
922 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
923 <td>2</td>
924 <td>Z axis select</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
925 </tr>
926 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
927 <td>1</td>
928 <td>Y axis select</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
929 </tr>
930 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
931 <td>0</td>
932 <td>X axis select</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
933 </tr>
934 </table>
935
936 ## 139 - Queue extended point
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
937 This queues an absolute point to move to.
938
939 _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_
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
940
941 Payload
942
943 int32: X coordinate, in steps
944 int32: Y coordinate, in steps
945 int32: Z coordinate, in steps
946 int32: A coordinate, in steps
947 int32: B coordinate, in steps
948 uint32: Feedrate, in microseconds between steps on the max delta. (DDA)
949
a799946 Filled in blank responses for the spec
Dave Sayles authored
950 Response (0 bytes)
951
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
952 ## 140 - Set extended position
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
953 reset the current position of the axes to the given values.
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
954
955 Payload
956
957 int32: X position, in steps
958 int32: Y position, in steps
959 int32: Z position, in steps
960 int32: A position, in steps
961 int32: B position, in steps
962
a799946 Filled in blank responses for the spec
Dave Sayles authored
963 Response (0 bytes)
964
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
965 ## 141 - Wait for platform ready: Wait until a build platform is ready before proceeding
dc023c8 @cibomahto Update documentation.
cibomahto authored
966 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.
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
967
968 Payload
969
dc023c8 @cibomahto Update documentation.
cibomahto authored
970 uint8: Tool ID of the build platform to wait for
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
971 uint16: delay between query packets sent to the tool, in ms (nominally 100 ms)
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
972 uint16: Timeout before continuing without tool ready, in seconds (nominally 1 minute)
973
a799946 Filled in blank responses for the spec
Dave Sayles authored
974 Response (0 bytes)
975
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
976 ## 142 - Queue extended point, new style
977 This queues a point to move to.
978
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
979 _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._
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
980
981 Payload
982
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
983 int32: X coordinate, in steps
984 int32: Y coordinate, in steps
985 int32: Z coordinate, in steps
986 int32: A coordinate, in steps
987 int32: B coordinate, in steps
988 uint32: Duration of the movement, in microseconds
989 uint8: Axes bitfield to specify which axes are relative. Any axis with a bit set should make a relative movement.
990
a799946 Filled in blank responses for the spec
Dave Sayles authored
991 Response (0 bytes)
992
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
993 ## 143 - Store home positions
994 Record the positions of the selected axes to device EEPROM
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
995
996 Payload
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
997
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
998 uint8: Axes bitfield to specify which axes' positions to store. Any axis with a bit set should have its position stored.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
999
a799946 Filled in blank responses for the spec
Dave Sayles authored
1000 Response (0 bytes)
1001
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1002 ## 144 - Recall home positions
1003 Recall the positions of the selected axes from device EEPROM
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1004
1005 Payload
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1006
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
1007 uint8: Axes bitfield to specify which axes' positions to recall. Any axis with a bit set should have its position recalled.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1008
a799946 Filled in blank responses for the spec
Dave Sayles authored
1009 Response (0 bytes)
1010
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1011 ## 145 - Set digital potentiometer value
1012 Set the value of the digital potentiometers that control the voltage reference for the botsteps
1013
1014 Payload
8025bc4 Bugfix: missing WAIT_FOR_BUTTON definition. Also, fix some formatting…
matt.mets@makerbot.com authored
1015
4c1df84 @aleonard updating protocol doc
aleonard authored
1016 uint8: axis value (valid range 0-4) which axis pot to set
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1017 uint8: value (valid range 0-127), values over max will be capped at max
1018
a799946 Filled in blank responses for the spec
Dave Sayles authored
1019 Response (0 bytes)
1020
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1021 ## 146 - Set RGB LED value
1022 Set Brightness levels for RGB led strip
1023
1024 Payload
8025bc4 Bugfix: missing WAIT_FOR_BUTTON definition. Also, fix some formatting…
matt.mets@makerbot.com authored
1025
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1026 uint8: red value (all pix are 0-255)
1027 uint8: green
1028 uint8: blue
1029 uint8: blink rate (0-255 valid)
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1030 uint8: 0 (reserved for future use)
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1031
a799946 Filled in blank responses for the spec
Dave Sayles authored
1032 Response (0 bytes)
1033
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1034 ## 147 - Set Beep
1035 Set a buzzer frequency and buzz time
1036
1037 Payload
8025bc4 Bugfix: missing WAIT_FOR_BUTTON definition. Also, fix some formatting…
matt.mets@makerbot.com authored
1038
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1039 uint16: frequency
1040 uint16: buzz length in ms
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1041 uint8: 0 (reserved for future use)
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1042
a799946 Filled in blank responses for the spec
Dave Sayles authored
1043 Response (0 bytes)
1044
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1045 ## 148 - Wait for button
1046 Wait until either a user presses a button on the interface board, or a timeout occurs.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1047
1048 Payload
8025bc4 Bugfix: missing WAIT_FOR_BUTTON definition. Also, fix some formatting…
matt.mets@makerbot.com authored
1049
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1050 uint8: Bit field of buttons to wait for (see below)
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1051 uint16: Timeout, in seconds. A value of 0 indicates that the command should not time out.
1052 uint8: Options bitfield (see below)
1053
a799946 Filled in blank responses for the spec
Dave Sayles authored
1054 Response (0 bytes)
1055
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1056 Button field
1057 <table>
1058 <tr>
1059 <th>Bit</th>
1060 <th>Name</th>
1061 </tr>
1062 <tr>
1063 <td>7</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1064 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1065 </tr>
1066 <tr>
1067 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1068 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1069 </tr>
1070 <tr>
1071 <td>5</td>
1072 <td>RESET</td>
1073 </tr>
1074 <tr>
1075 <td>4</td>
1076 <td>UP</td>
1077 </tr>
1078 <tr>
1079 <td>3</td>
1080 <td>DOWN</td>
1081 </tr>
1082 <tr>
1083 <td>2</td>
1084 <td>LEFT</td>
1085 </tr>
1086 <tr>
1087 <td>1</td>
1088 <td>RIGHT</td>
1089 </tr>
1090 <tr>
1091 <td>0</td>
1092 <td>CENTER</td>
1093 </tr>
1094 </table>
1095
1096 Options Field
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1097 <table>
1098 <tr>
1099 <th>Bit</th>
1100 <th>Name</th>
1101 </tr>
1102 <tr>
1103 <td>7</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1104 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1105 </tr>
1106 <tr>
1107 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1108 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1109 </tr>
1110 <tr>
1111 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1112 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1113 </tr>
1114 <tr>
1115 <td>4</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1116 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1117 </tr>
1118 <tr>
1119 <td>3</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1120 <td>0 (reserved for future use)</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1121 </tr>
1122 <tr>
1123 <td>2</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1124 <td>clear screen on button press</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1125 </tr>
1126 <tr>
1127 <td>1</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1128 <td>reset bot on timeout</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1129 </tr>
1130 <tr>
1131 <td>0</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1132 <td>change to ready state on timeout</td>
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1133 </tr>
1134 </table>
1135
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
1136 ## 149 - Display message to LCD
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1137 This command is used to display a message to the LCD board.
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
1138 The maximum buffer size is larger than the maximum package size, so a full screen cannot be written with one command.
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1139 Messages are stored in a buffer and the full buffer is displayed when the "last message in group" flag is 1.
b0f4e81 @aleonard protocol doc updated
aleonard authored
1140 If the "last message in group" is not sent, the message will never be displayed
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1141
96589fa @dgs3 Spec'd DisplayMessage wrong...Byte 0 should be false to clear the mes…
dgs3 authored
1142 if the "clear message" flag is 0, the message buffer will be cleared and any existing timeout out will be cleared.
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1143
6d36730 @dgs3 Updated docs
dgs3 authored
1144 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.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1145
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1146 Text will auto-wrap at end of line. \n is recognized as new line start. \r is ignored.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1147
1148 Payload
8025bc4 Bugfix: missing WAIT_FOR_BUTTON definition. Also, fix some formatting…
matt.mets@makerbot.com authored
1149
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1150 uint8: Options bitfield (see below)
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1151 uint8: Horizontal position to display the message at (commonly 0-19)
1152 uint8: Vertical position to display the message at (commonly 0-3)
f783fd2 @cibomahto Add the remaining host commands
cibomahto authored
1153 uint8: Timeout, in seconds. If 0, this message will left on the screen
1154 1+N bytes: Message to write to the screen, in ASCII, terminated with a null character.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1155
a799946 Filled in blank responses for the spec
Dave Sayles authored
1156 Response (0 bytes)
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1157
6394e3a @tedbrandston Spelling/grammar/clarity fixes to documentation.
tedbrandston authored
1158 Options Field
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1159 <table>
1160 <tr>
1161 <th>Bit</th>
1162 <th>Name</th>
1163 </tr>
1164 <tr>
1165 <td>7</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1166 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1167 </tr>
1168 <tr>
1169 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1170 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1171 </tr>
1172 <tr>
1173 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1174 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1175 </tr>
1176 <tr>
1177 <td>4</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1178 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1179 </tr>
1180 <tr>
1181 <td>3</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1182 <td>0 (reserved for future use)</td>
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1183 </tr>
1184 <tr>
1185 <td>2</td>
1186 <td>wait for button press</td>
1187 </tr>
1188 <tr>
1189 <td>1</td>
1190 <td>last message in group</td>
1191 </tr>
1192 <tr>
1193 <td>0</td>
1194 <td>clear existing message</td>
1195 </tr>
1196 </table>
1197
1198 ## 150 - Set Build Percentage
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1199 Set the percent done for the current build. This value will be displayed on the Monitor screen
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1200
1201 Payload
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1202
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1203 uint8: percent (0-100)
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1204 uint8: 0 (reserved for future use) (reserved for future use)
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1205
a799946 Filled in blank responses for the spec
Dave Sayles authored
1206 Response (0 bytes)
1207
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1208 ## 151 - Queue Song
1209 Play predefined songs on the piezo buzzer
1210
1211 Payload
1212
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1213 uint8: songID: select from a predefined list of songs
1214
a799946 Filled in blank responses for the spec
Dave Sayles authored
1215 Response (0 bytes)
1216
b0f4e81 @aleonard protocol doc updated
aleonard authored
1217 song ID 0: error tone with 4 cycles
1218 song ID 1: done tone
1219 song ID 2: error tone with 2 cycles
1220
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1221
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
1222 ## 152 - reset to Factory
d4a3aff Add diagrams for tool commands.
matt.mets@makerbot.com authored
1223 Calls a factory reset on the eeprom. Resets all values to their "factory" settings. A soft reset of the board is also called.
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1224
b0f4e81 @aleonard protocol doc updated
aleonard authored
1225 This function resets all eeprom values to defaults except those that are considered "Factory" settings. Factory settings are:
1226
1227 Toolhead Calibration Settings
1228 Axis Inversion Settings
1229 Tool Count (single or dual)
1230
1231 These settings will not be cleared by reset to Factory. A full eeprom reset must be called to clear these settings.
1232
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1233 Payload
1234
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1235 uint8: 0 (reserved for future use)
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1236
a799946 Filled in blank responses for the spec
Dave Sayles authored
1237 Response (0 bytes)
9adba8e @aleonard s3g_protocol doc updated with current replicator commands
aleonard authored
1238
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1239 ## 153 - Build start notification
b0f4e81 @aleonard protocol doc updated
aleonard authored
1240 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.
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1241
1242 Payload
1243
8050db7 @dgs3 Updated docs for build start notificaiton.
dgs3 authored
1244 uint32: 0 (reserved for future use)
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1245 1+N bytes: Name of the build, in ASCII, null terminated
1246
1247 Response (0 bytes)
1248
1249 ## 154 - Build end notification
1250 Tells the motherboard that a build has been completed or aborted.
1251
5980a56 @dgs3 Fixed Build End Notification to send the one expected byte.
dgs3 authored
1252 Payload (1 byte)
1253
1254 uint8: 0 (reserved for future use)
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1255
1256 Response (0 bytes)
1257
2277f81 @aleonard added new commands to s3gProtocol.md
aleonard authored
1258 ## 155 - Queue extended point x3g
1259 This queues an absolute point to move to.
1260
1261 Payload
1262
1263 int32: X coordinate, in steps
1264 int32: Y coordinate, in steps
1265 int32: Z coordinate, in steps
1266 int32: A coordinate, in steps
1267 int32: B coordinate, in steps
1268 uint32: DDA Feedrate, in steps/s
1269 uint8: Axes bitfield to specify which axes are relative. Any axis with a bit set should make a relative movement.
c3c2f05 @aleonard mod description in s3gProtocol.md
aleonard authored
1270 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
2277f81 @aleonard added new commands to s3gProtocol.md
aleonard authored
1271 uint16: feedrate in mm/s, multiplied by 64 to assist fixed point calculation on the bot
1272
1273 Response (0 bytes)
1274
1275 ## 157 - Stream Version
1276 Used at the start of a build to tell the bot the active x3g version.
1277 The bot can use this information to provide feedback on compatibility to the user.
1278
1279 Payload
1280
cc4cafb @aleonard update s3gProtocol.md
aleonard authored
1281 uint8: x3g version high byte
1282 uint8: x3g version low byte
1283 uint8: not implemented
1284 uint32: not implemented
1285 uint16: bot type: PID for the intended bot is sent
2277f81 @aleonard added new commands to s3gProtocol.md
aleonard authored
1286 <table>
1287 <tr>
1288 <th>Bot Type</th>
1289 <th>PID</th>
1290 </tr>
1291 <tr>
1292 <td>Replicator</td>
1293 <td>0xD314</td>
1294 </tr>
1295 <tr>
1296 <td>Repliator 2</td>
1297 <td>0xB015</td>
1298 </tr>
1299 </table>
cc4cafb @aleonard update s3gProtocol.md
aleonard authored
1300 uint16: not implemented
1301 uint32: not implemented
1302 uint32: not implemented
1303 uint8: not implemented
2277f81 @aleonard added new commands to s3gProtocol.md
aleonard authored
1304
1305 Response (0 bytes)
cd5fb98 @cibomahto Implement init, abort_immediately,build_start_notification,build_end_…
cibomahto authored
1306
dc023c8 @cibomahto Update documentation.
cibomahto authored
1307 # Tool Query Commands
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1308
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
1309 ## 00 - Get version: Query firmware for version information
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1310 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.
1311
1312 Payload
1313
1314 uint16: Host Version
1315
1316 Response
1317
1318 uint16: Firmware Version
1319
bf3e88b @cibomahto Documentation update, add playback_capture, get_extended_position
cibomahto authored
1320 ## 02 - Get toolhead temperature
dc023c8 @cibomahto Update documentation.
cibomahto authored
1321 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.
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1322
1323 Payload (0 bytes)
1324
1325 Response
1326
1327 int16: Current temperature, in Celsius
1328
1329 ## 17 - Get motor speed (RPM)
1330
1331 Payload (0 bytes)
1332
1333 Response
1334
1335 uint32: Duration of each rotation, in microseconds
1336
1337 ## 22 - Is tool ready?
1338 Query the tool to determine if it has reached target temperature. Note that this only queries the toolhead, not the build platform.
1339
1340 Payload (0 bytes)
1341
1342 Response
1343
1344 uint8: 1 if the tool is ready, 0 otherwise.
1345
1346 ## 25 - Read from EEPROM
dee45aa @cibomahto Add read/write EEPROM commands, for host and slave targets. Add get v…
cibomahto authored
1347 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.
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1348
1349 Payload
1350
1351 uint16: EEPROM memory offset to begin reading from
1352 uint8: Number of bytes to read, N.
1353
1354 Response
1355
1356 N bytes: Data read from the EEPROM
1357
1358 ## 26 - Write to EEPROM
1359 Write the given bytes to the EEPROM, starting at the given offset.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1360
1361 Payload
1362
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1363 uint16: EEPROM memory offset to begin writing to
1364 uint8: Number of bytes to write
1365 N bytes: Data to write to EEPROM
1366
1367 Response
1368
1369 uint8: Number of bytes successfully written to the EEPROM
1370
1371 ## 30 - Get build platform temperature
dc023c8 @cibomahto Update documentation.
cibomahto authored
1372 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.
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1373
1374 Payload (0 bytes)
1375
1376 Response
1377
1378 int16: Current temperature, in Celsius
1379
1380 ## 32 - Get toolhead target temperature
1381 This returns the target temperature (setpoint) of the toolhead.
1382
1383 Payload (0 bytes)
1384
1385 Response
1386
1387 int16: Target temperature, in Celsius
1388
1389 ## 33 - Get build platform target temperature
1390 This returns the target temperature (setpoint) of the build platform.
1391
1392 Payload (0 bytes)
1393
1394 Response
1395
1396 int16: Target temperature, in Celsius
1397
1398 ## 35 - Is build platform ready?
0d5c0ff @cibomahto Documentation bugfix
cibomahto authored
1399 Query the build platform to determine if it has reached target temperature. Note that this only queries the build platform, not the toolhead.
ba2f153 @cibomahto Add host query commands to documentation.
cibomahto authored
1400
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1401 Payload (0 bytes)
1402
1403 Response
1404
1405 uint8: 1 if the tool is ready, 0 otherwise.
1406
1407 ## 36 - Get tool status
1408 Retrieve some status information from the tool
1409
1410 Payload (0 bytes)
1411
1412 Response
1413
1414 uint8: Bitfield containing status information (see below)
1415
1d13273 @aleonard updated tool and motherboard status commmands, tests and documentation
aleonard authored
1416 DEPRECATED BITFIELD TABLE
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1417 <table>
1418 <tr>
1419 <th>Bit</th>
1420 <th>Name</th>
1421 <th>Details</th>
1422 </tr>
1423 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1424 <td>7</td>
1425 <td>EXTRUDER_ERROR</td>
1426 <td>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.</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1427 </tr>
1428 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1429 <td>6</td>
1430 <td>PLATFORM_ERROR</td>
1431 <td>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.</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1432 </tr>
1433 <tr>
1434 <td>5</td>
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1435 <td>WDRF *Deprecated*</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1436 <td>Watchdog reset flag was set at restart</td>
1437 </tr>
1438 <tr>
1439 <td>4</td>
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1440 <td>BORF *Deprecated*</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1441 <td>Brownout reset flag was set at restart</td>
1442 </tr>
1443 <tr>
1444 <td>3</td>
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1445 <td>EXTRF *Deprecated*</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1446 <td>External reset flag was set at restart</td>
1447 </tr>
1448 <tr>
1449 <td>2</td>
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1450 <td>PORF *Deprecated*</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1451 <td>Power-on reset flag was set at restart</td>
1452 </tr>
1453 <tr>
1454 <td>1</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1455 <td>0 (reserved for future use)</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1456 <td></td>
1457 </tr>
1458 <tr>
1459 <td>0</td>
1460 <td>EXTRUDER_READY</td>
1461 <td>The extruder has reached target temperature</td>
1462 </tr>
1463 </table>
1464
1d13273 @aleonard updated tool and motherboard status commmands, tests and documentation
aleonard authored
1465 NEW BITFIELD TABLE
1466 <table>
1467 <tr>
1468 <th>Bit</th>
1469 <th>Name</th>
1470 <th>Details</th>
1471 </tr>
1472 <tr>
1473 <td>7</td>
1474 <td>EXTRUDER_ERROR</td>
1475 <td>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.</td>
1476 </tr>
1477 <tr>
1478 <td>6</td>
1479 <td>PLATFORM_ERROR</td>
1480 <td>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.</td>
1481 </tr>
1482 <tr>
1483 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1484 <td>0 (reserved for future use)></td>
1d13273 @aleonard updated tool and motherboard status commmands, tests and documentation
aleonard authored
1485 <td></td>
1486 </tr>
1487 <tr>
1488 <td>4</td>
1489 <td>Temperature Dropping</td>
1490 <td>Heater reached temperature but temperature subsequently dropped 30 degrees below target temp. </td>
1491 </tr>
1492 <tr>
1493 <td>3</td>
1494 <td>Not Heating</td>
1495 <td>Heater is not heating up as expected, flagged if improper after heating for 40 seconds.</td>
1496 </tr>
1497 <tr>
1498 <td>2</td>
1499 <td>Software Cutoff</td>
1500 <td>Temperature was recorded above maximum allowable. Heater shutdown for safety.</td>
1501 </tr>
1502 <tr>
1503 <td>1</td>
1504 <td>Not Plugged In</td>
1505 <td>The tool or platform is not plugged in.</td>
1506 </tr>
1507 <tr>
1508 <td>0</td>
1509 <td>EXTRUDER_READY</td>
1510 <td>The extruder has reached target temperature</td>
1511 </tr>
1512 </table>
1513
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1514 ## 37 - Get PID state
1515 Retrieve the state variables of the PID controller. This is intended for tuning the PID constants.
1516
1517 Payload (0 bytes)
1518
1519 Response
dd6bdea @cibomahto More documentation cleanup
cibomahto authored
1520
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1521 int16: Extruder heater error term
1522 int16: Extruder heater delta term
1523 int16: Extruder heater last output
1524 int16: Platform heater error term
1525 int16: Platform heater delta term
1526 int16: Platform heater last output
1527
dc023c8 @cibomahto Update documentation.
cibomahto authored
1528 # Tool Action Commands
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1529
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
1530 ## 01 - init: Initialize firmware to boot state
57e50e5 Fixed format of s3g_protocol
Dave Sayles authored
1531 Initialization resets the toolhead and all processes it controls to the boot state. some examples of processes that will be reset are:
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1532
1533 * Resetting target temperatures to 0
1534 * Turning off all outputs (fan, motor, etc)
1535 * Detaching all servo devices
1536 * Resetting motor speed to 0
1537
1538 Payload (0 bytes)
1539
1540 Response (0 bytes)
1541
1542 ## 03 - Set toolhead target temperature
dc023c8 @cibomahto Update documentation.
cibomahto authored
1543 This sets the desired temperature for the heating element. The tool firmware will then attempt to maintain this temperature as closely as possible.
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1544
1545 Payload
1546
1547 int16: Desired target temperature, in Celsius
1548
1549 Response (0 bytes)
1550
1551 ## 06 - Set motor speed (RPM)
1552 This sets the motor speed as an RPM value, but does not enable/disable it.
1553
1554 Payload
1555
1556 uint32: Duration of each rotation, in microseconds
1557
1558 Response (0 bytes)
1559
1560 ## 10 - Enable/disable motor
1561 This command can be used to turn the motor on or off. The motor direction must be specified when enabling the motor.
1562
1563 Payload
1564
1565 uint8: Bitfield codifying the command (see below)
1566
1567 Response (0 bytes)
1568
1569 <table>
1570 <tr>
1571 <th>Bit</th>
1572 <th>Name</th>
1573 <th>Details</th>
1574 </tr>
1575 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1576 <td>7</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1577 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1578 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1579 </tr>
1580 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1581 <td>6</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1582 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1583 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1584 </tr>
1585 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1586 <td>5</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1587 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1588 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1589 </tr>
1590 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1591 <td>4</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1592 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1593 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1594 </tr>
1595 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1596 <td>3</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1597 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1598 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1599 </tr>
1600 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1601 <td>2</td>
f321ab1 @cibomahto Fix some outstanding TODOs
cibomahto authored
1602 <td>0 (reserved for future use)</td>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1603 <td></td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1604 </tr>
1605 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1606 <td>1</td>
1607 <td>DIR</td>
1608 <td>If set, motor should be turned in a clockwise direciton. Otherwise, it should be turned in a counterclockwise direction</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1609 </tr>
1610 <tr>
642eaf6 @cibomahto Clean up tables, reword architecture section.
cibomahto authored
1611 <td>0</td>
1612 <td>ENABLE</td>
1613 <td>If set, enable the motor. If unset, disable the motor</td>
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1614 </tr>
1615 </table>
1616
1617 ## 12 - Enable/disable fan
b0f4e81 @aleonard protocol doc updated
aleonard authored
1618 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).
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1619
1620 Payload
1621
1622 uint8: 1 to enable, 0 to disable.
1623
1624 Response (0 bytes)
1625
b648d77 @dgs3 Renamed extra device to extra output.
dgs3 authored
1626 ## 13 - Enable/disable extra output
1627 Turn the extra output attached to a toolhead on or off
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1628
1629 Payload
1630
1631 uint8: 1 to enable, 0 to disable.
1632
1633 Response (0 bytes)
1634
1635 ## 14 - Set servo 1 position
1636 Set the position of a servo connected to the first servo output.
1637
1638 Payload
1639
1640 uint8: Desired angle, from 0 - 180
1641
1642 Response (0 bytes)
1643
9118ba8 @FarMcKon refactor to make all kinds of functions use python style names
FarMcKon authored
1644 ## 23 - pause/resume: Halt execution temporarily
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1645 This function is inteded to be called infrequently by the end user in order to make build-time adjustments during a print.
1646
1647 Payload (0 bytes)
1648
1649 Response (0 bytes)
1650
1651 ## 24 - Abort immediately: Terminate all operations and reset
1652 This function is intended to be used to terminate a print during printing. Disables any engaged heaters and motors.
1653
1654 Payload (0 bytes)
1655
1656 Response (0 bytes)
1657
1658 ## 31 - Set build platform target temperature
dc023c8 @cibomahto Update documentation.
cibomahto authored
1659 This sets the desired temperature for the build platform. The tool firmware will then attempt to maintain this temperature as closely as possible.
d732135 @cibomahto Finish adding extruder commands.
cibomahto authored
1660
1661 Payload
1662
1663 int16: Desired target temperature, in Celsius
1664
1665 Response (0 bytes)
1666
Something went wrong with that request. Please try again.