Return Values

Return Value	Description
0	The acquisition has been started successfully.
<0	Gbe error code

2.6.2 Gbe_stopAcquisition

Syntax

Return Values

Return Value	Description
0	The acquisition has been stopped successfully.
<0	Gbe error code

2.7 Event System

2.7.1 Event Notification

The SiliconSoftware frame grabber SDK extension for GigE Vision allows an application to react asynchronously on certain events created by the GigE Vision subsystem. These events are either

- created by GigE Vision cameras according to the GigE Vision protocol specification or

- created by the Basler Runtime components itself.

Therefore a mechanism of callback functions is implemented. This mechanism works in addition to the callback / event mechanism defined at the general SiliconSoftware frame grabber SDK (“fglib”, for details see the frame grabber SDK manual).

Event notification is available at 2 different levels:

- board events (camera events, related to the frame grabber),

- camera events (events related to an attached camera).

The following table shows the available event notifications:

Event Type	Level	Remarks
GBE_EVENT_GEVEVENT	Camera	An event triggered by the camera and sent by using the GigE Vision protocol.
GBE_EVENT_CAMERA_CONECTION_LOST	Camera	An already attached camera disappeared
GBE_EVENT_DISCOVERY_CHANGE	Board	A camera has been detected by the discovery process, e.g. a camera is connected to a frame grabber port

Depending of the type of the event, additional data is delivered, when the notification is done, e.g.

- the camera port, when a camera has been detected
- the camera handle, when a camera got lost
- payload data from camera, in case of GigE Vision events.

Therefore event subsystem of the GBE library consists of 2 functions

- Gbe_registerBoardEventCallback
- Gbe_registerCameraEventCallback,

including the corresponding declarations of callback functions types.

The callback handlers will be informed about the type of event and additional event data if available by declaring a data structure GbeEventInfo_Struct. The user’s context out of the registration of callback handlers might be passed by additional user data pointer, which can be passed when calling the according Gbe_registerXXXXEventCallback functions.

Example:

// callback handler for camera events

int CameraEventHandler)(struct BoardHandle *boardHandle,

const GbeEventInfo *const eventInfo,

const void *userData)

{

(myClass*) userData ->data; // Access some data….

}

// method to register the event handler

// passes a pointer to the object towards the SDK, which can

// be accessed at the callback function

Void myClass::DoRegisterCallback()

{

// Pass the context to the callback handler (this-pointer)

Gbe_registerCameraEventCallback(&CameraEventHandler, this);

}

Remarks:

Details of the usage can be seen at a specific SDK example for GbE.

2.7.2 GigE Vision Camera Events

This chapter describes the usage and retrieval of events, sent by a GigE Vision camera according to the GigE Vision standard specification. For additional details see also the GigE Vision standard.

Which events of this type are available within the SDK correlates directly with the functionality of a specific, connected GigE Vision camera. In general, the GigE Vision events can be read by using the camera’s GenICam files, for example by using the SiliconSoftware GenICam Explorer tool. Activation and deactivation of the events can be done by accessing the according GenICam parameters of the cameras. Therefore the parameter interface of the SiliconSoftware GigE SDK can be used:

- Gbe_setEnumerationValue()

- Gbe_setIntegerValue()

- …

When an event occurs, the callback handler gets informed about details of the GigE Vision event by the GbeEventInfo structure indicated by type == GBE_EVENT_GEVEVENT. Additional data retrieved from the GigE Vision protocol is stored in form of the GigE Vision event structure. For further details please refer to the camera manufacturer’s documentation.

2.7.3 Events generated by the SiliconSoftware Runtime

These events are indicated by different event types, which are passed by the GebEventInfo structure.

GebEventInfo.type : GBE_EVENT_XXX, where XXX <> GEVEVENT

For further details, see the SDK function list documentation.

2.8 Sending Action Commands via Firmware

In addition to sending action commands per software, you can also send action commands via the firmware of your Basler frame grabber(s) to the connected GigE Vision cameras.

For each camera channel, one dedicated action command is available in the firmware. The content (function) of each action command is defined by software.

The sending of an action command to the camera is triggered by the applet: In specific situations defined by the applet design, the applet sends an action command trigger signal to the firmware. On detecting a rising edge of this trigger signal, the firmware sends the preconfigured action command to the GigE Vision camera.

The firmware sends the action command to the camera with a fix latency of 2000 ns +/- 16 ns. This means, the time gap between the detection of the rising edge of the action command trigger signal by the firmware and the actual sending of the action command by the firmware is always 2000 ns +/- 16 ns.

The index number of the action command is the same as the index number of the connected camera port. There is a 1:1 connection between the action command trigger in VisualApplets and the corresponding GigE Vision camera.

microEnable 4 GigE Vision frame Grabber using Action Commands

Requirements

To be able to use this feature, the following firmware and software must be used:

• Basler Runtime Software version 5.4.3 or higher
• GigE Vision Applets Set 2.4 or higher
• Firmware for microEnable IV AQ4-GE / -GPoE: version 1.36 (hex) or higher
• Firmware for microEnable IV VQ4-GE / -GPoE: version 1.8a (hex) or higher

Workflow

To use action commands with acquisition applets delivered by Basler, you need to proceed the following steps: 

1. Configure the firmware for using action commands (via SDK).
2. Configure the camera for using action commands (via SDK).
3. Configure the applet to the required values.

The following sections describe how to proceed these steps in detail. An SDK Example for implementing Action Commands is available in our documentation.

Configuring the Firmware

You configure the firmware for sending action commands via SDK. See the SDK Example, lines 165 - 193.

For each camera, exactly 1 dedicated action command is implemented in the firmware.

To configure the firmware for using action commands:

1. Disable the sending of action commands by firmware:
   
   
2. For each channel, set values for Device Key, Group Key and Group Mask according to the settings of the connected camera, for example:
   
   

Use Same Values as in Camera Configuration: Make sure you set the same values here as are set in the corresponding camera configuration. Otherwise, action commands will not be acknowledged by the camera.

Since we use a 1:1 connection between firmware and camera, the actual values are of no importance. Therefore, all cameras can use the same device key as they are not connected via a network.

1. Optional: Define a time out threshold (tolerated time gap between the moment the firmware is sending an action command and the moment it is receiving an acknowledge from the camera):
   
   
   The default timeout is 250.000.000 ticks [1 tick = 16 ns]. This is 4 seconds.
   If you don't define the timeout threshold, the default value will be used.


2. Enable the sending of action commands by firmware:
   
   

Configuring the Cameras

You need to configure the cameras for receiving action commands via SDK. See the SDK Example, lines 195 - 218.

For each camera, exactly 1 dedicated action command is implemented in the firmware.

For configuring the cameras, the following new camera properties are available in the SDK:

To configure the cameras for receiving action commands:

1. For each camera, set values for Device Key, Group Key and Group Mask according to the settings made for the connected firmware channels. For example: 
   
   
   


2. Set a value for the ActionSelector. The value depends on the camera. Make sure you enter here the index number of the first action command in the camera.
   
   

Registering a Camera Event Callback

Register a camera event callback that informs you in case the camera doesn't react within the time you defined as time out threshold (see section 1.3). See the SDK Example, lines 220 - 223.

A new camera event is available in the SDK for this purpose:

To register the camera event callback: 

1. Enter the following lines into your code:
   
   

Activating the Trigger State

Finally, you should activate the trigger state. See the SDK Example, lines 250 - 253.

To activate the trigger state:

1. Set parameter FG_TRIGGERSTATE to TS_ACTIVE:
   

 

Implementing the Pending Action Command Counter

The counter for pending action commands counts the number of action commands that have been sent by the applet (image processing FPGA), but for which no acknowledge packet has been sent by the camera.

Each Action Command Trigger that is sent by the applet to the firmware increments register PendingActionCmdCount. Each action command acknowledge packet received from the camera decrements registerPendingActionCmdCount.

The PendingActionCmdCount counter is overflow and underflow protected.

See the SDK Example, lines 284 - 289.

To implement the pending action command counter:

1. Enter, for example, the following lines to your code: 

Configuring the Applet

For information how to configure the applet, refer to the documentation of the applet you are using.

 

2.8 Helper Functions

Functional Description

Gbe_getErrorDescription() Get error description.

2.9.1 Gbe_getErrorDescription

Syntax

const char* Gbe_getErrorDescription(int errcode)

Parameters

Parameter	Type	Description
errcode	int	Gbe error code.

Return Values

Return Value	Description
0	error getting error string.
!=0	error description as string