ascii module

AsciiAxis

class zaber.serial.AsciiAxis(device, number)

Bases: object

Represents one axis of an ASCII device.

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_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 axis until it is idle.

Raises:UnexpectedReplyError – The reply received was not sent by the expected device and axis.
Returns: An AsciiReply object containing the first reply
received.
move_abs(position, blocking=True)

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

Parameters:
  • position – An integer representing the position in microsteps to which to move the axis.
  • 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 and axis.
Returns: An AsciiReply object containing the first reply
received.
move_rel(distance, blocking=True)

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

Parameters:
  • distance – An integer representing the number of microsteps by which to move the axis.
  • 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 and axis.
Returns: An AsciiReply object containing the first reply
received.
move_vel(speed, blocking=False)

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

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

Notes

Unlike the other two move commands, move_vel() does not by default poll the axis 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 and axis.
Returns: An AsciiReply object 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 axis.

Notes

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

Raises:UnexpectedReplyError – The reply received was not sent by the expected device and axis.
Returns: An AsciiReply object 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.
__str__()
Returns an encoded ASCII command, without the newline

terminator.

Returns:
A string containing an otherwise-valid ASCII command, without the newline (ie. “
”) at the end of the string
for ease of printing.
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: object

Represents an ASCII device.

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_status()

Queries the device for its status and returns the result.

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 until it is idle.

Returns:An AsciiReply containing the first reply received.
move_abs(position, blocking=True)

Sends the “move abs” command to the device 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 funciton 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.
Returns:

An AsciiReply containing the first reply received.
move_rel(distance, blocking=True)

Sends the “move rel” command to the device 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.
Returns:

An AsciiReply containing the first reply received.
move_vel(speed, blocking=False)

Sends the “move vel” command to make the device 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.
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.

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.
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 characteres 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:ValueError – The string could not be parsed.
__str__()

Returns a reply string resembling the string which would have created this AsciiReply.

Returns:The same string as is returned by encode().
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.01)

Bases: object

A class for interacting with Zaber devices using the ASCII protocol.

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.

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.
baudrate
close()

Closes the serial port.

flush()

Flushes the buffers of the underlying serial port.

open()

Opens the serial port.

read()

Reads a reply from the serial port.

Raises:
Returns:

An AsciiReply containing the reply received.
timeout
write(command)

Writes a command to the serial port.

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