PIXCI® Imaging Products: Configuring Raptor Photonics Cameras via Serial Commands

1. PIXCI® Imaging Products: Configuring Raptor Photonics Cameras via Serial Commands

Raptor Photonics cameras provide many settings and configurable features; these features are configured via ‘serial commands’.

When using the XCAP GUI application, a camera specific dialog handles configuring the camera. If using a programming language or application environment, this application note will help the reader get started with camera configuration and ‘serial commands’.

Simple setting of ´Static´ Parameters

Typically, many camera settings and features need not be changed often or quickly. While other features, such as gain and exposure, must be changed ‘on-the-fly’.

Configuring the relatively ‘static’ camera settings is easily done by exporting a video setup file (i.e. .fmt file) from the XCAP GUI application, and importing into the XCLIB C/C++ API/SDK. In XCAP, after configuring the camera via the XCAP GUI, use PIXCI®, PIXCI® Export Video Setup. In XCLIB, use:

    pxd_PIXCIopen(..., "", pathnameToVideoSetup.fmt);

Of course, multiple video setup files with different camera configurations can be exported, and the desired configuration and video setup file imported. If programming in C/C++, XCLIB also provides a mechanism to compile one or more video setup files into the application, so that they need not be loaded at run time and can’t be misplaced.

Some applications acquire images and video via the PIXCI® Frame Server (Direct Show) driver (for Windows) or the PIXCI® Video for Linux (V4L2) driver. While the application does not, directly, use pxd_PIXCIopen, there is provision for specifying the video setup file to be used; see the relevant PIXCI® Imaging Drivers: Media Foundation Frame Server (Windows ’Camera’ Device & DirectShow Source) or PIXCI® Imaging Drivers: Video for Linux Driver (V4L2) application note.

Formatting of Serial Commands

For camera settings and features that must be changed on-the-fly, there are two aspects: First, the format of the serial command and serial responses as byte array data. Second, how data is sent to, and received from, the camera.

1. The format of serial commands and responses, including, the ‘Set System Status’ and, for each camera feature, the address(es) and the data value(s) required, are described in the Raptor camera documentation (i.e. the camera’s ‘ICD’ or ‘IM’). Available from Raptor Photonics.

2. A spreadsheet to show the formatted data for various serial commands is available from Raptor Photonics.

3. The example raptos.c program illustrates how to format and send a serial command, and how to receive and interpret the response. It does not describe each camera feature and register, but shows how to initialize the camera’s ‘System Status’, set an arbitrary register address to a desired value, and how to query a register address. It also specifically illustrates the setting of the most popular features, such as gain and exposure, and querying sensor temperature. Although written in ‘C’, it is intended to be readable (i.e. avoiding the more esoteric elements of ‘C’ syntax) and thus also of interest to users of LabView, Matlab, Python, VB, etc. Available from EPIX, Inc. Technical Support.

Similarly, the RaptorCOM.vb and RaptorXCLIB.vb programs illustrates use of serial commands using VB.NET. Available from EPIX, Inc. Technical Support.

4. The XCAP GUI application can show the serial command data it sends and the responses received; thus providing additional examples. See the Capture & Adjust dialog, under Port (tab), and enable Serial Logging as Xmt+Rcv, Hex.

Sending of Serial Commands

A formatted serial command can be sent to the camera, and the camera’s response received, via:

1. The XCLIB C/C++ SDK/API along with pxd_serialWrite() and pxd_serialRead() functions. Also see pxd_serialConfigure() for setting the correct baud rate.

2. The PIXCI® frame grabber’s COM port (for Windows) along with WriteFile() and ReadFile(). Also see SetCommState() for setting the correct baud rate. The optional COM port driver can be installed using the XCAP GUI application, see PIXCI®, PIXCI® Open/Close, Close, Driver Assistant.

3. The PIXCI® frame grabber’s tty port (for Linux) along with write() and read(). Also see tcsetattr() for setting the correct baud rate. The optional tty port driver can be installed using the XCAP GUI application, see PIXCI®, PIXCI® Open/Close, Close, Driver Assistant.[1]

4. The Camera Link Standard’s ‘clSerial’ API (for Windows) and its PIXCI® frame grabber’s implementation via clserEPX.DLL along with clSerialWrite() and clSerialRead(). Also see clSetBaudRate() for setting the correct baud rate. The optional clserEPX.DLL can be installed using the XCAP GUI application, see PIXCI®, PIXCI® Open/Close, Close, Driver Assistant. Use of the ‘clSerial’ functions is described in the Camera Link Standard specification.

The example raptos.c program, mentioned above, illustrates all of the these methods. The example RaptorCOM.vb program, mentioned above, illustrates using the PIXCI® frame grabber’s COM port (for Windows). The example RaptorXCLIB.vb program, mentioned above, illustrates using the PIXCI® frame grabber’s XCLIB C/C++ SDK/API.

Most interpretive application environments, such as LabView or Matlab, will offer their own, unique, support for sending and receiving data through a COM or tty port. When using PIXCI® frame grabber’s COM port (for Windows) or the PIXCI® frame grabber’s tty port (for Linux), using their specific support for COM or tty ports is the recommended approach, rather than using various, environment specific, extensions to call system functions such as WriteFile() or write().

Hints

The syntax of serial commands shown in the camera manual (IM or ICD), the spreadsheet, or serial logging in XCAP will vary, such as:

    0x4F 0x12 0x50
    4F 12 50
    /4F//12//50/

but generally describe byte values expressed in hexadecimal. Functions such as XCLIB’s pxd_serialWrite(), a COM port’s WriteFile(), a tty port’s write(), or a clSerial’s clSerialWrite() expect, for the example above, a three byte array; the first value of which is 4F (base 16), the second is 12 (base 16), etc. Or, can accept a three byte string.[2] Passing a string, such as:

    "0x4F 0x12 0x50"
    "0x4F, 0x12, 0x50"
    "4F 12 50"
    "4F1250"
    "/4F//12//50/"

will not work; the above functions are not designed to convert a textual description of the data. From C/C++, passing a string of:

    "\x4F\x12\x50"

will work; but only because C/C++ provides syntax for specifying each byte of the string via a hexadecimal value via a back-slash ‘escape’ — and not due to any feature of pxd_serialWrite(), WriteFile(), write(), clSerialWrite(), or of the camera.

In some programming environments, there may be confusion as to how to pass an array of bytes, each initialized to any/all 8-bit values, to pxd_serialWrite(), WriteFile(), write(), or clSerialWrite() — in contrast to passing a ‘readable’ textual string. The XCLIB C/C++ API/SDK, the PIXCI® frame grabber’s COM port driver, and the PIXCI® frame grabber’s clserEPX.DLL implementation of ‘clSerial’ all provide data logging features; the data passed to pxd_serialWrite(), WriteFile(), or clSerialWrite() is reported in the log as, both, the interpretation as ASCII characters (which can be ignored) and as hexadecimal byte values; this can provide quick feedback as to whether the proper serial data is being passed.[3] While the PIXCI® frame grabber’s tty driver does not have a specific option to log data passed via write(), there are several generic tools to log ‘tty’ data.[4]

Or, as a last resort, if the application environment doesn’t easily support COM or tty ports, but does support executing a system command line, the Linux echo command can be invoked, such as:

    echo -n -e \x4F\x12\x50 > /dev/ttyS0

(replacing port ‘/dev/ttyS0’ as appropriate) to send a three byte command expressed as hexadecimal byte values. Or under Windows, a utility program, available from EPIX(R) Technical Support, can be invoked, such as:

    catarg -h 4F 12 50 > COM1

(replacing port ‘COM1’ as appropriate) to send a three byte command expressed as hexadecimal byte values. In either case, XCLIB must have been opened with a video setup file which includes Raptor serial commands; aside from the convenience of setting ‘static’ camera settings, the video setup file sets the appropriate baud rate for the COM or tty port.

Updated: 27 March 2023

Footnotes __________

1. On some Linux distributions, a (non-super) user will need permission
to access (any) tty port. Check modes of /dev/ttyS*; see chmod and/or
adduser commands; or consult IT manager.

2. By virtue of C/C++ implementing a string as a 1−D byte array and the
above functions having been designed to use C/C++ conventions. We can
ignore the C/C++ convention that a byte of 00 (base 16) is appended to
a string as a termination marker; the above functions accept and re-
quire a byte count — they neither require the marker nor terminate
processing for a data byte of 00 (base 16).

3. For pxd_serialWrite(), see ‘XCLIBLOG’ in the XCLIB Reference Manual.
For others, see XCAP’s Driver Assistant options as the driver is in-
stalled.

4. Search Linux forums for suggestions and solutions for ‘tty data spy-
ing’ or for ‘serial sniffer’.