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.
RaptorPIXIC.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;
the
RaptorXCLIB.py
program illustrates use of serial commands
using Python.
Available from EPIX, Inc. Technical Support.
A formatted serial command can be sent to the camera, and the camera's response received, 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.
libclserEPX.so
along with
clSerialWrite()
and
clSerialRead().
Also see
clSetBaudRate()
for setting the correct baud rate.
The optional
libclserEPX.so
can be installed using
the XCAP GUI application, see
PIXCI®, PIXCI® Open/Close, Close, Driver Assistant.
The example
RaptorPIXCI.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
and
RaptorXCLIB.py
programs, 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.
Copyright (C) EPIX, Inc. All Rights Reserved
Updated: 10-Sep-2024