ascii module¶

AsciiAxis¶

class zaber.serial.AsciiAxis(device, number)¶

Bases: zaber.serial.asciimovementmixin.AsciiMovementMixin

Represents one axis of an ASCII device. It is safe to use in multi- threaded environments.

parent¶: An AsciiDevice which represents the device which has this axis.

number¶: The number of this axis. 1-9.

Parameters

device – An AsciiDevice which is the parent of this axis.
number – The number of this axis. Must be 1-9.

Raises

ValueError – The axis number was not between 1 and 9.

get_position()¶

Queries the axis for its position and returns the result.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device and axis.
Returns: A number representing the current device position in its native units of measure. See the device manual for unit conversions.

get_status()¶

Queries the axis for its status and returns the result.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device and axis.
Returns: A string containing either “BUSY” or “IDLE”, depending on the response received from the axis.

home()¶

Sends the “home” command, then polls the device or axis until it is idle.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

move_abs(position, blocking=True)¶

Sends the “move abs” command to the device or axis to move it to the specified position, then polls the device until it is idle.

Parameters

position – An integer representing the position in microsteps to which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_rel(distance, blocking=True)¶

Sends the “move rel” command to the device or axis to move it by the specified distance, then polls the device until it is idle.

Parameters

distance – An integer representing the number of microsteps by which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device, and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_vel(speed, blocking=False)¶

Sends the “move vel” command to make the device or axis move at the specified speed.

Parameters

speed – An integer representing the speed at which to move the device.
blocking – An optional boolean, False by default. If set to True, this function will poll the device repeatedly until it reports that it is idle.

Notes

Unlike the other two move commands, move_vel() does not by default poll the device until it is idle. move_vel() will return immediately after receiving a response from the device unless the “blocking” argument is set to True.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

poll_until_idle()¶

Polls the axis and blocks until the device reports that the axis is idle.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device and axis.

Returns: An AsciiReply object containing the last reply: received.

send(message)¶

Sends a message to the axis and then waits for a reply.

Parameters: message – A string or AsciiCommand object containing a command to be sent to this axis.

Notes

Regardless of the device address or axis number supplied in (or omitted from) the message passed to this function, this function will always send the command to only this axis.

Though this is intended to make sending commands to a particular axis easier by allowing the user to pass in a “global command” (ie. one whose target device and axis are both 0), this can result in some unexpected behaviour. For example, if the user tries to call send() with an AsciiCommand which has a different target axis number than the number of this axis, they may be surprised to find that the command was sent to this axis rather than the one originally specified in the AsciiCommand.

Examples

Since send() will automatically set (or overwrite) the target axis and device address of the message, all of the following calls to send() will result in identical ASCII messages being sent to the serial port:

>>> axis.send("home")
>>> axis.send(AsciiCommand("home"))
>>> axis.send("0 0 home")
>>> axis.send("4 8 home")
>>> axis.send(AsciiCommand(1, 4, "home"))

Raises: UnexpectedReplyError – The reply received was not sent by the expected device and axis.

Returns: An AsciiReply object containing the reply received.

stop()¶

Sends the “stop” command to the device or axis.

Notes

The stop command can be used to pre-empt any movement command in order to stop the device early.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

AsciiCommand¶

class zaber.serial.AsciiCommand(*args)¶

Bases: object

Models a single command in Zaber’s ASCII protocol.

device_address¶: An integer representing the address of the device to which to send this command.

axis_number¶: The integer number of the particular axis which should execute this command. An axis number of 0 specifies that all axes should execute the command, or that the command is “device scope”.

message_id¶: Optional. An integer to be used as a message ID. If a command has a message ID, then the device will send a reply with a matching message ID. A message_id value of None indicates that a message ID is not to be used. 0 is a valid message ID.

data¶: The bulk of the command. data includes a valid ASCII command and any parameters of that command, separated by spaces. A data value of “” (the empty string) is valid, and is often used as a “get status” command to query whether a device is busy or idle.

Parameters: *args – A number of arguments beginning with 0 to 3 integers followed by one or more strings.

Notes

For every absent integer argument to __init__, any string argument(s) will be examined for leading integers. The first integer found (as an argument or as the leading part of a string) will set the device_address property, the second integer will be taken as the axis_number property, and the third integer found will be the message_id property.

When a string argument contains text which can not be interpreted as an integer, all arguments which follow it are considered to be a part of the data. This is consistent with how ASCII commands are parsed by the Zaber device firmware.

All leading ‘/’ and trailing ‘\r\n’ characters in string arguments are stripped when the arguments are parsed.

Examples

The flexible argument structure of this constructor allows commands to be constructed by passing in integers followed by a command and its parameters, or by passing in one fully-formed, valid ASCII command string, or a mix of the two if the user desires.

For example, all of the following constructors will create identical AsciiCommand objects:

>>> AsciiCommand("/1 0 move abs 10000\r\n")
>>> AsciiCommand("1 move abs 10000")
>>> AsciiCommand(1, 0, "move abs 10000")
>>> AsciiCommand(1, "move abs 10000")
>>> AsciiCommand("1", "move abs", "10000")
>>> AsciiCommand(1, "move abs", 10000)

Raises: TypeError – An argument was passed to the constructor which was neither an integer nor a string.

encode()¶

Return a valid ASCII command based on this object’s attributes.

The string returned by this function is a fully valid command, formatted according to Zaber’s Ascii Protocol Manual.

Returns: A valid, fully-formed ASCII command.

AsciiDevice¶

class zaber.serial.AsciiDevice(port, address)¶

Bases: zaber.serial.asciimovementmixin.AsciiMovementMixin

Represents an ASCII device. It is safe to use in multi-threaded environments.

port¶: The port to which this device is connected.

address¶: The address of this device. 1-99.

Parameters

port – An AsciiSerial object representing the port to which this device is connected.
address – An integer representing the address of this device. It must be between 1-99.

Raises

ValueError – The address was not between 1 and 99.

axis(number)¶

Returns an AsciiAxis with this device as a parent and the number specified.

Parameters: number – The number of the axis. 1-9.

Notes

This function will always return a new AsciiAxis instance. If you are working extensively with axes, you may want to create just one set of AsciiAxis objects by directly using the AsciiAxis constructor instead of this function to avoid creating lots and lots of objects.

Returns: A new AsciiAxis instance to represent the axis specified.

get_position()¶

Queries the axis for its position and returns the result.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device and axis.
Returns: A number representing the current device position in its native units of measure. See the device manual for unit conversions. If this command is used on a multi-axis device, the return value is the position of the first axis.

get_status(axis_number=0)¶

Queries the device for its status and returns the result.

Parameters: axis_number – An optional integer specifying a particular axis whose status to query. axis_number must be between 0 and 9. If provided, the device will only report the busy status of the axis specified. When omitted, the device will report itself as busy if any axis is moving.
Raises: UnexpectedReplyError – The reply received was not sent by the expected device.
Returns: A string containing either “BUSY” or “IDLE”, depending on the response received from the device.

home()¶

Sends the “home” command, then polls the device or axis until it is idle.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

lockstep(lockstep_group=1)¶

Returns an AsciiLockstep using this device for lockstep (synchronized movement of axes).

Parameters: lockstep_group – The number of the lockstep group between 1-9. Defaults to first lockstep group of the device.

Notes

This function will always return a new AsciiLockstep instance. If you are working extensively with locksteps, you may want to preserve returned instance instead of calling the function repeatedly.

Returns: A new AsciiLockstep instance to represent the lockstep group specified.

move_abs(position, blocking=True)¶

Sends the “move abs” command to the device or axis to move it to the specified position, then polls the device until it is idle.

Parameters

position – An integer representing the position in microsteps to which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_rel(distance, blocking=True)¶

Sends the “move rel” command to the device or axis to move it by the specified distance, then polls the device until it is idle.

Parameters

distance – An integer representing the number of microsteps by which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device, and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_vel(speed, blocking=False)¶

Sends the “move vel” command to make the device or axis move at the specified speed.

Parameters

speed – An integer representing the speed at which to move the device.
blocking – An optional boolean, False by default. If set to True, this function will poll the device repeatedly until it reports that it is idle.

Notes

Unlike the other two move commands, move_vel() does not by default poll the device until it is idle. move_vel() will return immediately after receiving a response from the device unless the “blocking” argument is set to True.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

poll_until_idle(axis_number=0)¶

Polls the device’s status, blocking until it is idle.

Parameters: axis_number – An optional integer specifying a particular axis whose status to poll. axis_number must be between 0 and 9. If provided, the device will only report the busy status of the axis specified. When omitted, the device will report itself as busy if any axis is moving.
Raises: UnexpectedReplyError – The reply received was not sent by the expected device.
Returns: An AsciiReply containing the last reply received.

send(message)¶

Sends a message to the device, then waits for a reply.

Parameters: message – A string or AsciiCommand representing the message to be sent to the device.

Notes

Regardless of the device address specified in the message, this function will always send the message to this device. The axis number will be preserved.

This behaviour is intended to prevent the user from accidentally sending a message to all devices instead of just one. For example, if device1 is an AsciiDevice with an address of 1, device1.send(“home”) will send the ASCII string “/1 0 home\r\n”, instead of sending the command “globally” with “/0 0 home\r\n”.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device.
Returns: An AsciiReply containing the reply received.

stop()¶

Sends the “stop” command to the device or axis.

Notes

The stop command can be used to pre-empt any movement command in order to stop the device early.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

AsciiReply¶

class zaber.serial.AsciiReply(reply_string)¶

Bases: object

Models a single reply in Zaber’s ASCII protocol.

message_type¶: A string of length 1 containing either ‘@’, ‘!’, or ‘#’, depending on whether the message type was a “reply”, “alert”, or “info”, respectively. Most messages received from Zaber devices are of type “reply”, or ‘@’.

device_address¶: An integer between 1 and 99 representing the address of the device from which the reply was sent.

axis_number¶: An integer between 0 and 9 representing the axis from which the reply was sent. An axis number of 0 represents a reply received from the device as a whole.

message_id¶: An integer between 0 and 255 if present, or None otherwise.

reply_flag¶: A string of length two, containing either “OK” or “RJ”, depending on whether the command was accepted or rejected by the device. Value will be None for device replies that do not have a reply flag, such as info and alert messages.

device_status¶: A string of length 4, containing either “BUSY” or “IDLE”, depending on whether the device is moving or stationary.

warning_flag¶: A string of length 2, usually “–”. If it is not “–”, it will be one of the two-letter warning flags described in the Warning Flags section of the Ascii Protocol Manual.

data¶: A string containing the response data.

checksum¶: A string of length 2 containing two characters representing a hexadecimal checksum, or None if a checksum was not found in the reply.

Parameters

reply_string – A string in one of the formats described in Zaber’s Ascii Protocol Manual. It will be parsed by this constructor in order to populate the attributes of the new AsciiReply.

Raises

TypeError – The reply_string is not a string.
ValueError – The string could not be parsed.

encode()¶

Encodes the AsciiReply’s attributes back into a valid string resembling the string which would have created the AsciiReply.

Returns: A string in the format described in Zaber’s Ascii Protocol Manual.

AsciiSerial¶

class zaber.serial.AsciiSerial(port, baud=115200, timeout=5, inter_char_timeout=0.5)¶

Bases: object

A class for interacting with Zaber devices using the ASCII protocol. It is safe to use in multi-threaded environments.

baudrate¶: An integer representing the desired communication baud rate. Valid bauds are 115200, 57600, 38400, 19200, and 9600.

timeout¶: A number representing the number of seconds to wait for input before timing out. Floating-point numbers can be used to specify times shorter than one second. A value of None can also be used to specify an infinite timeout. A value of 0 specifies that all reads and writes should be non-blocking (return immediately without waiting). Defaults to 5.

lock¶: The threading.RLock guarding the port. Each method takes the lock and is therefore thread safe. However, to ensure no other threads access the port across multiple method calls, the caller should acquire the lock.

Parameters

port – A string containing the name or URL of the serial port to which to connect.
baud – An integer representing the baud rate at which to communicate over the serial port.
timeout – A number representing the number of seconds to wait for a reply. Fractional numbers are accepted and can be used to specify times shorter than a second.
inter_char_timeout – A number representing the number of seconds to wait between bytes in a reply. If your computer is bad at reading incoming serial data in a timely fashion, try increasing this value.

Notes

When port is not None, this constructor immediately opens the serial port. There is no need to call open() after creating this object, unless you passed None as port.

Raises: ValueError – An invalid baud rate was specified.

property baudrate¶

can_read()¶

Checks if any data has been received by the port, without blocking.

If the return value is True, it means some data is available but it does not guarantee there is enough to read a complete reply; it’s still possible for the next read call to block waiting for data, and it’s still possible to time out if transmission was interrupted.

Returns: True if data is available to read; False otherwise.

close()¶: Closes the serial port.

flush()¶: Flushes the buffers of the underlying serial port.

property lock¶

open()¶: Opens the serial port.

read()¶

Reads a reply from the serial port.

Raises

zaber.serial.TimeoutError – The duration specified by timeout elapsed before a full reply could be read.
ValueError – The reply read could not be parsed and is invalid.

Returns

An AsciiReply containing the reply received.

property timeout¶

write(command)¶

Writes a command to the serial port.

Parameters: command – A string or AsciiCommand representing a command to be sent.

AsciiLockstep¶

class zaber.serial.AsciiLockstep(device, lockstep_group=1)¶

Bases: zaber.serial.asciimovementmixin.AsciiMovementMixin

Represents an lockstep group of particular device (AsciiDevice). Allows to setup and control lockstep (synchronized movement of axes).

device¶: The AsciiDevice of this lockstep group.

lockstep_group¶: The lockstep group number of the device.

Constructs object allowing to setup lockstep (synchronized movement of axes). Controls movement of the lockstep. Requires instance of AsciiDevice on which lockstep is performed.

Parameters

device – An AsciiDevice instance on which lockstep is performed.
lockstep_group – An integer representing the lockstep group of this device. It must be greater or equal to 1. Different devices may support different number of lockstep groups. Defaults to lockstep group 1.

Raises

ValueError – The lockstep_group was not greater or equal to 1.

disable()¶

Disables this lockstep group. Allows participating axes to move independently again.

Returns: An AsciiReply containing the reply received.

enable(axis1=1, axis2=2)¶

Enables this lockstep group and sets up axes participating in lockstep group. After calling this function axes will move together maintaining offset from time of this call.

Future movement must be performed using this lockstep group (this instance). Movement commands sent directly to axis or device won’t be performed.

Parameters

axis1 – An integer between 1 and 9 representing the first device axis which participates in lockstep group. Defaults to first axis of the device.
axis2 – An integer between 1 and 9 representing the second device axis which participates in lockstep group. Defaults to second axis of the device.

Returns

An AsciiReply containing the reply received.

get_status()¶

Queries the lockstep for its status and returns the result.

Returns: A string containing either “BUSY” or “IDLE”, depending on the response received from the device.

home()¶

Sends the “home” command, then polls the device or axis until it is idle.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

info()¶

Queries lockstep group’s state returning AsciiLockstepInfo. Observe AsciiLockstepInfo.is_enabled to determine whether lockstep is enabled for this lockstep group. Observe AsciiLockstepInfo.twist to find out whether axis are in perfect sync.

Returns: An AsciiLockstepInfo containing the state of this lockstep group.

move_abs(position, blocking=True)¶

Sends the “move abs” command to the device or axis to move it to the specified position, then polls the device until it is idle.

Parameters

position – An integer representing the position in microsteps to which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_rel(distance, blocking=True)¶

Sends the “move rel” command to the device or axis to move it by the specified distance, then polls the device until it is idle.

Parameters

distance – An integer representing the number of microsteps by which to move the device.
blocking – An optional boolean, True by default. If set to False, this function will return immediately after receiving a reply from the device, and it will not poll the device further.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device or axis.

Returns

An AsciiReply containing the first reply received.

move_vel(speed, blocking=False)¶

Sends the “move vel” command to make the device or axis move at the specified speed.

Parameters

speed – An integer representing the speed at which to move the device.
blocking – An optional boolean, False by default. If set to True, this function will poll the device repeatedly until it reports that it is idle.

Notes

Unlike the other two move commands, move_vel() does not by default poll the device until it is idle. move_vel() will return immediately after receiving a response from the device unless the “blocking” argument is set to True.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

poll_until_idle()¶

Polls the lockstep group’s status, blocking until it is idle.

Returns: An AsciiReply containing the last reply received.

send(message)¶

Sends a raw message to this lockstep group, then waits for a reply. It is preferred to use functions as e.g. “enable” or “move_abs” to perform commands rather than sending raw messages using this function.

Parameters

message – A string representing the message to be sent to the lockstep group.

Raises

UnexpectedReplyError – The reply received was not sent by the expected device.
TypeError – The message is not a string.

Returns

An AsciiReply containing the reply received.

stop()¶

Sends the “stop” command to the device or axis.

Notes

The stop command can be used to pre-empt any movement command in order to stop the device early.

Raises: UnexpectedReplyError – The reply received was not sent by the expected device or axis.
Returns: An AsciiReply containing the first reply received.

AsciiLockstepInfo¶

class zaber.serial.AsciiLockstepInfo(message_data)¶

Bases: object

Models lockstep info message reply in Zaber’s ASCII protocol.

is_enabled¶: A boolean determining whether lockstep is enabled for this lockstep group.

axis1¶: An integer between 1 and 9 representing the first axis for which the lockstep is enabled.

axis2¶: An integer between 1 and 9 representing the second axis for which the lockstep is enabled.

offset¶: An integer representing the offset between axis1 and axis2 for which the lockstep was enabled. This offset will be maintained during movement of the lockstep group. Offset is determined from position of both axes at time when lockstep is enabled.

twist¶: An integer representing the current twist between axis1 and axis2 considering the offset. Value 0 represents perfect sync between both axes in the lockstep group.

Parameters

message_data – A string from AsciiReply’s attribute data. It will be parsed by this constructor in order to populate the attributes of the new AsciiLockstepInfo.

Raises

TypeError – The message_data is not a string.
ValueError – The message_data string could not be parsed.

Navigation

Related Topics

ascii module¶

AsciiAxis¶

AsciiCommand¶

AsciiDevice¶

AsciiReply¶

AsciiSerial¶

AsciiLockstep¶

AsciiLockstepInfo¶