NAV

Introduction

This is the migration guide for users of the AxiDraw CLI (Command Line Interface) who are migrating to the Bantam Tools NextDraw™ CLI and users of the AxiDraw Python API who are migrating to the Bantam Tools NextDraw™ Python library.

The Bantam Tools NextDraw™

The Bantam Tools NextDraw™ drawing and handwriting machine is the proven and reliable compatible computer-controlled plotter that provides versatile solutions to artists, innovators and educators.

The Bantam Tools NextDraw™ is designed and manufactured by Bantam Tools in Peekskill, New York.

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

Please also see the central documentation site for the Bantam Tools NextDraw; many additional resources are listed there.

NextDraw owners may request technical and other product support by contacting us directly through our contact form, or discord chat.

Software Variants

The primary software for the Bantam Tools NextDraw™ is available in three supported variants:

The Bantam Tools NextDraw software for Inkscape is a GUI-based software package that works as a set of extensions to Inkscape.

The Bantam Tools NextDraw Command Line Interface is an application programming interface (API) for using the Bantam Tools NextDraw™ from either the command line interface (CLI) or within shell scripts and other environments that make use of shell commands.

The Bantam Tools NextDraw Python library is an application programming interface (API) for the Bantam Tools NextDraw™, designed to let you control the NextDraw from within your own Python scripts.

Invoking the software

Calling the CLI

Using the CLI

Example 1: Plot a file named file.svg using axicli:

axicli file.svg

Example 2: The same, with the Bantam Tools NextDraw CLI:

nextdraw file.svg

If you are migrating from the AxiDraw CLI (Command Line Interface) to the Bantam Tools NextDraw™ CLI, the most basic change is that where you used axicli before, replace that with nextdraw to use the Bantam Tools NextDraw™ CLI.

In short, replace axicli FILE_NAME [OPTIONS] with nextdraw FILE_NAME [OPTIONS].

Importing Python API

Importing the Python API

Example 1: Plot a file named file.svg using AxiDraw Python API:

from pyaxidraw import axidraw   # Import the module
ad = axidraw.AxiDraw()          # Create class instance
ad.plot_setup("file.svg")       # Load file & configure plot context
ad.plot_run()                   # Plot the file

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw   # Import the module
nd1 = NextDraw()                # Create class instance
nd1.plot_setup("file.svg")      # Load file & configure plot context
nd1.plot_run()                  # Plot the file

If you are migrating from the AxiDraw Python API to the Bantam Tools NextDraw™ Python library, the most basic change is that the import statement for using the library is different.

To update the basic import statement, replace from pyaxidraw import axidraw with from nextdraw import NextDraw.

And, create the class instance with NextDraw() instead of axidraw.AxiDraw().

(Capitalization matters in all cases here.)

General differences

This is a list of general differences: What's new in the Bantam Tools NextDraw software, from the perspective of someone coming from AxiDraw software.

Hardware & compatibility

The Bantam Tools NextDraw software supports all models of Bantam Tools NextDraw™, and all AxiDraw models manufactured by Evil Mad Scientist. (Evil Mad Scientist is now part of Bantam Tools.)

The minimum firmware version required by the Bantam Tools NextDraw software is 3.0.2.

Default model selection

The default model selection in the Bantam Tools NextDraw APIs is the 8, selecting the Bantam Tools NextDraw™ 8511.

If you have been using the AxiDraw API with the default model selection (AxiDraw V2, V3, SE/A4) and not explicitly selecting a hardware model with the model option, you'll probably want to begin doing so.

See the description of the model option for more information. [CLI details, Python API details]

It's important to select the right model so that you get the right default travel limits, type of pen-lift servo configured, and configure the software as to whether to use automatic or manual homing.

Homing procedures

The procedure for how the Home position is set and determined has changed significantly from the AxiDraw APIs.

In the AxiDraw software, a plot or interactive session was always assumed to start with the machine in the Home position. That is to say, starting a plot or interactive session would set the internal XY position counter to (0, 0). For this reason, it was necessary to move the carriage to the Home position before starting a new plot or interactive session, whenever if it had not been returned there at the end of the last plot or interactive session. For example, if a plot was paused and not resumed, one would need to return the carriage to the Home corner before starting a new one.

(When resuming a plot, the previous carriage position was stored in the SVG file itself.)

In the NextDraw software, an internal position counter on the machine keeps track of the XY carriage position so long as the motors remain energized. The position does need to be set, or "indexed", when powering the motors on, or in some cases when changing Handling modes. (Changing handling modes can cause the motor position counter to be reset).

This means, for example, that if a plot is started in the Home corner, and then paused and not resumed, it is generally not necessary to return the carriage to the Home position before starting new plots, so long as the motors remain powered on. Similarly, subsequent interactive API sessions will remember the current carriage position so long as the motors remain powered on.

Automatic Homing

Bantam Tools NextDraw™ models support automatic homing. When the model option selected is a Bantam Tools NextDraw™ and the homing feature is not disabled, the carriage will automatically move to the Home position to index itself in some circumstances. Those circumstances include first starting a plot or calling connect() in an interactive session in the Python API, if the machine is not already indexed, or when changing Handling mode.

An extended discussion about homing is available in section "3.2 Automatic and Manual Homing" of the Bantam Tools NextDraw User Guide.

There are new options, homing in the Python API and no_homing in the CLI API that can be used to control this feature. [CLI details, Python API details]

There is also a new mode, find_home, which can "manually" begin the automatic homing sequence. [CLI details, Python API details]

Manual Homing

On hardware models that do not support automatic homing, or when automatic homing is disabled, the position where the motors are first powered on will be used as the "index" position that sets as the (0,0) origin for a plot or interactive session.

Since the default model is the Bantam Tools NextDraw 8511, which does support automatic homing, best practice is to set the model before beginning your plot or interactive session, especially if you are using hardware that does not support automatic homing.

New motion planner

The Bantam Tools NextDraw software uses a new motion planner.

Generally speaking, motion is faster, smoother with less vibration, and quieter. The speed and print quality differences can be dramatic in some cases.

New handling modes

The new handling option allows you to select one of four general "Handling modes": Technical drawing, Handwriting, Sketching, or Constant speed, which control the overall scales of precision, speed and acceleration. [CLI details, Python API details]

Configuration file items

The new nextdraw_conf.py configuration file has significant differences from the axidraw_conf.py configuration file.

If you are using a custom configuration file with just a few specific settings, check for differences in those specific settings.

If you are using a customized "full length" configuration file -- a full copy of axidraw_conf.py with some edits -- best practice would be to start with a fresh copy of nextdraw_conf.py to edit. If necessary, run a run a diff of your old configuration file versus the default axidraw_conf.py to keep track of what custom settings you are using.

Pause warning

When a plot in progress is stopped or paused, and you save output SVG from that plot, that output SVG will contain plot progress data in the file, indicating that a plot was previously paused.

If you try to start a new plot from with that document in the plot or layers mode (rather than res_plot, to resume plotting), you may instead get a warning message. This warning is removed after it is shown once, assuming that you save the output data.

The warning message can be removed by setting the pause_warning parameter to False in your configuration file, or with the params syntax in the Python API.

Other differences

Changes to options

Manual -> Utility

Manual -> Utility

Example 1: Enable XY motors using AxiDraw Python API:

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

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw   # Import the module
nd1 = NextDraw()
nd1.plot_setup()
nd1.options.mode = "utility"
nd1.options.utility_cmd = "enable_xy"
nd1.plot_run()

Example 3: Enable XY motors using AxiDraw CLI:

axicli --mode manual --manual_cmd enable_xy

Example 4: The same, with the Bantam Tools NextDraw CLI:

nextdraw --mode utility --utility_cmd enable_xy

The manual mode in the AxiDraw software has been replaced by the new utility mode in the Bantam Tools NextDraw APIs. [CLI details, Python API details]

Similarly, the manual_cmd option has been replaced by the new utility_cmd option in the Bantam Tools NextDraw APIs. [CLI details, Python API details]

Pen delays

Certain options that were present in the AxiDraw software are not available in the Bantam Tools NextDraw APIs.

The pen_delay_down and pen_delay_up options from the AxiDraw API are not available as options in of the Bantam Tools NextDraw APIs.

It is possible to use a delay after raising or lowering the pen by setting a pen_delay_down or pen_delay_up in the configuration file or with the params syntax in the Python API.

Remove Const_speed option

Plotting with constant speed

Example 1: Plot file.svg with constant pen-down speed, with AxiDraw Python API:

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

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw 
nd1 = NextDraw()
nd1.plot_setup("file.svg")
nd1.options.handling = 4 # Select Constant speed Handling mode
nd1.plot_run()

Example 3: Plot file.svg with constant pen-down speed, with AxiDraw CLI

axicli file.svg --const_speed

Example 4: The same, with the Bantam Tools NextDraw CLI:

nextdraw file.svg --handling 4

The const_speed option in the AxiDraw software is not part of the NextDraw software. If you are using it, update to using the the Constant speed handling mode. [CLI details, Python API details]

Preview rendering

Preview rendering

Example 1: Run a plot preview without rendering pen motion, in AxiDraw Python API:

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

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw 
nd1 = NextDraw()
nd1.plot_setup("file.svg")
nd1.options.preview = False
nd1.options.rendering = False
output_svg = nd1.plot_run(True)

Example 3: Run a plot preview without rendering pen motion, in AxiDraw CLI:

axicli file.svg -v --rendering 0 -o outputfile.svg

Example 4: The same, with the Bantam Tools NextDraw CLI:

nextdraw file.svg -v --no_render -o outputfile.svg

In the AxiDraw software, the integer rendering option controls which paths are rendered, if any, when running a plot preview.

In the NextDraw software, preview rendering is boolean (not integer) and is on by default. The rendering option in the Python API is boolean.

There is a separate no_render option in the CLI API to disable preview rendering.

Fine-grain control of which paths are rendered is still possible using the new preview_paths parameter in your configuration file, or with the params syntax in the Python API.

toggle mode -> utility_cmd

Toggling the pen

Example 1: Toggle the pen, in AxiDraw Python API:

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

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw 
nd1 = NextDraw()
nd1.plot_setup()
nd1.options.mode = "utility"
nd1.options.utility_cmd = "toggle"
nd1.plot_run()

Example 3: Toggle the pen, in AxiDraw CLI:

axicli --mode toggle

Example 4: The same, with the Bantam Tools NextDraw CLI:

nextdraw -mode utility -M toggle

The toggle mode in the AxiDraw software is not present in the NextDraw software. So, if you are using it, transition to using the new toggle utility command (utility_cmd).

Select the utility value for mode and the toggle value for utility_cmd. [CLI details, Python API details]

Remove res_home mode

The res_home mode from the AxiDraw API is not present in the Bantam Tools NextDraw APIs.

The NextDraw software has significant improvements in its pause and resume capability which make the res_home mode obsolete. Plots can be resumed from any carriage position; the carriage position is not stored in the SVG file. (See Homing procedures for more information.) The walk_home command in utility mode can be used as a replacement, if you need to move the carriage Home.

If using a Bantam Tools NextDraw™, the find_home mode can also be used. [CLI details, Python API details]

Remove fw_version

The fw_version manual command from the AxiDraw APIs is not present in the NextDraw APIs.

The firmware version can be reported by the sysinfo mode. [CLI details, Python API details]

The firmware version is also available as a variable that can be read directly in the Python API.

Remove deprecated items

Two long-deprecated items in the AxiDraw APIs, the walk_dist option and the legacy reorder mode, are not present in the NextDraw APIs.

Additionally, the long-deprecated value 3 for reordering is not supported in the NextDraw APIs.

Python API changes

Error handling

The Bantam Tools NextDraw Python library supports new error codes, 105 and 106, for loss of power and homing failures.

There are also corresponding variables, errors.power and errors.homing which, if set, will raise errors in Python upon homing failure or loss of power. See full documentation for details.

usb_command, usb_query

usb_command, usb_query

Example 1: Query step position, in AxiDraw Python API:

from pyaxidraw import axidraw
ad = axidraw.AxiDraw()
ad.interactive()
step_pos = ad.usb_query("QS\r") # Query step position
print("Step pos: " + step_pos)
ad.disconnect()

Example 2: The same, with the Bantam Tools NextDraw Python API:

from nextdraw import NextDraw
nd1 = NextDraw()
nd1.interactive()
step_pos = nd1.usb_query("QS") # Query step position
print("Step pos: " + step_pos)
nd1.disconnect()

The usb_command, usb_query low level serial command utility commands do not need an \r at the end of the command or query; it was required in the AxiDraw software. (The \r is added automatically by the NextDraw software.)

Copyright

Documentation Copyright 2024 Windell H. Oskay, Bantam Tools. All rights reserved.