EDT PDV SDK Documentation 6.1.0
Communications/Control
Collaboration diagram for 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, u_char *cmd, int len)
 Reads a Basler binary frame command. Checks the framing and BCC. More...
 
int pdv_serial_write_basler (PdvDev pdv_p, u_char *cmd, int len)
 Send a Basler formatted serial frame. Adds the framing and BCC. More...
 
int pdv_serial_read_duncan (PdvDev pdv_p, u_char *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, u_char *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, u_char wchar)
 Set the serial wait character. More...
 
int pdv_serial_get_waitchar (PdvDev pdv_p, u_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_pThe open PDV device handle.
baudThe 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_pThe 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.
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
cmdThe 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
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
cmdA buffer containing the serial command.
lenThe 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_pThe open PDV device handle.
Returns
The number of bytes available in the driver's write buffer.
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
bufThe buffer containing the serial command.
sizeThe number of bytes to send.
Returns
0 on success, -1 on failure.
See also
pdv_serial_command(), pdv_serial_binary_command()
Here is the call graph for this function:

◆ 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_pThe open PDV device handle.
[out]bufThe buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
sizeThe 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);
Here is the call graph for this function:
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
[out]bufThe buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
sizeThe number of bytes to be read.
Returns
The number of bytes read into the buffer.
See also
pdv_serial_wait(), pdv_serial_read()
Here is the call graph for this function:

◆ 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_pThe open PDV device handle.
[out]bufThe buffer to receive the data. It must be at least size + 1 bytes (size bytes of data plus a one byte NULL terminator).
sizeThe number of bytes to be read.
nulltermTrue to null terminate the buffer read in, false to disable that.
Returns
The number of bytes read into buf.
See also
pdv_serial_read()
Here is the call graph for this function:
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
newprefixA string to prefix to serial commands, or NULL.
newtermA string to append to serial commands, or NULL.
See also
pdv_serial_command(), serial_prefix and serial_term directives in the Camera Configuration Guide.
Here is the call graph for this function:

◆ pdv_serial_prefix()

const char * pdv_serial_prefix ( PdvDev  pdv_p)

Get the serial prefix.

Parameters
pdv_pThe 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_pThe 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_pThe open PDV device handle.
Here is the call graph for this function:

◆ 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_pThe open PDV device handle.
Here is the caller graph for this function:

◆ pdv_serial_read_basler()

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

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

Parameters
pdv_pThe open PDV device handle.
[out]cmdThe buffer to receive the data.
lenThe 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
Here is the call graph for this function:

◆ pdv_serial_write_basler()

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

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

Parameters
pdv_pThe open PDV device handle.
cmdThe serial data to send.
lenThe 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,
u_char *  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_pThe open PDV device handle.
[out]frameThe 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.
Here is the call graph for this function:

◆ pdv_serial_write_duncan()

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

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

Parameters
pdv_pThe open PDV device handle.
cmdbufA buffer containing the command, minus framing information.
sizeThe 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.

Parameters
pdv_pThe open PDV device handle.
msecsNumber of milliseconds to wait before timing out.
countThe maximum number of bytes to wait for before returning.
Returns
On success, the number of bytes of serial data returned from the camera. -1 on failure.
See also
pdv_serial_read(), serial_timeout directive in the Camera Configuration Guide.
Here is the caller graph for this function:

◆ 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_pThe open PDV device handle.
msecsNumber of milliseconds to wait before timing out.
countThe maximum number of bytes to wait for before returning.
Returns
The number of bytes of serial data returned from the camera.
Here is the call graph for this function:

◆ pdv_serial_set_waitchar()

int pdv_serial_set_waitchar ( PdvDev  pdv_p,
int  enable,
u_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_pThe open PDV device handle.
enableNonzero to enable wait character detection.
wcharThe 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,
u_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_pThe open PDV device handle.
[out]wcharThe 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_pThe 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
newsizeThe 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_pThe 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_pThe 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.