Communications/Control

Functions
int	pdv_serial_set_baud (PdvDev pdv_p, int baud)
	Sets the baud rate on the serial lines; applies only to cameras with serial control. Valid values are 9600, 19200, 38500, 57500, and 115200. More...
int	pdv_serial_get_baud (PdvDev pdv_p)
	Get the baud rate, typically initialized by the serial_baud directive in the config file. More...
int	pdv_serial_command (PdvDev pdv_p, const char *cmd)
	Sends an ASCII serial command to the camera, with ASCII camera command formatting. Applies only to cameras that use a serial control method for camera-computer communications. More...
int	pdv_serial_binary_command (PdvDev pdv_p, const uint8_t *cmd, int len)
	Sends a binary serial command to the camera. Applies only to cameras that use a serial control method for for camera-computer communications. More...
int	pdv_serial_write_available (PdvDev pdv_p)
	Get the number of bytes available in the driver's serial write buffer. More...
int	pdv_serial_write (PdvDev pdv_p, const char *buf, int size)
	Performs a serial write over the serial lines. Not recommended for use in new code, consider using pdv_serial_command() or pdv_serial_binary_command() instead. More...
int	pdv_serial_read (PdvDev pdv_p, char *buf, int size)
	Performs a serial read over the serial control lines. More...
int	pdv_serial_read_blocking (PdvDev pdv_p, char *buf, int size)
	Performs a serial read over the serial control lines, blocks until all requested data is read. More...
int	pdv_serial_read_nullterm (PdvDev pdv_p, char *buf, int size, int nullterm)
	Performs a serial read over the serial control lines. The buffer passed in will be NULL-terminated if nullterm is true. More...
void	pdv_serial_set_delimiters (PdvDev pdv_p, const char *newprefix, const char *newterm)
	Set the prefix and terminator for serial commands. More...
const char *	pdv_serial_prefix (PdvDev pdv_p)
	Get the serial prefix. More...
const char *	pdv_serial_term (PdvDev pdv_p)
	Get the serial terminator. More...
void	pdv_serial_send_break (PdvDev pdv_p)
	Send a break condition on the serial connection. More...
void	pdv_serial_reset (PdvDev pdv_p)
	Resets the serial interface. Clears any outstanding reads and writes and puts the serial interface in a known idle state. More...
int	pdv_serial_read_basler (PdvDev pdv_p, uint8_t *cmd, int len)
	Reads a Basler binary frame command. Checks the framing and BCC. More...
int	pdv_serial_write_basler (PdvDev pdv_p, uint8_t *cmd, int len)
	Send a Basler formatted serial frame. Adds the framing and BCC. More...
int	pdv_serial_read_duncan (PdvDev pdv_p, uint8_t *frame)
	Read a binary serial response from a Duncantech MS and DT series camera – checks for STX and size, then waits for size+1 more bytes. More...
int	pdv_serial_write_duncan (PdvDev pdv_p, uint8_t *cmdbuf, int size)
	Send a Duncantech MS / DT series camera frame – adds the framing and checksum, then sends the command. More...
int	pdv_serial_wait (PdvDev pdv_p, int msecs, int count)
	Waits for a response from the camera as a result of a pdv_serial_write() or pdv_serial_command(). More...
int	pdv_serial_wait_next (PdvDev pdv_p, int msecs, int count)
	Wait for new serial data to come in. Ignore any previously received data. More...
int	pdv_serial_set_waitchar (PdvDev pdv_p, int enable, unsigned char wchar)
	Set the serial wait character. More...
int	pdv_serial_get_waitchar (PdvDev pdv_p, unsigned char *wchar)
	Get serial wait character. More...
int	pdv_serial_get_numbytes (PdvDev pdv_p)
	Returns the number of bytes of unread data in the serial response buffer. More...
int	pdv_serial_get_block_size (void)
	Returns the block size for serial writes. More...
void	pdv_serial_set_block_size (int newsize)
	Sets the block size for serial writes. More...
int	pdv_serial_get_timeout (PdvDev pdv_p)
	Get the value of the serial timeout. More...
int	pdv_get_pause_for_serial (PdvDev pdv_p)
	Get the serial pause time, in milliseconds. More...

Detailed Description

Serial communications and camera control subroutines. Subroutines in this section of the library fall into three general categories: 1) low level serial communications and control, 2) framing commands for cameras that have sophisticated command framing protocols, and 3) high level convenience routines for specific operations on selected cameras.

These subroutines are used to communicate with cameras that have a serial command set. Since there is (to date) no standard command set, programmers who wish to embed camera control commands within applications will need to write code that is specific to the camera(s) in use.

Serial control typically consists a command/response sequence, and looks like the following:

pdv_serial_command(pdv_p, command_string); // ASCII; for binary use pdv_serial_binary_command
n = pdv_serial_wait(pdv_p, timeout, nchars);
pdv_serial_read(pdv_p, response_string, n);

The above is the most general purpose method, but it can be slow since pdv_serial_wait will only return after the timeout period expires, in order to ensure that all of the response characters have come in. If the last character of a response is known and can be assured to always be unique within that response, then the use of a serial wait character can be used. When set, it causes pdv_serial_wait to() return immediately when the character is seen, without waiting for the full timeout period to expire:

pdv_serial_set_waitchar(pdv_p, '\n');    // only needs to be set once
pdv_serial_command(pdv_p, command_string);
n = pdv_serial_wait(pdv_p, timeout, nchars); // still use max timeout in case of failure
pdv_serial_read(pdv_p, response_string, n);

Note

When this library was originally developed, there were a relatively small number of cameras and camera command sets to deal with. Consequently, subroutines written to directly control specific camera parameters such as pdv_set_exposure(), pdv_set_gain() and pdv_set_blacklevel() were coded to handle those tasks for the majority of cameras that had such functionality. With the proliferation of cameras and command sets over the years, these "convenience routines" have become less useful. They remain helpful for cameras whose command sets conform to the relatively narrow format defined by the serial_exposure, serial_gain and serial_offset config directives, but even then such control is limited, so for full control of cameras it is usually necessary for programmers to code such control with the lower-level subroutines pdv_serial_command(), pdv_serial_binary_command(), pdv_serial_wait() and pdv_serial_read() (or specialized framing commands such as pdv_serial_write_basler()). One important exception is if the camera and board are to be set up for pulse-width, aka level trigger acquisition control (where the length of the board's shutter timer is used to control the length of the EXPOSE pulse and consequently the camera's integration time). When using that mode (enabled via the method_camera_shutter_timing configuration directive), pdv_set_exposure() should be used, since it also controls the board's expose timer.

Function Documentation

pdv_serial_set_baud()

int pdv_serial_set_baud	(	PdvDev	pdv_p,
		int	baud
	)

Sets the baud rate on the serial lines; applies only to cameras with serial control. Valid values are 9600, 19200, 38500, 57500, and 115200.

Note

The baud rate is ordinarily initialized using the value of the serial_baud directive in the configuration file, and defaults to 9600 if the directive is not present. Under most circumstances, applications do not need to set the baud rate explicitly.

Parameters

pdv_p	The open PDV device handle.
baud	The desired baud rate.

Returns

0 on success, -1 on error.

See also

serial_baud directive in the Camera Configuration Guide.

pdv_serial_get_baud()

int pdv_serial_get_baud

(

PdvDev

pdv_p

)

Get the baud rate, typically initialized by the serial_baud directive in the config file.

Parameters

pdv_p

The open PDV device handle.

Returns

The baud rate in bits/sec, or 0 on error.

See also

serial_baud directive in the Camera Configuration Guide.

pdv_serial_command()

int pdv_serial_command	(	PdvDev	pdv_p,
		const char *	cmd
	)

Sends an ASCII serial command to the camera, with ASCII camera command formatting. Applies only to cameras that use a serial control method for camera-computer communications.

Parameters

pdv_p	The open PDV device handle.
cmd	The command to send to the camera.

Returns

0 on success, -1 on failure

See also

pdv_serial_term(), pdv_serial_prefix(), pdv_serial_set_delimiters(), pdv_serial_write()

Appends the required serial terminator onto the string before sending. The default serial terminator is the \\r (carriage return) character, which is the most common serial terminator character for cameras with use ASCII serial command sets. If the serial_term directive is present in the config file in use, it will use the terminator specified by that instead. For example, if the camera requires a CR/LF (carriage return/line feed) to terminate instead of just a single carriage return, make sure the following command is in the config file in use:

serial_term: "\r\n"

Also available but much less common is the serial prefix, which can also be added to any command via the serial_prefix camera configuration directive. By default there is no serial prefix.

For a detailed example of serial communications, see the serial_cmd.c example program.

Consult your camera manufacturer's users guide for information on serial command format reqirements.

Example:

pdv_serial_command(pdv_p, "DEF_ON"); // set defect correction on

pdv_serial_binary_command()

int pdv_serial_binary_command	(	PdvDev	pdv_p,
		const uint8_t *	cmd,
		int	len
	)

Sends a binary serial command to the camera. Applies only to cameras that use a serial control method for for camera-computer communications.

Parameters

pdv_p	The open PDV device handle.
cmd	A buffer containing the serial command.
len	The number of bytes to send.

Returns

0 on success, -1 on failure.

See also

pdv_serial_command(), pdv_serial_read(), pdv_serial_wait()

Similar to pdv_serial_command(), but for binary instead of ASCII commands, it uses a count instead of a terminating NULL to indicate the end of the data. Also, it doesn't add on any terminating CR or LF characters.

Consult your camera manufacturer user's guide for information on serial command format requirements.

For a detailed example of serial communications, see the serial_cmd.c example program.

pdv_serial_write_available()

int pdv_serial_write_available

(

PdvDev

pdv_p

)

Get the number of bytes available in the driver's serial write buffer.

Parameters

pdv_p

The open PDV device handle.

Returns

The number of bytes available in the driver's write buffer.

pdv_serial_write()

int pdv_serial_write	(	PdvDev	pdv_p,
		const char *	buf,
		int	size
	)

Performs a serial write over the serial lines. Not recommended for use in new code, consider using pdv_serial_command() or pdv_serial_binary_command() instead.

Parameters

pdv_p	The open PDV device handle.
buf	The buffer containing the serial command.
size	The number of bytes to send.

Returns

0 on success, -1 on failure.

See also

pdv_serial_command(), pdv_serial_binary_command()

pdv_serial_read()

int pdv_serial_read	(	PdvDev	pdv_p,
		char *	buf,
		int	size
	)

Performs a serial read over the serial control lines.

The serial data read will be stored in a user supplied buffer. That buffer will be NULL-terminated. Use pdv_serial_read_nullterm(pdv_p, FALSE) if you don't want that behavior.

Parameters

	pdv_p	The open PDV device handle.
[out]	buf	The buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
	size	The number of bytes to be read.

Returns

The number of bytes read into the buffer.

See also

pdv_serial_wait()

Example:

int count = 64;  // wait for 64 bytes, or timeout, whichever comes first.
int got = pdv_serial_wait(pdv_p, 0, count);
char buf[count+1];
 
// read the data we waited for
pdv_serial_read(pdv_p, buf, got);
if (got < count)
  printf("timeout occurred while waiting for serial data\n");
if (got != 0)
  printf("data read over serial: %s\n", buf);

pdv_serial_read_blocking()

int pdv_serial_read_blocking	(	PdvDev	pdv_p,
		char *	buf,
		int	size
	)

Performs a serial read over the serial control lines, blocks until all requested data is read.

Parameters

	pdv_p	The open PDV device handle.
[out]	buf	The buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
	size	The number of bytes to be read.

Returns

The number of bytes read into the buffer.

See also

pdv_serial_wait(), pdv_serial_read()

pdv_serial_read_nullterm()

int pdv_serial_read_nullterm	(	PdvDev	pdv_p,
		char *	buf,
		int	size,
		int	nullterm
	)

Performs a serial read over the serial control lines. The buffer passed in will be NULL-terminated if nullterm is true.

Parameters

	pdv_p	The open PDV device handle.
[out]	buf	The buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
	size	The number of bytes to be read.
	nullterm	True to null terminate the buffer read in, false to disable that.

Returns

The number of bytes read into buf.

See also

pdv_serial_read()

pdv_serial_set_delimiters()

void pdv_serial_set_delimiters	(	PdvDev	pdv_p,
		const char *	newprefix,
		const char *	newterm
	)

Set the prefix and terminator for serial commands.

The serial prefix and terminator are typically set through the serial_term and serial_prefix config file directives.

Parameters

pdv_p	The open PDV device handle.
newprefix	A string to prefix to serial commands, or NULL.
newterm	A string to append to serial commands, or NULL.

See also

pdv_serial_command(), serial_prefix and serial_term directives in the Camera Configuration Guide.

pdv_serial_prefix()

const char * pdv_serial_prefix

(

PdvDev

pdv_p

)

Get the serial prefix.

Parameters

pdv_p

The open PDV device handle.

Returns

The serial prefix string.

See also

pdv_serial_command(), serial_prefix directive in the Camera Configuration Guide.

pdv_serial_term()

const char * pdv_serial_term

(

PdvDev

pdv_p

)

Get the serial terminator.

Parameters

pdv_p

The open PDV device handle.

Returns

The serial terminator string.

See also

pdv_serial_command(), serial_term directive in the Camera Configuration Guide.

pdv_serial_send_break()

void pdv_serial_send_break

(

PdvDev

pdv_p

)

Send a break condition on the serial connection.

Parameters

pdv_p

The open PDV device handle.

pdv_serial_reset()

void pdv_serial_reset

(

PdvDev

pdv_p

)

Resets the serial interface. Clears any outstanding reads and writes and puts the serial interface in a known idle state.

Parameters

pdv_p

The open PDV device handle.

pdv_serial_read_basler()

int pdv_serial_read_basler	(	PdvDev	pdv_p,
		uint8_t *	cmd,
		int	len
	)

Reads a Basler binary frame command. Checks the framing and BCC.

Parameters

	pdv_p	The open PDV device handle.
[out]	cmd	The buffer to receive the data.
	len	The maximum number of bytes to be read.

Returns

The number of characters read back, or 0 if none or failure.

See also

BASLER A202K Camera Manual Doc. ID number DA044003

pdv_serial_write_basler()

int pdv_serial_write_basler	(	PdvDev	pdv_p,
		uint8_t *	cmd,
		int	len
	)

Send a Basler formatted serial frame. Adds the framing and BCC.

Parameters

pdv_p	The open PDV device handle.
cmd	The serial data to send.
len	The number of bytes to send.

Returns

The number of characters read back, or 0 if none or failure.

0 on success, -1 on failure.

See also

BASLER A202K Camera Manual Doc. ID number DA044003

pdv_serial_read_duncan()

int pdv_serial_read_duncan	(	PdvDev	pdv_p,
		uint8_t *	frame
	)

Read a binary serial response from a Duncantech MS and DT series camera – checks for STX and size, then waits for size+1 more bytes.

Parameters

	pdv_p	The open PDV device handle.
[out]	frame	The buffer to receive the data.

Returns

The number of characters read back, or 0 if none or failure.

See also

pdv_serial_write_duncan(), DuncanTech User Manual Doc # 9000-0001-05.

pdv_serial_write_duncan()

int pdv_serial_write_duncan	(	PdvDev	pdv_p,
		uint8_t *	cmdbuf,
		int	size
	)

Send a Duncantech MS / DT series camera frame – adds the framing and checksum, then sends the command.

Parameters

pdv_p	The open PDV device handle.
cmdbuf	A buffer containing the command, minus framing information.
size	The number of bytes in the cmdbuf.

Returns

0 on success, -1 on failure.

See also

pdv_serial_read_duncan(), DuncanTech User Manual Doc # 9000-0001-05.

pdv_serial_wait()

int pdv_serial_wait	(	PdvDev	pdv_p,
		int	msecs,
		int	count
	)

Waits for a response from the camera as a result of a pdv_serial_write() or pdv_serial_command().

After calling this function, use pdv_serial_read() to get the data. For a detailed example of serial communications, see the serial_cmd.c example program.

If the timeout value is zero, the default from the serial_timeout directive in the config file is used. If no default timeout value was specified, the timeout will be 1000 milliseconds.

If two threads attempt to call pdv_serial_wait() at the same time, one will return immediately with a result of -EBUSY.

Parameters

pdv_p	The open PDV device handle.
msecs	Number of milliseconds to wait before timing out.
count	The maximum number of bytes to wait for before returning.

Returns

On success or timeout, the number of bytes of serial data returned from the camera. Negative error code on error.

See also

pdv_serial_read(), serial_timeout directive in the Camera Configuration Guide.

pdv_serial_wait_next()

int pdv_serial_wait_next	(	PdvDev	pdv_p,
		int	msecs,
		int	count
	)

Wait for new serial data to come in. Ignore any previously received data.

Parameters

pdv_p	The open PDV device handle.
msecs	Number of milliseconds to wait before timing out.
count	The maximum number of bytes to wait for before returning.

Returns

The number of bytes of serial data returned from the camera.

pdv_serial_set_waitchar()

int pdv_serial_set_waitchar	(	PdvDev	pdv_p,
		int	enable,
		unsigned char	wchar
	)

Set the serial wait character.

Normally pdv_serial_wait() will wait until the serial_timeout period expires before returning (unless the max number of characters is seen). This is the most general purpose and robust method since there's no other way of knowing all different camera response formats. However if each response can be expected to be 1 line terminated by the same character(such as a newline) every time, then setting the serial_waitchar to that character can greatly shorten the time it takes for a pdv_serial_wait() call to return.

This character can also be initialized in the camera configuration directive serial_waitchar.

Parameters

pdv_p	The open PDV device handle.
enable	Nonzero to enable wait character detection.
wchar	The end of message character to detect.

Returns

0 in success, -1 on failure

See also

pdv_serial_get_waitchar() and serial_waitchar directive in the <a * href="https://edt.com/downloads/camera-configuration-guide.pdf"> Camera Configuration Guide.

pdv_serial_get_waitchar()

int pdv_serial_get_waitchar	(	PdvDev	pdv_p,
		unsigned char *	wchar
	)

Get serial wait character.

If wait character detection is enabled, pdv_serial_wait() will return immediately after the wait character is detected.

Parameters

	pdv_p	The open PDV device handle.
[out]	wchar	The character wait character detection will wait for.

Returns

1 if waitchar enabled, 0 if disabled.

See also

pdv_serial_set_waitchar() and serial_waitchar directive in the <a * href="https://edt.com/downloads/camera-configuration-guide.pdf"> Camera Configuration Guide.

pdv_serial_get_numbytes()

int pdv_serial_get_numbytes

(

PdvDev

pdv_p

)

Returns the number of bytes of unread data in the serial response buffer.

Similar to pdv_serial_wait() but doesn't wait for any timeout period, nor does it have any minimum count parameter.

Parameters

pdv_p

The open PDV device handle.

Returns

The number of bytes of serial data returned from the camera.

pdv_serial_get_block_size()

int pdv_serial_get_block_size

(

void

)

Returns the block size for serial writes.

Returns

The serial block size in bytes.

pdv_serial_set_block_size()

void pdv_serial_set_block_size

(

int

newsize

)

Sets the block size for serial writes.

The default size is 1024.

Parameters

newsize

The new serial block size in bytes.

pdv_serial_get_timeout()

int pdv_serial_get_timeout

(

PdvDev

pdv_p

)

Get the value of the serial timeout.

Parameters

pdv_p

The open PDV device handle.

Returns

The timeout in milliseconds.

See also

serial_timeout directive in the <a * href="https://edt.com/downloads/camera-configuration-guide.pdf"> Camera Configuration Guide.

pdv_get_pause_for_serial()

int pdv_get_pause_for_serial

(

PdvDev

pdv_p

)

Get the serial pause time, in milliseconds.

Set by the pause_for_serial directive in a camera configuration file.

Parameters

pdv_p

The open PDV device handle.

Returns

The serial pause time in milliseconds.

See also

pause_for_serial directive in the <a * href="https://edt.com/downloads/camera-configuration-guide.pdf"> Camera Configuration Guide.