The s3g module is designed to communicate with a Makerbot Printer via s3g Packets. The main objectives of this module are to transform certain actions (i.e. move-to-a-position, heat-up-a-toolhead) into packets of information to be sent and to decode packets of information received from a printer into human parsable formats.

##VirtualEnv Due to s3g's dependency on our (Makerbot Industries) own version of pyserial, and for the sake of not polluting your own system that may have the 'true' version of pyserial installed, we suggest invoking s3g inside a virtualenv. We provide the necessary files to operate inside a VirtualEnv that will install all dependencies for you without polluting your own machine.

First, obtain a copy of our version of pyserial. This can be done VIA git. On the same directory level as s3g, in a terminal window issue:

git clone git@github.com:makerbot/pyserial.git

To create the VirtualEnv, inside the root directory of the s3g folder, issue:

python virtualenv.py virtualenv

To configure the VirtualEnv, navigate to the root directory of the s3g driver and, in a terminal issue:

./setup.sh

To activate the VirtualEnv, in the root directory of the s3g driver, issue:

. virtualenv/bin/activate

##Machine Connection

To connect to a machine, you will need the following module:

• pySerial.

To run the unit tests, you will need the following modules:

• Mock (Note: Use version 0.8 or greater)
• unittest2 (Python 2.6 and earlier)

Import both the s3g module and pyserial:

import s3g, serial

Create an s3g object, and attach it to a serial port:

r = s3g.s3g()
file = serial.Serial(port, 115200, timeout=.2)
r.writer = s3g.Writer.StreamWriter(file)

Note: Replace port with your serial port (example: '/dev/tty.usbmodemfd121')

Home the x, y, and z axes:

r.find_axes_maximums(['x', 'y'], 500, 60)
r.find_axes_minimums(['z'], 500, 60)
r.recall_home_positions(['x', 'y', 'z', 'a', 'b'])

Instruct the machine to move in a square pattern:

r.queue_extended_point([2000,0,5000,0,0], 400)
r.queue_extended_point([2000,2000,5000,0,0], 400)
r.queue_extended_point([0,2000,5000,0,0], 400)
r.queue_extended_point([0,0,5000,0,0], 400)

Note: All points are in steps, and all speeds are in DDA. This is s3g, not gcode!

Now, instruct the machine to heat toolhead 0, wait up to 5 minutes for it to reach temperature, then extrude for 12.5 seconds:

r.set_toolhead_temperature(0, 220)
r.wait_for_tool_ready(0,100,5*60)
r.queue_extended_point([0,0,5000,-5000,0], 2500)

Finally, don't forget to turn off the toolhead heater, and disable the stepper motors:

r.set_toolhead_temperature(0,0)
r.toggle_axes(['x','y','z','a','b'],False)

Those are the basics of how to control a machine. For more details, consult the s3g protocol and the s3g source.

There are a few specific data formats that are used throughout this module, that warrant further explanation here.

Points come in two flavors: regular and extended.

Regular points are expressed as a list of x, y, and z coordinates:

[x, y, z]

Extended points are expressed as a list of x, y, a, and b coordinates:

[x, y, z, a, b]

There are several commands that require a list of axes as input. This parameter is passed as a python list of strings, where each axis is its own separate string. To pass in all axes:

['x', 'y', 'z', 'a', 'b']

The s3g module will raise an exception if it encounters a problem during transmission. Conditions, such as timeouts, bad packets being received from the bot and poorly formatted parameters all can cause the s3g module to raise exceptions. Some of these states are recoverable, while some require a machine restart. We can categorize s3g's error states into the following:

TODO: This is largely duplicated in the errors.py doc, consider rewriting as a summary of the base error types only.

A Buffer Overflow Error is raised when the machine has full buffer.

Retryable Errors are non-catastrophic errors raised by s3g. While alone they cannot cause s3g to terminate, an aggregate of 5 errors will cause s3g to quit.

Packet Decode Errors
Generic Errors
CRC Mismatch Errors
Timeout Errors

Packet decode errors are raised if there is a problem evaluating a return packet from an s3g Host:

Bad Packet Lengths
Bad Packet Field Lenghts
Bad Packet CRCs
Bad Packet Headers

Transmission Errors are thrown when more than 5 Retryable Errors are raised.

These errors are caused by ostensibly well formed packets returned from the machine, but with incorrect data:

Bad Heat Element Ready Responses
Bad EEPROM Read/Write Lengths
UnrecognizedResponseError

Parameter errors are raised when imporperly formatted arguments are passed into an s3g function.

Bad Point Length
EEPROM Read/Write length too long
Bad Tool Index
Bad button name

Tool Bus errors are raised when the machine cannot communicate with its toolbus.

Downstream Timeout Error
Tool Lock Error

Bot generated errors will throw their own specific errors, such as:

SD Card Errors
Extended Stop Errors
Build Cancel Errors

GCode errors are thrown when reading through a GCode file and parsing out g/m codes and comments. Cause By:

Improperly Formatted Comments
Bad Codes
Codes That Are Repeated Multiple Times On A Single Line
M And G Codes Present On The Same Line

An External Stop Error is raised when an external thread sets the External Stop Flag in s3g.Writer.StreamWriter to true, which terminates the Stream Writer's packet sending process.

These errors are thrown when the s3g module encounters errors during s3g stream parsing.
Caused By:

Encoded Strings Above The Max Payload Length

Contributions are welcome to this project! All changes must be in the style of the project, and include unit tests that are as complete as possible. Place all source code in the s3g/ directory, and all tests in the tests/ directory. Before submitting a patch, ensure that all unit tests pass by running the unit test script:

python unit_tests.py