zaber.motion.ascii.Device Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of motion-library Show documentation
Show all versions of motion-library Show documentation
A library that aims to provide easy-to-use API for communication with Zaber devices using Zaber ASCII Protocol.
// ===== THIS FILE IS GENERATED FROM A TEMPLATE ===== //
// ============== DO NOT EDIT DIRECTLY ============== //
package zaber.motion.ascii;
import zaber.motion.FirmwareVersion;
import zaber.motion.protobufs.Main;
import zaber.motion.gateway.Call;
import zaber.motion.exceptions.MotionLibException;
import zaber.motion.Measurement;
import java.util.Arrays;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;
import java.util.concurrent.ExecutionException;
/**
* Represents the controller part of one device - may be either a standalone controller or an integrated controller.
*/
public class Device {
private Connection connection;
/**
* @return Connection of this device.
*/
public Connection getConnection() {
return this.connection;
}
private int deviceAddress;
/**
* @return The device address uniquely identifies the device on the connection.
* It can be configured or automatically assigned by the renumber command.
*/
public int getDeviceAddress() {
return this.deviceAddress;
}
private DeviceSettings settings;
/**
* @return Settings and properties of this device.
*/
public DeviceSettings getSettings() {
return this.settings;
}
private DeviceIO io;
/**
* @return I/O channels of this device.
*/
public DeviceIO getIO() {
return this.io;
}
private AllAxes allAxes;
/**
* @return Virtual axis which allows you to target all axes of this device.
*/
public AllAxes getAllAxes() {
return this.allAxes;
}
private Warnings warnings;
/**
* @return Warnings and faults of this device and all its axes.
*/
public Warnings getWarnings() {
return this.warnings;
}
/**
* @return Identity of the device.
*/
public DeviceIdentity getIdentity() {
return this.retrieveIdentity();
}
/**
* @return Indicates whether or not the device has been identified.
*/
public boolean getIsIdentified() {
return this.retrieveIsIdentified();
}
/**
* @return Unique ID of the device hardware.
*/
public int getDeviceId() {
return this.getIdentity().getDeviceId();
}
/**
* @return Serial number of the device.
*/
public long getSerialNumber() {
return this.getIdentity().getSerialNumber();
}
/**
* @return Name of the product.
*/
public String getName() {
return this.getIdentity().getName();
}
/**
* @return Number of axes this device has.
*/
public int getAxisCount() {
return this.getIdentity().getAxisCount();
}
/**
* @return Version of the firmware.
*/
public FirmwareVersion getFirmwareVersion() {
return this.getIdentity().getFirmwareVersion();
}
public Device(
Connection connection, int deviceAddress) {
this.connection = connection;
this.deviceAddress = deviceAddress;
this.settings = new DeviceSettings(this);
this.io = new DeviceIO(this);
this.allAxes = new AllAxes(this);
this.warnings = new Warnings(this, 0);
}
/**
* Queries the device and the database, gathering information about the product.
* Without this information features such as unit conversions will not work.
* Usually, called automatically by detect devices method.
* @return A CompletableFuture that can be completed to get the result:
* Device identification data.
*/
public CompletableFuture identifyAsync() {
Main.DeviceIdentifyRequest.Builder builder = Main.DeviceIdentifyRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
CompletableFuture response = Call.callAsync(
"device/identify",
builder.build(),
Main.DeviceIdentity.parser());
return response
.thenApply(r -> DeviceIdentity.fromProtobuf(r));
}
/**
* Queries the device and the database, gathering information about the product.
* Without this information features such as unit conversions will not work.
* Usually, called automatically by detect devices method.
* @return Device identification data.
*/
public DeviceIdentity identify() {
try {
return identifyAsync().get();
} catch (ExecutionException e) {
if (e.getCause() instanceof MotionLibException) {
throw (MotionLibException) e.getCause();
} else {
throw new MotionLibException(e.getCause());
}
} catch (InterruptedException e) {
throw new MotionLibException(e);
}
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when the device rejects the command.
* @param timeout The timeout, in milliseconds, for a device to respond to the command.
* Overrides the connection default request timeout.
* @return A CompletableFuture that can be completed to get the result:
* A response to the command.
*/
public CompletableFuture genericCommandAsync(
String command, int axis, boolean checkErrors, int timeout) {
Main.GenericCommandRequest.Builder builder = Main.GenericCommandRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
builder = builder.setCommand(command);
builder = builder.setAxis(axis);
builder = builder.setCheckErrors(checkErrors);
builder = builder.setTimeout(timeout);
CompletableFuture response = Call.callAsync(
"interface/generic_command",
builder.build(),
Main.GenericCommandResponse.parser());
return response
.thenApply(r -> Response.fromProtobuf(r));
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when the device rejects the command.
* @return A CompletableFuture that can be completed to get the result:
* A response to the command.
*/
public CompletableFuture genericCommandAsync(
String command, int axis, boolean checkErrors) {
return genericCommandAsync(command, axis, checkErrors, 0);
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @return A CompletableFuture that can be completed to get the result:
* A response to the command.
*/
public CompletableFuture genericCommandAsync(
String command, int axis) {
return genericCommandAsync(command, axis, true, 0);
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @return A CompletableFuture that can be completed to get the result:
* A response to the command.
*/
public CompletableFuture genericCommandAsync(
String command) {
return genericCommandAsync(command, 0, true, 0);
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when the device rejects the command.
* @param timeout The timeout, in milliseconds, for a device to respond to the command.
* Overrides the connection default request timeout.
* @return A response to the command.
*/
public Response genericCommand(
String command, int axis, boolean checkErrors, int timeout) {
try {
return genericCommandAsync(command, axis, checkErrors, timeout).get();
} catch (ExecutionException e) {
if (e.getCause() instanceof MotionLibException) {
throw (MotionLibException) e.getCause();
} else {
throw new MotionLibException(e.getCause());
}
} catch (InterruptedException e) {
throw new MotionLibException(e);
}
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when the device rejects the command.
* @return A response to the command.
*/
public Response genericCommand(
String command, int axis, boolean checkErrors) {
return genericCommand(command, axis, checkErrors, 0);
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @return A response to the command.
*/
public Response genericCommand(
String command, int axis) {
return genericCommand(command, axis, true, 0);
}
/**
* Sends a generic ASCII command to this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @return A response to the command.
*/
public Response genericCommand(
String command) {
return genericCommand(command, 0, true, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when a device rejects the command.
* @param timeout The timeout, in milliseconds, for a device to respond to the command.
* Overrides the connection default request timeout.
* @return A CompletableFuture that can be completed to get the result:
* All responses to the command.
*/
public CompletableFuture genericCommandMultiResponseAsync(
String command, int axis, boolean checkErrors, int timeout) {
Main.GenericCommandRequest.Builder builder = Main.GenericCommandRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
builder = builder.setCommand(command);
builder = builder.setAxis(axis);
builder = builder.setCheckErrors(checkErrors);
builder = builder.setTimeout(timeout);
CompletableFuture response = Call.callAsync(
"interface/generic_command_multi_response",
builder.build(),
Main.GenericCommandResponseCollection.parser());
return response
.thenApply(r -> r.getResponsesList().stream()
.map(resp -> Response.fromProtobuf(resp)).toArray(Response[]::new));
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when a device rejects the command.
* @return A CompletableFuture that can be completed to get the result:
* All responses to the command.
*/
public CompletableFuture genericCommandMultiResponseAsync(
String command, int axis, boolean checkErrors) {
return genericCommandMultiResponseAsync(command, axis, checkErrors, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @return A CompletableFuture that can be completed to get the result:
* All responses to the command.
*/
public CompletableFuture genericCommandMultiResponseAsync(
String command, int axis) {
return genericCommandMultiResponseAsync(command, axis, true, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @return A CompletableFuture that can be completed to get the result:
* All responses to the command.
*/
public CompletableFuture genericCommandMultiResponseAsync(
String command) {
return genericCommandMultiResponseAsync(command, 0, true, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when a device rejects the command.
* @param timeout The timeout, in milliseconds, for a device to respond to the command.
* Overrides the connection default request timeout.
* @return All responses to the command.
*/
public Response[] genericCommandMultiResponse(
String command, int axis, boolean checkErrors, int timeout) {
try {
return genericCommandMultiResponseAsync(command, axis, checkErrors, timeout).get();
} catch (ExecutionException e) {
if (e.getCause() instanceof MotionLibException) {
throw (MotionLibException) e.getCause();
} else {
throw new MotionLibException(e.getCause());
}
} catch (InterruptedException e) {
throw new MotionLibException(e);
}
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @param checkErrors Controls whether to throw an exception when a device rejects the command.
* @return All responses to the command.
*/
public Response[] genericCommandMultiResponse(
String command, int axis, boolean checkErrors) {
return genericCommandMultiResponse(command, axis, checkErrors, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @return All responses to the command.
*/
public Response[] genericCommandMultiResponse(
String command, int axis) {
return genericCommandMultiResponse(command, axis, true, 0);
}
/**
* Sends a generic ASCII command to this device and expect multiple responses.
* Responses are returned in order of arrival.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @return All responses to the command.
*/
public Response[] genericCommandMultiResponse(
String command) {
return genericCommandMultiResponse(command, 0, true, 0);
}
/**
* Sends a generic ASCII command to this device without expecting a response and without adding a message ID
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
* @return A CompletableFuture that can be completed to know when the work is complete.
*/
public CompletableFuture genericCommandNoResponseAsync(
String command, int axis) {
Main.GenericCommandRequest.Builder builder = Main.GenericCommandRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
builder = builder.setCommand(command);
builder = builder.setAxis(axis);
return Call.callAsync("interface/generic_command_no_response", builder.build(), null)
.thenApply(r -> (Void) null);
}
/**
* Sends a generic ASCII command to this device without expecting a response and without adding a message ID
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @return A CompletableFuture that can be completed to know when the work is complete.
*/
public CompletableFuture genericCommandNoResponseAsync(
String command) {
return genericCommandNoResponseAsync(command, 0);
}
/**
* Sends a generic ASCII command to this device without expecting a response and without adding a message ID
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
* @param axis Optional axis number to send the command to.
*/
public void genericCommandNoResponse(
String command, int axis) {
try {
genericCommandNoResponseAsync(command, axis).get();
} catch (ExecutionException e) {
if (e.getCause() instanceof MotionLibException) {
throw (MotionLibException) e.getCause();
} else {
throw new MotionLibException(e.getCause());
}
} catch (InterruptedException e) {
throw new MotionLibException(e);
}
}
/**
* Sends a generic ASCII command to this device without expecting a response and without adding a message ID
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param command Command and its parameters.
*/
public void genericCommandNoResponse(
String command) {
genericCommandNoResponse(command, 0);
}
/**
* Gets an Axis class instance which allows you to control a particular axis on this device.
* Axes are numbered from 1.
* @param axisNumber Number of axis intended to control.
* @return Axis instance.
*/
public Axis getAxis(
int axisNumber) {
if (axisNumber <= 0) {
throw new IllegalArgumentException("Invalid value; physical axes are numbered from 1.");
}
return new Axis(this, axisNumber);
}
/**
* Gets a Lockstep class instance which allows you to control a particular lockstep group on the device.
* @param lockstepGroupId The ID of the lockstep group to control. Lockstep group IDs start at one.
* @return Lockstep instance.
*/
public Lockstep getLockstep(
int lockstepGroupId) {
if (lockstepGroupId <= 0) {
throw new IllegalArgumentException("Invalid value; lockstep groups are numbered from 1.");
}
return new Lockstep(this, lockstepGroupId);
}
/**
* Formats parameters into a command and performs unit conversions.
* Parameters in the command template are denoted by a question mark.
* Command returned is only valid for this device.
* For more information refer to: [ASCII Protocol Manual](https://www.zaber.com/protocol-manual#topic_commands).
* @param commandTemplate Template of a command to prepare. Parameters are denoted by question marks.
* @param parameters Variable number of command parameters.
* @return Command with converted parameters.
*/
public String prepareCommand(
String commandTemplate, Measurement... parameters) {
Main.PrepareCommandRequest.Builder builder = Main.PrepareCommandRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
builder = builder.setCommandTemplate(commandTemplate);
builder = builder.addAllParameters(Arrays.asList(parameters).stream()
.map(p -> Measurement.toProtobuf(p)).collect(Collectors.toList()));
Main.PrepareCommandResponse response = Call.callSync(
"device/prepare_command",
builder.build(),
Main.PrepareCommandResponse.parser());
return response.getCommand();
}
/**
* Returns a string that represents the device.
* @return A string that represents the device.
*/
public String toString() {
Main.ToStringRequest.Builder builder = Main.ToStringRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
Main.ToStringResponse response = Call.callSync(
"device/device_to_string",
builder.build(),
Main.ToStringResponse.parser());
return response.getToStr();
}
/**
* Gets a Stream class instance which allows you to control a particular stream on the device.
* @param streamId The ID of the stream to control. Stream IDs start at one.
* @return Stream instance.
*/
public Stream getStream(
int streamId) {
if (streamId <= 0) {
throw new IllegalArgumentException("Invalid value; streams are numbered from 1.");
}
return new Stream(this, streamId);
}
/**
* Gets a StreamBuffer class instance which is a handle for a stream buffer on the device.
* @param streamBufferId The ID of the stream buffer to control. Stream buffer IDs start at one.
* @return StreamBuffer instance.
*/
public StreamBuffer getStreamBuffer(
int streamBufferId) {
if (streamBufferId <= 0) {
throw new IllegalArgumentException("Invalid value; stream buffers are numbered from 1.");
}
return new StreamBuffer(this, streamBufferId);
}
/**
* Returns identity.
* @return Device identity.
*/
private DeviceIdentity retrieveIdentity() {
Main.DeviceGetIdentityRequest.Builder builder = Main.DeviceGetIdentityRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
Main.DeviceGetIdentityResponse response = Call.callSync(
"device/get_identity",
builder.build(),
Main.DeviceGetIdentityResponse.parser());
return DeviceIdentity.fromProtobuf(response.getIdentity());
}
/**
* Returns whether or not the device have been identified.
* @return True if the device has already been identified. False otherwise.
*/
private boolean retrieveIsIdentified() {
Main.DeviceGetIsIdentifiedRequest.Builder builder = Main.DeviceGetIsIdentifiedRequest.newBuilder();
builder = builder.setInterfaceId(getConnection().getInterfaceId());
builder = builder.setDevice(getDeviceAddress());
Main.DeviceGetIsIdentifiedResponse response = Call.callSync(
"device/get_is_identified",
builder.build(),
Main.DeviceGetIsIdentifiedResponse.parser());
return response.getIsIdentified();
}
}