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_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);
Functions | |
| int | pdv_get_baud (PdvDev *pdv_p) |
| Get the baud rate, typically initialized by the serial_baud directive in the config file (default 9600). | |
| int | pdv_get_serial_block_size () |
| Returns the block size for serial writes. | |
| int | pdv_get_waitchar (PdvDev *pdv_p, u_char *waitc) |
| Get serial wait character, or byte. | |
| int | pdv_query_serial (PdvDev *pdv_p, char *cmd, char **resp) |
| Send a serial command, get the response in a multiline string, one line per string pointer. | |
| int | pdv_read_basler_frame (PdvDev *pdv_p, u_char *frame, int len) |
| Read a Basler binary frame command. | |
| int | pdv_read_duncan_frame (PdvDev *pdv_p, u_char *frame) |
| Read response (binary serial) from a Duncantech MS and DT series camera -- checks for STX and size, then waits for size+1 more bytes. | |
| void | pdv_reset_serial (PdvDev *pdv_p) |
| Resets the serial interface. | |
| int | pdv_send_basler_command (PdvDev *pdv_p, int cmd, int rwflag, int len, int data) |
| Send a basler binary command -- do the framing and BCC. | |
| int | pdv_send_basler_frame (PdvDev *pdv_p, u_char *cmd, int len) |
| Send a Basler formatted serial frame. | |
| void | pdv_send_break (PdvDev *pdv_p) |
| send serial break (only aiag and related xilinx files) | |
| int | pdv_send_duncan_frame (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. | |
| int | pdv_send_msg (PdvDev *ed, int chan, const char *buf, int size) |
| wrapper for edt_send_msg, but added pause between bytes if indicated by pause_for_serial (done initially for imperx cam) | |
| int | pdv_serial_binary_command (PdvDev *pdv_p, const char *cmd, int len) |
| Sends binary serial command(s) to the camera. | |
| int | pdv_serial_binary_command_flagged (PdvDev *pdv_p, const char *cmd, int len, u_int flag) |
| Sends a binary serial command. | |
| int | pdv_serial_check_enabled (PdvDev *pdv_p) |
| int | pdv_serial_command (PdvDev *pdv_p, const char *cmd) |
| Sends an ASCII serial command to the camera, with ASCII camera command formatting. | |
| int | pdv_serial_command_flagged (PdvDev *pdv_p, const char *cmd, u_int flag) |
| Bottom level serial_command that takes a flag for different options. | |
| int | pdv_serial_command_hex (PdvDev *pdv_p, const char *str, int length) |
| Send hex byte command (formatted ascii "0xNN") as binary. | |
| int | pdv_serial_get_numbytes (PdvDev *pdv_p) |
| Returns the number of bytes of unread data in the serial response buffer. | |
| char * | pdv_serial_prefix (PdvDev *pdv_p) |
| Get the serial prefix. | |
| int | pdv_serial_read (PdvDev *pdv_p, char *buf, int count) |
| Performs a serial read over the serial control lines. | |
| 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 serial is read. | |
| int | pdv_serial_read_disable (PdvDev *pdv_p) |
| int | pdv_serial_read_enable (PdvDev *pdv_p) |
| int | pdv_serial_read_nullterm (PdvDev *pdv_p, char *buf, int size, int nullterm) |
| Preforms a serial read over the RS-422 or RS-232 lines if EDT has provided a special cable to accommodate RS-422 or RS-232 serial control. | |
| char * | pdv_serial_term (PdvDev *pdv_p) |
| Get the serial terminator. | |
| void | pdv_serial_txrx (PdvDev *pdv_p, char *txbuf, int txcount, char *rxbuf, int rxcount, int timeout, u_char *wchar) |
| Serial send AND recieve -- send a command and wait for the response. | |
| int | pdv_serial_wait (PdvDev *pdv_p, int msecs, int count) |
| Waits for response from the camera as a result of a pdv_serial_write or pdv_serial_command. | |
| int | pdv_serial_wait_next (EdtDev *pdv_p, int msecs, int count) |
| Wait for next serial to come in -- ignore any previous if 0, just wait for the next thing, however many it is. | |
| int | pdv_serial_write (PdvDev *pdv_p, const char *buf, int size) |
| Performs a serial write over the serial lines. | |
| int | pdv_serial_write_available (PdvDev *pdv_p) |
| pdv_serial_write_avail Get the number of bytes available in the driver's serial write buffer. | |
| int | pdv_serial_write_single_block (PdvDev *pdv_p, const char *buf, int size) |
| Writes a serial command buffer to a serial aia (Kodak type) device. | |
| int | pdv_set_baud (PdvDev *pdv_p, int baud) |
| Sets the baud rate on the serial lines; applies only to cameras with serial control. | |
| void | pdv_set_serial_block_size (int newsize) |
| Sets the block size for serial writes if the default of 512 is not adequate. | |
| void | pdv_set_serial_delimiters (PdvDev *pdv_p, char *prefix, char *term) |
| Get the serial prefix. | |
| int | pdv_set_serial_parity (PdvDev *pdv_p, char parity) |
| Sets parity to even, odd, or none. | |
| int | pdv_set_waitchar (PdvDev *pdv_p, int enable, u_char wchar) |
| Set serial wait character. | |
| int pdv_get_baud | ( | PdvDev * | pdv_p | ) |
Get the baud rate, typically initialized by the serial_baud directive in the config file (default 9600).
| int pdv_get_serial_block_size | ( | void | ) |
Returns the block size for serial writes.
| int pdv_get_waitchar | ( | PdvDev * | pdv_p, | |
| u_char * | waitc | |||
| ) |
Get serial wait character, or byte.
This value, if set, is what pdv_serial_wait will return immediately after it comes in instead of waiting for the serial timeout period to expire.
| pdv_p | same as it ever was | |
| waitc | character (byte) to wait for |
| int pdv_query_serial | ( | PdvDev * | pdv_p, | |
| char * | cmd, | |||
| char ** | resp | |||
| ) |
| int pdv_read_basler_frame | ( | PdvDev * | pdv_p, | |
| u_char * | frame, | |||
| int | len | |||
| ) |
| int pdv_read_duncan_frame | ( | PdvDev * | pdv_p, | |
| u_char * | frame | |||
| ) |
Read response (binary serial) from a Duncantech MS and DT series camera -- checks for STX and size, then waits for size+1 more bytes.
Ref. DuncanTech User Manual Doc # 9000-0001-05.
Convenience routine for Duncantech (Redlake) DT/MS series cameras only.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| frame | buffer containing the frame read back from the camera |
| void pdv_reset_serial | ( | PdvDev * | pdv_p | ) |
Resets the serial interface.
This is mostly used during initialization (initcam) to make sure any outstanding reads and writes from previous interrupted applications are cleaned up and to put the serial state machine in a known idle state. Applications typically do not need to call this subroutine.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| int pdv_send_basler_command | ( | PdvDev * | pdv_p, | |
| int | cmd, | |||
| int | rwflag, | |||
| int | len, | |||
| int | data | |||
| ) |
Send a basler binary command -- do the framing and BCC.
ref. BASLER A202K Camera Manual Doc. ID number DA044003.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| cmd | basler command | |
| rwflag | read/write flag -- 1 if read, 0 if write | |
| len | data length | |
| data | the data (if any) |
| int pdv_send_basler_frame | ( | PdvDev * | pdv_p, | |
| u_char * | cmd, | |||
| int | len | |||
| ) |
| int pdv_send_duncan_frame | ( | 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.
Ref. DuncanTech User Manual Doc # 9000-0001-05.
cmdbuf: command buf: typically includes command, 2 size bytes, and size-1 message butes size: number of message bytes plus command byte
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| cmdbuf | buffer containing the command, minus framing information | |
| size | number of bytes in the cmdbuf |
| int pdv_send_msg | ( | PdvDev * | ed, | |
| int | chan, | |||
| const char * | buf, | |||
| int | size | |||
| ) |
wrapper for edt_send_msg, but added pause between bytes if indicated by pause_for_serial (done initially for imperx cam)
| int pdv_serial_binary_command | ( | PdvDev * | pdv_p, | |
| const char * | cmd, | |||
| int | len | |||
| ) |
Sends binary serial command(s) to the camera.
Applicable only to cameras that use RS-232 or RS-422 binary serial for camera-computer communications. 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_p | pointer to pdv device structure returned by pdv_open | |
| cmd | buffer containing serial command(s) | |
| len | number of bytes to send |
| int pdv_serial_binary_command_flagged | ( | PdvDev * | pdv_p, | |
| const char * | cmd, | |||
| int | len, | |||
| u_int | flag | |||
| ) |
Sends a binary serial command.
convenience wrapper for pdv_serial_write() -- takes the command string and prepends the 'c' to it if FOI, then calls pdv_serial_write(). Because of the FOI issue, applications should ALWAYS use this or one of the other pdv serial command calls (pdv_serial_binary_command, pdv_serial_command_flagged, etc.) instead of calling pdv_serial_write directly
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| cmd | command -- must be a valid serial command for the camera in use, as defined in camera manufacturer's user's manual | |
| len | number of bytes of cmd to write | |
| flag | flag bits -- so far only SCFLAG_NORESP is defined -- tells the driver not to wait for a response before returning |
| 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.
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_p | pointer to pdv device structure returned by pdv_open | |
| cmd | command -- must be a valid serial command for the camera in use, as as defined in the camera manufacturer's user's manual |
pdv_serial_term, pdv_serial_prefix, pdv_set_serial_delimiters, pdv_serial_write
| int pdv_serial_command_flagged | ( | PdvDev * | pdv_p, | |
| const char * | cmd, | |||
| u_int | flag | |||
| ) |
Bottom level serial_command that takes a flag for different options.
Primarily for internal use; applications should avoid calling directly and instead use pdv_serial_command.
The only flag is the SCFLAG_NORESP flag, which says whether to wait for response on FOI. Normal case is no, but internally (when called from pdv_set_exposure, for example) the flag is set to 1 so it doesn't slow down the data stream.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| cmd | command to send | |
| flag | flag whether to wait for response on FOI |
| int pdv_serial_command_hex | ( | PdvDev * | pdv_p, | |
| const char * | str, | |||
| int | length | |||
| ) |
Send hex byte command (formatted ascii "0xNN") as binary.
Assumes the format has already been checked.
Not all that useful for user applications, mainly it's here for special use by pdv_initcam.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| str | ASCII command string containing "0x%s" hex formatted string | |
| length | reserved, for future use |
| 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| count | Maximum number of bytes to wait for before returning. |
| char* pdv_serial_prefix | ( | PdvDev * | pdv_p | ) |
Get the serial prefix.
See pdv_serial_command for more about the serial prefix.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| int pdv_serial_read | ( | PdvDev * | pdv_p, | |
| char * | buf, | |||
| int | count | |||
| ) |
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.
Example
int count = 64; // wait for 64 bytes, or timeout, whichever comes first. int got = pdv_serial_wait(pdv_p, 0, count); // read the data we waited for. char buf[count+1]; 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_p | pointer to pdv device structure returned by pdv_open | |
| buf | pointer to data buffer--must be preallocated to at least count + 1 bytes (count bytes of data plus a one byte NULL terminator). | |
| count | Number of bytes to be read. |
| 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 serial is read.
Similar to pdv_serial_read but blocks until all requested serial bytes have been received. The serial data read will be stored in a user supplied buffer.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| buf | pointer to data buffer--must be preallocated to at least count + 1 bytes (count bytes of data plus a one byte NULL terminator). | |
| count | Number of bytes to be read. |
| int pdv_serial_read_nullterm | ( | PdvDev * | pdv_p, | |
| char * | buf, | |||
| int | size, | |||
| int | nullterm | |||
| ) |
Preforms a serial read over the RS-422 or RS-232 lines if EDT has provided a special cable to accommodate RS-422 or RS-232 serial control.
The buffer passed in will be NULL-terminated if nullterm is true.
| pdv_p | device struct returned from pdv_open | |
| buf | pointer to data buffer--must be preallocated to at least count bytes | |
| size | number of bytes to be read, which must be at most one less than the size of the buf (so there is room for the NULL terminator). | |
| nullterm | true to null terminate the buffer read in, false to disable that. |
| char* pdv_serial_term | ( | PdvDev * | pdv_p | ) |
Get the serial terminator.
See pdv_serial_command for more about the serial terminator.
| pdv_p | pointer to pdv device structure returned by pdv_open |
| void pdv_serial_txrx | ( | PdvDev * | pdv_p, | |
| char * | txbuf, | |||
| int | txcount, | |||
| char * | rxbuf, | |||
| int | rxcount, | |||
| int | timeout, | |||
| u_char * | wchar | |||
| ) |
Serial send AND recieve -- send a command and wait for the response.
Takes both expected receive count and char on which to terminate the receive -- if both are specified will return on first one -- that is if there's a count of 4 but the 3rd char back is the one specified in wchar, then will return after 3.
| pdv_p | device handle returned by pdv_open | |
| txbuf | buffer to send out | |
| txcount | number of characters to send out | |
| rxbuf | buffer to hold response | |
| rxcount | number of characters expected back | |
| timeout | number of milliseconds to wait for expected response | |
| wchar | pointer to terminating char (NULL if none) |
| int pdv_serial_wait | ( | PdvDev * | pdv_p, | |
| int | msecs, | |||
| int | count | |||
| ) |
Waits for 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.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| msecs | number of milliseconds to wait before timing out. If this parameter is 0, the defualt timeout value is used, as specified by the serial_timeout directive in the current configuration file. If no default timout value was specified, the default is 1000 milliseconds (1 second). | |
| count | Maximum number of bytes to wait for before returning. |
| int pdv_serial_wait_next | ( | EdtDev * | pdv_p, | |
| int | msecs, | |||
| int | count | |||
| ) |
Wait for next serial to come in -- ignore any previous if 0, just wait for the next thing, however many it is.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| msecs | number of milliseconds to wait before timing out | |
| count | number maximum number to wait for |
| int pdv_serial_write | ( | PdvDev * | pdv_p, | |
| const char * | buf, | |||
| int | size | |||
| ) |
Performs a serial write over the serial lines.
This command applies only to cameras that use a serial control method.
This function is mainly for sending binary data over the serial lines to the camera. It can be used for ASCII commands, but pdv_serial_command is generally easier.
For a detailed example of serial communications, see the serial_cmd.c example program.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| buf | buffer containing serial command(s) | |
| size | number of bytes to send |
| int pdv_serial_write_available | ( | PdvDev * | pdv_p | ) |
| int pdv_serial_write_single_block | ( | PdvDev * | pdv_p, | |
| const char * | buf, | |||
| int | size | |||
| ) |
Writes a serial command buffer to a serial aia (Kodak type) device.
Note: applications should pretty much ALWAYS use pdv_serial_command or pdv_serial_binary_command instead of calling pdv_serial_write directly since, when a FOI is detected, those two calls prepend the required that is needed to pass the command on to the camera.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| buf | string to send to the device | |
| size | number of bytes to write |
| int pdv_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.
| baud | the desired baud rate. | |
| pdv_p | pointer to pdv device structure returned by pdv_open |
| void pdv_set_serial_block_size | ( | int | newsize | ) |
| void pdv_set_serial_delimiters | ( | PdvDev * | pdv_p, | |
| char * | prefix, | |||
| char * | term | |||
| ) |
Get the serial prefix.
The serial prefix (if any) is typically set through the config file, which is that is the preferred way to set up any serial delimiters; calling this subroutine directly should be avoided.
See pdv_serial_command for more about the serial delimiters.
| pdv_p | pointer to pdv device structure returned by pdv_open | |
| prefix | - see pdv_serial_command | |
| term | - see pdv_serial_command |
| int pdv_set_serial_parity | ( | PdvDev * | pdv_p, | |
| char | parity | |||
| ) |
| int pdv_set_waitchar | ( | PdvDev * | pdv_p, | |
| int | enable, | |||
| u_char | wchar | |||
| ) |
Set 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 the camera formats are known, and specifically a 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.
1.4.7