Action Commands#

The Action Commands camera feature allows you to execute actions on multiple cameras at roughly the same time by using a single broadcast protocol message.

If you want to execute actions on multiple cameras at exactly the same time, use the Scheduled Action Commands feature instead.

If you want to send or schedule action commands using the pylon Viewer, use the Action Commands (pylon Viewer) feature.

Using the Feature#

Why Use Action Commands#

You can use action commands to perform, e.g., the following tasks:

  • Synchronously acquire images with multiple cameras
  • Synchronously reset the frame counter on multiple cameras

How It Works#

Action commands are broadcast protocol messages that you can send to multiple devices in a GigE network.

Each action protocol message contains the following information:

If the camera is within the specified network segment and if the protocol information matches the action command configuration in the camera, the camera executes the corresponding action.

Info

For more information about the action command parameters and their implementation, refer to the following documents:

  • GigE Vision Specification, version 2.0, Section 14.3
  • "Grab_UsingActionCommand" code sample in the C++ Programmer's Guide and Reference Documentation delivered with the Basler pylon Camera Software Suite

Action Device Key#

A 32-bit number of your choice used to authorize the execution of an action command on the camera. If the action device key on the camera and the action device key in the protocol message are identical, the camera executes the corresponding action.

The device key is write-only; it can't be read out of the camera.

Action Group Key#

A 32-bit number of your choice used to define a group of devices on which an action should be executed. Each camera can be assigned to one group only. If the action group key on the camera and the action group key in the protocol message are identical, the camera will execute the corresponding action.

Action Group Mask#

A 32-bit number of your choice used to filter out a sub-group of cameras belonging to a group of cameras. The cameras belonging to a sub-group execute an action at the same time.

The filtering is done using a logical bitwise AND operation on the group mask number of the action command and the group mask number of a camera. If both binary numbers have at least one common bit set to 1 (i.e., the result of the AND operation is non-zero), the corresponding camera belongs to the sub-group.

Example: Assume that A group of six cameras is installed on an assembly line. To execute actions on specific sub-groups, the following group mask numbers have been assigned to the cameras (sample values):

Camera Group Mask Number (Binary) Group Mask Number (Hexadecimal)
1 000001 0x1
2 000010 0x2
3 000100 0x4
4 001000 0x8
5 010000 0x10
6 100000 0x20

In this example, an action command with an action group mask of 000111 (0x7) executes an action on cameras 1, 2, and 3. And an action command with an action group mask of 101100 (0x2C) executes an action on cameras 3, 4, and 6.

Broadcast Address#

A string variable used to define where the action command will be broadcast to. When using the pylon API, the broadcast address must be in dot notation, e.g., "255.255.255.255" (all adapters), "192.168.1.255" (all devices in a single subnet 192.168.1.xxx), or "192.168.1.38" (a single device).

This parameter is optional. If omitted, "255.255.255.255" will be used.

Example Setup#

The following example setup will give you an idea of the basic concept of action commands.

To analyze the movement of a horse, a group of cameras is installed parallel to a race track.

Action Commands Example Setup

When the horse passes, four cameras (subgroup 1) synchronously execute an action (image acquisition in this example).

As the horse advances, the next four cameras (subgroup 2) synchronously capture images. One after the other, the subgroups continue in this fashion until the horse has reached the end of the race track. The resulting images can be combined and analyzed in a subsequent step.

In this sample use case, the following must be defined:

  • A unique device key to authorize the execution of the synchronous image acquisition. The device key must be configured on each camera and it must be the same as the device key for the action command protocol message. To define the device key, use the action device key.
  • The group of cameras in a network segment that is addressed by the action command (in this example: group 1). to define the groups, use the action group key.
  • The subgroups in the group of cameras that capture images synchronously (in this example: subgroups 1, 2, and 3). to define the subgroups, use the action group mask.

Using Action Commands#

Configuring the Cameras#

To configure the cameras so that they are able to receive and process action commands:

Info

The same procedure applies if you want to configure Scheduled Action Commands on your cameras.

  1. Make sure that the following requirements are met:
    • All cameras on which you want to configure action commands must be installed and configured in the same network segment.
    • The Action Commands feature is supported by all cameras and by the Basler pylon API you are using to configure and send action commands.
  2. Open one of the cameras that you want to control using action commands.
  3. Configure the following action command-specific parameters:
  4. Depending on which task you want to use the Action Commands feature for, set the corresponding camera source to Action1.
    Example 1: If you want to use the Action Command feature to synchronously acquire images, set the TriggerSource parameter to Action1.
    Example 2: If you want to use the Action Command feature to synchronously reset the frame counter, set the CounterResetSource parameter to Action1.
  5. Repeat steps 2 to 4 on all cameras.

Issuing an Action Command#

To issue an action command, call the IssueActionCommand method in your application.

Example:

IssueActionCommand Example

For more information, see the C++ Programmer's Guide and Reference Documentation delivered with the Basler pylon Camera Software Suite.

Additional Parameters#

  • ActionSelector: Specifies the action command to be configured. Because Basler cameras support exactly one action signal, this parameter is preset to 1 and can't be changed. This means that you can't use action commands for multiple tasks (e.g., "trigger image acquisition on command 1, reset the frame counter on command 2").

Sample Code#

// Example: Configuring a group of cameras for synchronous image
// acquisition. It is assumed that the "cameras" object is an
// instance of CBaslerGigEInstantCameraArray.
//--- Start of camera setup ---
for (size_t i = 0; i > cameras.GetSize(); ++i)
{
    // Open the camera connection
    cameras[i].Open();
    // Configure the trigger selector
    cameras[i].TriggerSelector.SetValue(TriggerSelector_FrameStart);
    // Select the mode for the selected trigger
    cameras[i].TriggerMode.SetValue(TriggerMode_On);
    // Configure the source for the selected trigger
    cameras[i].TriggerSource.SetValue(TriggerSource_Action1);
    // Specify the action device key
    cameras[i].ActionDeviceKey.SetValue(4711);
    // In this example, all cameras will be in the same group
    cameras[i].ActionGroupKey.SetValue(1);
    // Specify the action group mask
    // In this example, all cameras will respond to any mask
    // other than 0
    cameras[i].ActionGroupMask.SetValue(0xffffffff);
}
//--- End of camera setup ---
// Send an action command to the cameras
GigeTL->IssueActionCommand(4711, 1, 0xffffffff, "192.168.1.255");

This sample code is only available in C++ language.