FLIR Spinnaker areaDetector driver

Table of Contents

• Introduction
• Camera firmware
• Video modes
• Format7 modes
• Pixel formats
• Frame rates
• Properties
• Standard driver parameters
• Point Grey specific driver parameters
• Configuration
• MEDM screens

Introduction

This is an EPICS areaDetector driver for cameras from FLIR (formerly Point Grey). It uses their new Spinnaker SDK, while the ADPointGrey driver uses their older FlyCap2 SDK. It should work with most GigE, 10GigE, and USB 3.0 cameras. It has been tested on GigE (BlackFlyS), and USB 3.0 (Grasshopper3) cameras.

The driver should work on both Windows and Linux. However, so far it has only been tested on Windows. The problem is that the Spinnaker SDK is only supported on Ubuntu 16. There are 2 contraints that prevent it from running on older Linux versions, and on other distributions. The libSpinnaker.so file from their Spinnaker SDK was built with gcc 5.4 and requires GLIBC 2.14 and GLIBCXX 3.4.21. This means it cannot be used with gcc 4.8 on RHEL 7, for example. Furthermore the Spinnaker libraries depend on these shareable libraries: libswscale-ffmpeg.so.3, libavcodec-ffmpeg.so.56, libavutil-ffmpeg.so.54, and libavformat-ffmpeg.so.56. These libraries come from an ffmpeg package that appears to only be available for Ubuntu, and not for Red Hat/Centos distributions. Building ffmpeg from source does not even work because the .so library names and the symbols inside those libraries do not match the ones that the Spinnaker SDK was built with. This is unfortunate, and I have asked FLIR to consider distributing a version of the SDK that will build on RHEL 7.

This driver inherits from ADDriver. It implements many of the parameters in asynNDArrayDriver.h and in ADArrayDriver.h. It also implements a number of parameters that are specific to the Spinnaker cameras. The spinnaker class documentation describes this class in detail.

Camera firmware

FLIR frequently updates the available firmware for each camera to add features and fix bugs. However, they are not very good about putting the link to the latest firmware on their Web site. At present one must e-mail the support team (mv-support@flir.com) and ask them if newer firmware is available for a particular camera, and if so to provide access to it. They normally do this by sending a link to a Dropbox folder.

Properties

The Spinnaker SDK supports cameras that use the GenICam interface. This includes GigE Vision and USB3 Vision cameras. GenICam cameras have an XML file in the camera that describes the complete list of properties that the camera supports. These properties can be accessed in a generic manner. This means that libraries that support GenICam are quite simple to use, since all properties are accessed in a generic way. It supports introspection, so that software can determine which properties are supported, and what the allowed ranges and choices for a specific property are. The ADSpinnaker driver is only 60% of the size of the old ADPointGrey driver because of the simplicity of the SDK. The choices for menu-type properties are built at run-time from the values supported by the camera. For some properties these choices can change dynamically when some other property is changed. EPICS Channel Access does not support callbacks when enum choices change. This means that GUI clients cannot update the choices on an open screen when the driver changes them. For this reason enum records that can change their choices at run-time are displayed on a related display (ADSpinnakerMore) that must be closed and re-opened to see the new choices. The valid range of numeric properties can similarly change dynamically at run-time based on changes in other properties. These changes will be immediately reflected the DRVL, DRVH, LOPR, and HOPR fields of the records. However, EPICS Channel Access does not support callbacks when graphics display limits change, so EPICS GUI clients do not update slider widget limits when HOPR and LOPR change. For this reason numeric records that can change their choices at run-time are also displayed on ADSpinnakerMore that must be closed and re-opened to have the slider limits update.

Standard areaDetector parameters

The following table describes how the Point Grey driver implements some of the standard driver parameters.

Point Grey specific driver parameters

The Point Grey driver implements the following parameters in addition to those in asynNDArrayDriver.h and ADDriver.h. The database file is spinnaker.template for all records except the property records, which are in spinnakerProperty.template.

Configuration

The ADSpinnaker driver is created with the spinnakerConfig command, either from C/C++ or from the EPICS IOC shell.

spinnakerConfig(const char *portName, const char* cameraId, int traceMask, int memoryChannel,
              int maxBuffers, size_t maxMemory, 
              int priority, int stackSize)
  

The cameraId parameter can either be an index of the camera in the list of available cameras (e.g. 0 if there is only a single Point Grey camera available) or the serial number of the camera to use. For additional details on the meaning of the parameters to this function refer to the detailed documentation on the spinnakerConfig function in the spinnaker.cpp documentation and in the documentation for the constructor for the spinnaker class.

The traceMask can be set to a value > 1 to enable asynTrace debugging during initialization, before the value can be set from the IOC shell or via the asynRecord. Set this to 0x21 to enable ASYN_TRACE_WARNING, which will trace all calls to the Point Grey FlyCap2 library.

The memoryChannel can be set to a value > 0 to load the initial camera parameters from non-volatile memory in the camera. Setting memoryChannel to N loads from memoryChannel N-1, i.e. 1 loads memory channel 0. There is currently a problem with Linux and for BlackFly GigE cameras. If the IOC is run a second time after it has been used to acquire any images the driver loses communication with the camera. The problem appears to be that there is a corrupt setting in the camera, which causes it to malfunction the next time the program is run. Setting memoryChannel 1 will work around this problem by replacing the settings in the camera with a default set. Since the EPICS IOC sets nearly all the camera settings to save/restore values at startup anyway, this is not a serious limitation.

There an example IOC boot directory and startup script (iocBoot/iocSpinnaker/st.cmd) provided with areaDetector.

MEDM screens

The following show the MEDM screens that are used to control the Point Grey cameras.

spinnaker.adl is the main screen used to control Point Grey cameras.

spinnaker.adl

spinnakerProperties.adl is the screen used to control the properties of Point Grey cameras. Note that some of these properties, such as Shutter, FrameRate, and Gain can also be controlled by standard areaDetector records, like AcquireTime, AcquirePeriod, and Gain. The widgets on the medm screen are hidden if the corresponding feature is not available.

spinnakerProperties.adl for a BlackFly GigE color camera in RGB mode

spinnakerProperties.adl for a Grasshopper3 monochrome camera

spinnakerFrameRate.adl is the screen used to control the frame rate in standard video modes. This is a separate screen because the valid enum strings for the Framerate record can change when the standard video mode is changed. When that is changed it is necessary to close this screen and re-open it in order for the new menus to be displayed. This is a limitation of the EPICS Channel Access which does not send monitor events for changes in enum fields. Note that the readback of the FrameRate on the main spinnaker.adl screen can also be incorrect, so it may be necessary to close and re-open that main screen as well.

spinnakerFrameRate.adl

spinnakerPixelFormat.adl is the screen used to control the pixel format in Format7 mode. This is a separate screen because the valid enum strings for the PixelFormat can change when the Format7 mode is changed. When that is changed it is necessary to close this screen and re-open it in order for the new menus to be displayed. This is a limitation of the EPICS Channel Access which does not send monitor events for changes in enum fields. Note that the readback of the PixelFormat on the main spinnaker.adl screen can also be incorrect, so it may be necessary to close and re-open that main screen as well.

spinnakerPixelFormat.adl