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 Binary Protocol.

Generic command method

The following example demonstrates how to send an arbitrary command:

// const { binary: { Connection, CommandCode } } = require('@zaber/motion');

// connection is the previously opened Connection
const response = await connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
console.log('Response:', response);

# from zaber_motion.binary import Connection, CommandCode

# connection is the previously opened Connection
response = connection.generic_command(1, CommandCode.ECHO_DATA, 12345)
print("Response:", response)

// connection is the previously opened Connection
var response = connection.GenericCommand(1, CommandCode.EchoData, 12345);
Console.WriteLine("Response: " + response);

// import zaber.motion.binary.Connection;
// import zaber.motion.binary.CommandCode;
// import zaber.motion.binary.Message;

// connection is the previously opened Connection
Message response = connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
System.out.println("Response data: " + response.toString());

% import zaber.motion.binary.Connection;
% import zaber.motion.binary.CommandCode;

% connection is the previously opened Connection
response = connection.genericCommand(1, CommandCode.ECHO_DATA, 12345);
fprintf('Response data: %s.\n', response.toString());

% import zaber.motion.binary.Connection;
% import zaber.motion.binary.CommandCode;

% connection is the previously opened Connection
response = connection.genericCommand(1, CommandCode.EchoData, 12345);

% Note: data class `toString` methods were added in toolbox version 8.4.0
fprintf('Response data: %s\n', response.toString());

// connection is the previously opened Connection
Message response = connection.genericCommand(1, CommandCode::ECHO_DATA, 12345);
std::cout << "Response data: " << response.toString() << std::endl;

In the example above, the Echo Data command is sent to device number 1. The method returns a response which contains the fields from the reply of the device.

Binary protocol move commands return a response when movement is complete or when another command has pre-empted it. The default timeout for the genericCommand method is 0.5 seconds, so if you are using it to send movement commands, a timeout exception is thrown if the movement takes longer to complete. In this case, you should adjust the timeout by setting the timeout argument to the number of seconds you expect the movement to take. The example below homes the device with a timeout of 10 seconds.

await connection.genericCommand(1, CommandCode.HOME, 0, { timeout: 10 });

connection.generic_command(1, CommandCode.HOME, 0, 10)

connection.GenericCommand(1, CommandCode.Home, 0, 10);

connection.genericCommand(1, CommandCode.HOME, 0, 10);

connection.genericCommand(1, CommandCode.HOME, 0, 10);

connection.genericCommand(1, CommandCode.Home, 0, 10);

connection.genericCommand(1, CommandCode::HOME, 0, 10);

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

In addition to the genericCommand method, there are two related methods. The first is genericCommandNoResponse , which does not wait for a response from the device after issuing the command. The second method is genericCommandMultiResponse , which reads all responses on the port after issuing the command. The genericCommandMultiResponse method is used when sending a command to device 0, as doing this sends the command to all the devices on the port.

In addition to the Connection class, these methods can also be found in the Device class (removing the need to specify device arguments).

Unit conversions

You may also send arbitrary commands with unit conversions on both its parameter and the returned data. The example below demonstrates the use of the genericCommandWithUnits method to move the device by 3 millimetres and convert the returned position to centimetres.

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

const position = await device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Length.MILLIMETRES, Length.CENTIMETRES, { timeout: 10 });
console.log('Position in centimetres:', position);

# from zaber_motion.binary import Connection, CommandCode
# from zaber_motion import Units

position = device.generic_command_with_units(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10)
print("Position in centimetres:", position)

var position = device.GenericCommandWithUnits(CommandCode.MoveRelative, 3, Units.Length_Millimetres, Units.Length_Centimetres, 10);
Console.WriteLine("Position in centimetres: " + position);

// import zaber.motion.binary.Connection;
// import zaber.motion.binary.Device;
// import zaber.motion.binary.CommandCode;
// import zaber.motion.Units;

double position = device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10);
System.out.println("Position in centimetres: " + position);

% import zaber.motion.binary.Connection;
% import zaber.motion.binary.Device;
% import zaber.motion.binary.CommandCode;
% import zaber.motion.Units;

position = device.genericCommandWithUnits(CommandCode.MOVE_RELATIVE, 3, Units.LENGTH_MILLIMETRES, Units.LENGTH_CENTIMETRES, 10);
fprintf('Position in centimetres: %d\n', position);

% import zaber.motion.binary.Connection;
% import zaber.motion.binary.Device;
% import zaber.motion.binary.CommandCode;
% import zaber.motion.Units;

position = device.genericCommandWithUnits(CommandCode.MoveRelative, 3, Units.Length("mm"), Units.Length("cm"), 10);
fprintf('Position in centimetres: %f\n', position);

// connection is the previously opened Connection
double position = device.genericCommandWithUnits(CommandCode::MOVE_RELATIVE, 3, Units::LENGTH_MILLIMETRES, Units::LENGTH_CENTIMETRES, 10);
std::cout << "Position in centimetres: " << position << std::endl;

Command Reference

To see the full command reference, visit:

Sending arbitrary commands

Generic command method

Unit conversions

Command Reference

API Reference