Balluff - BVS CA-GT Technical Documentation
|
GigE Vision specifies so called Action Commands to trigger an action in multiple devices at roughly the same time.
Action commands can be unicasted or broadcasted by applications having either exclusive
, write
or read
(only when the device is configured accordingly) access to the device. They can be used e.g. to
The most typical scenario is when an application wants to trigger a simultaneous action on multiple devices. This case is shown by the figure below. The application fires a broadcast Action command that will reach all the devices on the subnet.
Action commands can also be used by secondary applications. This can even be another device on the same subnet. This is depicted in the following figure.
Upon reception of an Action command, the device will decode the information to identify which internal action signal is requested. An action signal is a device internal signal that can be used as a trigger for functional units inside the device (ex: a frame trigger). It can be routed to all signal sinks of the device.
Each Action command message contains information for the device to validate the requested operation:
device_key
to authorize the action on this device.group_key
to define a group of devices on which actions have to be executed.group_mask
to be used to filter out some of these devices from the group.Action commands can only be asserted if the device has an open primary control channel (so if an application has established write
or exclusive
access to a device) or when unconditional action
mode is enabled.
A device can define several Action commands which can be selected via the ActionSelector
in the device features property tree.
The conditions for an Action command to be asserted by the device are:
device_key
in the Action command sent by the application and the ActionDeviceKey
property of the device must be equal.group_key
in the Action command sent by the application and the ActionGroupKey
property for the corresponding action of the device must be equal.group_mask
in the Action command sent by the application against the ActionGroupMask
for the corresponding action of the device must be non-zero. Therefore, they must have at least one common bit set at the same position in the register.If these four conditions are met for at least one action signal configured on the device, then the device internally asserts the requested action. As these conditions could be met on more than one action, the device could assert more than one action signal in parallel. If one of the four conditions is not met for any supported action signal, then the device ignores the Action command.
This first condition asks for the write
or exclusive
access being established between the application and the device unless the ActionUnconditionalMode
has been enabled. In this mode, the device can assert the requested action even if no application has established write
or exclusive
access as long as the 3 other conditions are met.
Scheduled
Action
Commands
provide a way to trigger actions in a device at a specific time in the future. The typical use case is depicted in the following diagram:
The transmitter of an Action command records the exact time when the source signal is asserted (External signal). This time t0 is incremented by a delta time ΔtL and transmitted in an Action command to the receivers. The delta time ΔtL has to be larger than the longest possible transmission and processing latency of the Action command in the network.
If the packet passes the Action command filters in the receiver, then the action signal is put into a time queue (the depth of this queue is indicated by the ActionQueueSize
property).
When the time of the local clock is greater or equal to the time of an action signal in the queue, the signal is removed from the queue and asserted. Combined with the timestamp precision of IEEE 1588 which can be sub-microseconds, a Scheduled Action command provides a way to allow low-jitter software trigger. If the sender of an Action command is not capable to set a future time into the packet, the Action command has a flag to fall back to legacy mode (bit 0 of the flag field). In this mode the signal is asserted in the moment the packet passes the Action command filters.
The following examples illustrate the behavior of Action commands in various scenarios. The figure below shows four different Action commands sent by an application. The content of the Action command packet is illustrated on the left side of the figure.
The content of the Action command must be examined against the conditions listed above for each supported action signal.
For the first request (ACTION_CMD #1)
Action Command 1 | Device 0 | Device 1 | |||
ACTION_0 | ACTION_1 | ACTION_2 | ACTION_0 | ||
device_key | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 |
group_key | 0x00000024 | 0x00000024 | 0x00000042 | 0x12341244 | 0x00000024 |
group_mask | 0x00000003 | 0x00000001 | 0xFFFFFFFF | 0x00000000 | 0x00000002 |
Device 0 receives the request and looks for the four conditions:
exclusive
or write
access has been established between the application and the device (or unconditional action is enabled)device_key
matchesgroup_key
matchesgroup_mask
is non-zeroAll four conditions are met only for ACTION_0, thus the device immediately asserts the internal signal represented by ACTION_0. The same steps are followed by Device 1. Only the group_mask
is different, but nevertheless the logical bitwise AND operation produces a non-zero value, leading to the assertion of ACTION_0 by Device 1.
For the second request (ACTION_CMD #2)
Action Command 2 | Device 0 | Device 1 | |||
ACTION_0 | ACTION_1 | ACTION_2 | ACTION 0 | ||
device_key | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 |
group_key | 0x00000042 | 0x00000024 | 0x00000042 | 0x12341244 | 0x00000024 |
group_mask | 0x000000F2 | 0x00000001 | 0xFFFFFFFF | 0x00000000 | 0x00000002 |
Looking for the four conditions, Device 0 will assert ACTION_1 while Device 1 will not assert any signal because the group_key
condition is not met. Therefore, Device 1 ignores the request.
For the third request (ACTION_CMD #3)
Action Command 3 | Device 0 | Device 1 | |||
ACTION_0 | ACTION_1 | ACTION_2 | ACTION 0 | ||
device_key | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 | 0x34638452 |
group_key | 0x00000024 | 0x00000024 | 0x00000042 | 0x12341244 | 0x00000024 |
group_mask | 0x00000002 | 0x00000001 | 0xFFFFFFFF | 0x00000000 | 0x00000002 |
In the third example, the group_mask
and group_key
of Device 0 do not match with ACTION_CMD #3 for any of the ACTION_0 to ACTION_2. Therefore, Device 0 ignores the request. Device 1 asserts ACTION_0 since the 4 conditions are met.
The ACTION_CMD is flexible enough to accommodate simultaneous triggering of the same functional action in functionally different devices.
For instance, let's assume the software trigger of Device 0 can only be associated to its ACTION_3 and that the software trigger of Device 1 can only be associated to its ACTION_1. And the Action command supports to trigger the same functional action provided that their respective action group key and masks are set in order to meet the conditions from the previous list.
For the fourth request (ACTION_CMD #4)
Action Command 4 | Device 0 | Device 1 | |
ACTION_3 | ACTION_1 | ||
device_key | 0x34638452 | 0x34638452 | 0x34638452 |
group_key | 0x00000001 | 0x00000001 | 0x00000001 |
group_mask | 0x00000001 | 0xFFFFFFFF | 0xFFFFFFFF |
In this case, Device 0 asserts ACTION_3 and Device 1 asserts ACTION_1 since the conditions are met. As a result of this, the software trigger of both devices can be simultaneously triggered even though they are associated to different action numbers.
The following section uses C# code snippets but the same thing can be done using a variety of other programming languages as well.
To set up an Action command on the device something like this is needed:
private static void setupActionCommandOnDevice(GenICam.ActionControl ac, Int64 deviceKey, Int64 actionNumber, Int64 groupKey, Int64 groupMask) { if ((deviceKey == 0) && (groupKey == 0) && (groupMask == 0)) { Console.WriteLine("Switching off action {0}.", actionNumber); } else { Console.WriteLine("Setting up action {0}. Device key: 0x{1:X8}, group key: 0x{2:X8}, group mask: 0x{3:X8}", actionNumber, deviceKey, groupKey, groupMask); } ac.actionDeviceKey.write(deviceKey); ac.actionSelector.write(actionNumber); ac.actionGroupKey.write(groupKey); ac.actionGroupMask.write(groupMask); }
deviceKey
parameter will only be set up once as there is only one register for it on each device while there can be various Action commands.Now to send Action commands to devices connected to a certain interface it might be necessary to locate the correct instance of the InterfaceModule class first. One way to do this would be like this:
private static List<GenICam.InterfaceModule> getGenTLInterfaceListForDevice(Device pDev) { // first get a list of ALL interfaces in the current system GenICam.SystemModule systemModule = new GenICam.SystemModule(pDev); Dictionary<String, Int64> interfaceIDToIndexMap = new Dictionary<string, long>(); Int64 interfaceCount = systemModule.interfaceSelector.maxValue + 1; for (Int64 i = 0; i < interfaceCount; i++) { systemModule.interfaceSelector.write(i); interfaceIDToIndexMap.Add(systemModule.interfaceID.read(), i); } // now try to get access to the interfaces the device in question is connected to PropertyI64 interfaceID = new PropertyI64(); DeviceComponentLocator locator = new DeviceComponentLocator(pDev.hDev); locator.bindComponent(interfaceID, "InterfaceID"); if (interfaceID.isValid == false) { return null; } ReadOnlyCollection<String> interfacesTheDeviceIsConnectedTo = interfaceID.listOfValidStrings; // create an instance of the GenICam.InterfaceModule class for each interface the device is // connected to List<GenICam.InterfaceModule> interfaces = new List<GenICam.InterfaceModule>(); foreach (String interfaceIDString in interfacesTheDeviceIsConnectedTo) { interfaces.Add(new GenICam.InterfaceModule(pDev, interfaceIDToIndexMap[interfaceIDString])); } return interfaces; }
Once the desired interface has been located it could be configured to send an Action command like this:
private static void setupActionCommandOnInterface(GenICam.InterfaceModule im, Int32 destinationIP, Int64 deviceKey, Int64 groupKey, Int64 groupMask, bool boScheduledAction) { im.mvActionDestinationIPAddress.write(destinationIP); im.mvActionDeviceKey.write(deviceKey); im.mvActionGroupKey.write(groupKey); im.mvActionGroupMask.write(groupMask); im.mvActionScheduledTimeEnable.write(boScheduledAction ? TBoolean.bTrue : TBoolean.bFalse); // here the desired execution time must also be configured for Scheduled Action commands // if desired by writing to the im.mvActionScheduledTime property }
Now the interface is set up completely and sending an Action command works like this:
private static void sendActionCommand(GenICam.InterfaceModule im) { im.mvActionSend.call(); }
Depending on the value of destinationIP
when actually firing the Action command either a broadcast or a unicast message will be generated and send to either one or all devices in the subnet and depending on whether one or more Action commands on the device are set up to assert the command they will react appropriately or will silently ignore the command.