Software Development Kit (SDK) - CoaXPress Extension


.
Table of Content

About this Document

1

General usage

1.1
Classes and hierachy
1.2
API

2

Initialization

2.1
Create a board handle
2.2
Power-over-CoaXPress

3

Creating camera connections

3.1
Discovery
3.2
Manual link configuration
3.3
Using a frame grabber configuration file
3.4
Assigning links to image processing
3.5
Query information about the camera

4

Camera Access and Control

5

Image Acquisition

6

Releasing resources

7

Error handling

8

Event notification

X

Appendix

X.1
Compiler and Linker Settings
X.2
Dependencies
Runtime 5
May 2015


Supported Frame Grabbers:

CoaXPress:

  • microEnable 5 AQ8-CXP6D (Iron Man)
  • microEnable 5 VQ8-CXP6D (Iron Man)
  • microEnable 5 AQ8-CXP6B (discontinued)
  • microEnable 5 VQ8-CXP6B (discontinued)

Supported Operating Systems:

Windows:

  • Windows Server 2012
  • Windows Server 2010
  • Windows Server 2008
  • Windows XP (32bit/64bit)
  • Windows 8 (32bit/64bit)
  • Windows 7 (32bit/64bit)
  • Windows Vista (32bit/64bit)



About this Document

This document provides specific information on how to operate your microEnable 5 CoaXPress frame grabber with the Software Development Kit.

For basic functions that can be used for all frame grabber families please refer to our global SDK Manual.

The purpose of the CoaxPress Extension mainly refers to the detection and control of cameras supplied having a CoaxPress interface. Therefore Basler provides a specific API, that has to be used in combination with the standard frame grabber library. The control of the camera is primarily based on the GenICam interface, which CoaxPress cameras should provide. Furthermore a direct access to camera registers is available as well.


The following aspects are covered within this document:

  • Activating a power supply over CoaxPress
  • Automatic detection of cameras connected to the frame grabber
  • Manual setup of cameras connected to the frame grabber
  • Parametrizing and controlling of cameras by using the GenICam interface



1 General usage

1.1 Classes and hierachy

The major concept of this library tries to follow the users point of view and represents a hierachical structure, which can be understood easily: A frame grabber (board) - represented by a board handle - supports up to 4 cameras - each represented by an according camera handle. Each camera administrates 1 up to 4 camera links, dependend on the topology of the system (type of connected cameras, link aggregation).

1 board (board handle) : n cameras (camera handle)

1 camera (camera handle) : n links (camera properties)


These objects are created by according functions within the library and have to be used for further access at each level.

1.2 API

The library works in combination with the standard SDK (FgLibX) SDK Manual.

The scheme of using could look like this:

  1. Create a frame grabber handle (FGLib-SDK) by addressing the framegrabber and the applet
  2. Create an board handle (SiSo-Genicam-SDK)
  3. Create the camera handle(s), either by automatic detection or by predefining the used cameras (SiSo-Genicam-SDK) and connect to cameras.
  4. Activate GenICam connection
  5. Parametrize the camera (image dimensions, camera triggering, etc.) (SiSo-Genicam-SDK)
  6. Parametrize the applet according to application needs (FGLib-SDK)
  7. Start Acquisition at the applet (FGLib-SDK)
  8. Start Acquisition at the camera (SiSo-Genicam-SDK)
  9. Grab images (FGLib-SDK)
  10. Release resources (SiSo-Genicam-SDK)
  11. Release resources (FGLib-SDK)



2. Initialization

2.1 Create a board handle

As mentioned above, the library requires an access to the frame grabber. Therefore a board handle obtained by a previous call of Fg_Init( <AppletName>, <BoardIndex>) is required. For further details please refer to the SDK documentation. First step for using the SiSo-genicam library itself is creating a SiSo-Genicam board handle by using the function

Sgc_InitBoard().

This function creates resources for a board object, controlling various cameras. A Fg-Lib board handle has to be given and a SiSo-Genicam board handle will be returned. This board handle will be used for further access to cameras.

Note, that these two board handle have to be distinguished.

2.2 Power-Over-CoaXPress

The microEnable 5 CoaXPress Series frame grabber support "Power-over- CoaxPress" as specified in the CoaXPress standards A specific function is available with which the power supply at the frame grabber's CXP connectors can be activated. The functions is named

Sgc_PowerSwitch()

This function switches the power off for a certain period of time and reactivates the power supply again.

Important note:

Due to varying bootup times for different camera types, the caller of this function needs to wait until the camera has boot up. The period of time, until the camera is ready to communicate over CoaxPress, needs to be figured out from camera documentation. Please refer to the camera manufacturer to get according information. The Sgc_PowerSwitch() function does not handle this aspect at all.


3. Creating camera connections

Before a camera can be controlled, a connection to the according camera needs to be established. The SiSo-Genicam SDK offers different ways to get access to a CoaXPress camera. During this phase, also the system topology (the fact how many cameras,how many links at each camera, which link is connected to which frame grabber port) and the link speed (CXP-1 up to CXP-6) needs to be known:

a) Automatic detection (camera discovery according to the CoaxPress specification)

b) Predefine the camera connection (either manually or by using stored connection)

c) Load previously saved camera configurations

After one of these steps has been done, camera and link information can be queried. A set of functions refer to this aspect as listed below:


Sgc_scanPorts() : Automatic camera detection (discovery)

Sgc_getCamera() : Create or retrieve a camera handle

Sgc_getCameraPropertyWithType() : Retrieve camera information

Sgc_setCameraPropertyWithType() : Set camera and link configuration

Sgc_CxpConnect() : Establish a camera connection based on camera configuration

Sgc_getCameraCount() : Retrieve the number of present cameras

Sgc_getCameraByIndex() : Retrieve an existing camera handle


3.1 Discovery

The camera detection is based on the defintion of the CoaXPress standard and tries to detect the connected cameras, connected camera links and the optimal operational bit rate. Therefore all frame grabber camera ports are scanned and the detected link at a certain port will be scanned for optimal speed. As a result, camera handles are created automatically inside the library and can be retrieved for further access (Sgc_getCameraCount(), Sgc_getCameraByIndex(),Sgc_getCameraPropertyWithType()).

Camera connection data might be saved to an configuration file for later reconnects. The function that performs the discovery is named:

Sgc_scanPorts()

To use the detected, optimal parameters for camera connection, you need to call Sgc_CxpConnect() in a next step.

Please note that cameras might run in a certain default configuration mode, having a reduced speed and number of camera links (please refer to the respective camera documentation). In such cases an additional manual setting can be done by using the functions for manual configuration.

Example in pseudo-code:

// Discovery

Sgc_scanPorts();


// Display camera information

CameraCount = Sgc_getCameraCount();

for (i = 0 to CameraCount-1)

CameraHandle = Sgc_getCameraByIndex(i);

ShowCameraInfo(CameraHandle);

The procedure of discovery assigns the camera links to the image processing according to a fixed scheme. For more details please refer to section 3.4 "Assigning links for image processing".


3.2 Manual link configuration

As an alternative, the SiSo-Genicam SDK offers possibilities for manual link configuration.

Camera and link properties can be given from the application in order to establish a connection based on such a configuration. This could be an option to increase the speed for system boot up time, since the process of link and speed detection is skipped and a connection is done immediately.

On the other side, this way might cause errors, if a link configuration does not match the phyical connection.

Functions needed for manual link configuration are:

Sgc_getCamera()

Sgc_setCameraPropertyWithType()

Sgc_CxpConnect()


Example in pseudo-code:

// create a handle for the grabber port A

CameraHandle1 = Sgc_getCamera(FragemGrabberPort_A);

Sgc_setCameraProperty(CameraHandle1, "Linkspeed", SPEED_1250);

Sgc_setCameraProperty(CameraHandle1, "MasterId", 1001);

// create a handle for the grabber port B

CameraHandle2 = Sgc_getCamera(FragemGrabberPort_B);

Sgc_setCameraProperty(CameraHandle1, "Linkspeed", SPEED_1250);

Sgc_setCameraProperty(CameraHandle1, "MasterId", 1002);


// try to connect based on the configuration

Sgc_CxpConnect();

// Display camera information

CameraCount = Sgc_getCameraCount();

for (i = 0 to CameraCount-1)

CameraHandle = Sgc_getCameraByIndex(i);

ShowCameraInfo(CameraHandle);


In addition the camera links need to be connected to certain applet ports for performing the image processing. For more details please refer to section "3.4 Assigning links for image processing"

3.3 Using a frame grabber configuration file

Connections can be created by using predefined configuration files. Such files contain information about connected cameras, enabled camera links per camera, speed rate of the CoaXPress link (CXP-1, CXP-2, CXP-3, CXP-5 or CXP-6) and connected frame grabber link ports and other additional information. The file format is based an XML and can be easily read and written by an application.

Sgc_LoadLinkConfiguration()

Sgc_SaveLinkConfiguration()

This functions can act as a bridge between discovery and a manual configuration in that way, that after a successfull and satifying discovery data is saved and connections are furtherly created based on frame grabber configuration files

Example in pseudo-code:


// Connection based on frame grabber configuration file,

// in case of an error do a rescan and save a new configuration file

bool error = Sgc_LoadLinkConfiguration();

if (error)

// Rescan and save new configuration

Sgc_scanPorts();

Sgc_SaveLinkConfiguration();


// Further camera interaction

// Display camera information

CameraCount = Sgc_getCameraCount();

for (i = 0 to CameraCount-1)

CameraHandle = Sgc_getCameraByIndex(i);

ShowCameraInfo(CameraHandle);


3.4 Assigning links to image processing

The CoaXPress standard covers definitions for link aggregation (LAG). In order to support the feature of link aggregation, it is necessary to define the relationship between the used links of the frame grabber camera interface and the interface to the image processing chain of a certain the applet. In case of automatic detection (discovery), this job is done automatically according to some rules. The application does not need to take care of this.

The discovery procedure assigns the links to the applet following a well defined ordering scheme:

1. camera having the most number of links

2. within one camera according to the DeviceLinkId defined at the bootstrap registers for each camera link.

When doing a manual configuration, this assignment has to be done by calls to the Sgc_SetCameraProperty() function by using the property CAM_PROP_APPLETPORT_S for the applet port and CAM_PROP_FGPORT_S for the frame grabber port. It is strongly recommended to comply with the schema for discovery.

Example: using a camera having a LAG x2 interface:

Precondition:

- 2 camera links are connected to the frame grabber

- The master link is connected to the frame grabber port A (CXP1)

- 1st. extension link is connected to frame grabber port B (CXP2)

Remarks: Frame grabber port A (CXP1) is that one, which is next to the PCI-slot (see Hardware description for further details).

Applet is processing in LAG mode using 4 links:

Property definition for this topology:

// set Port A (CXP1) as Master

int link2Define = 0; // define 1st link

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_MASTERLINK_S, &link2Define, SGC_PROPERTY_TYPE_UINT, NULL);

int frameGrabberPort = 0; // Port A, CXP1

int appletPort = 0; // 1st applet port

// Assign 1st frame grabber port to 1st Applet port

link2Define = 0; // define 1st link

frameGrabberPort = 0; // Port A, CXP1

appletPort = 0; // 1st applet port

// set first link to frame grabber port A, CXP1

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_FGPORT_S, &frameGrabberPort, SGC_PROPERTY_TYPE_UINT, &link2Define);

// assign this link to 1st applet applet port(= 0)

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_APPLETPORT_S, &appletPort, SGC_PROPERTY_TYPE_UINT, &link2Define);

// Assign 2nd frame grabber port to 2nd Applet port

link2Define = 1; // define 1st link

frameGrabberPort = 1; // Port B, CXP2

appletPort = 1; // 2nd Applet port

// set second link to frame grabber port

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_FGPORT_S, &frameGrabberPort, SGC_PROPERTY_TYPE_UINT, &link2Define);

// assign this link to 1st applet applet port(= 0)

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_APPLETPORT_S, &appletPort, SGC_PROPERTY_TYPE_UINT, &link2Define);

<EndOfExample>


3.5 Query information about the camera

IRetrieving information about the camera, independendly whether the camera connection is done automatically or manually can be done by using the following functions:

Sgc_getCameraCount() : retrieve the number of present cameras

Sgc_getCameraByIndex() : retrieve an existing camera handle

Sgc_getCameraPropertyWithType() : retrieve a certain information from a camera handle or link

Example:

// Display camera information

CameraCount = Sgc_getCameraCount();

for (i = 0 to CameraCount-1)

CameraHandle = Sgc_getCameraByIndex(i);

int result = 0;

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_XXX_S, &result);

Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_YYY_S, &result);

The available camera properties are defined at the CAM_PROP_XXX constants at the file SISO_GENICAM.H.


4 Camera Access and Control

This chapter describes the concepts of camera control and camera parametrization by using the SISO_GENICAM library. Be aware, that this control goes hand in hand with the basic parametrization of the image processing functions of the applets. For details please refer to the Basler frame grabber SDK manual. In the following the focus is set to the SISO_GENICAM library only.

Basically the camera access is done by reading or writing camera registers, which have to be known and can be obtained from the camera manufacturer.

The camera parametization and camera control is possible by using two different concepts:

a) access by using the GenICam interface defintion

b) access by reading or writing the camera registers directly

Both ways do not exclude each other and might be used in combination. Using the GenICam interface is more convenient and should be preferred. SISO_GENICAM library offers here basic support. It provides methods for reading and writing control data to the camera in different data types (integers, enumerations, strings, etc.), which are defined within the GenICam standard.

Function overview:

Sgc_setIntegerValue() : write an integer value for a certain camera feature

Sgc_getIntegerValue() : read an integer value for a certain camera feature

Sgc_setEnumerationValue() : write an enumeration value for a certain camera feature

Sgc_getEnumerationValue() : read an enumeration value for a certain camera feature

Sgc_setStringValue() : write an enumeration value for a certain camera feature

Sgc_getStringValue() : read an enumeration value for a certain camera feature

Sgc_setBooleanValue() : write a boolean value for a certain camera feature

Sgc_getBooleanValue() : read a boolean value for a certain camera feature

Sgc_setFloatValue() : write a floating point value for a certain camera feature

Sgc_getFloatValue() : read a floating point for a certain camera feature

Sgc_executeCommand() : Executes a command defined by camera's GenICam

For details please refer to the SISO_GENICAM function reference documentation


Before any access can be performed, a connection to the camera based on a valid camera GenICam XML has to be established in addition to the underlying CoaXPress connection (as described above). It is possible, either

- to use a GenICam stored at the camera, or

- to use a GenICam file present at the hard disk.

Relevant functions are:

Sgc_connectCamera() : reads the GenICam information from the camera

Sgc_connectCameraWithExternalXml() : reads the GenICam information from the hard disk

Sgc_getGenICamXML() : allows to get a copy of the currently used GenICam XML

Sgc_setGenICamXML() : allows to set the currently GenICam XML

Please note, that currently not all cameras supply a GenICam XML inside the camera. So occasionally for a communication based on GenICam an external XML is mandatorily required.

Alternatively to GenICam communication, direct camera register access is possible.

Function overview:

Sgc_DirectRegisterRead() : read a camera register value from a camera connected to a certain grabber port

Sgc_DirectRegisterWrite() : write a camera register value to a camera connected to a certain grabber port

The adresses and valid values for each register is camera specific and needs to be known.


5. Image Acquisition

To start and stop the camera's image acquisition, the following functions are provided:

Sgc_startAcquisition() : starting the acquisition based on the GenICAm command ""

Sgc_stopAcquisition() : stoppping the acquisition based on the GenICAm command ""

Again this functions are used in combination with functions of the standard frame grabber SDK. In this case it is related to the following functions

Fg_StartAcquire()

Fg_StopAcquire()

which start and stop the image processing and the data transfer.

The recommended sequence is

1. Start Acquisition (Fg_StartAcquire())

This starts the processing at the applet and data transfer to PC memory

2. Start Acquisition at the camera (Sgc_startAcquisition())

This starts the image acquisition at the camera and the transfer of images from the camera to the frame grabber.

3. grab images ....

4. Stop Acquisition at the camera (Sgc_stopAcquisition())

This stops the image acquisition at the camera and the transfer of frames from the camera to the frame grabber.

5. Stop Acquisition (Fg_StopAcquire())

This stops image processing at the frame grabber and data transfer to the PC memory

This sequences ensures, that no images are lost or corrupted (within the limitations of a certain applet, which is in use). To make sure, that a timeout occurs between step 1) and 2) doesn't occur, enlarge the timeout accordingly by using the FG_TIMEOUT parameter of the applet. This is especially of interest, when an external triggering of the camera is used.



6. Releasing resources

All resources created should be released by calling

Sgc_freeBoard().

This function releases all resources, which are currently administered from a board handle.


7. Error handling

In general, the functions return the state of success to the caller by giving an according return value (integer value). A return value of 0 indicates success. If the return value is < 0 , an error occurred. The return value in this case represents an error code. This value can be translated to a text message by using

Sgc_getErrorDescription()

which returns a NULL-terminated string.

8. Event notification

To allow event notification from frame grabber to an application, it is possible to register a callback handler for event notifications. The function therefor is named

Sgc_registerEventCallback()

Currently no events are defined.


x Appendix

x.1 Compiler and linker settings:


An application, that wants to use the Silicon-Software genicam library has to be linked against the SISO_GENICAM.LIB at the directory <SISO-INSTALL-DIR>\lib.

Function prototypes, structures and definitions can be found in the header file SISO_GENICAM.h (directory: <SISO-INSTALL-DIR>\include).

The implementation can be found in the file SISO_GENICAM.DLL (directory : <SISO-INSTALL-DIR>\bin).


x.2 Dependencies:


Using this library requires the GenAPI-library (Genicam standard). Generally, this package will be installed by the Silicon-Software Runtime installation. It might be updated, if necessary. Please refer to the GenICam web site for further details.




Back Forward