Sending arbitrary commands

The library includes methods for the most commonly used device commands. There are additional commands available to devices, and a set of generic methods for sending arbitrary commands to a device is included in the library. Constructing the low level commands for these methods requires knowledge of the underlying Zaber ASCII Protocol.

Generic command method

The following example demonstrates how to send an arbitrary command:

// connection is the previously opened Connection
const response = await connection.genericCommand('home', { device: 1, axis: 1 });

# connection is the previously opened Connection
response = connection.generic_command('home', device=1, axis=1)

// connection is the previously opened Connection
var response = connection.GenericCommand("home", device: 1, axis: 1);

// connection is the previously opened Connection
Response response = connection.genericCommand("home", 1, 1);

% connection is the previously opened Connection
response = connection.genericCommand('home', 1, 1);

// connection is the previously opened Connection
Response response = connection.genericCommand("home", 1, 1);

In the example above, the home command is sent to device number 1, axis number 1. The device number is the second parameter, the axis number is the third. The method returns a response which contains the fields from the reply of the device. Note that the device initiates homing and sends the response immediately. The process of homing takes additional time after the method returns.

If the device rejects the command, the method throws an exception. If you want to override this behavior and examine the response in case of rejection, you may change the last argument, check_errors , to false.

In addition to the generic_command method, there are two other related methods; the generic_command_no_response method does not look for any response from the device, and the generic_command_multi_response method reads all responses on the port and can be used if the command is sent to device 0 so that all devices respond. In addition to the Connection class, these methods can also be found in the

Device

and Axis classes (removing the need to specify device and axis arguments).

Unit conversions

A feature that this library adds is unit conversions. Even if an arbitrary command is being sent, there's an option to perform unit conversions on its parameters using the prepare_command method. This method is available on the Device class as well as the Axis class. The arguments consist of command template and command arguments specified as Measurement instances.

Unit conversion is not supported for device-scope commands where axes can be remapped, such as stream and pvt commands.

Since axis unit conversion is specific to the particular hardware of the axis, a command prepared for an axis can only be safely executed on the Axis class instance which produced the command.

The following example prepares and issues an axis command which executes 3 sinusoidal movements with an amplitude of 10 mm and a period of 2 seconds.

// const { ascii: { Connection }, Length, Time } = require('@zaber/motion');

const cmd = axis.prepareCommand('move sin ? ? ?',
  { value: 10, unit: Length.MILLIMETRES },
  { value: 2, unit: Time.SECONDS },
  { value: 3 }
);
await axis.genericCommand(cmd);

# from zaber_motion import Measurement

cmd = axis.prepare_command("move sin ? ? ?",
    Measurement(value=10, unit=Units.LENGTH_MILLIMETRES),
    Measurement(value=2, unit=Units.TIME_SECONDS),
    Measurement(value=3)
)
axis.generic_command(cmd)

var cmd = axis.PrepareCommand("move sin ? ? ?",
    new Measurement() { Value = 10, Unit = Units.Length_Millimetres },
    new Measurement() { Value = 2, Unit = Units.Time_Seconds },
    new Measurement() { Value = 3 }
);
axis.GenericCommand(cmd);

// import zaber.motion.Measurement;

String cmd = axis.prepareCommand("move sin ? ? ?",
    new Measurement(10, Units.LENGTH_MILLIMETRES),
    new Measurement(2, Units.TIME_SECONDS),
    new Measurement(3)
);
axis.genericCommand(cmd);

% import zaber.motion.Measurement;

cmd = axis.prepareCommand('move sin ? ? ?', ...
    [Measurement(10, Units.LENGTH_MILLIMETRES), ...
    Measurement(1, Units.TIME_SECONDS), ...
    Measurement(3)]);
axis.genericCommand(cmd);

std::string cmd = axis.prepareCommand("move sin ? ? ?",
    Measurement(10, Units::LENGTH_MILLIMETRES),
    Measurement(1, Units::TIME_SECONDS),
    Measurement(3)
);
axis.genericCommand(cmd);

Reference

To see the full command reference, visit: