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 SVGQuick 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 most other operations that are outside of the Interactive context. (Certain utility modes that do not plot a file will work correctly without a file input.) 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 XYExample: 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 optionsOne 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_pendownExample 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_penupExample 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
accelExample 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_downExample 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_upExample 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.
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-up position value.
Allowed values: Integers from 0 to 100.
Default: 60, given by pen_pos_up
in axidraw_conf.py
pen_rate_lower
pen_rate_lowerExample 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_raiseExample 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_downExample 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_upExample 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_speedExample 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
modelExample 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
portExample 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_configExample 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
modeExample 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: Toggle the pen up or down, using "toggle" mode:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
ad.options.mode = "toggle"
ad.plot_run()
Example 3: Disable the XY stepper motors, using "manual" mode:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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 |
plot
mode: plotExample 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: layersExample 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: alignExample: Put the AxiDraw into Align mode:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
An SVG file input is to plot_setup()
is allowed but not required for this mode to operate correctly.
toggle
mode: toggleExample: Toggle the pen up or down, using "toggle" mode:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
An SVG file input is to plot_setup()
is allowed but not required for this mode to operate correctly.
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.
An SVG file input is to plot_setup()
is allowed but not required for
commands in manual mode.
sysinfo
mode: sysinfoExample: Request sysinfo:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
ad.options.mode = "sysinfo"
ad.plot_run()
Typical response (example on Mac):
Your AxiDraw has firmware version 2.6.0.
An update is available to EBB firmware v. 2.6.1;
To download the updater, please visit: axidraw.com/fw
This is AxiDraw Control version 2.3.2.
~~ 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.
An SVG file input is to plot_setup()
is allowed but not required for this mode to operate correctly.
version
mode: versionExample: Query software version:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
An SVG file input is to plot_setup()
is allowed but not required for this mode to operate correctly.
res_plot, res_home
modes: res_plot, res_homeExample: 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 SVG file input is to plot_setup()
is allowed but not required in manual mode.
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 |
ebb_version
manual_cmd: ebb_versionExample 1. Query the EBB firmware version:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.6.0. To update the firmware on your AxiDraw, please see these instructions.
lower_pen, raise_pen
manual_cmd: lower pen, raise penExample 1: Lower the pen:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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()
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.
walk_x, walk_y
manual_cmd: walk_x, walk_yExample 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()
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()
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()
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.
enable_xy, disable_xy
manual_cmd: enable_xy, disable_xyExample 1: Enable the XY stepper motors:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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()
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.
bootload
manual_cmd: bootloadExample: Put the AxiDraw into bootloader mode:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
strip_data
manual_cmd: strip_dataExample: 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 this command has no effect unless there is an input SVG file and the output SVG is both generated and saved.
list_names
manual_cmd: list_namesExample. List available AxiDraw units:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
read_name
manual_cmd: read_nameExample: Read the USB Nickname from a single connected AxiDraw:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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.
write_name
manual_cmd: write_nameExample 1: Write a USB Nickname ("AxiDraw 17") to a single connected AxiDraw:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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()
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_distExample: Move the carriage 1.5 inches in the +x direction:
from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.plot_setup()
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
layerExample: 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
copiesExample 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_delayExample 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_rotateExample: 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
previewExample 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, 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
renderingExample: 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.
Note also that this option is only applicable to the three modes which parse and plot the SVG document: plot (default), layers, and res_plot.
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_timeExample: 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.
Note also that this option is only applicable to the three modes which parse and plot the SVG document: plot (default), layers, and res_plot.
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
unitsExample 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)
Initialize Plot context and Parse SVG input
Syntax: plot_setup([svg_input])
The plot_setup
function parses the input SVG 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 SVG file argument to the function ("svg_input") is optional.
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.
If it is called without a file name argument, as plot_setup()
or
plot_setup(None)
, then the Plot context will still be initialized
but it will not have an SVG file available to plot.
This approach be helpful when
using utility modes that do not plot the file (align, toggle, manual,
sysinfo, version) since no file need be provided.
Execution of these utility modes may also be faster (particularly versus
large SVG inputs), since the input
file will not be parsed.
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()
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.
If the Plot context was initialized without an
input SVG file (using plot_setup()
or plot_setup(None)
), then the output
returned will be an "empty" SVG placeholder 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()
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.2 -- 2019-01-22
Input file no longer required for plot_setup().
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.
Copyright
Copyright 2019 Windell H. Oskay, Evil Mad Scientist Laboratories