A python implementation of the s3g protocol, to speak to MakerBots.
Python JavaScript C++ Graphviz (DOT) Other
Clone or download
#5 Compare This branch is 1281 commits ahead of cibomahto:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
debian Fix pyserial depends Feb 18, 2013
doc Updated docs Nov 29, 2012
examples Pass a condition object when opening a serial port. Feb 13, 2013
firmware_testing moved all .markdown files to .md files, to match our naming conventio… Aug 2, 2012
makerbot_driver Add "use_legacy_parser" flag to the TOM profiles Mar 27, 2013
rpm rpm spec file for fedora support Feb 11, 2013
submodule Update submodule ref to pull in clang support Jun 26, 2013
technician_tests Add technicial test for serial port timeouts. Aug 22, 2012
tests updates to MachineDetector and Firmware Uploader to allow for multipl… Mar 26, 2013
.gitignore updated gitignore Aug 31, 2012
.gitmodules Change conveyor_bins to use the http url so that readonly access works Feb 28, 2013
CONTRIBUTING.md * Added pep8 git hook Sep 26, 2012
COPYING.txt Add AGPLv3 license. May 31, 2012
HACKING.md Updated hacking.md Aug 10, 2012
MANIFEST.in updating manifest and setup.py to include eeprom.json Aug 16, 2012
README.md Implemented support for a local avrdude (to be used on a user's mac/e… Aug 28, 2012
SConstruct Fix typo Feb 15, 2013
change_log.md Updated version number, change log added Oct 2, 2012
copy_avrdude.py Log the files being copied. Feb 15, 2013
git_hook_pre-commit Added pep8 git hook Oct 4, 2012
mb_version Adding version file. Jan 24, 2013
pi_tests.py changed unit test naming convention to easily plug post_installation … Sep 5, 2012
pic_tests.py Renamed the installation test files correctly Jul 19, 2012
setup-dev.sh Fix egg build to pull in dependencies from eggs, add new setup script… Feb 5, 2013
setup.py Renamed Preprocessors to GcodeProcessors Dec 4, 2012
setup.sh update .egg Aug 20, 2012
setup_s3g_env.py Adding more helpful failure messages to setup_env.py Feb 8, 2013
setup_s3g_env.sh Install from the right path Feb 5, 2013
test.sh updated test for scons to meet arcweb's spec Jul 23, 2012
unit_tests.py Added post_install and post_install_control pyscripts. Reverted unit_… Jul 19, 2012
virtualenv.py Added virtualenv to s3g Jul 12, 2012



The makerbot_driver module is designed to communicate with a Makerbot Printer via makerbot_driver 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 makerbot_driver'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 makerbot_driver 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 makerbot_driver, in a terminal window issue:

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

Dependent submodules must be up to date to run the virutalenv. In the root directory of makerbot_driver, issue:

git submodule update --init

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

python virtualenv.py virtualenv

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


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

. virtualenv/bin/activate


makerbot_driver uses AVRDude to upload firmware to the machine. Because AVRDude is platform specific, the user needs to copy over the correct AVRDude executable to makerbot_driver/Firmware.

On all platforms, the protocol for invoking AVRDude is to first search for a local AVRDude executable. In the event that no local binary is found, we attempt to invoke an AVRDude defined in the user's path.

###Mac and Windows Distributions

Running the copy_avrdude.py script will copy the correct avrdude executable from conveyor_bins. To execute:

python copy_avrdude.py

###Linux Distributions

On linux systems, we request that the user use a distribution service (i.e. 'apt-get') to pull down AVRDude.

##Machine Connection

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

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)

Example: Connecting to a Replicator

Import both the makerbot_driver module and pyserial:

import makerbot_driver, serial

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

r = makerbot_driver.s3g()
file = serial.Serial(port, 115200, timeout=1)
r.writer = makerbot_driver.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.queue_extended_point([0,0,5000,-5000,0], 2500)

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


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

Data types

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]

Axes Lists

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']

Error handling

The makerbot_driver 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 makerbot_driver module to raise exceptions. Some of these states are recoverable, while some require a machine restart. We can categorize makerbot_driver'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.

Buffer Overflow Error (used internally)

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

Retryable Errors (used internally)

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

Packet Decode Errors
Generic Errors
CRC Mismatch Errors
Timeout Errors

Packet Decode Errors (used internally):

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:

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

Protocol Errors

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

Parameter Errors

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

ToolBusError (used internally):

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

Downstream Timeout Error
Tool Lock Error

Other Errors

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

SD Card Errors
Extended Stop Errors
Build Cancel Errors

GCode 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

External Stop Error

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

S3G Stream Reading Errors

These errors are thrown when the makerbot_driver module encounters errors during makerbot_driver 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