Introduction

The AxiDraw Command Line Interface AxiCLI is an 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 and vertex lists.)

About AxiDraw

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

For general information about getting started with and operating the AxiDraw, please see our extensive PDF user guide, available here.

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, discord chat, or through our github issues list.

Installation

One line install

If you already have Python 3.8 or newer installed, use the following in a terminal:
python -m pip install https://cdn.evilmadscientist.com/dl/ad/public/AxiDraw_API.zip

This procedure installs both the AxiDraw CLI and the AxiDraw Python Module. The link is permanent and will be kept up to date. The current release version is 3.9.6.

If you use this method, you may also want to download the zip file conventionally, since the download includes example python scripts, an example configuration file, an example SVG file, and instructions for un-installing the software.

Standard install

Download the API from this permanent link The current release version is 3.9.6.

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

(Abbreviated instructions: Install Python 3. Unzip the archive, move into the directory, and use python -m pip install . to install the software.)

Upgrading

If you already have this software installed, we recommend the following method to upgrade: python -m pip install https://cdn.evilmadscientist.com/dl/ad/public/AxiDraw_API.zip --upgrade --upgrade-strategy eager

Quick start

Quick start

Typical usage, to plot a file: axicli FILE_NAME [OPTIONS]

Example 1: Plot a file named AxiDraw_trivial.svg

axicli AxiDraw_trivial.svg

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

axicli input.svg -o output.svg

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

Alternate syntax: python -m axicli FILE_NAME [OPTIONS]

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 smaller number of utility functions.

A file input is required syntax for most operations. Certain utility modes that do not perform any plotting do allow the file input to be omitted.

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 using the output_file flag. 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.

A plot underway can be paused by pressing the physical pause button on the AxiDraw or by using Control+C on your keyboard.

Special commands

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

• axicli --help

  Show quick help

• axicli --version or axicli version

  Display software version of AxiDraw software and its CLI wrapper

Additionally, the following utility modes do not require an input file, unless an output file is specified: cycle, align, toggle, manual, sysinfo, version.

Setting options

CLI Syntax

CLI Syntax

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

axicli FILE_NAME --option_name value

Example 1: Plot file.svg, with maximum pen-down speed of 50%, acceleration 80%:

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

Example 2: Use manual mode with the manual command to disable the XY motors (this command does not require an input file):

axicli --mode manual --manual_cmd disable_xy 

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

axicli -m manual -M disable_xy 

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

axicli 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 are set from within the axidraw_conf.py configuration file within the files installed by the API. These include the pen up and pen down heights, basic speed settings, and so forth. The configuration file also includes additional parameters and defaults that are only set in configuration files and do not have any equivalent that is accessible through command line arguments.

An example configuration file can be in the API download at:
examples_config/axidraw_conf_copy.py

You can duplicate, move, rename, and edit this file as needed, though you should keep the ".py" file extension. You may wish to use different configuration files to have quick settings ready for (for example) draft versus final plotting speeds, different size AxiDraw models, different paper size limits, which particular AxiDraw unit to plot to, or previewing without plotting. Configuration files do not need to be as complex as the example file; it is perfectly reasonable to use a configuration file that specifies even just a single option value.

A few specific 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. Several additional commands such as timed delays and forced pauses can be controlled through this mechanism as well.

The order of preference for options and parameters is as follows:

1: Options and values values specified in the SVG file (as in, by layer names) overrule those specified either by the command line or in your configuration file.

2: Options and values specified on the command line argument overrule those in your configuration file.

3: Options and values given in a specified configuration file overrule those in the default axidraw_conf.py configuration file.

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.

As an aside, 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.

mode

mode

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

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

Example 2: Cycle the pen down then up:

axicli -m cycle

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

axicli -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.

Modes that process or plot the file (plot, layers, res_plot, res_home, reorder) always require a file input. The other ("utility") modes (align, toggle, manual, sysinfo, version) do not require a file input unless an output file is specified with the output_file option.

Default: 'plot', set in axidraw_conf.py or your specified config file.

plot

mode: plot

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

axicli file.svg 

Example 2: The same, explicitly setting the mode:

axicli file.svg --mode plot

Example 3: The same, using short codes:

axicli 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. An input file, to be plotted, is always required when in plot mode.

layers

mode: layers

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

axicli 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":

axicli 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 layers that have layer names beginning with the selected number will plot. The selected number is given by the value of the --layer option, and may be in the range of 0 - 1000.

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.

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

An input file, to be plotted, is always required when in layers mode.

Sublayers and other named groups are not considered to be layers for this or other software features that operate by layers; only "top-level" layers can be addressed in layers mode.

For more information about options available based on layer name, and how to create layers when generating SVG outside of Inkscape, please see the AxiDraw Layer Control documentation.

cycle

mode: cycle

Example 1: Cycle the pen down and then up, using "cycle" mode:

axicli --mode cycle 

Example 2: Cycle the pen down and then up, with pen-down and pen-up heights set to 20% and 80% respectively:

axicli --mode cycle --pen_pos_down 20 --pen_pos_up 80

Example 3: Cycle the pen down then up, with pen-down and pen-up heights set to 10% and 90% respectively and all short codes:

axicli -mcycle -d10 -u90

Cycle the pen down and back up

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

This is a setup mode that can be used used to prepare the AxiDraw for use. It will lower the pen, wait 0.5 seconds, and then raise the pen. Cycling before inserting your pen ensures that your pen holder starts in the pen-up position, with current pen-up and pen-down heights applied.

Cycle mode is equivalent to selecting the "Setup" tab of AxiDraw Control (within Inkscape) and choosing the "Cycle pen down then up" option within that tab.

An input file is not required in this mode unless an output file is specified with the output_file option. Execution of the command is typically faster without an input file.

If you wish to only lower or raise the pen, not cycle down and up, use the toggle mode or the lower_pen/raise_pen manual commands instead.

align

mode: align

Example 1: Enter align mode:

axicli --mode align 

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

axicli -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.

Note that the pen will only be raised if it was in the down state or indeterminate state. It will not be raised if it was already in the pen-up state.

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 input file is not required in this mode unless an output file is specified with the output_file option. Execution of the command is typically faster without an input file.

toggle

mode: toggle

Example 1: Toggle the pen up or down:

axicli --mode toggle 

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

axicli -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.

An input file is not required in this mode unless an output file is specified with the output_file option. Execution of the command is typically faster without an input file.

If you wish to only lower or raise the pen — not toggle to the opposite state — use one of the lower_pen/raise_pen manual commands instead.

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.

An input file is not required in this mode unless an output file is specified with the output_file option. Note in particular that the strip_data manual command has no effect unless both an input and output file are specified.

sysinfo

mode: sysinfo

Example 1: Request sysinfo:

axicli --mode sysinfo

Example 2: Request sysinfo using short code:

axicli -m sysinfo

Typical response to sysinfo request (example on Mac):

This is AxiDraw Control version 3.9.6.
Your AxiDraw Control software is up to date.

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


Additional system information:
3.10.6 (main, Aug 30 2022, 04:58:14) [Clang 13.1.6 (clang-1316.0.21.2.5)]
Voltage readout: 296 (~ 9.08 V).
Current setpoint: 483 (~ 0.89 A).

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:

• 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.
• Estimated voltage input at the EBB, as well as motor current setpoint.

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 (or your specified configuration file) and changing the value of check_updates to False.

An input file is not required in this mode unless an output file is specified with the output_file option. Execution of the command is typically faster without an input file.

version

mode: version

Example 1: Request version:

axicli --mode version

Example 2: Request version using short code:

axicli -m version

Typical response:

2.5.0

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.

An input file is not required in this mode unless an output file is specified with the output_file option. Execution of the command is typically faster without an input file.

res_plot, res_home

modes: res_plot, res_home

Examples:

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

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

axicli temp.svg --mode res_home 

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

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

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

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

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

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

Resume a paused plot or return to Home position

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 plot is paused by pressing the physical pause button on the AxiDraw, or using Control+C on the keyboard. (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 position that a plot will be resumed at can be read and set by the res_read and res_adj_in/res_adj_mm manual commands.

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.

An input file, to be plotted, is always required in both res_home and res_plot modes.

reorder

mode: reorder

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

axicli file.svg --mode reorder --reordering 3 -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:

axicli file.svg -m reorder --reordering 3 -o out.svg

Example 3: Re-order an SVG file (file.svg), preserving groups as-is, and save the output as "out.svg"

axicli file.svg -m reorder -G1 -o out.svg

Re-order SVG file for speed (Legacy version; deprecated)

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

Reorder mode is one of two available ways to reducing the amount of pen-up travel by altering the order or plotting different elements in the SVG file. The other way is the reordering option when used in a plot.

These two approaches correspond to the two options described in the AxiDraw User Guide: One is an option that can be used while plotting (but does not save any changes to the order of elements), while this Reorder mode is a separate stand-alone mode that can make changes to the file (but does not plot).

Reorder mode 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. Using this mode to process a file can reduce the amount of pen-up travel that will occur when subsequently plotting the file.

(To instead perform re-ordering during plotting operations, you may wish to use the reordering option in combination with another mode.)

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 reordering option. Note that the behavior selected by these values is different than that when used in any other mode.

Allowed values of reordering: Integers from 0 to 3:

• 0: No reordering; preserve order of objects. [DEFAULT]
• 1: Reorder objects, preserving groups.
• 2: Reorder objects, reordering within each group.
• 3: Reorder all objects, breaking apart groups.

If reordering of 0 is selected, optimization is disabled. The plot order is given by the order that elements appear in the SVG file. This is the default option, used when no value of reordering is given. (It is necessary to assert a reordering value of 1, 2, or 3 in order for any sorting to be performed in Reorder mode.)

If reordering of 1 is selected, the order of groups and elements with respect to other groups and elements (on the same layer) will be altered to reduce pen-up travel. However, the elements within each group encountered will be left in their original order within the group. This may be useful, for example, if you have a grouped line of handwriting-like text that you would like to be written left-to-right, but want to optimize the order of other objects on the page.

If reordering of 2 is selected, groups and elements will (as with the previous case) be re-ordered to reduce pen-up travel. However, elements within every group will also be re-ordered, even including highly-nested subgroups of subgroups.

If reordering of 3 is selected, each group that is encountered will be dissolved, and the contents of all groups will be re-ordered along with all other elements on the same layer.

Reorder mode requires an SVG file input, and an output file is required for it to be useful. Best practice is to keep a backup copy of your original SVG, in case of unexpected output.

Since Reorder mode is an "offline" mode, it can be used even without an AxiDraw present, much like plotting with the Plot Preview preview option enabled. (The preview option is not applicable to reorder mode.)

config

config

Example 1: Plot a file, using settings in a file called "local_config.py"

axicli file.svg --config local_config.py

Example 2: Plot the same file, using a path to a file in another directory. (Example on Mac; paths look different on other computers.)

axicli file.svg -f ~/axidraw/configs/draft_quality.py

Example 3: Use a configuration file called "estimate.py", which defaults to have preview mode enabled and time reporting. This will not plot the file, but just estimate the time that the file will take to plot.

axicli file.svg -f estimate.py

AxiDraw Configuration File

Syntax: [-f, --config] file_name

Select a custom configuration file to use. The file_name given in the syntax above may be a file name in the same directory, or a path to the configuration file.

An example configuration file can be in the API download at: examples_config/axidraw_conf_copy.py

You can duplicate, move, rename, and edit this file as needed, though you should keep the ".py" file extension. You may wish to use different configuration files to have quick settings ready for (for example) draft versus final plotting speeds, different size AxiDraw models, different paper size limits, which particular AxiDraw unit to plot to, or previewing without plotting. Configuration files do not need to be as complex as the example file; it is perfectly reasonable to use a configuration file that specifies even just a single option value.

Default: Use defaults from the axidraw_conf.py file installed with the software, rather than from a local configuration file.

progress

progress

Example 1: Plot a file with the progress bar enabled:

axicli file.svg --progress

Example 2: Plot a file with reordering and displaying progress:

axicli file.svg -bG2 

Display progress bar while plotting

Syntax: [-b, --progress]

By default progress bars are disabled; axicli is a "silent" interface, providing little if any feedback while a plot is working.

The progress bar may be enabled by using the --progress option (-b). It is a simple "flag" type argument, and takes no value argument. When enabled, the progress bar will visually display progress through the plot. It will also display some additional information such as the estimated print time and "axicli plot complete" when the plot finishes.

A typical display might be as follows (with a line break added for readability):

Plot Progress: 28%|##############2 | 2693/9460
[01:08<02:15, 49.79 mm/s]

The left part (first line) gives the percentage through the plot. The graph portion represents completed progress by # and partial progress on the leading glyph (not quite a full #) by numbers 1-9. The fraction after that shows the progress through the file in terms of total travel in millimeters. Here, we are at 2693 mm through a plot that has a total of 9460 mm of pen-up + pen-down travel.

The right part (second line, here) gives the elapsed and extrapolated remaining time, formatted as: [(elapsed time) < (remaining time)]. It also shows the average rate of pen movement in millimeters per second (somewhat skewed by the fact that the pen lifts and lowers at 0 mm/s horizontally). In practice, the estimated print time generated before printing tends to be more accurate than the extrapolated time remaining.

When plotting multiple copies, the progress bar shows progress through an individual copy, but is labeled to indicate which copy number is being plotted. A new, simplified progress bar will be displayed during the delay between pages. Delays at the beginning of layers, added by AxiDraw Layer Control, are indicated with a second, similar progress bar.

Enabling the progress bar slightly increase the time between initiating the plot and when the AxiDraw actually begins to plot, since it quietly runs a plot preview to calculate the plot length and duration. In typical cases, this added time increases the total (computation + plotting) duration of a plot by under 1%.

The progress bar feature is only available from the AxiDraw CLI, when the option is enabled, and in modes that actually plot to the AxiDraw ("plot", "layers", "res_plot"). It is not available while running a preview nor while generating a digest without plotting.

To enable progress bars by default, edit axidraw_conf.py or your specified config file and change the value of progress from False to True. (Note that there is not an override to disable progress bars if enabled in the configuration file.)

Default: False, given by progress in axidraw_conf.py or your specified config file.

speed_pendown

speed_pendown

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

axicli file.svg --speed_pendown 20

Example 2: The same, with short codes:

axicli 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, set in axidraw_conf.py or your specified config file.

speed_penup

speed_penup

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

axicli file.svg --speed_penup 50

Example 2: The same, with short codes:

axicli 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, set in axidraw_conf.py or your specified config file.

accel

accel

Example 1: Plot file.svg, with maximum pen-down speed of 50%, acceleration 80%:

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

Example 2: The same, with short codes:

axicli 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, set in axidraw_conf.py or your specified config file.

pen_pos_down

pen_pos_down

Example 1: Plot file.svg, with pen-down height of 20%:

axicli file.svg --pen_pos_down 20 

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

axicli -mcycle -d10 -u90

Example 3: Lower the pen to 30% height:

axicli -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, set in axidraw_conf.py or your specified config file.

pen_pos_up

pen_pos_up

Example 1:
Plot file.svg, with pen-up height of 80%:

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

axicli -mtoggle -d10 -u90

Example 3: Raise the pen to 70% height:

axicli -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, set in axidraw_conf.py or your specified config file.

pen_rate_lower

pen_rate_lower

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

axicli file.svg --pen_rate_lower 5 

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

axicli -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, set in axidraw_conf.py or your specified config file.

pen_rate_raise

pen_rate_raise

Example 1: Plot file.svg, raising the pen very quickly from the paper (100% speed):

axicli file.svg --pen_rate_raise 100 

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

axicli -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, set in axidraw_conf.py or your specified config file.

pen_delay_down

pen_delay_down

Example 1: Plot file.svg, adding an extra delay of 250 ms after lowering the pen:

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

axicli 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 option 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, set in axidraw_conf.py or your specified config file.

pen_delay_up

pen_delay_up

Example 1: Plot file.svg, adding an extra delay of 250 ms after raising the pen:

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

axicli 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 option 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, set in axidraw_conf.py or your specified config file.

no_rotate

no_rotate

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

axicli file.svg --no_rotate

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

axicli 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 axidraw_conf.py or your specified config file and change the value of auto_rotate from True to False. (Note that there is not an override to re-enable auto-rotate if it is disabled in the configuration file.)

const_speed

const_speed

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

axicli file.svg --const_speed

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

axicli 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 feature 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 axidraw_conf.py or your specified config 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:

axicli file.svg --report_time

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

axicli file.svg -vTC

Report time and distance

Syntax: [-T, --report_time]

Report time and distance plotted after the 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 feature 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.

When resuming a plot with res_plot mode, please be aware that the distances reported will reflect the pen-down distance since the beginning of the document, rather than since the plot resumed. (Distances are calculated this way, using the total pen-down distance through the document, to ensure that a plot can be paused and resumed, even if started in res_plot mode.)

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 axidraw_conf.py or your specified config file and change the value of report_time from False to True.

manual_cmd

This option allows you to specify exactly which particular "manual" command will be executed if the mode is set to manual. This option 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 not required unless an output file is specified. However, several of the commands (such as res_adj_in, strip_data, etc.) are not useful unless input or input and output files are specified. For manual commands such as raise_pen that do not interact with the SVG document, execution is typically faster without SVG input file.

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

Default: 'fw_version', set in axidraw_conf.py or your specified config file.

fw_version

manual_cmd: fw_version

Example 1: Query the EBB firmware version:

axicli --mode manual --manual_cmd fw_version 

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

axicli -m manual

Typical response:

EBBv13_and_above EB Firmware Version 2.6.5

Manual command: Query firmware version

Syntax: [-M, --manual_cmd] fw_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.8.1. 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:

axicli -m manual -M lower_pen 

Example 2: Raise the pen, very slowly

axicli -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.

Note that lower_pen will only lower the pen if it was in the up state or an indeterminate state. It will not be lowered if it was already in the pen-down state.

Similarly, raise_pen will only raise the pen if it was in the down state or an indeterminate state. It will not be raised if it was already in the pen-up state.

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

axicli --mode manual --manual_cmd walk_y

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

axicli -m manual -M walk_x --dist 1.5
axicli -m manual -M walk_x --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:

axicli -m manual -M walk_x -w 3.937 -s 10
axicli -m manual -M walk_y -w 3.937 -s 20
axicli -m manual -M walk_x -w -3.937 -s 30
axicli -m manual -M walk_y -w -3.937 -s 40

Manual commands: Walk the carriage in the X or Y direction, inch units

Syntax: [-M, --manual_cmd] walk_x

Syntax: [-M, --manual_cmd] walk_y

These two "walk" commands will move the AxiDraw carriage by a distance in inches given by the value of the dist option, along one axis or the other.

The dist option has a default value of 1.0. This distance is given in inches, when using the walk_x or walk_y manual commands. If you would prefer to use millimeter units, see the walk_mmx, walk_mmy commands instead.

The walk_x and walk_y movements are relative to the current position (not absolute), and are NOT checked versus the current carriage position for sane range of motion. Use caution: They can easily run the AxiDraw past its safe range of motion.

Walk movements are "out of band" movements; they can provide a means of offsetting the XY position of the AxiDraw carriage before starting a plot. (The position where a plot starts will be the origin for that plot.) This ability to offset the origin may occasionally provide utility in test, setup, and calibration routines.

After making manual movements, and before plotting, you may wish to manually return the AxiDraw carriage to the Home corner. Alternately, you can use the walk_home manual command to "reset" any walks, returning the carriage to the position where the motors were first enabled.

Please note that these "walk" commands are not meant as a substitute for full motion control. If you require full interactive XY movement, consider using the interactive context within the Python API, which provides full XY movement control as well as software limit checking.

walk_mmx, walk_mmy

manual_cmd: walk_x, walk_y

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

axicli --mode manual --manual_cmd walk_mmy

Example 2: Move the carriage 2.0 inches (50.8 mm) in the +x direction, and then back:

axicli -m manual -M walk_mmx --dist 50.8
axicli -m manual -M walk_mmx --dist -50.8

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

axicli -m manual -M walk_mmx -w 100 -s 10
axicli -m manual -M walk_mmy -w 100 -s 20
axicli -m manual -M walk_mmx -w -100 -s 30
axicli -m manual -M walk_mmy -w -100 -s 40

Manual commands: Walk the carriage in the X or Y direction, mm units

Syntax: [-M, --manual_cmd] walk_mmx

Syntax: [-M, --manual_cmd] walk_mmy

These two "walk" commands will move the AxiDraw carriage by a distance in millimeters given by the value of the dist option, along one axis or the other.

The dist option has a default value of 1.0. This distance is given in millimeters, when using the walk_mmx or walk_mmy manual commands. If you would prefer to use inch units, see the walk_x, walk_y commands instead.

The walk_mmx and walk_mmy movements are relative to the current position (not absolute), and are NOT checked versus the current carriage position for sane range of motion. Use caution: They can easily run the AxiDraw past its safe range of motion.

Walk movements are "out of band" movements; they can provide a means of offsetting the XY position of the AxiDraw carriage before starting a plot. (The position where a plot starts will be the origin for that plot.) This ability to offset the origin may occasionally provide utility in test, setup, and calibration routines.

After making manual movements, and before plotting, you may wish to manually return the AxiDraw carriage to the Home corner. Alternately, you can use the walk_home manual command to "reset" any walks, returning the carriage to the position where the motors were first enabled.

Please note that these "walk" commands are not meant as a substitute for full motion control. If you require full interactive XY movement, consider using the interactive context within the Python API, which provides full XY movement control as well as software limit checking.

walk_home

manual_cmd: walk_home

Example 1: Move the carriage back to the position where it was enabled, for example after a plot was stopped.

axicli --mode manual --manual_cmd walk_home

Example 2: Move the carriage 2.0 inches (50.8 mm) in the +x direction, and then back:

axicli -m manual -M walk_mmx --dist 50.8
axicli -m manual -M walk_home

Manual command: Walk the carriage back to its initial position

Syntax: [-M, --manual_cmd] walk_home

The walk_home manual command is a special "manual walk" type command that moves the carriage to the initial position where the motors were enabled.

In normal operation, where the AxiDraw is located in the Home position before enabling the motors, starting a plot, or using other manual walk commands, walk_home will return the AxiDraw to the Home position. But, if the motors were initially enabled in some different position, this command will instead return the AxiDraw to that other position.

This command can be used to reset the AxiDraw carriage position — moving it back to Home — after one or more manual walk commands.

It can also be used to return the AxiDraw to the Home position, for example after pausing a plot that will not be resumed.

Note that changing the motor resolution will generally count as "re-enabling" the motors with the new resolution, and may alter the position that walk_home will return to.

The walk_home command requires EBB firmware 2.6.2 or newer.

enable_xy, disable_xy

manual_cmd: enable_xy, disable_xy

Example 1: Enable the XY stepper motors:

axicli --mode manual --manual_cmd enable_xy 

Example 2: Disable the XY stepper motors:

axicli -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.

res_read

manual_cmd: res_read

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

axicli file.svg -m manual -M res_read -o output.svg

Typical response, with a file paused at 200 mm of pen-down travel:

Plot was paused after 200.000 mm (7.874 inches) of pen-down travel.

Typical responses, for a file that finished plotting normally:

No in-progress plot data found in file.
To set up the plot to be resumed at a given point, add an offset.

Typical response, with a file that has had its resume position adjusted:

Plot was originally paused after 200.000 mm (7.874 inches) of
pen-down travel. The resume position was then adjusted to 225.400 mm
(8.874 inches).

Manual command: Read position where a paused plot will resume

Syntax: [-M, --manual_cmd] res_read

When a plot is paused, the progress through the file is saved in the SVG document so that the plot may be resumed later with res_plot mode. The res_read manual command reads the SVG and reports that progress as human-readable text.

Plot progress is measured as the total path length of pen-down movement from the beginning of the plot to where it was paused. One may adjust that distance, so it is more proper to say that it measures the pen-down distance from the beginning of the plot to the point where the AxiDraw would resume plotting with res_plot mode.

The "beginning of the plot" refers to the first vertex of the first plottable object in the SVG document. (Exactly what that object is depends on which optimizations are applied and, for example, whether the plot was started in Layers mode.)

The "beginning of the plot" still refers to the first plottable object, even when a plot is resumed with res_plot mode; it is not the position from which the plot was resumed. For example, if a plot were paused after plotting paths with a total arc length of 250 mm, and then resumed and paused again after drawing another 100 mm, res_plot would report a value of 350 mm.

The resume position can be adjusted with the res_adj_in and res_adj_mm commands. See the res_plot mode description for further discussion of pause-and-resume methods when using this API.

res_adj_in, res_adj_mm

manual_cmd: res_adj_in, res_adj_mm

Example 1: Adjust resume position from file.svg, such that when resumed it would start 20 mm before its pause position.

axicli file.svg -m manual -M res_adj_mm --dist -20 -o file.svg

Typical response, with a file paused at 200 mm of pen-down travel:

Plot was paused after 200.000 mm of pen-down travel.
After adding a new offset of -20.000 mm, the resume position
    is now set at 180.000 mm.

Example 2: Configure a document to begin printing (when used with res_plot mode) after 12.5 inches of pen-down distance.

axicli file.svg -m manual -M res_adj_in --dist 12.5 -o file.svg

Typical response, with a file that was not initially paused:

This document was configured to start plotting at the beginning
of the file. After adding a new offset of 12.500 inches, the
resume position is now set at 12.500 inches.

Manual commands: Adjust resume position of paused plot

Syntax: [-M, --manual_cmd] res_adj_in

Syntax: [-M, --manual_cmd] res_adj_mm

These two commands adjust the position where a paused plot will resume, by a distance given by the value of the dist option and units selected by choosing either res_adj_in or res_adj_mm. See the res_read command description for how to read the existing resume position and for an extended discussion of what that position means.

The dist option has a default value of 1.0 and can be positive or negative. Its value, in units of inches when using res_adj_in, and in millimeters when using res_adj_mm, is added to the the current resume position to produce the new position.

If the new resume position is less than or equal to zero, it will reset to zero (the beginning of the plot), where res_plot mode cannot "resume" the plot. The resume position can also be set to a distance longer than the total pen-down length of the plot. In that case, res_plot mode can be run, but nothing will print (since the resume point is after the end of the plot).

If an SVG document does not have any in-progress plot saved, it is possible to use res_adj_in or res_adj_mm to add an offset from zero, and then start a plot at that position using res_plot. This provides a means of starting a plot partway through, even if it did not begin as a paused plot.

strip_data

manual_cmd: strip_data

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

axicli 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 connected AxiDraw units:

axicli -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 connected 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:

axicli --mode manual --manual_cmd read_name

Typical responses:

AxiDraw nickname: AxiDraw 16

or

This AxiDraw does not have a nickname assigned.

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 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_name

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

axicli -m manual -M "write_nameAxiDraw 17"

Typical response:

Nickname written. Rebooting EBB.

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

axicli -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 option 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 option. 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.

Assigned Nicknames are semi-permanent; they will persist when power is cycled, but can be overwritten by this command, (or other utilities that assign a nickname), and will be erased (reset to default) if you should run a firmware update at some point in the future.

Since the nickname itself 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.

bootload

manual_cmd: bootload

Example: Put the AxiDraw into bootloader mode:

axicli --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 fw_version for more about firmware versions and updating.

dist

dist

Example 1: Move the carriage 2.5 inches in the +x direction, and then back.

axicli --mode manual --manual_cmd walk_x --dist 2.5
axicli -m manual -M walk_x -w -2.5

Example 2: Adjust resume position from file.svg, such that when resumed it would start 20 mm before its existing pause position.

axicli file.svg -m manual -M res_adj_mm --dist -20 -o file.svg

Distance for Walk and Adjust Resume Position manual commands

Syntax: [-w, --dist] value

The dist option provides the amount of distance for manual mode commands, when the manual command specified by manual_cmd requires a distance input. The value of dist is a floating point number that may be positive or negative. Its default value is 1.0.

The units of the distance given by dist are selected by choosing a specific manual command. The distance is in millimeters for manual walk commands walk_mmx or walk_mmy and for the res_adj_mm command to adjust resume position. The distance is in inches for manual walk commands walk_x or walk_y and for the res_adj_in command to adjust resume position.

Values of dist should be chosen with care, since no limit checking is performed. This is especially true with the manual walk commands, which are relative to the current position (not absolute), and are NOT checked for safe range of motion. These are fully manual commands, and can easily run the AxiDraw past its safe range of motion.

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

Default: 1.0, set in axidraw_conf.py or your specified config file.

Compatibility note: This option was previously named walk_dist, and renamed to dist as of software version 3.8. The old name walk_dist is deprecated but still functional for CLI use, shell scripts, and configuration files that do use it (and do not set dist). The walk_dist syntax will be removed in a future version.

layer

layer

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

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

Example 2: The same, with short codes:

axicli file.svg -m layers -l3

Select layer(s) to plot when in layers mode

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 layers mode, with a given layer specified by this option will plot only layers whose names begin with the selected number. While only a single integer value may be given for layer, that value may match with multiple layer names, so that any number of layers may be selected for plotting.

For example, suppose that your file has layers with the following names:

• "guide lines"
• "5-red"
• "2 black"
• "55"
• "5 Outlines"

Then, if a layer option of 5 is given in layers mode, the two layers named "5-red" and "5 Outlines" will be plotted, while the layers named "guide lines", "55", and "2 black" will be skipped.

Allowed values: Integers from 1 to 1000.

Default: 1, given by default_Layer in axidraw_conf.py or your specified config file.

copies

copies

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

axicli file.svg --copies 2  

Example 2: Plot a file continuously (until paused by button or Control+C):

axicli file.svg -c0

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

axicli 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 option 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 option.

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 Control+C or the physical pause button is pressed.

A set of plots in progress can be paused at any time by pressing Control+C or the physical pause button on the AxiDraw. If a plot is active when paused, it will stop at that location in the usual way (saving progress in the output file, if an output file is specified). If paused 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 or your specified config file.

page_delay

page_delay

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

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

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

axicli 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 or your specified config file.

preview

preview

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

axicli file.svg -v --report_time 

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

axicli file.svg -vg3 -o outputfile.svg

Plot preview

Syntax: [-v, --preview]

Plot Preview is an offline simulation setting that, if enabled, disables communication to the USB port 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 option 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, set in axidraw_conf.py or your specified config file.

rendering

rendering

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

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

axicli 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.

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. Further, it only has an effect when Plot Preview is enabled.

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 option 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), set in axidraw_conf.py or your specified config file.

reordering

reordering

Example 1: Plot an SVG file (file.svg), reordering for speed including allowing path reversal prior to plotting.

axicli file.svg -G2

Example 2: Preview how an SVG file (file.svg) will plot with basic optimization, reordering elements for speed but preserving their directions. SVG objects in the output SVG file will be preserved in their original order.

axicli file.svg -vTg2 -G1 -o out.svg

Specify level of plot optimization

Syntax: [-G, --reordering] value

When so selected with the reordering option, a plot optimization tool is used to re-order elements in the input SVG prior to plotting or rendering a preview. By changing the order and (optionally) direction of paths, the plot duration can be lowered by reducing the amount of pen-up travel required during the plot.

The reordering option is only applicable in the modes that parse and plot the SVG document: plot (default), layers, and res_plot.

(There is also a separate legacy reorder mode, which uses different values of the reordering option.)

Normal order of plotting

Normally and by default, each path within a SVG document is plotted (with one exception) in the same order and in the same direction as it appears in the document. This order is generally the order in which the objects were created. In a graphical vector editor like Inkscape, newer objects are drawn on top of older ones; a "lower" object is one that appears earlier in the document.

The exception is that if one path ends very close to where another begins (and if those paths are not separated by layers), then those two paths are normally joined together, skipping an unnecessary pen lift. The maximum gap that can be joined is given by the min_gap parameter in the axidraw_conf.py configuration file.

The default option, which generally respects the original document order, is often preferable, for example in handwriting-like applications, where you may wish the writing to be in the same order that a person would write the words, e.g. right-to-left, top-to-bottom on the page.

How reordering works

When you plot an SVG document, the following operations occur:

1. A temporary copy of the SVG document is made.
2. Graphical elements like circles and rectangles are rendered into paths.
3. The document is separated by layers.
4. Within each layer:
   • All groups, sub-layers, and compound paths are broken apart.
   • Paths are joined together if one starts where another ends.
   • The paths are re-ordered for speed.
5. The document is plotted (or the preview is rendered).
6. The document is reverted to the temporary copy.
7. If rendering a preview, the preview paths are added to the document.

Path sorting uses a "greedy" algorithm, a suboptimal but relatively fast approach. Depending on the nature of the SVG document, it can reduce the pen-up travel distance by 50-90% and reduce the plotting time by 30-50%. Potential time savings should be weighed against the execution time of the sort, which may be considerable for documents with a great number of separate objects. In most cases reordering adds only a few seconds before plotting starts and results in a significant overall time savings.

If path reversal is allowed, then:

• The stage of joining two paths with coincident ends will check to see if paths can be joined if one or both are reversed.
• Sorting the paths for speed will consider reversing each path.

If path reversal is not allowed, then every path will be plotted in the same direction as it occurs in the document, even if that results in a slower plot.

You may find it helpful to run plots with preview, rendering, and/or report_time enabled. With those tools, you can visualize the effect that optimization has with different values of reordering and estimate the plot duration on documents that have and have not been sorted.

Re-ordering is by layer

The optimization tool is layer-aware: All objects will be left on their original layers. That makes it safe to use on multicolor plots where colors are separated by layers.

An SVG document without layers can still be optimized. The document root, the set of elements that are not in layers, is re-ordered as though it is a single layer.

If the SVG contains elements in document root that are separated by layers, each set of elements that is not separated by layers is treated as a virtual layer for the purposes of reordering.

Changes to the document are not saved

The changes to the order of elements in the SVG document are ephemeral and only made to the temporary copy. If you save an output SVG, the objects in that output SVG will retain their original order.

For example, if your SVG document has deeply nested groups, you can plot it with the reordering of 2, but if you save the output SVG, it will retain your original grouping.

Values of the reordering option

Allowed values: Integers from 0 to 4:

• 0: Least; Only connect adjoining paths. [DEFAULT]
• 1: Basic; Also reorder paths for speed
• 2: Full; Also allow path reversal
• 3: [Deprecated; currently gives same behavior as 2.]
• 4: None; Strictly preserve file order

The reordering values of 0 and 4 are identical except that the "strict" value of 4 also disables path joining. Path joining may be disabled separately via the min_gap parameter value.

Default: 0 (Plot in original order, connecting adjoining paths to reduce unnecessary pen lifts), set in axidraw_conf.py or your specified config file.

random_start

random_start

Example 1: Plot a file, randomizing the start position of closed shapes within that file:

axicli file.svg --random_start

Example 2: The same, using short codes:

axicli file.svg -Y

Randomize start positions of closed paths

Syntax: [-Y, --random_start]

Randomize start locations of closed paths.

By default, this option is disabled, and the AxiDraw will draw closed paths in the direction that they are given in the file (or possibly, the reverse of that, depending on the reordering option).

A pen may form a visible mark at the location where it is lowered or raised. In artwork where the same closed shape is repeated many times, that can cause a seam-like visual artifact if many of those marks line up at matching points on the repeated shapes.

With the random_start option, the start position of closed paths — paths where the start points and end points are coincident — will be randomized, which can help to hide that specific type of visual artifact.

This feature may be enabled by using the --random_start option (-Y). It is a simple "flag" type argument, and takes no value argument

To enable this option by default, edit axidraw_conf.py or your specified config file and change the value of random_start from False to True.

hiding

random_start

Example 1: Plot a file, using hidden-line removal:

axicli file.svg --hiding

Example 2: The same, using short codes:

axicli file.svg -H

Enable hidden-line removal

Syntax: [-H, --hiding]

By default, this option is disabled, and the AxiDraw will draw all paths (or objects that can be directly represented as paths) in the SVG document. All fill and stroke (outline) properties of individual objects are ignored. Phrased differently, All paths are normally plotted as though there is a stroke along the path and no fill.

When the hiding option is enabled, the AxiDraw software will instead plot paths (or not) based (1) on their fill and stroke properties and (2) whether or not they are occluded behind other objects. An object that does not have a stroke property (e.g., no outline in Inkscape) will not plot, nor will one hidden behind a solid fill. Typically, when working with documents that include filled regions, this means that the AxiDraw output will visually resemble the original SVG artwork more closely. In cases of ambiguity, consider running Plot Preview (preview) with rendering enabled in order to understand how the document is processed.

There are two important drawbacks to bear in mind. First, the hiding option requires additional processing time before plotting, especially in instances with large numbers of objects to process. Second, hidden-line removal does not preserve the orientation of individual SVG strokes. We generally recommend using the reordering option, with "full" reordering, to orient the output paths for efficient plotting.

In cases where the processing time becomes large, or when processing repeatedly might be needed (as in, when a document might be paused and resumed during the plotting process), it may be convenient to instead process the document once, separately, using the digest option.

This feature may be enabled by using the --hiding option (-H). It is a simple "flag" type argument, and takes no value argument

To enable this option by default, edit axidraw_conf.py or your specified config file and change the value of hiding from False to True.

model

model

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

axicli file.svg --model 2

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

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

• 1 - AxiDraw V2, V3, or SE/A4
• 2 - AxiDraw V3/A3 or SE/A3
• 3 - AxiDraw V3 XLX
• 4 - AxiDraw MiniKit
• 5 - AxiDraw SE/A1
• 6 - AxiDraw SE/A2
• 7 - AxiDraw V3/B6

Default: 1 (AxiDraw V2, V3, or SE/A4), set in axidraw_conf.py or your specified config file.

The physical size definitions for each model type are also configured in in the configuration file.

penlift

model

Example 1: Plot a file, using default pen-lift configuration.

axicli file.svg --penlift 1

Example 2: Plot a file, using narrow-band brushless pen-lift servo motor.

axicli file.svg -q3

Pen lift servo configuration

Syntax: [-q, --penlift] value

Select the hardware configuration for the AxiDraw's pen-lift servo mechanism. Unless changed, this option leaves your AxiDraw configured to use its factory-standard pen-lift servo.

The default value, 1, specifies to use the default configuration for the AxiDraw model. A value of 2 explicitly selects to use a "standard" PWM-controlled hobby servo, controlled at output "B1", the lowest set of three pins on an AxiDraw's EBB control board. (Since all AxiDraw models thus far do use this as their default, the value 2 currently produces the same results as a value of 1, regardless of AxiDraw model.)

A value of 3 configures the servo output to instead (A) be directed to output pin "B2", the third set up on the AxiDraw's EBB control board (two positions higher than normal) and (B) produce a control signal appropriate for a narrow-band brushless pen-lift servo motor.

Allowed values: Integers from 1 to 3:

• 1 - Default for AxiDraw model.
• 2 - Standard servo (lowest connector position)
• 3 - Narrow-band brushless servo (3rd position up)

Default: 1 (Default for AxiDraw model), set in axidraw_conf.py or your specified config file.

port

port

Example 1: Plot a file to the USB port enumerated as /dev/cu.usbmodem1441:

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

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

axicli file.svg -pGlueDispenser

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

axicli 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 option 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 option.

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 option are strings, which specify either the USB port or AxiDraw USB nickname to use.

Default: None, set in axidraw_conf.py or your specified config file.

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:

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

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

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

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

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

• If no port value is specified, the first AxiDraw located via USB will be used.

• If a port value is specified, then the software will attempt to communicate only with that specified AxiDraw.

The port_config option can override this behavior. Allowed values of the option are integers 0, 1, and 3:

• 0 - Do not override; use standard "port" option behavior.
• 1 - Address only the first AxiDraw located via USB
• 3 - Address all AxiDraw units located via USB

If port_config is 0, then the software will follow the default behavior described above.

If port_config is 1, then the software will communicate only with the first AxiDraw located, even if even if a --port option is specified.

If port_config is 3, the software will simultaneously communicate with all AxiDraw units located via USB. While most features (including plotting) are supported and work well in this fashion, note that are some important differences. Please see "Working with multiple AxiDraw machines" below for an extended discussion.

Default: 0, set in axidraw_conf.py or your specified config file.

output_file

output_file

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

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

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

Specify output SVG file name

Syntax: [-o, --output_file] file_name

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 preview and rendering for more about how rendered previews are generated.

See the digest feature below for an option to save an optimized "Plob" plot digest, rather than the full SVG.

While certain utility modes do not generally require that an input file is specified, an input file is required in all cases when an output file is specified.

Allowed values of the option are strings, which specify the output file name, or a relative or absolute path ending in a file name.

Default: None

digest

digest

Example 1: Plot a file named input.svg, and save the "Plob" plot digest instead of the full SVG:

axicli input.svg --digest 1 -o output_plob.svg

Example 2: Generate a "Plob" plot digest from the file named input.svg, and save it without plotting the document or rendering a preview:

axicli input.svg -O2 -o output_plob.svg

Plot digest output option

Syntax: [-O, --digest]

When a digest value greater than 0 is chosen, the output_file will not be the (lightly modified) input SVG, but instead a "plot digest object", or Plob. A Plob is a restricted-format subset of SVG that the AxiDraw software "digests" the file into before plotting.

In detail, the Plob is a new file generated from the input SVG after:

• Removing hidden and non-printable layers and objects
• Removing ignored layers, if working in layers mode.
• Reducing all plottable shapes and paths to vertex lists
• Applying, then removing any transformations
• Removing all style information
• Applying the auto-rotate function (if enabled)
• Cropping all paths at the plot edges
• Joining together sufficiently close path ends (unless disabled)
• Randomizing the start point of closed paths (if enabled)
• Reordering paths in the document for speed (if enabled)
• Flattening the document structure
• Adding metadata including the hardware model

Generating the Plob is destructive; any SVG shapes such as rectangles or original paths that were present in the original SVG document will not be present in the Plob output. Keep a copy of your original SVG document.

A Plob file may be used as the input to the AxiDraw software, just like any other SVG input. Plotting a Plob prepared for the same AxiDraw model allows the AxiDraw software to skip all of the steps above and immediately begin plotting the document. Note however, that once generated, the Plob file cannot be modified at all, or it will no longer be recognized as a valid Plob file. (Two exceptions: Pause/resume data and plot preview updates are permitted modifications.)

If a plot underway is paused while the digest option is enabled, the output Plob will include plot progress data for resuming the plot, just as a regular SVG would. Partial plots -- those paused while plotting or that resume plotting in the middle of the document -- still contain the entire Plob including the parts that are not printed in those situations.

The digest option may be helpful in a variety of situations, including but not limited to:

• Processing a document once into a Plob that can be plotted many times
• Using different computers for document preparation versus plotting
• Improving the speed of operations that involve pause and resume cycles
• Separating a document with named layers into separate files

If a digest value of 1 is chosen and an output file is saved, that output file will be in the Plob format (instead of full SVG), but no other changes occur. Plots and plot previews will proceed normally.

A digest value of 2 overrides most software functions, to only generate the Plob and perform no other function. (Internally, it enables preview but disables running previews and time estimates.) Using this option minimizes the total time for Plob generation, as there is no need to wait for a plot or preview to finish.

Allowed values: Integers from 0 to 2:

• 0 - Disabled; No change to behavior or output [DEFAULT]
• 1 - Output "plob" digest, not full SVG, when outputting file
• 2 - Disable plots and previews; generate digest only

Default: 0 (Disabled), set in axidraw_conf.py or your specified config file.

webhook

webhook

Example 1: Plot a file and generate a webhook notification, to a specific URL when the plot finishes.

axicli file.svg --webhook --webhook_url "https://url.to.post.to/"

Example 2: The same, using short codes

axicli file.svg -WU "https://url.to.post.to/"

Enable webhook alerts

Syntax: [-W, --webhook]

If the webhook option is enabled and an URL is provided via the webhook_url option, then the software will post to that URL when a plot completes.

This feature can be used in combination with various services including IFTTT, to provide various forms of notifications such as email alerts, mobile alerts, or integration with other hardware or software.

When enabled, webhook alerts are only generated when a plot finishes (or is paused) and all three of these conditions are met:

1. When actually plotting to the AxiDraw (not in preview mode),
2. In a mode that plots a document: plot (default), layers, or res_plot, and
3. An URL is provided via the webhook_url option.

The data posted to the URL is JSON formatted and contains the following key/value pairs:

The "Port" value here is taken from the port option. If you are operating multiple named AxiDraw machines, this value can be used to indicate which machine has completed a plot.

Webooks may be enabled by using the --webhook option (-W). It is a simple "flag" type argument, and takes no value argument.

To enable this option by default, edit axidraw_conf.py or your specified config file and change the value of webhook from False to True.

webhook_url

webhook_url

Example: Plot a file and generate a webhook notification, to a specific URL when the plot finishes.

axicli file.svg --webhook --webhook_url "https://url.to.post.to/"

URL for webhook alerts

Syntax: [-U, --webhook_url] value

The URL to post data to, if the webhook option is enabled.

The webhook option has no effect unless a URL is also provided, via this option.

An extended discussion about webhooks, including instructions for setting up mobile notifications via IFTTT, is available here.

Default: None, set in axidraw_conf.py or your specified config file.

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 plot is paused (by Control+C or the physical pause button) 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.

API Changelog

Revision Notes: Summary of changes affecting API.

Please note that the changelog.txt file included with the download is more comprehensive and includes details about older releases that are no longer listed below.

v 3.9.6 (2023-12)

Maintenance release: Adds Python 3.12, drop 3.7. Python 3.8 - 3.12 are now supported.

Archived release here.

v 3.9.4 (2023-09)

Pen-lift servo motor initialization routines rewritten for more consistent behavior; changes principally affect the AxiDraw Python API.

Last version to support Python 3.7.

Archived release here.

v 3.9 (2023-05)

New option, hiding, enables new hidden-line removal feature.

Added new res_read, res_adj_in and res_adj_mm manual commands, which allow one to read and/or adjust the the position at which a paused plot will be resumed.

Archived release (3.9.3) here.

v 3.8 (2023-01)

Added new penlift option, to enable brushless servo option.

Renamed the walk_dist option to dist. The old option name walk_dist is now deprecated (and temporarily still functional on the command line and in scripts that use it).

New parameters in the axidraw_conf.py include file: button_interval controlling interval of polling the physical pause button and 6 others that support the new servo option.

Progress bar now shows progress as mm travel (rather than an overall "node" count).

Archived release here.

v 3.7.2 (2022-11-09)

Removed "bezier_segmentation_tolerance" and "smoothness" parameters from configuration file; replaced with a single "curve_tolerance" parameter.

Add support for Python 3.11. Python 3.7 - 3.11 are now supported.

3.7.2 Archive release here.

v 3.6 (2022-10-01)

Defaults for mode, manual_cmd, and walk_dist can now be set inside the configuration file.

AxiCLI now returns a non-zero exit code on keyboard or pause button interrupt while plotting, as well as on certain errors.

Archived release here.

v 3.5 (2022-08-10)

New feature available in CLI: Progress bars while plotting.

Added new setup mode, cycle, to assist with setting pen height.

New parameter in the axidraw_conf.py configuration file: servo_pin for re-assigning the pen-lift servo digital output to a different output pin.

Archived release here.

v 3.4 (2022-07-22)

Added a new "strict" value to reordering that disables all optimizations including path joining. Changed description (but not behavior) of the other values for clarity.

New parameters in the axidraw_conf.py configuration file: preview_color_up and preview_color_down allow one to set the colors used in preview rendering.

Archived release here.

v 3.3 (2022-06-11)

Expand model option values with AxiDraw V3/B6.

Drop support for Python 3.6. Python 3.7 or newer is now required.

Archived release here.

v 3.2 (2022-02-24)

Expand model option values with AxiDraw SE/A1, SE/A2.

Improved model for time duration of raising/lowering pen-lift servo motor; two adjustable parameters added to the configuration file.

New walk_home command added to the list of manual commands.

Plots underway can now be paused with Control+C in addition to the physical pause button.

Archived release here.

v 3.1 (2022-01-05)

New plot digest feature: The digest option can enable saving a plot digest, rather than the full SVG output

New Webhook notifications feature. Added webhook and webhook_url options.

New parameter in the axidraw_conf.py configuration file: report_lifts enables reporting the number of pen lifts in a plot.

Archived release here.

v 3.0 (2021-10-12)

Added new random_start feature to randomize the start position of closed paths.

Added new axicli --version command

Significant changes to plot optimization:

• Improved automatic path joining.
• New sub-path optimization: All sub-paths on a layer can now be re-ordered.
• New feature can optionally reverse paths during optimization.
• New option to randomize start position of closed paths
• Layer aware sorting (and other per-layer control) is by top-level layers only, not sublayers.

As part of this, changes to the reordering option:

• The previous values were 0-3. 0: No reordering (Default), 1: Reorder but preserve groups, 2: Reorder within groups, and 3: Break apart groups.
• The new values are 0-3. 0: No reordering (Default), 1: Reorder objects, preserving path orientation, and 2: Reorder objects, allow path reversal.
• The value of 3 is deprecated and may be removed in future versions. It behaves identically to a value of 2.

These new features and changes are only available as part of a plot, and not in reorder mode, which retains its prior options.

Reorder mode is now deprecated and will be removed in a future version.

Additional changes:

• Added upgrade instructions to the installation instructions.
• The ebb_version manual command, previously deprecated, has been removed.

Archived release here.

v 2.7.5 (2021-08-18)

Add support for Python 3.10; Python 3.6-3.10 are now supported.

Archived release here.

v 2.7.4 (2021-06-17)

Drop support for Python 3.5. Python 3.6 or newer is now required.

Archived release here.

Copyright

Copyright 2023 Windell H. Oskay, Evil Mad Scientist Laboratories