NAV Navbar

Introduction

This documentation covers "AxiCLI", the application programming interface (API) for using AxiDraw from either the command line interface (CLI) or within shell scripts and other environments that make use of shell commands.

The primary function of this software is to plot SVG documents. This method is described below, beginning at Quick start.

While AxiCLI is designed as a "stand alone" utility, it is written in python. If you would like to control the AxiDraw from within your own python script, please see the separate API documentation for the python API. (As a side note, the python API supports an additional control method: interactive XY motion control through "moveto/lineto" type commands.)

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

Quick start

Typical usage: python axicli.py FILE_NAME OPTIONS

Example 1: Plot a file named AxiDraw_trivial.svg

python axicli.py AxiDraw_trivial.svg

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

python axicli.py input.svg -o output.svg

The output is saved as a file, called output.svg

The code examples here show the basic syntax for plotting an SVG file.

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.

A file input is required syntax, regardless of which type of command will be executed. In particular, note that even though some of the utility modes do not actually plot a file, the svg file input is still required. (As an exception to this rule, see the special commands listed below.)

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 an output SVG file. Saving the 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.

Special commands

The following three "special" commands have independent syntax and do not require an input file name to be specified:

Setting options

CLI Syntax

CLI Syntax

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

python axicli.py FILE_NAME --option_name value

Example 1. Use manual mode with the manual command to disable the XY motors:

python axicli.py file.svg --mode manual --manual_cmd disable_xy 

Example 2. Shell commands also have short forms, like this equivalent:

python axicli.py file.svg -M manual -m disable_xy 

Example 3. Simulate plotting a file, generating a rendered preview of all motion, making use of the the rendering (-g) and output file (-o) options, and saving the output file "outputfile.svg":

python axicli.py file.svg -vg3 -o outputfile.svg

Most plotting options can be set using CLI arguments.

For arguments that do take a value, specify only one value for each argument.

Each option also has a "short" single-character version. Short options can be combined together with their value without a space in between. You can also combine together multiple short (single-character) options together, so long as only the last option has a value.

Defaults and Precedence

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:

  1. Parameters values specified in the SVG file (as in, by layer names) overrule those specified either by the command line or in axidraw_conf.py.

  2. Options and values specified on the command line argument overrule those in axidraw_conf.py.

Note that each time you call AxiCLI, you are creating an independent AxiDraw session that works from default values and those that you specify. Settings are not preserved between invocations of it. For example, if you run a plot with a certain speed setting specified on the command line, subsequent plots will use the default speed unless you specify otherwise.

Finally, 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

The following is a list of optional arguments that can be applied. Each of these arguments will be described individually, after the list.

Option Description
--mode, -m Specify general mode of operation.
--speed_pendown, -s Maximum XY speed when the pen is down (plotting).
--speed_penup, -S Maximum XY speed when the pen is up.
--accel, -a Relative acceleration/deceleration speed.
--pen_pos_down, -d Pen height when the pen is down (plotting).
--pen_pos_up, -u Pen height when the pen is up.
--pen_rate_lower, -r Speed of lowering the pen-lift motor.
--pen_rate_raise, -R Speed of raising the pen-lift motor.
--pen_delay_down, -z Added delay after lowering pen.
--pen_delay_up, -Z Added delay after raising pen.
--no_rotate, -N Option: Disable auto-rotate; preserve plot orientation.
--const_speed, -C Option: Use constant speed when pen is down.
--report_time, -T Option: Report time and distance after the plot.
--manual_cmd, -M Specify which "manual" mode command to use.
--walk_dist, -w Distance to move for manual walk commands.
--layer, -l Specify which layer(s) to plot in the layers mode.
--copies, -c Specify the number of copies to plot.
--page_delay, -D Specify delay between pages, for multiple copies.
--preview, -v Option: Perform offline simulation of plot only.
--rendering, -g Option: Render motion when using preview.
--model, -L Select model of AxiDraw hardware.
--port, -p Specify a USB port or AxiDraw to use.
--port_config, -P Override how the USB ports are located.
--output_file, -o Specify an output file name.

mode

mode

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

python axicli.py file.svg --mode toggle   

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

python axicli.py file.svg -m manual -M disable_xy 

General mode of operation

Syntax: [-m, --mode] value

Specify the general mode of operation. 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
reorder Re-order the SVG file for more efficient plotting

plot

mode: plot

Example 1: Plot a file using default mode and parameters:

python axicli.py file.svg 

Example 2: The same, explicitly setting the mode:

python axicli.py file.svg --mode plot

Example 3: The same, using short codes:

python axicli.py file.svg -m plot

Plot the SVG file

Syntax: [-m plot, --mode plot]

The plot mode is for plotting an SVG file. This the default mode of operation, and generally does not need to be explicitly specified.

layers

mode: layers

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

python axicli.py file.svg --mode layers --layer 1

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 file as "output.svg":

python axicli.py file.svg -m layers -vTg3 -l5 -o output.svg

Plot a single layer (or set of layers)

Syntax: [-m layers, --mode layers]

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

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 1: Enter align mode:

python axicli.py file.svg --mode align 

Example 2: Enter align mode, setting the pen-up height to 85%:

python axicli.py file.svg -malign --pen_pos_up 85

Raise pen and disable XY stepper motors

Syntax: [-m align, --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 1: Toggle the pen up or down:

python axicli.py file.svg --mode toggle 

Example 2: Toggle the pen up or down, with pen-down and pen-up heights set to 40% and 60% respectively:

python axicli.py file.svg -mtoggle --pen_pos_down 40 --pen_pos_up 60

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

Syntax: [-m toggle, --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 for each individual manual_cmd item.

Execute a "manual" command

Syntax: [-m manual, --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" below 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 1: Request sysinfo:

python axicli.py file.svg --mode sysinfo

Example 2: Request sysinfo using short code:

python axicli.py file.svg -m sysinfo

Typical response to sysinfo request (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.2.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: [-m sysinfo, --mode sysinfo]

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

The information items listed are:

This is the only function in the AxiDraw software that uses an online connection, and it will only check for updates if explicitly requested to with the "sysinfo" mode or the Version tab within Inkscape. You can disable checking for updates (to fully disable the online connection) by editing the axidraw_conf.py file and changing the value of check_updates to False.

version

mode: version

Example 1: Request version:

python axicli.py file.svg --mode version

Example 2: Request version using short code:

python axicli.py file.svg --mode plot

Typical response:

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

AxiDraw Software Version

Syntax: [-m version, --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

Examples:

First, suppose that the AxiDraw was paused by a physical button press during a plot that was called by the following command:

python axicli.py file.svg -o temp.svg

This creates a "saved progress" output file called temp.svg.

To (A) return the AxiDraw to the home corner, use:

python axicli.py temp.svg --mode res_home 

To instead (B) resume plotting, use the following command:

python axicli.py temp.svg --mode res_plot 

One might prefer in either case (A) or (B) to save a new output file, just in case one should wish to allow additional pause/resume events:

python axicli.py temp.svg --mode res_home -o temp2.svg

python axicli.py temp.svg --mode res_plot -o temp2.svg

Again, it is possible to resume plotting after moving home via res_home. In order to do so, one needs to save the output data from the res_home command, and use that as the input for a subsequent res_plot command.

Let us suppose we are starting with the "saved progress" file temp2.svg, generated with the "res_home" resume action above. Then, one could resume plotting with the following command:

python axicli.py temp2.svg --mode res_plot

One may prefer to keep the a new file output open, should one wish to allow for subsequent pause/resume events:

python axicli.py temp2.svg --mode res_plot -o temp3.svg

Resume a paused plot

Syntax: [-m res_plot, --mode res_plot] / [-m res_home, --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:

  1. The physical pause button on the AxiDraw is pressed. (Plots can also be paused at predefined points with AxiDraw Layer Control.)
  2. The plot pauses after finishing the current line segment.
  3. The SVG file is updated, saving an index of progress through the file and last-known XY carriage location.
  4. 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 CLI, if the updated version of the SVG file is saved as the output file, by specifying an output file name.

The two "resume" modes available are:

  1. res_home: Return to Home Corner (only)
  2. 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 file.

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.

reorder

mode: reorder

Example 1: Re-order an SVG file (file.svg) for more efficient plotting, with default options, and save the output as "out.svg":

python axicli.py file.svg --mode reorder -o out.svg

Example 2: Re-order an SVG file (file.svg) for more efficient plotting, and save the output as "out.svg", breaking apart groups and sorting their elements:

python axicli.py file.svg -m reorder --group_sorting 2 -o out.svg

Example 3: Re-order an SVG file (file.svg), preserving groups as-is, and rendering a preview of pen-up travel:

python axicli.py file.svg -m reorder -G0 -g2  -o out.svg

Re-order SVG file for speed

Syntax: [-m reorder, --mode reorder]

This is an independent mode of operation that does not plot to the AxiDraw. Instead, it performs a layer-aware sorting of the plotting order (the order in which elements occur in the SVG file) to reduce the amount of pen-up travel that will occur while plotting the file.

If there are layers in the SVG file, the elements within each layer (or sublayer) will be re-ordered to reduce pen-up travel distance. All objects will be left on their original layers. Elements that are not in a layer (those in the root of the SVG document) will be sorted as though they were in a virtual layer.

When re-ordering a set of objects that include grouped elements, groups may be handled in one of three ways, selected by the value of the (group_sorting) option:

  1. Preserve groups, as-is.
  2. Re-order elements within each group. [Default]
  3. Break apart groups.

To preview the pen-up travel, you can turn on the preview rendering by setting a value of rendering equal to 2 or 3. Only the pen-up travel that is sorted by this routine will be shown. It will typically not (for example) show travel time between objects on different layers or within a layer that is preserved (and not sorted).

An output file is required for reorder mode to be useful. Best practice is to keep a copy of your original SVG file even after performing the sorting, just in case of unexpected output.

Since reorder is an "offline" mode, it can be used even without an AxiDraw present, much like plotting with the Plot Preview (preview) option enabled. (The value of preview has no bearing on the operation of reorder mode.)

Internally, reorder mode uses a simple "greedy" algorithm, which is a relatively fast, but not optimal type of sorting. Depending on the nature of the SVG file, it can in many cases it can reduce the amount of pen-up travel distance by 50-90%, and reduce the plotting time by 30-50%. These time savings should be weighed against the execution time of the sort, which may be considerable for files with a great number of separate objects.

As part of that weighing, you may find it helpful to use preview option to estimate the plot duration on files that have and have not been sorted.

speed_pendown

speed_pendown

Example 1: Plot file.svg, with maximum pen-down speed of 20% selected:

python axicli.py file.svg --speed_pendown 20

Example 2: The same, with short codes:

python axicli.py file.svg -s20

Pen-down Movement Speed

Syntax: [-s, --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: Plot file.svg, with maximum pen-up speed of 50% selected:

python axicli.py file.svg --speed_penup 50

Example 2: The same, with short codes:

python axicli.py file.svg -S50

Pen-up Movement Speed

Syntax: [-S, --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: Plot file.svg, with maximum pen-down speed of 50%, acceleration 80%:

python axicli.py file.svg --speed_pendown 50 --accel 80 

Example 2: The same, with short codes:

python axicli.py file.svg -s50 -a80 

Acceleration Factor

Syntax: [-a, --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: Plot file.svg, with pen-down height of 20%:

python axicli.py file.svg --pen_pos_down 20 

Example 2: Toggle the pen up or down, with pen-down and pen-up heights set to 10% and 90% respectively:

python axicli.py file.svg -mtoggle -d10 -u90

Example 3: Lower the pen to 30% height:

python axicli.py file.svg -mmanual -Mlower_pen -d30

Pen-down Position

Syntax: [-d, --pen_pos_down] value

DESCRIPTION

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:
Plot file.svg, with pen-up height of 80%:

python axicli.py file.svg --pen_pos_up 80 

Example 2: Toggle the pen up or down, with pen-down and pen-up heights set to 10% and 90% respectively:

python axicli.py file.svg -mtoggle -d10 -u90

Example 3: Raise the pen to 70% height:

python axicli.py file.svg -mmanual -Mraise_pen -u70

Pen-up Position

Syntax: [-u, --pen_pos_up] value

DESCRIPTION

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_lower

Example 1: Plot file.svg, lowering the pen very slowly to the paper (5% speed):

python axicli.py file.svg --pen_rate_lower 5 

Example 2: Quickly (90% speed) lower the pen to 10% height:

python axicli.py file.svg -mmanual -Mlower_pen -d10 -r90

Pen Lowering Rate

Syntax: [-r, --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. Plot file.svg, raising the pen very quickly from the paper (100% speed):

python axicli.py file.svg --pen_rate_raise 100 

Example 2: Slowly (10% speed) lower the pen to 60% height:

python axicli.py file.svg -mmanual -Mlower_pen -u60 -R10

Pen Raising Rate

Syntax: [-R, --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. Plot file.svg, adding an extra delay of 250 ms after lowering the pen:

python axicli.py file.svg --pen_delay_down 250 

Example 2. Plot file.svg, adding a "negative" delay, so that the carriage begins moving horizontally, even before it finishes lowering the pen:

python axicli.py file.svg -z -250 

Delay after lowering pen

Syntax: [-z, --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. Plot file.svg, adding an extra delay of 250 ms after raising the pen:

python axicli.py file.svg --pen_delay_up 250 

Example 2. Plot file.svg, adding a "negative" delay, so that the carriage begins moving horizontally, even before it finishes raising the pen:

python axicli.py file.svg -Z -250 

Delay after raising pen

Syntax: [-Z, --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

no_rotate

no_rotate

Example 1. Plot a file with auto-rotate disabled:

python axicli.py file.svg --no_rotate

Example 2. Plot a file in constant-speed mode, and with auto-rotate disabled:

python axicli.py file.svg -CN

Disable auto-rotate

Syntax: [-N, --no_rotate]

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 using the --no_rotate option (-N). It is a simple "flag" type argument, and takes no value argument.

To disable auto-rotate by default, edit the axidraw_conf.py configuration file and change the value of auto_rotate from True to False. (Note that there is not an override to disable preview mode if it is set as default in axidraw_conf.py.)

const_speed

const_speed

Example 1: Plot a file in constant-speed mode:

python axicli.py file.svg --const_speed

Example 2: Plot a file in constant-speed mode, and with auto-rotate disabled:

python axicli.py file.svg -CN

Plot with constant pen-down speed

Syntax: [-C, --const_speed]

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 using the --const_speed option (-C). It is a simple "flag" type argument, and takes no value argument

To enable this option by default, edit the axidraw_conf.py configuration file and change the value of const_speed from False to True.

report_time

report_time

Example 1: Plot a file and report time elapsed:

python axicli.py file.svg --report_time

Example 2: Preview a file, to see how long it will take to run with with constant-speed mode selected:

python axicli.py file.svg -vTC

Report time elapsed

Syntax: [-T, --report_time]

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.

Time reporting may be enabled by using the --report_time option (-T). It is a simple "flag" type argument, and takes no value argument.

To enable this option by default, edit the axidraw_conf.py configuration file and change the value of report_time from False to True.

manual_cmd

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 within the python API.)

An input SVG file is required by the syntax, even 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

ebb_version

manual_cmd: ebb_version

Example 1: Query the EBB firmware version:

python axicli.py file.svg --mode manual --manual_cmd ebb_version 

Example 2: Query the EBB firmware version (manual mode default):

python axicli.py file.svg -m manual

Typical response:

EBBv13_and_above EB Firmware Version 2.5.5

Manual command: Query EBB firmware version

Syntax: [-M, --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.

lower_pen, raise_pen

manual_cmd: lower pen, raise pen

Example 1: Lower the pen:

python axicli.py file.svg -m manual -M lower_pen 

Example 2: Raise the pen, very slowly

python axicli.py file.svg -m manual -M raise_pen --pen_rate_raise 1

Manual commands: Lower or raise the pen holder

Syntax: [-M, --manual_cmd] lower_pen

Syntax: [-M, --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_y

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

python axicli.py file.svg --mode manual --manual_cmd walk_y

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

python axicli.py file.svg -m manual -M walk_x --walk_dist 1.5
python axicli.py file.svg -m manual -M walk_x --walk_dist -1.5

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

python axicli.py file.svg -m manual -M walk_x -w 3.937 -s 10
python axicli.py file.svg -m manual -M walk_y -w 3.937 -s 20
python axicli.py file.svg -m manual -M walk_x -w -3.937 -s 30
python axicli.py file.svg -m manual -M walk_y -w -3.937 -s 40

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

Syntax: [-M, --manual_cmd] walk_x

Syntax: [-M, --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_xy

Example 1: Enable the XY stepper motors:

python axicli.py file.svg --mode manual --manual_cmd enable_xy 

Example 2: Disable the XY stepper motors:

python axicli.py file.svg -m manual -M disable_xy 

Manual commands: Enable or Disable the XY motors

Syntax: [-M, --manual_cmd] enable_xy

Syntax: [-M, --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: bootload

Example: Put the AxiDraw into bootloader mode:

python axicli.py file.svg --mode manual --manual_cmd bootload

(Note that you will need to either update the firmware OR disconnect both power and USB after executing this command.)

Manual command: Enter EBB Bootloader Mode

Syntax: [-M, --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_data

Example: Strip AxiDraw data from file.svg and save the result as output.svg:

python axicli.py file.svg -m manual -M strip_data -o output.svg

Manual command: Strip plotter data from SVG file

Syntax: [-M, --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 an output file is specified.

list_names

manual_cmd: list_names

Example: List available AxiDraw units:

python axicli.py file.svg -m manual -M list_names 

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: [-M, --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_name

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

python axicli.py file.svg --mode manual --manual_cmd read_name

Typical response:

AxiDraw nickname: AxiDraw 16

Manual command: Read AxiDraw USB Nickname

Syntax: [-M, --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 parameter 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_name

Example 1: Write a USB Nickname to a single connected AxiDraw:

python axicli.py file.svg -m manual -M "write_nameAxiDraw 17"

Typical response:

Nickname written. Rebooting EBB.

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

python axicli.py file.svg -m manual --port "AxiDraw 17" -M "write_name"

Manual command: Write AxiDraw USB Nickname

Syntax: [-M, --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 1: Move the carriage 2.5 inches in the +x direction, and then back.

python axicli.py file.svg --mode manual --manual_cmd walk_x --walk_dist 2.5
python axicli.py file.svg --mode manual --manual_cmd walk_x --walk_dist -2.5

Example 2: The same, with short codes:

python axicli.py file.svg -m manual -M walk_x -w 2.5
python axicli.py file.svg -m manual -M walk_x -w -2.5

Walk Distance

Syntax: [-w, --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.)

walk_dist is a floating point value, 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 1: Plot only layers with layer name beginning with "3":

python axicli.py file.svg --mode layers --layer 3

Example 2: The same, with short codes:

python axicli.py file.svg -m layers -l3

Select layer(s) to plot

Syntax: [-l, --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:

python axicli.py file.svg --copies 2  

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

python axicli.py file.svg -c0

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

python axicli.py file.svg  --copies 25 --page_delay 5

Number of copies to plot

Syntax: [-c, --copies] value

If copies has a value other than 0, then a plot that is started in plot 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.

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

python axicli.py file.svg --copies 2 --page_delay 5 

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

python axicli.py file.svg -c0 -D30 

Delay between copies

Syntax: [-D, --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

preview

preview

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

python axicli.py file.svg -v --report_time 

Example 2: Preview a file, generating a rendered preview of all motion, making use of the the rendering (-g) and output file (-o) options to save the output file as "outputfile.svg"

python axicli.py file.svg -vg3 -o outputfile.svg

Plot preview

Syntax: [-v, --preview]

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:

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.

Preview mode may be enabled by using the --preview (-v) option. It is a simple "flag" type argument, and takes no additional values.

Default: False, given by preview in axidraw_conf.py

rendering

rendering

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

python axicli.py file.svg -vg 2 -o outputfile.svg

Example 2: Preview a file, generating a rendered preview of pen-down motion, and reporting the estimated duration of the plot:

python axicli.py file.svg -Tvg 1 -o outputfile.svg

Rendering style

Syntax: [-g, --rendering] value

When plotting with Plot Preview --preview (-v) enabled and with an output file (--output_file or -o) specified, you can generate 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:

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

group_sorting

group_sorting

Example 1: Re-order an SVG file (file.svg) for more efficient plotting, and save the output as "out.svg", breaking apart groups and sorting their elements:

python axicli.py file.svg -m reorder --group_sorting 2 -o out.svg

Example 2: Re-order an SVG file (file.svg), preserving groups as-is, and rendering a preview of pen-up travel:

python axicli.py file.svg -m reorder -G0 -g2  -o out.svg

Group handling option for reorder mode

Syntax: [-G, --group_sorting] value

When re-ordering elements in the SVG file in reorder mode, this parameter controls how groups are handled.

Allowed values: Integers from 0 to 2:

Default: 2 (Re-order group elements), not adjustable.

If group_sorting of 0 is selected, to preserve groups, elements within each group encountered will be left in their original order within the group. The order of groups with respect to other groups and elements on the same layer (or virtual layer) will be altered to reduce pen-up travel.

If group_sorting of 1 is selected (or no value of group_sorting is given), the elements within each group in the file will be re-ordered, even including highly-nested subgroups of subgroups.

If group_sorting of 2 is selected, to break apart groups, each group that is encountered will be dissolved, and the contents of the group will be re-ordered along with other elements on the same layer (or virtual layer).

model

model

Example 1: Plot a file, while setting size limits for AxiDraw V3/A3:

python axicli.py file.svg --model 2

Example 2: Plot the same file, restricting the motion area to that of the AxiDraw V3 XLX:

python axicli.py file.svg -L3

AxiDraw hardware model

Syntax: [-L, --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 plot was started in the Home Corner, and that no loss of position control has occurred. Paths in the document will be clipped to the edges of the SVG document or of physical travel, whichever is smaller for each axis.

Limits are not checked when using manual walk commands.

Allowed values: Integers from 1 to 3:

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: Plot a file to the USB port enumerated as /dev/cu.usbmodem1441:

python axicli.py file.svg -p /dev/cu.usbmodem1441

Example 2: Plot a file to an AxiDraw with USB Nickname "GlueDispenser":

python axicli.py file.svg -pGlueDispenser

Example 3: Plot a file to an AxiDraw with USB Nickname "UV LED Array":

python axicli.py file.svg --port "UV LED Array"

Specify a USB port or named AxiDraw to use

Syntax: [-p, --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 a file 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:

python axicli.py file.svg -p "UV LED Array" --port_config 0

Example 2: Plot a file to the first available AxiDraw found on USB:

python axicli.py file.svg --port "AxiDraw 19" -P1

Example 3: Plot the same file simultaneously to all attached AxiDraw units:

python axicli.py file.svg -P3

Override how the USB ports are located

Syntax: [-P, --port_config] value

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

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

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.

If port_config is 3, the software will simultaneously to plot to all AxiDraw units located via USB. While most features work the same in this fashion, note that are some important differences. Please see "Working with multiple AxiDraw machines" below for an extended discussion.

Default: 0, given by port_config in axidraw_conf.py

output_file

output_file

Example 1: Plot a file named input.svg, and save an output file as output.svg:

python axicli.py input.svg -o output.svg

Example 2: Preview a file, generating a rendered preview of pen-down motion, and calculating the estimated duration of the plot:

python axicli.py file.svg -Tvg 1 -o outputfile.svg

Specify output SVG file name

Syntax: [-o, --output_file] value

Normally, this program accepts an SVG file as input, and does not produce an output file. However, if an output file name is specified, then it will produce and save an output SVG file. The output file contains the same SVG drawing that it accepted as input, but may also have plot progress saved in the file, or a rendered preview.

See the documentation above, under res_plot, res_home for more about how the plot progress data is saved in the output file, and how that can be used for the resume modes.

See the documentation above under both "Plot preview" and "Rendering style" for more about how rendered previews are generated.

Allowed values of the port parameter are strings, which specify the output file name.

Default: None

Multiple AxiDraw units

There are two main strategies for working with multiple machines with AxiCLI:

(A) Launch multiple instances of AxiCLI, using the --port argument to select different machines.

This method is straightforward, and can be used to send different files to different AxiDraw units.

(B) Use --port_config 3 (or -P3) to simultaneously plot the same file to all Axidraw units located via USB.

This method is a production-oriented choice for plotting the same document multiple times. While efficient, it uses the same interface that is normally used for working with a single AxiDraw, and that does have some side-effects:

  1. The pause/resume feature is not fully supported with -P3, and
  2. Most output messages (other than errors) are suppressed.

The reason for these changes is that there is still — even when plotting to multiple machines — a maximum of one output file generated. (One of the plot processes, chosen automatically, will be the one that saves the output file.) That output file may safely be used for things like plot previews. However if the physical pause button is pressed on one of several machines while plotting in -P3 mode, then the output file saved may or may not contain plot progress data for that particular AxiDraw.

If you plot with option -P3 in modes res_plot or res_home, the software will automatically revert to -P1 mode instead, plotting to only the first AxiDraw located.

For related reasons, most output messages other than errors are suppressed to avoid duplicate warning messages during the plot. Thus, if you need to request (e.g.) the firmware version from each AxiDraw, do so individually.

Troubleshooting

Debugging plot output

In case of unexpected plotting output, you may wish to preview your SVG document in Inkscape, to see how it will print.

Steps:

  1. Ungroup all objects, repeatedly if necessary.
  2. Set fill type to none
  3. Set stroke type to flat color (solid)
  4. Set stroke style to a constant width, e.g., 0.5 mm (0.020 inches).

Note that only path objects (and simple variations thereof) will print. Text should be converted to paths before plotting. Filled regions will not automatically be filled; use the AxiDraw Hatch Fill extension.

Revision Notes

v 2.2.0 -- 2018-10-01

Automatic checking for updates now performed with the sysinfo mode. Reorder mode and group_sorting option added.

v 2.1.1 -- 2018-08-31

Plots now clipped at edges of SVG document.

v. 2.1.0 -- 2018-08-24

Plots 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:

Copyright

Copyright 2018 Windell H. Oskay, Evil Mad Scientist Laboratories