Introduction

The AxiDraw python module is an application programming interface (API) for AxiDraw, designed to let you control the AxiDraw from within your own python scripts.

This python module supports the AxiDraw with two distinct control approaches:

Plotting SVG files, and
Interactive XY motion control through "moveto/lineto" type commands

To distinguish between these two control methods, we will refer to them as the Plot context and the Interactive context, for plotting SVG files or using XY motion control commands, respectively. Certain options and functions can only be used in one or the other context. Please see Quick start: Plotting SVG and Quick start: Interactive XY for more information.

If you wish to use the AxiDraw from the command line interface or within shell scripts and other environments that make use of shell commands, please see the separate documentation for the AxiDraw CLI. (As a side note, the CLI supports an additional function: A "reorder" mode, which can sort paths in an SVG file to reduce pen-up travel time.)

About AxiDraw

The AxiDraw writing and drawing machine is a modern pen plotter designed and manufactured by Evil Mad Scientist Laboratories in Sunnyvale, California.

AxiDraw software development is hosted at github. The central documentation site for AxiDraw is at the Evil Mad Scientist wiki; many additional development resources are listed there.

AxiDraw owners may request technical and other product support by contacting us directly through our contact form, through our github issues list, or through our support forums.

Installation

This is pre-release software, currently in a private beta for AxiDraw owners. We will release this more widely when we are ready to support it in a public release. If you would like access to this API, please contact us.

Please see Installation.txt included with the download for installation instructions.

Quick start: Plotting SVG

Quick start: Plotting SVG

Quick start example; Typical usage:

from pyaxidraw import axidraw   # Import the module
ad = axidraw.AxiDraw()          # Create class instance
ad.plot_setup(FILE_NAME)        # Load file & configure plot context
            # Plotting options can be set, here after plot_setup().
ad.plot_run()                   # Plot the file

Example 1: Plot a file named AxiDraw_trivial.svg

from pyaxidraw import axidraw   
ad = axidraw.AxiDraw()
ad.plot_setup("AxiDraw_trivial.svg")
ad.plot_run()

Example 2: Plot a file named input.svg, and collect the output SVG as a string:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("AxiDraw_trivial.svg")
output_svg = ad.plot_run(True)

plot_run(True) will generate output SVG. output_svg is a string equivalent to the contents of an SVG file.

The examples shown here will load and plot a file, using default parameters. Four lines of code are needed: to import the module, create an instance of the AxiDraw class, configure into Plot context, and run the script.

In addition to plotting a file, the API includes the ability to set a wide range of configuration options, as well as a number of utility modes. The options available in the Plot context include those described below in the Options: General and Options: Plot sections. Options may be set at any point after plot_setup() and before plot_run(). For more about the functions available in the Plot context, see Functions: Plot.

A file input is required for these and all other operations that are outside of the Interactive context. This is true even for utility modes do not actually plot a file. The SVG input may be the name of an SVG file or may be a python string that contains the contents of an SVG file.

By default, no output SVG is returned as part of the plotting process. However, in some situations it may be use useful to have the program generate and return output SVG. The SVG returned by plot_run(True) is a string containing the contents of an SVG file. Keeping that output SVG allows the capability to pause and subsequently resume a plot in progress, or to preview a plot. See further discussion under res_plot and rendering below.

Quick start: Interactive XY

Quick start: Interactive XY

Example: Draw a single line in Interactive context:

from pyaxidraw import axidraw   # import module
ad = axidraw.AxiDraw()          # Initialize class
ad.interactive()                # Enter interactive context
ad.connect()                    # Open serial port to AxiDraw 
                                # Absolute moves follow:
ad.moveto(1,1)                  # Pen-up move to (1 inch, 1 inch)
ad.lineto(2,1)                  # Pen-down move, to (2 inch, 1 inch)
ad.moveto(0,0)                  # Pen-up move, back to origin.
ad.disconnect()                 # Close serial port to AxiDraw

The Interactive context is a separate mode of operation that that accepts direct XY motion control commands. It does not use an SVG file as an input.

Interactive control requires a persistent session, and only works from within a python script.

Once the python module is imported, call the interactive() method to enter the Interactive context. To establish a USB connection to the AxiDraw, use connect(). You must also use disconnect() at the end of your session to terminate the USB session.

Plot options may be specified at any point after the interactive() call. The options will be applied when you call connect(). If you change one or more options after calling connect(), use the update() method to process the changes to the options before calling additional motion commands.

In addition to the plot options specified in Options: General, there is one additional parameter available in Interactive context, units, which can be used to switch between inch and centimeter units.

The options available in the Interactive context include those described below in the Options: General and Options: Interactive sections. The options described in Options: Plot do not apply in the Interactive context.

Setting options

Setting options

One or more options may be specified with the following syntax:

options.option_name = value

Example 1: Set the pen-up position to 70% height before plotting, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_pos_up = 70      # set pen-up position
ad.plot_run()

Example 2: Set the pen-up position to 70% height before plotting, making use of the Interactive context:

from pyaxidraw import axidraw   # import module
ad = axidraw.AxiDraw()          # Initialize class
ad.interactive()                # Enter interactive context
ad.options.pen_pos_up = 70      # set pen-up position
ad.connect()                    # Open serial port to AxiDraw 
ad.moveto(1,1)                  # Absolute pen-up move, to (1 inch, 1 inch)
ad.lineto(0,0)                  # Absolute pen-down move, back to origin.
ad.disconnect()                 # Close serial port to AxiDraw

Most plotting options can be set directly like variables within python. The various options and their values are detailed in the sections below. For options that you do not directly specify, the default value will be used.

The default value of most options can be set from within the axidraw_conf.py configuration file. These include the pen up and pen down heights, basic speed settings, and so forth. This configuration file can be found at: pyaxidraw/axidraw_conf.py

A few particular options (including pen up/down heights, and plotting speed) can also be set by encoding these settings into the SVG file. The mechanism for doing this is called "AxiDraw Layer Control", and it involves using special escape codes in the name of the layer(s) in the SVG file. A few additional commands such as timed delays and forced pauses can be controlled through this mechanism as well.

The order of preference for parameters is as follows:

Parameters values specified in the SVG file (as in, by layer names) overrule those specified either by your script or in axidraw_conf.py.
Options and values specified by your script overrule those in axidraw_conf.py.

If you do also use Inkscape for plotting SVG files, please note that option values and settings that you select from within the Inkscape GUI are NOT consulted and do not affect plotting from outside Inkscape.

Options (General)

The following is a list of "General" options: optional arguments that can be applied in either the Plot or Interactive contexts. Each of these will be described individually, after the list.

Option	Description
`speed_pendown`	Maximum XY speed when the pen is down (plotting).
`speed_penup`	Maximum XY speed when the pen is up.
`accel`	Relative acceleration/deceleration speed.
`pen_pos_down`	Pen height when the pen is down (plotting).
`pen_pos_up`	Pen height when the pen is up.
`pen_rate_lower`	Speed of lowering the pen-lift motor.
`pen_rate_raise`	Speed of raising the pen-lift motor.
`pen_delay_down`	Added delay after lowering pen.
`pen_delay_up`	Added delay after raising pen.
`const_speed`	Option: Use constant speed when pen is down.
`model`	Select model of AxiDraw hardware.
`port`	Specify a USB port or AxiDraw to use.
`port_config`	Override how the USB ports are located.

speed_pendown

speed_pendown

Example 1: Set up to plot with a maximum pen-down speed of 20% selected, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.speed_pendown = 20
ad.plot_run()

Example 2: Set up to plot with a maximum pen-down speed of 20% selected, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()       
ad.interactive()             
ad.options.speed_pendown = 20

Pen-down Movement Speed

Syntax: options.speed_pendown=value

Specify the speed limit for the XY carriage when the pen is down. That is, the maximum speed that the pen may move at while writing or drawing. This value is expressed as a percentage of maximum travel speed.

Pen-down movements use smooth acceleration unless the const_speed option is selected. Increasing this maximum speed tends to greatly affect behavior at corners and precision, but has a lesser impact on the average speed and total plotting time, especially on documents that consist of many small movements.

Allowed values: Integers from 1 to 110.

Default: 25, given by speed_pendown in axidraw_conf.py

speed_penup

speed_penup

Example 1: Set up to plot with a maximum pen-up speed of 50% selected, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.speed_penup = 50
ad.plot_run()

Example 2: Set up to plot with a maximum pen-up speed of 50% selected, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.speed_penup = 50

Pen-up Movement Speed

Syntax: options.speed_penup=value

Specify the speed limit for the XY carriage when the pen is up. That is, the maximum speed that the pen may move at while moving between paths that will be plotted. This value is expressed as a percentage of maximum travel speed.

Pen-up movements use smooth acceleration whether or not the const_speed option is selected. Increasing this maximum speed tends to have a minor effect on plot quality, but can have a significant affect on total plotting time, especially on documents that have many large pen-up movements.

Allowed values: Integers from 1 to 110.

Default: 75, given by speed_penup in axidraw_conf.py

accel

accel

Example 1: Set up to plot with an acceleration parameter of 80% selected, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.accel = 80
ad.plot_run()

Example 2: Set up to plot with an acceleration parameter of 80% selected, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.accel = 80

Acceleration Factor

Syntax: options.accel=value

Specify the relative acceleration/deceleration speed. This value is expressed as a percentage of maximum acceleration rate. The acceleration rate does not affect the top speed that can be achieved, but does influence how long it takes to get to different speeds.

Allowed values: Integers from 1 to 100.

Default: 75, given by accel in axidraw_conf.py

pen_pos_down

pen_pos_down

Example 1: Prepare to plot, with the pen-down height set to 20%, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_pos_down = 20
ad.plot_run()

Example 2: Prepare to plot, with the pen-down height set to 20%, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_pos_down = 20

Pen-down Position

Syntax: options.pen_pos_down=value

Specify the height of the pen when the pen is lowered (plotting). This value is expressed as a percentage of the vertical travel.

Depending on the operation that you are executing, setting this value may not immediately move the pen height to this position; rather, it sets the height that will be used as the pen-down position value.

Allowed values: Integers from 0 to 100.

Default: 40, given by pen_pos_down in axidraw_conf.py

pen_pos_up

pen_pos_up

Example 1: Prepare to plot, with the pen-up height set to 80%, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_pos_up = 80
ad.plot_run()

Example 2: Prepare to plot, with the pen-up height set to 80%, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_pos_up = 80

Pen-up Position

Syntax: options.pen_pos_up=value

Specify the height of the pen when the pen is raised (not plotting). This value is expressed as a percentage of the vertical travel.

Allowed values: Integers from 0 to 100.

Default: 60, given by pen_pos_up in axidraw_conf.py

pen_rate_lower

pen_rate_lower

Example 1: Set up to plot, with the pen set to lower very slowly to the paper (5% speed), making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_rate_lower = 5
ad.plot_run()

Example 2: Set up to plot, with the pen set to lower very slowly to the paper (5% speed), making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_rate_lower = 5

Pen Lowering Rate

Syntax: options.pen_rate_lower=value

Specify the rate at which the pen is lowered from the pen-up position to the pen-down position. This value is expressed as a relative percentage.

Allowed values: Integers from 1 to 100.

Default: 50, given by pen_rate_lower in axidraw_conf.py

pen_rate_raise

pen_rate_raise

Example 1: Set up to plot, with the pen set to raise very quickly to the paper (90% speed), making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_rate_raise = 90
ad.plot_run()

Example 2: Set up to plot, with the pen set to raise very quickly to the paper (90% speed), making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_rate_raise = 90

Pen Raising Rate

Syntax: options.pen_rate_raise=value

Specify the rate at which the pen is raised from the pen-down position to the pen-up position. This value is expressed as a relative percentage.

Allowed values: Integers from 1 to 100.

Default: 75, given by pen_rate_raise in axidraw_conf.py

pen_delay_down

pen_delay_down

Example 1: Add an extra delay of 250 ms, each time the pen is lowered, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_delay_down = 250
ad.plot_run()

Example 2: Add an extra delay of 250 ms, each time the pen is lowered, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_delay_down = 250

Delay after lowering pen

Syntax: options.pen_delay_down=value

Optional delay after lowering pen (ms). When lowering the pen, the AxiDraw will normally pause for a given period of time, so as to allow the pen to finish lowering before beginning horizontal pen-down movements. The period of time is calculated from the Pen Lowering Rate as well as the vertical distance to be traveled.

You can optionally modify the amount of delay time by adding some number of milliseconds, given by pen_delay_down, to the calculated delay, for example to intentionally begin moving before the pen is fully down, or to ensure that the pen is making solid contact before moving. The value of this parameter may be positive or negative, but if the total delay (calculated travel time + pen_delay_down) is less than zero, then a total delay time of zero will be used.

Allowed values: Integers from -500 to 500.

Default: 0, given by pen_delay_down in axidraw_conf.py

pen_delay_up

pen_delay_up

Example 1: Add an extra delay of 250 ms, each time the pen is raised, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.pen_delay_up = 250
ad.plot_run()

Example 2: Add an extra delay of 250 ms, each time the pen is raised, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_delay_up = 250

Delay after raising pen

Syntax: options.pen_delay_up=value

Optional delay after raising pen (ms). When raising the pen, the AxiDraw will normally pause for a given period of time, so as to allow the pen to finish going up before beginning horizontal pen-up movements. The period of time is calculated from the Pen Raising Rate as well as the vertical distance to be traveled.

You can optionally modify the amount of delay time by adding some number of milliseconds, given by pen_delay_up, to the calculated delay, for example to intentionally begin moving before the pen is fully up, or to ensure that the pen is fully above the paper before moving. The value of this parameter may be positive or negative, but if the total delay (calculated travel time + pen_delay_up) is less than zero, then a total delay time of zero will be used.

Allowed values: Integers from -500 to 500.

Default: 0, given by pen_delay_up in axidraw_conf.py

const_speed

const_speed

Example 1: Set up to plot, configuring for constant speed when pen is down, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.const_speed = True
ad.plot_run()

Example 2: Set up to plot, configuring for constant speed when pen is down, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.const_speed = True

Plot with constant pen-down speed

Syntax: options.const_speed=True

Use constant speed when pen is down.

By default, this option is disabled, and the AxiDraw will use acceleration so as to achieve higher maximum speeds. Some applications will benefit from using constant-speed motion instead.

This mode may be enabled by setting const_speed equal to True.

Allowed values: True, False.

Default: False, given by const_speed in axidraw_conf.py

model

model

Example 1: Set plotting size limits for the AxiDraw V3/A3, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.model = 2
ad.plot_run()

Example 2: Set plotting size limits for the AxiDraw V3/A3, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.model = 2

AxiDraw hardware model

Syntax: options.model=value

Select which model of AxiDraw hardware you are using. This is used to set the limits of travel. Limits are set by dead reckoning, under the assumption that a given session (plot or interactive session) was started with the carriage in the Home Corner, and that no loss of position control has occurred. Movements are clipped to occur within these limits.

Limits are not checked when using manual walk commands.

Allowed values: Integers from 1 to 3:

1 - AxiDraw V2 or AxiDraw V3
2 - AxiDraw V3/A3 or AxiDraw SE/A3
3 - AxiDraw V3 XLX

Default: 1 (AxiDraw V2 or AxiDraw V3), given by model in axidraw_conf.py

The physical size definitions for each model type are also configured in axidraw_conf.py.

port

port

Example 1: Specify to use the USB port enumerated as /dev/cu.usbmodem1441, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.port = "/dev/cu.usbmodem1441"
ad.plot_run()

Example 2: Specify to use the USB port enumerated as /dev/cu.usbmodem1441, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.port = "/dev/cu.usbmodem1441"
ad.connect()

Example 3: Specify to use the AxiDraw with USB Nickname "UV LED Array", making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.port = "UV LED Array"
ad.plot_run()

Example 4: Specify to use the AxiDraw with USB Nickname "UV LED Array", making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.port = "UV LED Array"
ad.connect()

Specify a USB port or named AxiDraw to use

Syntax: options.port=value

By default, the AxiDraw software works with the first available AxiDraw located on USB. Alternately, you can use the port parameter to specify a particular machine. You can specify the machine using the USB port enumeration (e.g., COM6 on Windows or /dev/cu.usbmodem1441 on a Mac) or by using an assigned USB nickname.

If any port is specified, then the software will attempt to open the connection to that (and only that) AxiDraw or USB port. It will return an error if the port or AxiDraw cannot be found. This behavior may be overridden by use of the port_config parameter.

USB port enumerations are typically not permanent; they may change with events as simple as unplugging a device and plugging it back in.

For a more permanent designation, you can assign an "AxiDraw USB Nickname" to a given machine as well. This USB nickname may be read and written using the manual commands. (See manual_cmd for additional information.)

Be aware that if multiple AxiDraw units are connected to one computer, it may not be trivial to identify which physical machine is currently identified as which USB device. You may wish to try an identifying action, for example raising the pen, to indicate which machine is which.

Allowed values of the port parameter are strings, which specify either the USB port or AxiDraw USB nickname to use.

Default: None, given by port in axidraw_conf.py

port_config

port_config

Example 1: Plot only to an AxiDraw with USB Nickname "UV LED Array"; Return an error if that unit is not found, explicitly using the default value (0) of port_config, within the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.port="UV LED Array"
ad.options.port_config = 0
ad.plot_run()

Example 2: Plot only to an AxiDraw with USB Nickname "UV LED Array"; Return an error if that unit is not found, explicitly using the default value (0) of port_config, within the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.port="UV LED Array"
ad.options.port_config = 0

Example 3: Plot to the first available AxiDraw found on USB, making use of the Plot context:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.port_config = 1
ad.plot_run()

Example 4: Plot to the first available AxiDraw found on USB, making use of the Interactive context:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.port_config = 1

Override how the USB ports are located

Syntax: options.port_config=value

By default, the software handles assignments of USB ports as follows:

If no port value is specified, the first AxiDraw located via USB will be the one that is used.
If a port value is specified, then the software will attempt to communicate only with that specified machine.

The port_config parameter can override this behavior. Allowed values of the parameter are integers 0-3:

0 - Do not override; use standard "port" parameter behavior.
1 - Address only the first AxiDraw located via USB
2 - Address only the specified AxiDraw

If port_config is 1, then the AxiDraw will plot to the first machine located, even if a port parameter is specified.

If port_config is 2, then the AxiDraw will plot to only the specific machine named, and will be unable to connect if it is not found.

Default: 0, given by port_config in axidraw_conf.py

Options (Plot)

The following is a list of optional arguments that can be applied in the Plot context, and which are not applicable in the Interactive context.

Each of these arguments will be described individually, after the list.

Option	Description
`mode`	Specify general mode of operation.
`manual_cmd`	Specify which "manual" mode command to use.
`walk_dist`	Distance to move for manual walk commands.
`layer`	Specify which layer(s) to plot in the layers mode.
`copies`	Specify the number of copies to plot.
`page_delay`	Specify delay between pages, for multiple copies.
`auto_rotate`	Option: Enable auto-rotate when plotting.
`preview`	Option: Perform offline simulation of plot only.
`rendering`	Option: Render motion when using preview.
`report_time`	Option: Report time and distance after the plot.

mode

mode

Example 1: Toggle the pen up or down, using "toggle" mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "toggle"
ad.plot_run()

Example 2: Disable the XY stepper motors, using "manual" mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "disable_xy"
ad.plot_run()

General mode of operation

Specify the general mode of operation, within in the Plot context. This is equivalent to selecting a function "tab" in the Inkscape-based GUI for AxiDraw Control.

The following is a list of allowed values of the mode parameter. Each of these modes will be described in detail, after the list.

Value	Description
`plot`	Plot the file. [DEFAULT]
`layers`	Plot a single layer (or set of layers), selected by `layer` parameter
`align`	A setup mode: Raise pen, disable XY stepper motors
`toggle`	A setup mode: Raise the pen if it is lowered, or vice versa
`manual`	Execute a utility command, specified by `manual_cmd` parameter
`sysinfo`	Query EBB firmware version and report system information
`version`	Report AxiDraw software version number
`res_plot`	Resume a plot in progress, using stored plot progress data
`res_home`	Return AxiDraw to home, using stored plot progress data

The mode option is only applicable within the Plot context; it cannot be used within an Interactive context session.

plot

mode: plot

Example 1: Plot a file called file.svg, explicitly setting plot mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "plot" # Default; you can comment out this line.
ad.plot_run()

Example 2: Plot a file called file.svg, using multiple modes including plot:

import time
from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")

ad.options.mode = "toggle" # Configure to toggle pen up/down
ad.plot_run()              # Execute that toggle
time.sleep(1.000)          # Wait one second
ad.plot_run()              # Toggle pen again
time.sleep(1.000)          # Wait one second
ad.options.mode = "plot"   # Configure back into plot mode
ad.plot_run()              # plot the file

Plot the SVG file

Syntax: options.mode = "plot"

The plot mode is for plotting an SVG file. This the default mode of operation, when in the Plot context, and in most cases does not need to be explicitly specified. One case where you may need to explicitly switch the mode to plot is if you should switch to another mode and then need to switch back.

layers

mode: layers

Example 1: Plot all document layers that have a layer name beginning with the number 1:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "layers"
ad.options.layer = 1
ad.plot_run()

Example 2: Render a preview of how a layer called "5-blue" (the only layer in file.svg that has a name starting with the number 5) will plot, including pen-up travel, and estimate how long that layer will take to plot. Save the output SVG into a variable called "output_svg":

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "layers"
ad.options.layer = 5
ad.options.preview = True
ad.options.rendering = 3
output_svg = ad.plot_run(True)

Plot a single layer (or set of layers)

Syntax: options.mode = "layers"

Plot a single layer (or set of layers), selected by a layer parameter.

When using the default (plot) mode, the entire document will be plotted. That is to say all paths, on all visible layers of the SVG document, will be plotted. You can instead use layers mode to plot a single layer or group of layers, for example to plot only layers that should be plotted in one color of ink.

If you plot in layers mode, only visible visible layers that have layer names beginning with the selected number will plot. The selected number is given by the value of the layer parameter, and may be in the range of 0 - 1000.

For example, a layer named "5-red" will be plotted if the number 5 is selected, but layers named "guide lines", "55", or "2-black" will be skipped.

Layers mode is equivalent to plotting from the "Layers" tab of AxiDraw Control within Inkscape.

See the description of the "layer" parameter below for additional information. For more information about options available based on layer name, please see the AxiDraw Layer Control documentation.

align

mode: align

Example: Put the AxiDraw into Align mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "align"
ad.plot_run()

Raise pen and disable XY stepper motors

Syntax: options.mode = "align"

This is a setup mode that may be used used to prepare the AxiDraw for use. It will raise the pen to the "pen up" position and turn off (disengage) the XY stepper motors. In this configuration, one can manually move the carriage to the home corner and insert a pen.

This mode is equivalent to selecting the "Setup" tab of AxiDraw Control (within Inkscape) and choosing the "Raise pen, turn off motors" option within that tab. Both raising the pen and turning off the XY motors are actions that can also be initiated in manual mode.

toggle

mode: toggle

Example: Toggle the pen up or down, using "toggle" mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "toggle"
ad.plot_run()

Toggle the pen position from up to down, or vice versa.

Syntax: options.mode = "toggle"

This is a setup mode that may be used used to prepare the AxiDraw for use. It will alternately raise or lower the pen each time that it is called.

This mode is equivalent to selecting the "Setup" tab of AxiDraw Control (within Inkscape) and choosing the "Toggle pen between UP, DOWN" option within that tab.

manual

mode: manual

See examples under the description of each individual manual_cmd item.

Execute a "manual" command

Syntax: options.mode = "manual"

Execute one of several "manual" utility commands, chosen from a list and specified with the manual_cmd argument.

See the description of manual_cmd for additional information about the available commands.

This mode is equivalent to selecting the "Manual" tab of AxiDraw Control within Inkscape.

sysinfo

mode: sysinfo

Example: Request sysinfo:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "sysinfo"
ad.plot_run()

Typical response (example on Mac):

Your AxiDraw has firmware version 2.5.5.
An update is available to EBB firmware v. 2.6.0;
To download the updater, please visit: axidraw.com/fw

This is AxiDraw Control version 2.3.0.
~~ An early-release (beta) version ~~
This is the newest available development version.
(The current "stable" release is v.1.7.8.)

Additional system information:
3.6.5 (default, Apr  4 2018, 17:29:15) 
[GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.1)]

Report system information

Syntax: options.mode = "sysinfo"

Query firmware version and report additional system information. This mode is equivalent to selecting the "Version" tab of AxiDraw Control within Inkscape.

The information items listed are:

The firmware revision for the AxiDraw's EBB control board.
Whether a firmware update is available.
The version number of the AxiDraw software.
Whether a software update is available.
Detailed version information of the python interpreter running the script, as given by python's sys.version command.

version

mode: version

Example: Query software version:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "version"
ad.plot_run()

Typical response:

AxiDraw Control - Version 2.0.0, 2018-06-18.

AxiDraw Software Version

Syntax: options.mode = "version"

Query and report AxiDraw software version. This mode is not available in the GUI (Inkscape) based version of this software.

res_plot, res_home

modes: res_plot, res_home

Example: Plot a file until it is paused (by button press or by AxiDraw Layer Control). Wait 5 seconds. Then move the XY carriage home. Wait 5 more seconds. Then, resume plotting:

import time
from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
output_svg = ad.plot_run(True)
time.sleep(5)
ad.plot_setup(output_svg)
ad.options.mode = "res_home"
output_homed = ad.plot_run(True)
time.sleep(5)
ad.plot_setup(output_homed)
ad.options.mode = "res_plot"
ad.plot_run()

Resume a paused plot

Syntax: options.mode = "res_plot"

Syntax: options.mode = "res_home"

It is possible to pause a plot underway, and save the progress of the plot such that the plot can be resumed later. These two "resume" modes allow you to continue working with a plot that has been paused with progress saved.

Background: When using AxiDraw Control through the Inkscape GUI, the following workflow is used to pause and resume plots that are underway:

The physical pause button on the AxiDraw is pressed. (Plots can also be paused at predefined points with AxiDraw Layer Control.)
The plot pauses after finishing the current line segment.
The SVG file is updated, saving an index of progress through the file and last-known XY carriage location.
The user may then use the Resume tab to return the carriage home or to resume the plot, using the stored plot progress data from the file as a reference.

The same basic procedure may be used through the python API, if the updated SVG is collected by as the output of plot_run, for example as: output_svg = plot_run(True).

The two "resume" modes available are:

res_home: Return to Home Corner (only)
res_plot: Resume plotting (From Home or Where Paused)

Please note that these modes can only be used if the file contains a stored record of the last-known carriage position, as well as the progress through the file. These records are generated automatically when a plot is paused, and included in the output SVG. You must use this output SVG as the input to the next plotting cycle, by using plot_setup.

The resume functionality allows the chained action of first moving to the home position (if and only if performed via res_home and saving the progress of having done so) and then using res_plot to resume plotting.

manual_cmd

Specify the manual command to execute

Syntax: options.manual_cmd = "command_name"

This parameter allows you to specify exactly which particular "manual" command will be executed if the mode is set to manual. This parameter is ignored if any mode other than manual is active.

Please note that while some of these commands do perform movements, these commands should not be considered "real time" control commands. They are intended as utility commands, for test, setup, and calibration. (If you need real-time movement commands, consider using the Interactive context instead.)

An input SVG file is required when using manual mode. The contents of the file are ignored except when executing strip_data.

The following is a list of allowed values of the manual_cmd parameter. Each of these commands will be described in detail, after the list.

Value	Description
`ebb_version`	Query EBB firmware version [DEFAULT]
`lower_pen`	Lower the pen
`raise_pen`	Raise the pen
`walk_x`	Walk carriage in X by a given distance
`walk_y`	Walk carriage in Y by a given distance
`enable_xy`	Enable (energize) XY stepper motors
`disable_xy`	Disable (de-energize) XY stepper motors
`bootload`	Enter EBB bootloader mode
`strip_data`	Strip plotter data from file
`list_names`	Read USB "nickname" or ports of all attached machines
`read_name`	Read the USB "nickname" of the AxiDraw
`write_name`	Write the USB "nickname" of the AxiDraw

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

ebb_version

manual_cmd: ebb_version

Example 1. Query the EBB firmware version:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "ebb_version"
ad.plot_run()

Typical response:

EBBv13_and_above EB Firmware Version 2.5.5

Manual command: Query EBB firmware version

Syntax: options.manual_cmd = "ebb_version"

Query and report the firmware version of the AxiDraw's EBB control board. This is the default option in manual mode.

As of this writing, the current firmware version is 2.5.5. To update the firmware on your AxiDraw, please see these instructions.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

lower_pen, raise_pen

manual_cmd: lower pen, raise pen

Example 1: Lower the pen:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "lower_pen"
ad.plot_run()

Example 2: Raise the pen, very slowly (10% speed), to 70% height:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "raise_pen"
ad.options.pen_rate_raise = 10
ad.options.pen_pos_up = 70
ad.plot_run()

Manual commands: Lower or raise the pen holder

Syntax: options.manual_cmd = "lower_pen"

Syntax: options.manual_cmd = "raise_pen"

The lower_pen and raise_pen manual commands will, respectively, lower or raise the pen holder. These are often useful for setup and verification.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

walk_x, walk_y

manual_cmd: walk_x, walk_y

Example 1: Move the carriage 1 inch in the y direction (one inch forward and away from Home):

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "walk_y"
ad.options.walk_dist = 1.0
ad.plot_run()

Example 2: Move the carriage 1.5 inches in the +x direction, and then back:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "walk_x"
ad.options.walk_dist = 1.5
ad.plot_run()
ad.options.walk_dist = -1.5
ad.plot_run()

Example 3: Move the carriage in a square, 10.0 cm on a side, with different speeds for each side of movement:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "walk_x"
ad.options.walk_dist = 3.937
ad.plot_run()
ad.options.manual_cmd = "walk_y"
ad.options.walk_dist = 3.937
ad.plot_run()
ad.options.manual_cmd = "walk_x"
ad.options.walk_dist = -3.937
ad.plot_run()
ad.options.manual_cmd = "walk_y"
ad.options.walk_dist = -3.937
ad.plot_run()

Manual commands: Walk the carriage in the X or Y direction

Syntax: options.manual_cmd = "walk_x"

Syntax: options.manual_cmd = "walk_y"

These two "walk" commands will move the AxiDraw carriage by a distance given by the value of the walk_dist parameter, along one axis or the other.

The walk_dist parameter has a default value of 1.0. The distance is given in inches. (1 inch is defined as exactly 2.54 cm.)

Walk movements are relative to the current position (not absolute), and are NOT checked versus the current carriage position for sane range of motion. Furthermore, walk movements are "out of band" movements; they do not update any kind of record about the current carriage position.

Use caution: These are fully manual commands, and can easily run the AxiDraw past its safe range of motion. After making manual movements, and before plotting, one should return the AxiDraw carriage to the Home corner.

Please note that these "walk" commands are not meant as a substitute for full motion control. They are provided since they may occasionally provide utility in test, setup, and calibration routines.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

enable_xy, disable_xy

manual_cmd: enable_xy, disable_xy

Example 1: Enable the XY stepper motors:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "enable_xy"
ad.plot_run()

Example 2: Disable the XY stepper motors:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "disable_xy"
ad.plot_run()

Manual commands: Enable or Disable the XY motors

Syntax: options.manual_cmd = "enable_xy"

Syntax: options.manual_cmd = "disable_xy"

These two commands turn on or turn off, respectively, power to the pair of stepper motors that controls the XY position of the AxiDraw carriage.

Stepper motor power is off by default at power up. It is often useful to turn off power to the XY motors so that the carriage can be manually moved to the home corner, prior to plotting.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

bootload

manual_cmd: bootload

Example: Put the AxiDraw into bootloader mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "bootload"
ad.plot_run()

Manual command: Enter EBB Bootloader Mode

Syntax: options.manual_cmd = "bootload"

This command will put the AxiDraw's EBB control board into bootloader mode. This is a special mode that is sometimes used as part of the process of updating the EBB firmware. This command is not used in any part of normal AxiDraw operation.

Bootloader mode may be identified by a particular rhythmic blinking of LEDs on the control board. If you should accidentally enter bootloader mode, disconnect the AxiDraw from both USB and power and then connect them again.

See ebb_version for more about firmware versions and updating.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

strip_data

manual_cmd: strip_data

Example: Strip AxiDraw data from file.svg and save the resulting SVG as a string in a variable named output_svg:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "strip_data"
output_svg = ad.plot_run(True)

Manual command: Strip plotter data from SVG file

Syntax: options.manual_cmd = "strip_data"

The command removes any AxiDraw specific plotter data (such as saved position data for the pause and resume feature) from the input file.

In practice it has no effect unless the output SVG is generated and saved.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

list_names

manual_cmd: list_names

Example. List available AxiDraw units:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "list_names"
ad.plot_run()

Typical response (with two connected AxiDraw units, on Mac):

East
/dev/cu.usbmodem1441

Typical response (with two connected AxiDraw units, on Windows):

East
COM4

Manual command: List attached AxiDraw units

Syntax: options.manual_cmd = "list_names"

List connected AxiDraw units, by USB "nickname" or by their USB port enumeration. AxiDraw units with firmware v2.5.5 or newer may have a USB "nickname" assigned to them. Units with older firmware will be listed as port designations.

This list of connected units does not indicate whether or not an AxiDraw is presently busy with another task; it simply lists each unit that is detected by your computer's USB interface.

See documentation for read_name and write_name below for more about AxiDraw naming.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

read_name

manual_cmd: read_name

Example: Read the USB Nickname from a single connected AxiDraw:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "read_name"
ad.plot_run()

Typical response:

AxiDraw nickname: AxiDraw 16

Manual command: Read AxiDraw USB Nickname

Syntax: options.manual_cmd = "read_name"

The read_name option is for reading an assigned USB "nickname." A nickname may be assigned to a given AxiDraw if it has firmware version 2.5.5 or newer. Nicknames are not required, but may be helpful when operating more than one AxiDraw: You can specify the given machine by name. (See the port option for additional information.)

When reading the name, it may be helpful to disconnect all AxiDraw units other than that one, so that you can be sure of which AxiDraw you are communicating with. Alternately, you can use an identifying action (say, toggling the pen) to identify which unit you are communicating with, or specify a port option.

The manual_cmd options are only applicable for use within the Plot context. They cannot be used within an Interactive context session.

write_name

manual_cmd: write_name

Example 1: Write a USB Nickname ("AxiDraw 17") to a single connected AxiDraw:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "write_nameAxiDraw 17"
ad.plot_run()

Typical response:

Nickname written. Rebooting EBB.

Example 2: Clear the USB Nickname from the Axidraw nicknamed "AxiDraw 17":

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.port = "AxiDraw 17"
ad.options.mode = "manual"
ad.options.manual_cmd = "write_name"
ad.plot_run()

Manual command: Write AxiDraw USB Nickname

Syntax: options.manual_cmd = "write_name[NICKNAME]"

The write_name command is for assigning a USB "nickname". A nickname may be assigned to a given AxiDraw if it has firmware version 2.5.5 or newer. Nicknames are not required, but may be helpful when operating more than one AxiDraw: You can specify the given machine by name. (See the --port parameter for additional information.)

When writing the name, it may be helpful to disconnect all AxiDraw units other than that one, so that you can be sure of which AxiDraw you are communicating with. Alternately, you can use an identifying action (say, toggling the pen) to identify which unit you are communicating with, or specify a port option.

When using write_name, the name itself is specified by concatenating the name with the write_name parameter. For example as write_nameNorth to assign the nickname "North". The name may be up to 16 characters long. Using a nickname of at least 3 characters is recommended. Writing an empty string (with nothing following write_name) will clear the nickname.

Since the nickname parameter is stored in a certain flash memory cell that can only be written a finite number of times, avoid applications that involve automated, repeated changes to the nickname tag.

walk_dist

walk_dist

Example: Move the carriage 1.5 inches in the +x direction:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "manual"
ad.options.manual_cmd = "walk_x"
ad.options.walk_dist = 1.5
ad.plot_run()

Walk Distance

Syntax: options.walk_dist=value

The distance to move the XY carriage of the AxiDraw, when in manual mode, and the manual_cmd parameter specifies either walk_x or walk_y.

The distance is given in inches. (1 inch is defined as exactly 2.54 cm.)

The value of walk_dist is a floating point number, with a default value of 1.0. Recommended values of the walk_dist parameter are in the range of -11.0 to +11.0. Larger distances can be achieved on larger AxiDraw models.

Walk movements are relative to the current position (not absolute), and are NOT checked for sane range of motion. These are fully manual commands, and can easily run the AxiDraw past its safe range of motion.

The "walk" commands are not meant as a substitute for full motion control, but are occasionally helpful for (e.g.,) calibration routines.

Allowed values: Floating point numbers (not limit checked).

Default: 1.0 (not adjustable).

layer

layer

Example: Plot only layers with layer name beginning with "3":

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "layers"
ad.options.layer = 3
ad.plot_run()

Select layer(s) to plot

Syntax: options.layer=value

Specify a number which indicates which layer (or layers) will be plotted when plotting in layers mode.

Normally, when plot mode is selected, we plot paths from all layers. You can also choose to plot a single layer or group of layers, for example to plot only a single color of ink.

Plotting in this mode, with layer specified will plot only layers whose names begin with the selected number.

For example, a layer named "5-red" will be printed if the number 5 is selected, but a layer named "2-black" or "guide lines" will not be.

Allowed values: Integers from 1 to 1000.

Default: 1, given by default_Layer in axidraw_conf.py

copies

copies

Example 1: Plot a file two times, using default parameters:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.copies = 2
ad.plot_run()

Example 2: Plot a file continuously (until pause button pressed):

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.copies = 0
ad.plot_run()

Example 3: Plot a file 25 times, with a 5 s delay between each plot:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.copies = 25
ad.options.page_delay = 5
ad.plot_run()

Number of copies to plot

Syntax: options.copies=value

If copies has a value other than 0, then a plot that is started in plot mode or layers mode will be plotted that number of times. This parameter has no effect in modes other than plot or layers.

An optional delay may be chosen between subsequent plots (e.g., for changing paper) with the page_delay parameter.

A value of 0 copies is a special value that will begin plotting a continuous sequence of copies, without a scheduled end. The sequence will continue until the physical pause button is pressed, unless the file itself specifies a pause through AxiDraw Layer Control.

A set of plots in progress can be canceled at any time by pressing the physical pause button on the AxiDraw. If a plot is active when the button is pressed, it will stop at that location in the usual way (saving progress in the output file, if an output file is specified). If the pause button is pressed while at home waiting between copies, then it simply exits without plotting any additional copies and without an error message.

Allowed values: Integers from 0 to 9999.

Default: 1, given by copies in axidraw_conf.py

page_delay

page_delay

Example 1: Plot a file 2 times, with a 5 s delay between plots

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.copies = 2
ad.options.page_delay = 5
ad.plot_run()

Example 2: Plot continuously, with a 30 s delay between each plot:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.copies = 0
ad.options.page_delay = 30
ad.plot_run()

Delay between copies

Syntax: options.page_delay=value

When plotting multiple copies, specify the delay in seconds between subsequent plots.

This value is used to specify the time interval that the AxiDraw dwells at the home position between subsequent layer or document plots, when plotting multiple copies. See the description of copies for more information.

Allowed values: Non-negative numbers.

Default: 15; set in axidraw_conf.py

auto_rotate

auto_rotate

Example: Plot a file, with auto_rotate disabled:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.auto_rotate = False
ad.plot_run()

Enable auto-rotate

Syntax: options.auto_rotate=value

Disable auto-rotate; preserve plot orientation.

By default "auto rotate" is enabled: If the SVG file being plotted has a page size that is taller than it is wide, then it will print in landscape mode rather than portrait mode.

Auto-rotate may be disabled by setting the auto_rotate option to False. If auto_rotate is disabled, plot orientation will be preserved, which may result in clipping of the artwork to the available plot area.

Allowed values: True, False.

Default: True; set in axidraw_conf.py

preview

preview

Example 1: Do not plot a file, but report how long it will take to plot.

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.preview = True
ad.options.report_time = True
ad.plot_run()

Example 2: Preview a file, generating a rendered preview of all motion, making use of the the rendering option to generate output SVG as "output_svg" that could be saved as an SVG file

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.preview = True
ad.options.rendering = 3
output_svg = ad.plot_run(True)

Plot Preview

Syntax: options.preview=value

Plot Preview is an offline simulation mode where the serial port is not used, and the AxiDraw does not move. This can be useful for one or more of the following reasons:

To estimate (in combination with report_time) the duration of a plot.
To render (if an output file is given) a graphical representation of the plot, to verify that the file will plot correctly.
To perform a "preflight check" for any errors that might be encountered while plotting the file.

Since it is an offline simulation mode, it can be used even without an AxiDraw present.

Note that the Plot Preview can be used in combination with other modes. If enabled, no serial communication will be attempted, so certain operations (e.g., raise pen) will neither function nor produce an error.

If Plot Preview is enabled, then it can also produce graphical output if both an appropriate value of the rendering parameter is chosen and an output file is generated.

Allowed values: True, False.

Default: False, given by preview in axidraw_conf.py

rendering

rendering

Example: Preview a file, generating a rendered preview of pen-up motion, making use of the the -v and -o options:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.preview = True
ad.options.rendering = 2
output_svg = ad.plot_run(True)

Rendering style

Syntax: options.rendering=value

When plotting with Plot Preview (preview) enabled and with SVG output generated, you can create a rendered preview of how the SVG document will plot. The rendering style option allows you to select which part (if any) of the plotting is rendered.

When a preview is rendered, that preview is added to the output SVG document, in a special "documentation" layer that will not be plotted. (For more information about documentation layers, please see the AxiDraw Layer Control documentation.)

The preview layer has sub-layers for showing the pen-up and/or pen-down movement of the carriage, depending which are generated. The rendering style parameter selects which of these (if any) are rendered.

Allowed values: Integers from 0 to 3:

0 - Do not render previews
1 - Render pen-down movement only
2 - Render pen-up movement only
3 - Render all movement, both pen-up and pen-down [DEFAULT]

Default: 3 (render all movement), given by rendering in axidraw_conf.py

report_time

report_time

Example: Plot a file and report time elapsed:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.report_time = True
ad.plot_run()

Report time elapsed

Syntax: options.report_time=value

Report time and distance plotted after each plot finishes.

By default, this option is disabled. Enabling it will print a report of time and distance travelled after each plot finishes. Using this mode in combination with Plot Preview (preview) can provide you with a time estimate of each plot, without requiring the use of the AxiDraw.

This mode may be enabled by setting report_time equal to True.

Allowed values: True, False.

Default: False, given by report_time in axidraw_conf.py

Options (Interactive)

One option, units, applies only in the Interactive context, within a python script.

units

units

Example 1: Move to different positions, givin in inch and cm units:

from pyaxidraw import axidraw   
ad = axidraw.AxiDraw()          
ad.interactive()            
ad.connect()                    # Open serial port to AxiDraw 
ad.moveto(1,1)                  # Pen-up move to (1,1) inch

ad.options.units = 1            # set working units to cm.
ad.update()                     # Process changes to options 
ad.line(5.08,5.08)              # Relative line of (2,2) inches
ad.moveto(0,0)                  # Pen-up move, back to origin.
ad.disconnect()                 # Close serial port to AxiDraw

Plot units

Syntax: options.units=value

Set the units for movement commands given in the Interactive context. If you change the units after calling connect(), use the update() method to process that change before calling additional motion commands.

Allowed values: Integers from 0 to 1:

0 - Inches [DEFAULT]
1 - Centimeters

Default: 0 (inches; not adjustable).

Functions: Plot

This is the python function reference for the functions available within the Plot context. These functions do not apply in the Interactive context.

Each of these functions will be described individually, after the list.

Function	Description
`plot_setup()`	Parse SVG file and intialize Plot context.
`plot_run()`	Perform the specified Plot context action.

plot_setup

plot_setup()

Example: Plot a file until it is paused (by button press or by AxiDraw Layer Control). Wait 5 seconds. Then move the XY carriage home.

import time
from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
output_svg = ad.plot_run(True)
time.sleep(5)
ad.plot_setup(output_svg)
ad.options.mode = "res_home"
output_homed = ad.plot_run(True)

Parse SVG file and intialize Plot context

Syntax: plot_setup(svg_input)

The plot_setup() function parses the input SVG file and initializes the various configuration option variables. Calling this function configures the software into the Plot context. This function must be called before setting the the values of any configuration option variables.

The argument "svg_input" is required. It may be the name of an SVG file (which will be opened and parsed) or it may be a python string that contains the contents of an SVG file. The example shown illustrates calling plot_setup() with both an SVG file as input as well as a string containing the contents of an SVG file.

plot_run

plot_run()

Example 1: Toggle the pen up or down, using "toggle" mode:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
ad.options.mode = "toggle"
ad.plot_run()

Example 2: Plot file.svg and capture the output as output_svg:

from pyaxidraw import axidraw 
ad = axidraw.AxiDraw()
ad.plot_setup("file.svg")
output_svg = ad.plot_run(True)

Perform the action that is configured within Plot context

Syntax: plot_run(output=False)

This function performs the action (plotting or otherwise) as set by the configuration variables that you have specified. Broadly speaking, this is the function "runs the AxiDraw software" when working in the Plot context.

By default, no output is returned by this function. If you would like to generate SVG output, call plot_run(True), for example as: output_svg = ad.plot_run(True)

The output that is returned is an output string consisting of the serialized contents of an SVG file. The output SVG contains the same SVG drawing that it accepted as input, but may also have plot progress saved in the file, or a rendered preview contained within it. You may choose to save this output SVG as an SVG file.

Functions: Interactive

This is the python function reference for the functions available within the Interactive context. These functions do not apply in the Plot context.

Each of these functions will be described individually, after the list.

Function	Description
`interactive()`	Initialize Interactive context.
`connect()`	Open serial connection to AxiDraw.
`disconnect()`	Close serial connection to AxiDraw.
`update()`	Apply changes to options.
`goto()`	Absolute move to (x,y) location.
`moveto()`	Absolute pen-up move to (x,y) location.
`lineto()`	Absolute pen-down move to (x,y) location.
`go()`	Relative move of distance (Δx,Δy).
`move()`	Relative pen-up move of (Δx,Δy).
`line()`	Relative pen-down move of (Δx,Δy).
`penup()`	Raise the pen.
`pendown()`	Lower the pen

interactive

interactive()

Example: Draw a single line in Interactive context, using absolute moves:

from pyaxidraw import axidraw   # import module
ad = axidraw.AxiDraw()          # Initialize class
ad.interactive()                # Enter interactive context
ad.connect()                    # Open serial port to AxiDraw 
ad.moveto(1,1)                  # Pen-up move to (1,1) inches
ad.lineto(2,1)                  # Pen-down move, to (2,1) inches
ad.moveto(0,0)                  # Pen-up move, back to origin
ad.disconnect()                 # Close serial port to AxiDraw

Initialize Interactive context

Syntax: interactive()

The interactive() function configures the software into the Interactive context. This function must be called before setting the the values of any configuration option variables within Interactive context.

connect

connect()

Example: Draw a single line in Interactive context using relative moves, with a pen-down speed of 20%:

from pyaxidraw import axidraw  
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.speed_pendown = 20
connected = ad.connect()
if not connected:
    return
ad.move(1,1)
ad.line(1,1)
ad.move(-2,-2)  # Pen-up move back to origin
ad.disconnect()

Open serial connection to AxiDraw

Syntax: connect()

The nature of an Interactive context session is that you directly specify not only every individual movement, but also when the session begins and ends. The connect() function a USB serial connection to the AxiDraw. It also applies any option values that you have
set after calling interactive(). The port must be closed with the disconnect() function at the end of your session. The function returns either True or False, respectively, if it successfully connected or did not.

Note that in addition to opening the USB connection, connect() is also used to process and apply any plot options that you wish to set. If you wish to change one or more options after calling connect(), use the update() method to process the changes to the options before calling additional motion commands.

In detail, connect() does the following:

Open the USB connection to AxiDraw
Parse and apply settings
Raise the pen
Enable the XY stepper motors (if not powered on)
Set the current XY position to (0,0)

Options that specify the USB port or its behavior (port or port_config) must be specified before (not after) opening the port with connect().

You must close the connection to the AxiDraw at the end of your session, using disconnect().

disconnect

disconnect()

Example: Open and close an interactive connection to AxiDraw:

from pyaxidraw import axidraw  
ad = axidraw.AxiDraw()
ad.interactive()
ad.connect()
ad.disconnect()

Close serial connection to AxiDraw

Syntax: disconnect()

The disconnect() function closes a serial connection to AxiDraw that was opened with the connect() function.

update

update()

Example: Use update() to apply changes to options after connect():

from pyaxidraw import axidraw   # import module
ad = axidraw.AxiDraw()          # Initialize class
ad.interactive()                # Enter interactive context
ad.connect()                    # Open serial port to AxiDraw 
ad.moveto(1,1)                  # Pen-up move to (1,1) inch
ad.options.units = 1            # set working units to cm.
ad.options.speed_pendown = 10   # set pen-down speed to 10%
ad.update()                     # Process changes to options 
ad.move(5.08,5.08)              # Relative move: (2,2) inches
ad.moveto(0,0)                  # Pen-up move, back to origin.
ad.disconnect()                 # Close serial port to AxiDraw

Apply changes to options, within Interactive context

Syntax: update()

Plot options may be specified at any point after the interactive() call. Options given before connect() will be applied by connect().

If, however, you change one or more options after calling connect(), you must use the update() method to process and apply those changes before calling additional motion commands. Changing options and using then using motion commands before calling update() may lead to undefined behavior.

Note that the options which specify the USB port or its behavior (port or port_config) must be specified before opening the port with connect(); they cannot be adjusted once the port is already open, even by update().

goto

goto()

Example: Draw a square using goto() for absolute position moves, in combination with penup() and pendown() commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.speed_pendown = 50   # set pen-down speed to 50%
ad.connect()                    # Open port to AxiDraw 
ad.goto(1,1)                    # Move to (1,1) inch
ad.pendown()                    # Lower pen
ad.goto(3.5,1)                  # Move to (3.5,1) inch
ad.goto(3.5,3.5)                # Move to (3.5,3.5) inch
ad.goto(1,3.5)                  # Move to (1,3.5) inch
ad.goto(1,1)                    # Move to (1,1) inch
ad.penup()                      # Raise pen
ad.goto(0,0)                    # Move to Home (0,0)
ad.disconnect()                 # Close serial port

Absolute move to (x,y) location

Syntax: goto(final_x,final_y)

The goto(x,y) command is an absolute move command, that moves the carriage to the final XY position that you have specified. In combination with setting options and using penup() and pendown(), it is sufficient to provide essentially any type of movement that is required.

The arguments to goto() are floating point numbers that represent the movement destination position. The units are in inches, unless specified otherwise with the units option. In most cases both arguments should be non-negative, since all allowed positions are in the (positive,positive) quadrant with respect to the Home position.

The limits of travel are given by the hardware model, as specified with the model option. Limit checking assumes that the session has been started with the AxiDraw carriage located at the Home position.

Relative movement commands can be used together with absolute movement commands as needed.

moveto

moveto()

Example: Draw a square using moveto() and lineto() absolute position movement commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.speed_pendown = 50   # set pen-down speed to 50%
ad.connect()                    # Open port to AxiDraw 
ad.moveto(1,1)                  # Move to (1,1) inch
ad.lineto(3.5,1)                # Move to (3.5,1) inch
ad.lineto(3.5,3.5)              
ad.lineto(1,3.5)                
ad.lineto(1,1)                  
ad.moveto(0,0)                  # Raise pen, return home
ad.disconnect()                 # Close serial port

Absolute pen-up move to (x,y) location

Syntax: moveto(final_x,final_y)

The moveto(x,y) command is an absolute move command, that performs a pen-up movement of the carriage to the final XY position that you have specified. In combination with setting options and using the lineto() function, it is sufficient to provide essentially any type of movement that is required.

The function works by raising the pen (if it is not already raised) and then performing a goto() movement to the given position.

The arguments to moveto() are floating point numbers that represent the movement destination position. The units are in inches, unless specified otherwise with the units option. In most cases both arguments should be non-negative, since all allowed positions are in the (positive,positive) quadrant with respect to the Home position.

lineto

lineto()

Example: Draw a square using moveto() and lineto() absolute position movement commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.connect()                    # Open port to AxiDraw 
ad.moveto(1,1)                  # Move to (1,1) inch
ad.lineto(3.5,1)                # Move to (3.5,1) inch
ad.lineto(3.5,3.5)              
ad.lineto(1,3.5)                
ad.lineto(1,1)                  
ad.moveto(0,0)                  # Raise pen, return home
ad.disconnect()                 # Close serial port

Absolute pen-down move to (x,y) location

Syntax: lineto(final_x,final_y)

The lineto(x,y) command is an absolute move command, that performs a pen-down movement of the carriage to the final XY position that you have specified. In combination with setting options and using the moveto() function, it is sufficient to provide essentially any type of movement that is required.

The function works by lowering the pen (if it is not already lowered) and then performing a goto() movement to the given position.

The arguments to lineto() are floating point numbers that represent the movement destination position. The units are in inches, unless specified otherwise with the units option. In most cases both arguments should be non-negative, since all allowed positions are in the (positive,positive) quadrant with respect to the Home position.

go

go()

Example: Draw a square using go() for relative position moves, in combination with penup() and pendown() commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.speed_pendown = 50   # set pen-down speed to 50%
ad.connect()                    # Open port to AxiDraw 
ad.go(1,1)                      # Move to (1,1) inch
ad.pendown()                    # Lower pen
ad.go(2.5,0)                    # Move to (3.5,1) inch
ad.go(0,2.5)                    # Move to (3.5,3.5) inch
ad.go(-2.5,0)                   # Move to (1,3.5) inch
ad.go(0,-2.5)                   # Move to (1,1) inch
ad.penup()                      # Raise pen
ad.go(-1,-1)                    # Move to Home position
ad.disconnect()                 # Close serial port

Relative move by (x,y) with respect to current location

Syntax: go(delta_x,delta_y)

The go(x,y) command is a relative move command, that moves the carriage by the distances that you have specified. In combination with setting options and using penup() and pendown(), it is sufficient to provide essentially any type of movement that is required.

The arguments to go() are floating point numbers that represent the movement distances. The units are in inches, unless specified otherwise with the units option.

Relative movement commands can be used together with absolute movement commands as needed.

move

move()

Example: Draw a square using move() and line() relative position movement commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.connect()                  # Open port to AxiDraw 
ad.move(1,1)                  # Move to (1,1) inch
ad.line(2.5,0)                # Lower pen, move to (3.5,1) inch
ad.line(0,2.5)                # Move to (3.5,3.5) inch
ad.line(-2.5,0)               # Move to (1,3.5) inch
ad.line(0,-2.5)               # Move to (1,1) inch
ad.move(-1,-1)                # Raise pen, return home
ad.disconnect()               # Close serial port

Relative pen-up move by (x,y) with respect to current location

Syntax: move(delta_x,delta_y)

The move(x,y) command is a relative move command, that performs a pen-up movement of the carriage by the distances that you have specified. In combination with setting options and using the line() function, it is sufficient to provide essentially any type of movement that is required.

The function works by raising the pen (if it is not already raised) and then performing a go() movement with the given distances

The arguments to move() are floating point numbers that represent the movement distances. The units are in inches, unless specified otherwise with the units option.

line

line()

Example: Draw a square using move() and line() relative position movement commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.connect()                  # Open port to AxiDraw 
ad.move(1,1)                  # Move to (1,1) inch
ad.line(2.5,0)                # Lower pen, move to (3.5,1) inch
ad.line(0,2.5)                # Move to (3.5,3.5) inch
ad.line(-2.5,0)               # Move to (1,3.5) inch
ad.line(0,-2.5)               # Move to (1,1) inch
ad.move(-1,-1)                # Raise pen, return home
ad.disconnect()               # Close serial port

Relative pen-down move by (x,y) with respect to current location

Syntax: line(delta_x,delta_y)

The line(x,y) command is a relative move command, that performs a pen-up movement of the carriage by the distances that you have specified. In combination with setting options and using the move() function, it is sufficient to provide essentially any type of movement that is required.

The function works by raising the pen (if it is not already raised) and then performing a go() movement with the given distances

The arguments to line() are floating point numbers that represent the movement distances. The units are in inches, unless specified otherwise with the units option.

penup

penup()

Example: Draw a line using go() and goto() for movement, in combination with penup() and pendown() commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.options.pen_pos_down = 20    # Set some options
ad.options.pen_pos_up = 80
ad.options.pen_rate_raise = 90
ad.options.accel = 80

ad.connect()                    # Open port to AxiDraw 
ad.goto(1,1)                    # Move to (1,1) inch
ad.pendown()                    # Lower pen
ad.go(2.5,2.5)                  # Move by (2.5,2.5) inch
ad.penup()                      # Raise pen
ad.goto(0,0)                    # Move to Home position
ad.disconnect()                 # Close serial port

Raise the pen

Syntax: penup()

The penup() command is a simple command that can raise then pen while in Interactive context. It is particularly useful in combination with the go() and goto() commands, which cause movements but do not raise or lower the pen.

pendown

penup()

Example: Draw some lines using mixed movement commands, in combination with penup() and pendown() commands in the Interactive context.

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
ad.connect()               # Open port to AxiDraw 
ad.moveto(1,1)             # Pen-up move to (1,1) inch
ad.pendown()               # Lower pen
ad.go(2.5,-1)              # Move by (2.5,-1) inch
ad.penup()                 # Raise pen
ad.go(0,3)                 # Move by (0,3) inch
ad.lineto(0,0)             # Pen-down move to home corner
ad.penup()                 # Raise pen
ad.disconnect()            # Close serial port

Raise the pen

Syntax: pendown()

The pendown() command is a simple command that can lower then pen while in Interactive context. It is particularly useful in combination with the go() and goto() commands, which cause movements but do not raise or lower the pen.

Revision Notes

v 2.3.0 -- 2018-12-08

25% increase in maximum XY speed now allowed. Change installation process to allow installation via pip.

v 2.2.0 -- 2018-10-01

Automatic checking for updates now performed with the sysinfo mode. Add note about "reorder" mode (CLI only).

v 2.1.1 -- 2018-08-31

Paths now clipped at edges of SVG document, when using Plot context.

v. 2.1.0 -- 2018-08-24

Paths and interactive XY movements now clipped with pen-up at extents of machine travel.

v. 2.0.0 -- 2018-08-22

Significant, breaking changes to option names and syntax, for clarity and compatibility. We recommend that you read through this documentation for the new option names.

Summary of changes:

Changed command line argument parser format
Changed names of most input parameters
Added short names for input parameters
Boolean input parameters have been changed to input flags
For details, please see changelog.txt included with the download.

Introduction

About AxiDraw

Installation

Quick start: Plotting SVG

Quick start: Interactive XY

Setting options

Options (General)

speed_pendown

speed_penup

accel

pen_pos_down

pen_pos_up

pen_rate_lower

pen_rate_raise

pen_delay_down

pen_delay_up

const_speed

model

port

port_config

Options (Plot)

mode

plot

layers

align

toggle

manual

sysinfo

version

res_plot, res_home

manual_cmd

ebb_version

lower_pen, raise_pen

walk_x, walk_y

enable_xy, disable_xy

bootload

strip_data

list_names

read_name

write_name

walk_dist

layer

copies

page_delay

auto_rotate

preview

rendering

report_time

Options (Interactive)

units

Functions: Plot

plot_setup

plot_run

Functions: Interactive

interactive

connect

disconnect

update

goto

moveto

lineto

go

move

line

penup

pendown

Revision Notes

Copyright