binary module

BinaryCommand

class zaber.serial.BinaryCommand(device_number, command_number, data=0, message_id=None)

Bases: object

Models a single command in Zaber’s Binary protocol.

device_number

An integer representing the number (a.k.a. address) of the device to which to send the command. A device number of 0 indicates the command should be executed by all devices. 0-255.

command_number

An integer representing the command to be sent to the device. Command numbers are listed in Zaber’s Binary Protocol Manual. 0-255.

data

The data value to be transmitted with the command.

message_id

The message ID of the command. 0-255, or None if not present.

Parameters

• device_number – An integer specifying the number of the target device to which to send this command. 0-255.

• command_number – An integer specifying the command to be sent. 0-255.

• data – An optional integer containing the data value to be sent with the command. When omitted, data will be set to 0.

• message_id – An optional integer specifying a message ID to give to the message. 0-255, or None if no message ID is to be used.

Raises

ValueError – An invalid value was passed.

encode()

Encodes a 6-byte byte string to be transmitted to a device.

Returns

A byte string of length 6, formatted according to Zaber’s Binary Protocol Manual.

BinaryDevice

class zaber.serial.BinaryDevice(port, number)

Bases: object

A class to represent a Zaber device in the Binary protocol. It is safe to use in multi-threaded environments.

port

A BinarySerial object which represents the port to which this device is connected.

number

The integer number of this device. 1-255.

Parameters

• port – A BinarySerial object to use as a parent port.

• number – An integer between 1 and 255 which is the number of this device.

Raises

ValueError – The device number was invalid.

get_position()

Sends the “Return Current Position” command (60), and returns the result.

Returns

An integer representing the device’s current position, it its native units of measure - see the device manual for unit conversions.

get_status()

Sends the “Return Status” command (54), and returns the result.

Returns

An integer representing a status code, according to Zaber’s Binary Protocol Manual.

home()

Sends the “home” command (1), then waits for the device to reply.

Returns: A BinaryReply containing the reply received.

move_abs(position)

Sends the “move absolute” command (20), then waits for the device to reply.

Parameters

position – The position in microsteps to which to move.

Returns: A BinaryReply containing the reply received.

move_rel(distance)

Sends the “move relative” command (21), then waits for the device to reply.

Parameters

distance – The distance in microsteps to which to move.

Returns: A BinaryReply containing the reply received.

move_vel(speed)

Sends the “move at constant speed” command (22), then waits for the device to reply.

Parameters

speed – An integer representing the speed at which to move.

Notes

Unlike the other “move” commands, the device replies immediately to this command. This means that when this function returns, it is likely that the device is still moving.

Returns: A BinaryReply containing the reply received.

send(*args)

Sends a command to this device, then waits for a response.

Parameters

*args – Either a single BinaryCommand, or 1-3 integers specifying, in order, the command number, data value, and message ID of the command to be sent.

Notes

The ability to pass integers to this function is provided as a convenience to the programmer. Calling device.send(2) is equivalent to calling device.send(BinaryCommand(device.number, 2)).

Note that in the Binary protocol, devices will only reply once they have completed a command. Since this function waits for a reply from the device, this function may block for a long time while it waits for a response. For the same reason, it is important to set the timeout of this device’s parent port to a value sufficiently high that any command sent will be completed within the timeout.

Regardless of the device address specified to this function, the device number of the transmitted command will be overwritten with the number of this device.

If the command has a message ID set, this function will return a reply with a message ID, after checking whether the message IDs match.

Raises

UnexpectedReplyError – The reply read was not sent by this device or the message ID of the reply (if in use) did not match the message ID of the command.

Returns: A BinaryReply containing the reply received.

stop()

Sends the “stop” command (23), then waits for the device to reply.

Returns: A BinaryReply containing the reply received.

BinaryReply

class zaber.serial.BinaryReply(reply, message_id=False)

Bases: object

Models a single reply in Zaber’s Binary protocol.

device_number

The number of the device from which this reply was sent.

command_number

The number of the command which triggered this reply.

data

The data value associated with the reply.

message_id

The message ID number, if present, otherwise None.

Parameters

• reply – A byte string of length 6 containing a binary reply encoded according to Zaber’s Binary Protocol Manual.

• message_id – True if a message ID should be extracted from the reply, False if not.

Notes

Because a Binary reply’s message ID truncates the last byte of the data value of the reply, it is impossible to tell whether a reply contains a message ID or not. Therefore, the user must specify whether or not a message ID should be assumed to be present.

Raises

TypeError – An invalid type was passed as reply. This may indicate that a unicode string was passed instead of a binary (ascii) string.

encode()

Returns the reply as a binary string, in the form in which it would appear if it had been read from the serial port.

Returns

A byte string of length 6 formatted according to the Binary Protocol Manual.

BinarySerial

class zaber.serial.BinarySerial(port, baud=9600, timeout=5, inter_char_timeout=0.5)

Bases: object

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

This class defines a few simple methods for writing to and reading from a device connected over the serial port. 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 and release it once all methods have returned.

Creates a new instance of the BinarySerial class.

Parameters

• port – A string containing the name 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

This class will open the port immediately upon instantiation. This follows the pattern set by PySerial, which this class uses internally to perform serial communication.

Raises

TypeError – The port argument passed was not a string.

property baudrate

The baud rate at which to read and write.

The default baud rate for the Binary protocol is 9600. T-Series devices are only capable of communication at 9600 baud. A-Series devices can communicate at 115200, 57600, 38400, 19200, and 9600 baud.

Note that this changes the baud rate of the computer on which this code is running. It does not change the baud rate of connected devices.

can_read()

Checks if enough data has been received to read a response, without blocking.

If the return value is True, it means at least six bytes are available to read from the serial port, so calling read() will not block.

Returns

True if a response 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(message_id=False)

Reads six bytes from the port and returns a BinaryReply.

Parameters

message_id – True if the response is expected to have a message ID. Defaults to False.

Returns

A BinaryCommand containing all of the information read from the serial port.

Raises

zaber.serial.TimeoutError – No data was read before the specified timeout elapsed.

property timeout

The number of seconds to wait for input while reading.

The timeout property accepts floating point numbers for fractional wait times.

write(*args)

Writes a command to the port.

This function accepts either a BinaryCommand object, a set of integer arguments, a list of integers, or a string. If passed integer arguments or a list of integers, those integers must be in the same order as would be passed to the BinaryCommand constructor (ie. device number, then command number, then data, and then an optional message ID).

Parameters

*args – A BinaryCommand to be sent, or between 2 and 4 integer arguments, or a list containing between 2 and 4 integers, or a string representing a properly-formatted Binary command.

Notes

Passing integers or a list of integers is equivalent to passing a BinaryCommand with those integers as constructor arguments.

For example, all of the following are equivalent:

>>> write(BinaryCommand(1, 55, 1000))
>>> write(1, 55, 1000)
>>> write([1, 55, 1000])
>>> write(struct.pack("<2Bl", 1, 55, 1000))
>>> write('\x01\x37\xe8\x03\x00\x00')

Raises

• TypeError – The arguments passed to write() did not conform to the specification of *args above.

• ValueError – A string of length other than 6 was passed.