Core Serial Library in C#  1.2
The Zaber Core Serial Library in C#

Table of Contents

The Zaber Core Serial Library is intended to provide a simple set of commands for interacting with Zaber devices over a serial port. It is recommended that before using this library, you first read the protocol manual corresponding to the protocol of your device.

The ASCII Protocol Manual is a complete reference for communicating with Zaber devices in ASCII. Note that many A-Series devices default to the binary protocol, and may need to be switched to ASCII before use. Appendix C of the ASCII Protocol Manual is a short guide to doing this switch.

The Binary Protocol Manual is a complete reference for communicating with Zaber devices in binary. Note that devices using the binary protocol will only reply once a command has completed, so more work must be done to properly receive responses. See the "Move Absolute" command reference for more info on this.

Getting Started

This library, at its core, is made up of four interfaces and abstract classes: IZaberPort, IZaberAxis, Command, and Reply.

Classes implementing IZaberPort will look suspiciously like the built-in System.IO.Ports.SerialPort class. This is intentional: the IZaberPort interface is intended as a simplifying layer built on top of the SerialPort class. Though IZaberPort does not define Read and Write methods, both of its implementing classes do. These classes are ZaberAsciiPort, and ZaberBinaryPort. Choose the one which matches your devices' communication protocol. Note that the default read time-out is infinite, just like that of SerialPort. This can be changed using the IZaberPort.ReadTimeout property.

The IZaberAxis interface adds an extra layer of convenient abstraction on top of IZaberPort, meant to make communicating with Zaber devices easier by modelling individual device axes. IZaberAxis does impose some limitations on the programmer, the most fundamental of which being that it only provides blocking methods which return when the axis has completed its movement. If you want to move multiple devices at once, classes implementing IZaberAxis will be of limited use. There are two classes which implement IZaberAxis, ZaberAsciiAxis, and ZaberBinaryDevice. A third class, ZaberAsciiDevice, exists to connect ZaberAsciiAxis objects to their parent ZaberAsciiPort objects.

Subclasses of Command and Reply are also divided by protocol. They model individual commands and replies to be sent to and received from devices or axes. They are used extensively in the library internally, and they provide methods for encoding commands for serial transmission and for decoding received replies to provide programmatic access to their data.

Examples

See the "Examples" page for examples of how to use this library.

Known Issues

The built-in SerialPort class has an issue where if a SerialPort object is used to open a COM port, then closed, and then opened again too soon, it will still be unavailable. This will throw an exception. Microsoft's documentation mentions this in the "Remarks" section of SerialPort.Open() and SerialPort.Close():

Only one open connection can exist per SerialPort object. The best practice for any application is to wait for some amount of time after calling the Close method before attempting to call the Open method, as the port may not be closed instantly.

This problem persists even if the SerialPort's Dispose() method is called, though this does help the problem to some degree. The problem gets noticeably worse when trying to access one COM port from multiple SerialPort objects in quick succession. Since this library uses SerialPort as a base for serial communications, it suffers from the same problem.

Unsupported Features

Some features of the Zaber firmware are incompatible with this library. The library is designed to work with devices set to the default settings, so do not worry if you have not changed any settings on your device. Message IDs and checksums are not supported by the library in either protocol.

ZaberBinaryDevice will only work when the binary device does not have Auto-Reply disabled. This is the default setting. In addition, ZaberBinaryDevice does some reply validation and will ignore automatic responses related to move tracking, but we also recommend that both the Move Tracking and Manual Move Tracking settings be disabled to ensure more predictable behaviour when using the ZaberBinaryDevice class.