MATRIX VISION - mvBlueCOUGAR-X/-XD Technical Documentation
Using Action Commands

GigE Vision specifies so called Action Commands to trigger an action in multiple devices at roughly the same time.

Note
Due to the nature of Ethernet, this is not as synchronous as a hardware trigger since different network segments can have different latencies. Nevertheless in a switched network, the resulting jitter is acceptable for a broad range of applications and this scheme provides a convenient way to synchronize devices by means of a software command.

Action commands can be unicasted or broadcasted by applications with either exclusive, write or read (only when the device is configured accordingly) access to the device. They can be used e.g. to

  • increment or reset counters
  • reset timers
  • act as trigger sources
  • ...

The most typical scenario is when an application desires to trigger a simultaneous action on multiple devices. This case is showed by the figure below. The application fires a broadcast action command that will reach all the devices on the subnet.

Figure 1: Action command sent as a broadcast to all devices in the subnet


Attention
Due to the nature of Ethernet an action command at a given time can only leave a single network interface thus sending action commands via several different network interfaces to different devices that are e.g. directly connected to a given network interface card in a PC only works sequential and therefore these commands will NOT reach the devices at the same time. This can only be achieved using Scheduled Action Commands. Depending on whether an action command is unicasted or broadcasted the command will either reach a single device on a given subnet or multiple devices.
Note
The following diagrams assume the connecting line between the PC and the devices to be the GVCP(GigE Vision control protocol)s control port socket. Therefore these diagram do no make any assumption about the physical connection between the devices and the PC. However for the examples to work they must all be connected to the same network interface of the PC using a network switch as otherwise as stated above it would not be possible to sent the very same action command using a single network packet to all the devices.

But 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.

Figure 2: Action command sent as a broadcast by one device to all other devices in the subnet


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:

  1. device_key to authorize the action on this device.
  2. group_key to define a group of devices on which actions have to be executed.
  3. 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:

  1. the device has an open primary control channel or unconditional action mode is enabled.
  2. the device_key in the action command sent by the application and the ActionDeviceKey property of the device must be equal.
  3. the group_key in the action command sent by the application and the ActionGroupKey property for the corresponding action of the device must be equal.
  4. the logical AND-wise operation of 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.

When these 4 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. When one of the 4 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. When this bit is set, 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 Command

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:

Figure 3: Principle of scheduled action commands


The transmitter of an action command records the exact time, when the source signal is asserted (External signal). This time t 0 is incremented by a delta time DELTA L and transmitted in an action command to the receivers. The delta time DELTA L 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.

Note
Scheduled action commands are not supported by every device. A device supporting scheduled action commands should also support time stamp synchronization based on IEEE1588. MATRIX VISION GigE Vision devices support IEEE1588 since firmware version 2.37.2285.0.

Examples

The following examples illustrate the behavior of action commands in various scenarios. The figure below shows 4 different action commands sent by an application. The content of the action command packet is illustrated on the left side of the figure.

Figure 4: Action command examples


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 1Device 0Device 1
ACTION 0ACTION 1ACTION 2ACTION 0
device_key0x346384520x346384520x346384520x346384520x34638452
group_key 0x000000240x000000240x000000420x123412440x00000024
group_mask0x000000030x000000010xFFFFFFFF0x000000000x00000002

Device 0 receives the request and looks for the 4 conditions.

  1. exclusive or write access has been established between the application and the device (or unconditional action is enabled)
  2. device_key matches
  3. group_key matches
  4. Logical AND-wise comparison of requested group_mask is non-zero

All 4 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 2Device 0Device 1
ACTION 0ACTION 1ACTION 2ACTION 0
device_key0x346384520x346384520x346384520x346384520x34638452
group_key 0x000000420x000000240x000000420x123412440x00000024
group_mask0x000000F20x000000010xFFFFFFFF0x000000000x00000002

Looking for the 4 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 3Device 0Device 1
ACTION 0ACTION 1ACTION 2ACTION 0
device_key0x346384520x346384520x346384520x346384520x34638452
group_key 0x000000240x000000240x000000420x123412440x00000024
group_mask0x000000020x000000010xFFFFFFFF0x000000000x00000002

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 4Device 0Device 1
ACTION 3ACTION 1
device_key0x346384520x346384520x34638452
group_key 0x000000010x000000010x00000001
group_mask0x000000010xFFFFFFFF0xFFFFFFFF

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.

Writing Code Using Action Commands

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);
}
Note
In a typical scenario the 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.