Impact Acquire SDK Java
Use Cases

Callbacks Triggered By GenICam™ Events

Note
This use case applies only to devices operating in GenICam™ interface layout. More details at chapter General and Which Interface Is Supported By Which Device?.

In some cases it is interesting to get notified about the occurrence of a certain event (e.g. a trigger signal or the end of an image being exposed) on the camera side as soon as possible. This can be achieved by using the events specified by the GenICam™ standard in combination with callbacks.

Depending on the firmware version the following events are currently supported:

  • General events:
    • EventExposureEnd
    • EventFrameEnd
  • Digital I/O related events:
    • EventLine4RisingEdge
    • EventLine4FallingEdge
    • EventLine4AnyEdge
    • EventLine5RisingEdge
    • EventLine5FallingEdge
    • EventLine5AnyEdge

The following example will illustrate how the events can be used to get notified about an image which has been exposed by the sensor, so the image has not been read out yet. This means the information about the finished image is available much earlier than the image itself. Depending on the resolution of the used device and the bandwidth of the used interface the saved time might be significant.

Note
This use case assumes that the image acquisition is already working and the used device supports the GenICam™ interface layout (see Preface for details), similar to the ContinuousCapture.java sample.
How it works
  1. The device is opened by calling
    pDev.open();
  1. An instance of the EventControl class is created.
  2. The desired GenICam™ event of the device is enabled.
  3. A callback is created.
  4. The callback is registered to the property which should execute the callback once its value or features change.
  5. As soon as the image acquisition starts, the callback will be invoked.

Any application that wants to get notified when a certain feature in the Impact Acquire property tree did change needs to derive a class from mvIMPACT::acquire::ComponentCallback and override the mvIMPACT::acquire::ComponentCallback::execute() method:

import mvIMPACT.acquire.*;
//-----------------------------------------------------------------------------
class EventCallback extends ComponentCallback
//-----------------------------------------------------------------------------
{
//=============================================================================
//=== Private member variables ================================================
//=============================================================================
private Object pUserData_;
//=============================================================================
//=== Public constructors =====================================================
//=============================================================================
public EventCallback( Object pUserData )
{
super();
pUserData_ = pUserData;
}
//=============================================================================
//=== Public member functions =================================================
//=============================================================================
@Override
public void execute( Component c, SWIGTYPE_p_void pUserData )
{
EventControl ec = (EventControl)getUserData();
if ( c.isProp() )
{
Property p = new Property( c.hObj() );
System.out.println("Component " + c.name() + " has changed. Its current value: " + p.readS() + "us. FrameID is: " + ec.getEventExposureEndFrameID().readS());
}
}
public Object getUserData()
{
return pUserData_;
}
}

In order to be able to do something useful each callback can carry a pointer to arbitrary user data that can be used to get access to any part of the application code within the callback context. This example attaches an instance of the class EventControl to get access to the events properties, when creating the callback handler later.

The event control class needs to be instantiated to get access to switch on the devices GenICam™ events. In this case the "ExposureEndEvent" is enabled and will be sent by the device once the exposure of an image has finished.

EventControl ec = new EventControl( pDev_ );
ec.getEventSelector().writeS( "ExposureEnd" );
ec.getEventNotification().writeS( "On" );

Now the actual callback handler will be created and a property will be registered to it:

EventCallback eventCallback = new EventCallback( "", ec );
// register a callback to eventExposureEndTimestamp
eventCallback.registerComponent( ec.getEventExposureEndTimestamp() );

Once the callback is not needed anymore, it should be unregistered:

// clean up
eventCallback.unregisterComponent( ec.getEventExposureEndTimestamp() );

The code used for this use case can be found at: GenICamCallbackOnEvent.java

GigE Vision™

Unicast Device Discovery

This section in meant to explain that it is also possible to access GigE Vision™ devices residing in a different subnet using the Impact Acquire driver stack.

Attention
Please be aware that typically routers or network traffic that needs to gets routed through different subnets usually does not work as reliable as when only switches and cables are involved so the full bandwidth delivered by one or multiple GigE Vision™ devices might not be achievable but condition monitoring or slow streaming for analysis might be an interesting use case still. If possible routers supporting a higher link speed than the attached cameras should be used in order to ensure a reliable connection.

More details about unicast device discovery can be found in the Impact Acquire GUI manual in the "Detecting Devices Residing In A Different Subnet" chapter belonging to the IPConfigure tool as well as in the GigE Vision™ device manuals under "Use Cases" where the "Discovering Devices In Different Subnets" is of particular interest.

When using the Impact Acquire API it is important to note that everything that will be configured using the API will get stored permanently for every user working on a particular system. This e.g. allows to configure everything up front using IPConfigure if the network setup is static. After this has been done each application using the Impact Acquire driver stack will detect the remote devices just as every other device. In order to clear or change this the API or IPConfigure has to be used again.

The properties needed for this configuration are

  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvUnicastDeviceDiscoveryCommandCount()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvUnicastDeviceDiscoveryCommandSelector()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvUnicastDeviceDiscoveryDestinationIPAddress()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvUnicastDeviceDiscoveryDestinationPort() (for devices not using the GigE Vision™ compliant control port)

Actions and their Balluff extensions

This section is meant to explain the basics of Actions and the details of Balluff extensions to them.

General description for action properties

The GigE Vision™ standard defines a packet type "ACTION_CMD" specifically for the purpose of directly invoking functionalities in cameras as a kind of network-based event. With these packets, any party connected to the network may invoke certain predefined actions in a number of cameras, allowing for quasi-synchronous or scheduled activities. For details on configuring and arming actions, see the corresponding chapter in the GigE Vision™ specification. For configuring actions in the camera, some features are defined by the SFNC (Standard Features Naming Convention) in chapter "Action Control", which may be accessed by the following properties:

  • mvIMPACT.acquire.GenICam.ActionControl.getActionDeviceKey()
  • mvIMPACT.acquire.GenICam.ActionControl.getActionSelector()
  • mvIMPACT.acquire.GenICam.ActionControl.getActionGroupMask()
  • mvIMPACT.acquire.GenICam.ActionControl.getActionGroupKey()
Note
The device asserts the selected action signal only if:
  • the selected ActionDeviceKey is equal to the action device key in the action protocol message,
  • the logical AND-wise operation of the action group mask in the action protocol message against the selected ActionGroupMask is non-zero
  • and the selected ActionGroupKey is equal to the action group key in the action protocol message.

This way, a predefined number of GigE Vision™ devices may be set up to react to a number of action signals by configuring them as TriggerSource, CounterTriggerSource, CounterEventSource, CounterResetSource, or TimerTriggerSource.

The Interface module of the GenICam™ producer, on the other hand, contains standard-compliant functionality to emit action signals. You may set the ActionDeviceKey, ActionGroupKey and ActionGroupMask as a preparation before invoking the mvIMPACT.acquire.GenICam.ActionControl.actionCommand() property itself, and you may set scheduling parameters to issue scheduled actions. The following properties are available:

  • mvIMPACT.acquire.GenICam.InterfaceModule.getActionDeviceKey()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getActionGroupMask()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getActionGroupKey()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getActionScheduledTimeEnable()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getActionScheduledTime()

In addition, you may set the GevActionDestinationIPAddress to unicast an action command to one camera only, or you may broadcast them if you select a broadcast address (like 169.254.255.255). See property:

  • mvIMPACT.acquire.GenICam.InterfaceModule.getGevActionDestinationIPAddress()

If you need an acknowledge for the action that you signal, you may enable property mvActionAcknowledgeEnable. The necessary functionality depends on whether you use unicast (directing the aAction to just one camera), or if you broadcast the action command. In case of a unicast, you'll see the success of the command immediately in the return code of the command. In case of a broadcast, you have to specify the finalization condition for the command; first, you have to specify how many responses you expect (mvActionAcknowledgesExpected), and second, you have to define a maximum wait time (mvActionAcknowledgeTimeout), which is necessary to terminate the command if the requested number of responses has not yet arrived. In case of an error, there is a property for the number of received acknowledges (mvActionAcknowledgesReceived) as well as a property for the number of packets among them that signaled an error status (mvActionAcknowledgesFailed).

The related properties are:

  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvActionAcknowledgeEnable()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvActionAcknowledgesExpected()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvActionAcknowledgeTimeout()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvActionAcknowledgesReceived()
  • mvIMPACT.acquire.GenICam.InterfaceModule.getMvActionAcknowledgeFailed()
Note
Balluff/MATRIX VISION cameras with an older firmware might send the acknowledge packet with a "GEV_STATUS_NOT_IMPLEMENTED" error status, and they may even send it in more cases than you expect. To avoid this, update your camera to a newer firmware.

Use cases for Actions and their acknowledges

Example 1: Suppose you have two cameras available in your application, both located at different spots beside a running lane. Both cameras shall take an image at a predefined time interval, but there is no possibility to synchronize the internal times with PTP, so scheduled Actions cannot be used. A small time difference in the interval is OK, and both cameras are controlled by a different PC, so actions shall be used. The time of exposure is determined at this PC, which will be broadcasting the action commands into the subnet with the two cameras. One camera will be triggered directly by setting the TriggerSource to its Action1 input, while on the other camera, the action signal triggers a 500ms timer, which in turn triggers the FrameStart of an image. Using action acknowledges, you can instantly receive confirmation for the success of the operation before even the first image is taken instead of having to wait for the end of exposure and the transfer of the image. In addition to the usual setup with the Keys and Mask properties and setting the gevActionDestinationIPAddress to the correct broadcast address, set mvActionAcknowledgeEnable to true, set mvActionAcknowledgesExpected to 2 and mvActionAcknowledgeTimeout to a suitable time (the default value is 20 ms). If the ActionCommand succeeds, you have the confirmation that the process has been successfully started and afterwards, mvActionAcknowledgesReceived holds the value of 2. Checking mvActionAcknowledgesFailed for a value of 0 asserts that both Acknowledge packets returned with a SUCCESS status.

Example 2: Suppose you have four cameras available in your application, and you'd like to use exactly two of them for a certain action command whose success you want an acknowledge for. Furthermore, you have a low-light environment resulting in long exposure times, and you need to know at once if the action command has been received, to be able to trigger the other two cameras with a different action command in case of an unsuccessful acknowledge. In addition to the usual setup with the Key and Mask properties and setting the gevActionDestinationIPAddress to a broadcast address, set mvActionAcknowledgeEnable to true, set mvActionAcknowledgesExpected to 2 and mvActionAcknowledgeTimeout to a suitable time (the default value is 20 ms). By setting up the standard action properties, you ensure that only the desired two cameras receive the first action command, and by enabling the acknowledge, you have a near-instant confirmation that the action command has arrived at the cameras and has triggered the desired activities (instead of, e.g. having to wait for the end of exposure and the transfer of the image). You check the result of the ActionCommand to see if the action was successful, and as an additional confirmation, assert that property mvActionAcknowledgesReceived holds the value 2.

Example 3: Suppose you have four cameras in a low-light scene, the action command is sent to all of the cameras, and the minimum condition is that at least three of them acknowledge the action command. All four cameras are now in the same action group, and you set mvActionAcknowledgesExpected to 3. In case that fewer than three cameras acknowledge the action command within the time defined by mvActionAcknowledgeTimeout, the ActionCommand fails. On arrival of the third acknowledge, the command is terminated successfully, and additional acknowledges are irrelevant.