Zaber's ASCII Protocol

Introduction

Zaber's ASCII protocol is the recommended protocol for communicating with all Zaber products with firmware version 6 or newer. It is a text based protocol designed to be human readable, intuitive, and easy to use.

Messages in the ASCII protocol all start with a single character indicating the message type, contain space-separated parameters, and end with a newline (↵). The two most common message types are commands, which start with / and are always sent by the user, and replies, which start with @ and are always sent by Zaber devices in response to commands.

/1 system reset↵
@01 0 OK IDLE -- 0↵

The first message, 1 system reset, is a command instructing the device at address 1 to reset. The second message, 01 0 OK IDLE -- 0 is a reply from device 1 saying that, among other things, the command succeeded (OK). Replies always have the following fields:

@01 0 OK IDLE -- 0↵
 ┬─ ┬ ┬─ ─┬── ┬─ ┬
 │  │ │   │   │  ╰─ The return value (0 if there is no relevant data)
 │  │ │   │   ╰──── The highest level fault or warning (-- means there are no faults or warnings)
 │  │ │   ╰──────── BUSY if the device is moving or IDLE otherwise
 │  │ ╰──────────── OK if the command succeeded or RJ if it was rejected
 │  ╰────────────── The axis number relevant for the reply 
 │                  (0 if it applies to all axes or the whole device, 1 onwards for individual axes)
 ╰───────────────── The address of the device sending the reply

There are two other types of messages, but they are used less frequently:

• Info messages, which start with a # and are sent by devices after replying to some commands.
• Alert messages, which start with ! and are spontaneously sent by a device when an event occurs. Alerts are disabled by default.

For more information on the types of ASCII protocol messages and their formats, see the Message Format section of the ASCII Protocol Manual.

Addressing

Each device using the ASCII protocol is assigned a unique address, and each axis on a device has a unique number. Together these two numbers define which devices and/or axes the command will be executed on. If a command omits one of these numbers, or specifies it be 0, the command is assumed to apply to all devices and/or axes. For instance, the following commands are equivalent and will be executed on all devices and axes in the chain:

/get pos↵
/0 get pos↵
/0 0 get pos↵

However, the following commands will be executed on all the axes of only device 2:

/2 get pos↵
/2 0 get pos↵

To send a command to only, for example, axis 1 on device 2, the device address and axis number must be fully specified:

/2 1 get pos↵

Commands

The ASCII protocol supports a wide range of useful commands to easily control the behaviour of the device, including:

move commands

Start basic motion

io commands

Configure digital and/or analog inputs and outputs

stream commands

Configure queued sequences of commands and coordinate multi-axis motion

trigger commands

Configure automatic actions to specific events

get and set commands

Configure device settings

For the full list of supported commands, see the Command Reference section of the ASCII Protocol Manual.

Making it Move

It is recommended that the first movement command sent to a device after it is connected and powered is the home command. The device will move to the home limit sensor and establish a reference position:

/home↵
@01 0 OK BUSY WR 0↵

If the device hasn't been homed, motion commands may not work as expected. The controller's position limits will not match the physical limits, absolute movements will not move to expected positions, and relative movements the device is capable of may be rejected for being outside the travel range. Replies from the device will include the No Reference Position (WR) flag:

/move rel 10000↵
@01 0 RJ IDLE WR BADDATA↵

Once the device has been homed, make the device move by sending a move command. For example, to move a distance of 10,000 forward from the current position:

/move rel 10000↵
@01 0 OK BUSY -- 0↵

To move to the absolute position 10,000, measured from the home position, regardless of the current position:

/move abs 10000↵
@01 0 OK BUSY -- 0↵

For information about unit conversions, see the Physical Units section in the ASCII Protocol Manual.

Changing a Device Setting

All settings are read and modified using the get and set commands. For example, to read the device's maxspeed setting:

/get maxspeed↵
@01 0 OK IDLE -- 153600↵

The maximum speed setting is currently 153,600.

On a multi-axis device, sending an axis-scope command without specifying an axis returns a value for each of the axes. If the setting is not supported on an axis, NA will be returned for that axis. For example:

/get maxspeed↵
@01 0 OK IDLE -- 153600 NA 153600↵

The maximum speed setting is 153,600 on axis 1 and 3, but is not supported on axis 2.

To set the maximum speed, for example, to be twice what was read use the set command:

/set maxspeed 307200↵
@01 0 OK IDLE -- 0↵

On a multi-axis device, the above command sets the maximum speed for all axes.

For a full list of supported settings, see the Setting Reference section in the ASCII Protocol Manual.

Software APIs

Although the ASCII protocol is simple and easy to use, properly using any protocol in software can be a tedious task. The Zaber Motion Library (ZML) APIs provide ergonomic and intuitive bindings for the ASCII protocol and extra features such as automatic unit conversions in a wide range of languages including Python, C#, Javascript, Java, C++, and others.