Provides a set of functions for interacting with Zaber devices in the ASCII protocol. More...

#include "z_common.h"

Include dependency graph for za_serial.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	za_reply

Functions
int	za_connect (z_port port, const char port_name)

int	za_disconnect (z_port port)

int	za_send (z_port port, const char *command)

int	za_receive (z_port port, char *destination, int length)

int	za_decode (struct za_reply destination, const char reply)

int	za_setbaud (z_port port, int baud)

int	za_drain (z_port port)

void	za_set_verbose (int value)

Detailed Description

Provides a set of functions for interacting with Zaber devices in the ASCII protocol.

Author: Eric Dand

Version: 1.0

Date: 28 November 2014

Copyright: Apache Software License Version 2.0

Definition in file za_serial.h.

Class Documentation

◆ za_reply

struct za_reply

Provides programmatic access to reply data.

This struct is provided as a convenience to allow for easier interaction with ASCII replies. The names of the fields are taken straight from the ASCII protocol manual.

Note that the response data may contain more than one piece of data: because many replies will return multiple pieces of data, the response_data field will simply contain the end of the message, without the newline terminators. (ie. "\r\n")

Definition at line 32 of file za_serial.h.

Collaboration diagram for za_reply:

Class Members
int	axis_number	The axis number: 0-9, where 0 refers to the whole device, and 1-9 refer only to that specific axis.
int	device_address	The address of the device, an integer between 1 and 99.
char	device_status[5]	Either "BUSY" when the axis is moving, or "IDLE" when it isn't.
char	message_type	The message type will always be '@' for replies. Info will have the type '#', and alerts '!'.
char	reply_flags[3]	Whether a command was accepted or rejected: either "OK" or "RJ".
char	response_data[128]	The response for the command executed. See the protocol manual entry for your command of choice to know what to expect here.
char	warning_flags[3]	The highest priority warning for the device, or – under normal conditions.

Function Documentation

◆ za_connect()

int za_connect	(	z_port *	port,
		const char *	port_name
	)

Connect to a serial port specified by port_name.

Configures the port to the ASCII protocol defaults (115200 baud, 8N1). If you have set your device to run at a different baud rate, use za_setbaud() to change it after connecting using this function.

On Linux the port name will likely be something like "/dev/ttyUSB0", on Windows "COM1", and on OS X and BSD systems "/dev/cu.usbserial-A4017CQX". It is important that OS X/BSD systems use the "callout" (cu.* or cua.*) port as opposed to the "dial in" ports with names starting with tty.*, which will not work with Zaber devices.

If you are re-using a z_port, make sure to use za_disconnect() to disconnect the old port before overwriting it with a new one.

Parameters

[out]	port	a pointer to a `z_port` to be written-over with the newly-connected port.
[in]	port_name	a string containing the name of the port to be opened.

Returns: Z_SUCCESS on success, Z_ERROR_NULL_PARAMETER if port or port_name is NULL, or Z_ERROR_SYSTEM_ERROR in case of system error.

Definition at line 53 of file za_serial.c.

◆ za_decode()

int za_decode	(	struct za_reply *	destination,
		const char *	reply
	)

Build a za_reply struct from a string pointed-to by reply.

The za_reply struct can then be used to gain easier access to the parts of an ASCII reply.

Parameters

[out]	destination	a pointer to a za_reply struct to be populated with the data found in reply.
[in]	reply	a pointer to a string containing a full reply from a Zaber device, as specified by the ASCII protocol manual.

Returns: Z_SUCCESS on success, Z_ERROR_NULL_PARAMETER if destination or reply is NULL, or Z_ERROR_COULD_NOT_DECODE if the reply is malformed.

Definition at line 527 of file za_serial.c.

Referenced by MagAOX::app::zaberStage< parentT >::getResponse(), poll_until_idle(), and MagAOX::app::zaberStage< parentT >::sendCommand().

◆ za_disconnect()

int za_disconnect ( z_port port )

Gracefully closes a connection.

Parameters

[in] port the port to be disconnected.

Returns: Z_SUCCESS on success, Z_ERROR_SYSTEM_ERROR in case of system error.

Definition at line 99 of file za_serial.c.

◆ za_drain()

int za_drain ( z_port port )

Flushes all input received but not yet read, and attempts to drain all input that would be incoming.

This function is intended to be used when many commands have been sent without reading any responses, and there is a need to read a response from a certain command. In other words, call this function before sending a command whose response you would like to read if you have not been consistently reading the responses to previous commands.

This function will always take at least 100ms to complete, as it tries to read input until it is certain no more is arriving by waiting 100ms before deciding there is no more input incoming. Do not use it for time-sensitive operations, or in any kind of "chatty" setup, eg. multiple devices daisy-chained together with move tracking enabled. In such a setup, the only reliable way to retrieve reply data is to always follow calls to za_send() with calls to za_receive().

Parameters

[in] port the port to drain.

Returns: Z_SUCCESS on success, or Z_ERROR_SYSTEM_ERROR in case of system error.

Definition at line 232 of file za_serial.c.

◆ za_receive()

int za_receive	(	z_port	port,
		char *	destination,
		int	length
	)

Reads a message from the serial port.

Blocks while reading until it encounters a newline character or its timeout has elapsed.

Note: It is recommended that your destination buffer be 256B long. This is long enough to hold any reply from a Zaber device using the ASCII protocol.

Note that this function will simply read the first message on the input buffer, whatever it may be. If you have sent many commands without receiving their corresponding replies, sorting them all out may be a real headache. Note also that the input buffer is finite, and allowing it to fill up will result in undefined behaviour. Try to receive responses to every command you send, or use za_drain() when necessary.

Passing NULL for destination and 0 for length will read a single reply, discarding it as it is read. This is useful for keeping your commands and replies straight without using zb_drain() when you don't care about the contents of most of the replies.

Parameters

[in]	port	the port to receive a message from.
[out]	destination	a pointer to which to write the reply read.
[in]	length	the length of the buffer pointed to by destination.

Returns: the number of bytes read, Z_ERROR_SYSTEM_ERROR in case of system error, or Z_ERROR_BUFFER_TOO_SMALL if length is insufficient to store the reply.

Definition at line 148 of file za_serial.c.

◆ za_send()

int za_send	(	z_port	port,
		const char *	command
	)

Sends a command to a serial port.

Automatically adds a '/' to begin the command and a '\n' to end it if these characters are omitted from command.

Parameters

[in]	port	the port to which to send the command.
[in]	command	a string containing the command to be sent.

Returns: the number of bytes written, Z_ERROR_NULL_PARAMETER if command is NULL, or Z_ERROR_SYSTEM_ERROR in case of system error.

Definition at line 112 of file za_serial.c.

◆ za_set_verbose()

void za_set_verbose ( int value )

Sets whether errors and extra info are reported to stderr.

Set value to 0 to disable all output. Additionally, you can compile this library with the macro NDEBUG defined, which will disable all output and skip checks to "verbose" altogether in the compiled code.

Parameters

[in] value whether or not the program should output error messages and info to stderr.

Definition at line 18 of file za_serial.c.

◆ za_setbaud()

int za_setbaud	(	z_port	port,
		int	baud
	)

Changes the baud rate of both input and output.

This function is unlikely to be necessary for typical use, as za_connect() already sets the baud rate to 115200, the recommended rate for the ASCII protocol.

Note: za_setbaud() flushes both input and output buffers to ensure a "clean slate" after the baud rate has been changed.

Also note that this sets the baud rate at which the program tries to talk to the device. It does not change the baud rate of the device itself. See the ASCII Protocol Manual for info on how to change the device's baud rate.

Valid baid rates are 9600, 19200, 38400, 57600, and 115200.

Parameters

[in]	port	the port to change.
[in]	baud	the new desired baud rate.

Returns: Z_SUCCESS on success, Z_ERROR_INVALID_BAUDRATE if the baud rate is not one specified above, or Z_ERROR_SYSTEM_ERROR in case of system error.

Definition at line 197 of file za_serial.c.

Classes

Functions

Detailed Description

Class Documentation

◆ za_reply

Function Documentation

◆ za_connect()

◆ za_decode()

◆ za_disconnect()

◆ za_drain()

◆ za_receive()

◆ za_send()

◆ za_set_verbose()

◆ za_setbaud()