Software/ASCII Labview Driver
This LabVIEW instrument driver includes subVIs and controls that make it easy to start controlling Zaber devices using the ASCII protocol, which is the default protocol of Zaber X-Series devices and is available on Zaber A-Series devices with firmware 6.06+. A LabVIEW driver for using the Binary protocol, which is the only protocol available on Zaber T-Series devices, is available here. Instructions for switching between the Binary and ASCII protocols are available here. For details on the different Zaber device series see the Series Reference Table.
Installation
There are several methods of downloading and installing the Zaber ASCII driver. The Direct Download method is recommended, as it downloads the most up-to-date version that will be the most backwards-compatible. To use the driver, the NI-VISA driver 4.5 or higher must also be installed.
Direct Download
A zip file containing the latest version of the driver is available for download here. This version is compatible with LabVIEW 2015 and higher, and may be more up-to-date than the certified driver version. Unzip the folder into <National Instruments>\LabVIEW<xxxx>\instr.lib. If you have trouble finding the driver or installing it, please contact us.
Download and Install using LabVIEW
In LabVIEW 2015 or higher, the driver can be installed from within LabVIEW by going to the Help menu and selecting 'Find Instrument Drivers...'. Select Zaber Technologies under 'Manufacturer' and press 'Search'. Select 'zaberA Instrument Driver' from the list and press 'Install>'. If you're updating to a new version, confirm that you want to overwrite the existing folder. Press 'Start using this driver' to complete installation.
Download from National Instruments IDNet
The latest National Instruments certified version of the driver is available for download from the National Instruments IDNet. This version is compatible with LabVIEW 2015 and higher. Install the folder using National Instruments installation instructions.
Older Versions of LabVIEW
If you are using a LabVIEW version from 2009 to 2014, you can try this zip file instead. This file contains the driver saved for LabVIEW 2009 but otherwise unmodified. Please note that the driver contains several polymorphic VIs that will not work in these versions of LabVIEW; you will have to select the non-polymorphic versions if you encounter problems. We do not test compatibility with older versions of LabVIEW.
VIs and Controls Included in the Driver
While many of the VIs included in the driver don't require a user to have knowledge of the underlying protocol, the lower level VIs do. The manual for the ASCII command protocol is here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual. This manual is a reference for what each command and setting does and how they are formatted.
Some VIs have versions that are marked as (FW7) and (Polymorphic). It's recommended to use the Polymorphic version of these VIs.
The reason is that the original version of the VI was designed with support for 32-bit integers on inputs and outputs, which was sufficient for Zaber devices with firmware 6.06 - 6.99. New devices with firmware version 7.01+ support responses with 64-bit integers. To support these larger integers, new VIs marked as (FW7) were created, and to maintain backward compatibility, the original versions are still provided. The Polymorphic VIs are versatile and will adapt between the original and FW7 as needed.
Device Information Table
In order to simplify and automate access to device-specific information, a table of information in CSV format is available in the direct download version of the library, along with a Python script that can be run to update the CSV with the newest values. These are not included in the certified library from National Instruments, but they can be downloaded here and added into the examples folder of the library. The table matches device IDs and peripheral IDs to device names, microstep sizes, and device types (linear, rotary, controller). The Control Panel example included in the driver shows an example of how this table can be incorporated into a VI and work with the Look Up Device Properties and Get Device IDs utility VIs.
Connection VIs
Initialize
Establishes communication with a Zaber device connected to a serial port or USB serial port and clears the serial buffer. Call this VI before calling other instrument driver VIs for this instrument. You need to call the Initialize VI only once at the beginning of an application, or again after using the Close VI.
Note: The default baud rate for the ASCII protocol is 115200, but the devices can be adjusted to use different baud rates in which case you should adjust the baud rate input. |
Initialize TCPIP
Establishes communication with a Zaber device connected to the local TCP/IP network. Call this VI before calling other instrument driver VIs for this instrument. You need to call the Initialize TCPIP VI only once at the beginning of an application, or again after using the Close VI.
This VI will work with Zaber devices that have an Ethernet connector, such as the X-MCC series, or with Zaber serial devices that are connected to the network using a hardware or software bridge. Note: There is a VI called Format TCPIP VISA Resource Name in the Utility section below that can assist with correctly formatting the resource name input for this VI. |
Close
Terminates the software connection to the instrument. Make sure to call at the end of all programs or the communication port will not be available to other software. |
Actions/Status VIs
Home
Moves an axis in the negative direction towards the home sensor in order to provide a reference position for absolute movements. It's recommended that this sequence is run following the power on of the device, but doesn't need to be run again unless a) the power to the device is cycled, or b) the reference position is lost (axis stalls). The VI will wait until the axis has homed to continue.
To home a single axis, specify the Device and Axis on the input. This VI requires that the Initialize VI has been called with the same serial port. |
Stop
Decelerates the specified axis to a stop. The VI will block until movement has stopped and the device is idle.
This VI requires that the Initialize VI has been called with the same serial port. |
Move
Moves an axis. You can optionally input the Device and Axis to move, and the other inputs specify the type of movement (absolute or relative), the units of the data you'd like to send, and the distance data in those units. If no movement type or unit is input the default is relative movement in microsteps. Finally if you are using any other unit than microsteps you must input the Microstep Size for the model.
No responses are returned with this VI, but if you would like to wait until the movement is completed to continue, you can combine this VI with the Poll Until Idle VI. This VI requires that the Initialize VI has been called with the same serial port. Note: See the Device Lookup control for the microstep size of your model, or check on the product specifications page for the product on www.zaber.com. |
Move at Velocity
Moves an axis at a specified velocity. If you select an input unit other than device speed units, you must also set the microstep size input to the physical size of your axis's microstep in micrometers or degrees - consult your device's manual for this value.
No responses are returned with this VI, but if you would like to wait until the movement is completed to continue, you can combine this VI with the Poll Until Idle VI. Movement stops when the stage reaches the end of its travel or a stop command is received. This VI requires that the Initialize VI has been called with the same serial port. Note: See the Device Lookup control for the microstep size of your model, or check on the product specifications page for the product on www.zaber.com. |
Sinusoidal Move
Moves an axis in a sinusoidal pattern. To define the sinusoidal motion parameters, specify the peak amplitude (half of the total amplitude) using device position units. You can optionally use the Convert Position Units to Device Units VI to convert from standard units of measure. Use a positive amplitude value to start at a negative peak and move forward, or a negative value to start at the positive peak and move backward.
Specify the period duration in milliseconds - period must be greater than zero. The period input has a resolution of 0.1ms. The motion will end when a "stop" command or a "move sin stop" command is received, or when the optional cycle count has been reached. This VI requires that the Initialize VI has been called with the same serial port. Note: See the Device Lookup control for the microstep size of your model, or check on the product specifications page for the product on www.zaber.com. |
Sinusoidal Stop
Halts a sinusoidal motion already in progress at the next cycle boundary.
The normal stop command (see the Stop VI) will decelerate a sinusoidal motion immediately. Use this sinusoidal stop command if you want motion to halt after a whole number of cycles. This VI requires that the Initialize VI has been called with the same serial port. |
Low Level VIs
Send Command
Sends a command to the device. For inputting the command, it combines the Device and Axis input, Command input, and Data value input to create a complete command. You could optionally send the complete command directly to the Command input. Omitting the Device and Axis will send the command to all devices/axes. See a command reference here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Command_Reference.
The Detect Devices VI is designed to provide an easy list of valid Device and Axis inputs. An array containing the complete strings of the responses is returned on the Response String Array output, and the details of the format of the response are described here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Replies. This VI also parses the strings, bundles the components, and returns them as an array of bundles on the Response Bundle Array pin. Additionally a pin returns the number of responses received. If the command is directed at a single axis, then the First Response Bundle pin can be used rather than indexing the Response Bundle Array. This VI requires that the Initialize VI has been called with the same serial port. |
Send Stream Command
Sends a command to the device and handles the AGAIN responses that can happen with streamed commands. Devices that support live streaming can queue up a number of commands for sequential execution, but when the queue is full the device will respond to new commands with AGAIN until some commands complete and free up space in the queue. This VI will block until the device either accepts the new command or produces an error.
This VI requires that the Initialize VI has been called with the same serial port. |
Check for Idle
Checks whether the axis is idle without waiting for it to become idle. To poll a specific axis, use the Device and Axis input. This VI is not designed to poll all devices unless only one device is connected.
This VI requires that the Initialize VI has been called with the same serial port. |
Poll Until Idle
Waits for any movement of the axis to complete and the axis to be idle before continuing. To poll a specific axis, use the Device and Axis input. This VI is not designed to poll all devices unless only one device is connected.
This VI requires that the Initialize VI has been called with the same serial port. |
Lockstep VIs
The Lockstep VIs are used to control a set of axes that are paired together to move in sync. To establish a pairing, use the Lockstep VIs in the Configure directory.
|
Virtual Axis VIs
The Virtual Axis VIs are used to control a set of axes that are have an assigned relationship. To configure a relationship, use the Virtual Axis VIs in the Configure directory.
|
Streaming VIs
The Streaming VIs are used to run a series of queued motions and actions in order. This is in contrast to most other commands, which will pre-empt any previous motion when they are sent. On multi-axis controllers, motors can be synchronized to move in lines, arcs, and circles. A stream can be opened to be run immediately, or a series of stream commands can be stored on the controller (called a Stream Buffer) and called back later.
|
I/O VIs
The Action Status I/O VIs are designed for controlling the value of outputs. These VIs are only for use with controllers that have digital or analog inputs and outputs, such as the X-MCB1.
|
Force VIs
The Force VIs allow force control rather than position control on some direct-drive devices, such as the X-DMQ-DE stage.
|
Configure VIs
Set Speed and Acceleration
Sets the speed and/or acceleration of an axis to a new value. The desired speed and acceleration are inputs. If either is not connected or the value is 0, then it won't be updated. The units for the speed and acceleration can be selected with the Units input. 'Data' units are the default, and other unit selections require the Microstep Size for the axis to be input. If you'd like to specify a Device and Axis to adjust the settings of, specify this input.
This VI requires that the Initialize VI has been called with the same serial port. |
Low Level VIs
Change Setting
Changes a setting of the device. Omitting the Device and Axis will change the settings of all connected devices. See a list of settings available here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Device_Settings. You do not need to include the 'set' command with this VI, you only need to input the setting you'd like to change.
The Detect Devices VI is designed to provide an easy list of valid Device and Axis inputs. This VI requires that the Initialize VI has been called with the same serial port. |
Joystick VIs
This set of VIs includes tools for quickly setting up the Zaber X-JOY3 joystick.
|
Lockstep VIs
The Lockstep VIs can setup or disable a lockstep pairing between axes. These VIs can only be used on a controller with multiple axes, such as the X-MCB2. The Lockstep Group input of the VIs should typically be 1.
|
Virtual Axis VIs
The Virtual Axis VIs can set a relationship between two axes that is used in the Virtual Axis commands in Action-Status directory. These VIs can only be used on a controller with multiple axes, such as the X-MCB2, and with Firmware version 6. The Virtual Axis Number input of the VIs should typically be 1.
|
Data VIs
Get Current Position
Returns the current position. The unit of the value returned depends on the Units input (default is microsteps). For units other than microsteps, a Microstep Size is required for accurate results. You can optionally read from the position of a single axis by specifying the Device and Axis input.
This VI requires that the Initialize VI has been called with the same serial port. |
Detect Devices
Polls the connected devices and returns an array of the Connected Devices and Axes. Elements of the array can be used as an input for the Device and Axis input of other VIs in this library, for example through a dropdown list.
This VI requires that the Initialize VI has been called with the same serial port. |
Low Level VIs
Get Setting
Reads a setting from the device. Omitting the Device and Axis will return the settings of all connected devices. See a list of settings available here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Device_Settings. You do not need to include the 'get' command with this VI, you only need to input the setting you'd like to check.
The Detect Devices VI is designed to provide an easy list of valid Device and Axis inputs. An array containing the complete strings of the responses is returned on the Response String Array output, and the details of the format of the response are described here: https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Replies. This VI also parses the strings, bundles the components, and returns them as an array of bundles on the Response Bundle Array pin. Additionally a pin returns the number of responses received. If the setting of a single axis is being read, then the First Response Bundle pin can be used rather than indexing the Response Bundle Array. This VI requires that the Initialize VI has been called with the same serial port. |
Streaming VIs
Use these VIs to get information from a device related to streaming.
|
Lockstep VIs
These VIs return information about device axes that belong to a lockstep set. They are available on multi-axis devices, such as the X-MCB2 controller.
|
I/O VIs
Use the I/O VIs to check the current values of analog or digital inputs or outputs. These commands are only available on devices with digital or analog inputs and outputs, such as the X-MCB1 controller.
|
Virtual Axis VIs
These VIs return information about any virtual axis relationships that have been set-up. They are available on multi-axis devices, such as the X-MCB2 controller, with Firmware version 6.
|
Utility VIs
The standard instrument library utility VIs are included. These allow you to reset, check error messages, run a self-test, and check the revision of the device and library. For more information on these VIs, download the library and check the VI descriptions of the utility VIs.
Get Device IDs
Returns the numeric device ID and peripheral ID if appropriate for one device and optional axis. The outputs can be used with the Look Up Device Properties VI to get information about the device such as its name and microstep size.
This VI is meant to work with only one device or one device and one axis at a time. Providing a device and axis input that matches multiple devices produces undefined behavior. When addressing a standalone controller, the first axis is assumed unless you specify an axis number or zero to get information about the controller itself. This VI requires that the Initialize VI has been called with the same serial port. |
Look Up Device Properties
This VI assists with looking up instrument properties in a table provided by Zaber. You can obtain the device ID and peripheral ID (if applicable) numbers from the device with the Get Device IDs VI, and use the LabVIEW Read Delimited Spreadsheet VI to load the lookup table. Given those inputs, this VI will attempt to find the device position scale factor and its name and motion type.
Note that this VI is not optimized for speed; for efficiency, do not look up device properties inside high-speed loops. Errors are produced if the table does not have the expected format, or if the device is not found in the table. |
Error Query
Checks a collection of responses for warning flags and reports all warnings from responding devices that have warning conditions.
Optional inputs allow for ignoring some warnings or treating some warnings as error conditions. Both of these inputs are arrays of strings, each of which should be a two-letter warning code as seen in the Zaber ASCII Protocol Manual at https://www.zaber.com/wiki/Manuals/ASCII_Protocol_Manual#Warning_Flags. You can globally ignore warnings or treat warnings as errors without having to wire up the relevant inputs everywhere by entering new defaults for the inputs - see the note on this VI's front panel. This VI requires that the Initialize VI has been called with the same serial port. |
Unit Conversion VIs
Commands send to devices will use Zaber Device Units for positions, speeds, and accelerations. These device units have a relationship to real world units based on the 'microstep size' specification of an axis. These conversion utilities are provided to easily convert from and to device units based on real-world units (millimeters, inches, degrees, etc.). These VIs require that the microstep size is input. Some VIs, such as the Move VI, integrate the conversion VIs and can provide an example of their usage. |
Format TCPIP VISA Resource Name
Helper VI to create a VISA resource name suitable for use with the Initialize TCPIP VI. This takes a hostname or IP address and a port number as inputs and produces a VISA resource name as output. |
Private VIs and Controls
The instrument driver includes some VIs and controls in the Private folder.
The private VIs are used as low-level building blocks for the other library VIs, and as such are not directly accessible. If access to low-level functions such as reading and writing to the serial port are desired, it's suggested that the user copy the VIs from the private folder to another location.
Examples
You can find the below examples in the examples folder of the instrument driver package.
Commands and Responses
The purpose of this example is to show how you can enter commands and read back responses. There are a number of ways to read responses, whether you just read one response, only want part of the response, or prefer the complete string. Try writing some of the example commands and see what response options are available. Enter the VISA resource your device is connected to and the Command string before running the VI |
TCPIP Commands and Responses
This variation of the above Commands and Responses example demonstrates how to connect to a network-enabled Zaber device, send commands and read back responses. |
Move
This example shows how you can use the Move VI to make movements easily. The Move VI allows you to use real world units while moving the stage. This is useful because typically you would send movement commands with microstep values and make conversions to see how it relates to real units. To use these units (except microsteps) make sure to input the Microstep Size before running. This value can be found on spec page for the product on www.zaber.com. |
TCPIP Move
This variation of the above Move example shows how to connect to a network-enabled Zaber device and make movements. |
Control Panel
This VI is a control panel that allows the user to perform a variety of commands and motions, see what devices are connected, read and change settings, and track the movements. It is both an example of the way you can use the instrument library as well as a versatile tool for basic usage.
This example requires that the Zaber A Series Device Table.csv file is installed in the examples folder. This file is included in the Direct Download version of the driver but not the version from National Instruments. To download the table, see the Device Information Table section for more details. |
Streaming
Streaming lets you queue a number of commands to be completed in series. With multi-axis controllers the movement is co-ordinated to make lines, arcs, or circles.
This example allows interactive execution of some of the streaming commands. Some of the features will function with single axis streams. |
IO Ports
This example shows how you can query and set inputs and outputs when they are available on Zaber controllers, such as the A-MCB2, X-MCB1, and X-MCB2. This example will not function when connected to a device that does not have I/O ports. |
XYZ List
This example moves a system of up to three axes through a list of co-ordinates. It uses the Move command as well as the Poll Until Idle library VI to co-ordinate the timing of the movements of the stages. |
Sinusoidal Move
Demonstrates how the Move Sin VI can be used to easily set-up and run a sinusoidal motion. This example also records the position and displays a position vs time chart during the motion. |
Joystick Configurator
This VI is a helper for reading and changing the axis and button settings for an X-JOY3 joystick. It can also serve as an example for creating custom joystick initialization routines.
Note that this tool only works with Zaber X-series joysticks such as the X-JOY3. |
Raster Scan
This VI is an application for doing raster scans or well plate traversals with Zaber stages. It can traverse a grid with any number of axes, and at each grid point can optionally send a sequence of commands to other Zaber devices, along with custom user-defined actions.
You must have at least two stages or a two-axis stage connected to your serial port to use this program. |
Custom Error and Warning Codes
The library defines the following custom error and warning codes:
Code | Type | Reason | Description |
---|---|---|---|
-1074000001 | Error | The self-test failed | When running the Self-Test VI, an echo command was sent to the device and the expected response was not received. Contact Zaber customer support. |
-1074000002 | Error | Warning Flag(s) reported as an error | When running the Error Query VI, one or more of the warning flags were set to be reported as error messages, and one or more of these has occurred. |
-1074000003 | Error | Invalid checksum result | The checksum number returned with the response did not match the checksum value of the response. This indicates that there was likely a problem in the transmission of the response from the controller to the computer. |
-1074000004 | Error | Invalid Reply Flag | The Reply Flag of the response was not a valid value (either OK or RJ). This indicates that there was likely a problem in the transmission of the response from the controller to the computer. |
-1074000005 | Error | Invalid Response Type | The Response Type was not a valid value (one of @, !, or #). This indicates that there was likely a problem in the transmission of the response from the controller to the computer. |
1073481728 | Warning | Warning Flag(s) reported | When running the Error Query VI, one or more of the warning flags were reported in a response. |
1073481729 | Warning | BADCHECKSUM | The checksum provided in the command message was incorrect. |
1073481730 | Warning | BADCOMMAND | The command or setting is incorrect or invalid. |
1073481731 | Warning | BADDATA | The data provided in the command is incorrect or out of range. |
1073481732 | Warning | STATUSBUSY | The device cannot be parked, nor can certain settings be changed, because it is currently busy. |
1073481733 | Warning | DEVICEONLY | An axis number was specified when trying to execute a device only command. |
1073481734 | Warning | PARKED | The axis cannot move because it is currently parked. |
1073481735 | Warning | AGAIN | The command cannot be processed right now. The user or application should send the command again. Occurs only during streamed motion. |
1073481736 | Warning | BADMESSAGEID | A message ID was provided, but was not either -- or a number from 0 to 99. |
1073481737 | Warning | BADAXIS | The command was sent with an axis number greater than the number of axes available. |
1073481738 | Warning | LOCKSTEP | An axis cannot be moved using normal motion commands because it is part of a lockstep group. You must use lockstep commands for motion or disable the lockstep group first. |
1073481739 | Warning | FULL | The device has run out of permanent storage and cannot accept the command. Occurs when storing to a stream buffer or when saving commands to joystick keys. |
1073481740 | Warning | NOACCESS | The command or setting is not available at the current access level. |
Any other error or warning codes LabVIEW reports aren't specified by Zaber, and National Instruments documentation should be consulted. Serial communication handling using VISA drivers is one common source of error messages. Check the error message in the National Instruments Knowledge Base: https://www.ni.com/kb/.