Skip to content

Action Commands#

The Action Commands camera feature allows you to execute actions on multiple GigE 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:

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.

Action Group Key#

A 32-bit number of your choice used to define a group of devices on which an action should be executed. If the action group key on the camera and the action group key in the protocol message are identical, the camera executes 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 are 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 the connection to one of the cameras that you want to control using action commands.
  3. Set the ActionDeviceKey parameter to a 32-bit number of your choice. The key must be unique among all cameras in the network segment.
  4. Configure the following parameters:
  5. Depending on which task you want to use action commands for, set the corresponding camera source to Action1.
    Example 1: If you want to use action commands to acquire images, set the TriggerSource parameter to Action1.
    Example 2: If you want to use action commands to reset a counter, set the CounterResetSource parameter to Action1.
  6. Repeat steps 2 to 4 on all cameras.

Info

You can also set multiple sources to Action1. This allows you to execute multiple tasks at once whenever an action command is received.

Issuing an Action Command#

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

Example:

IssueActionCommand Example

For more information, see the pylon API Documentation.

Configuring Action Signals (ace 2 Pro Only)#

Basler ace 2 Pro cameras support two action signals instead of one. This allows you to define two types of commands and use them to execute different actions on the camera.

For example, you can configure the camera to trigger image acquisition with command 1, and start the timer with command 2.

For this purpose, in addition to the Action1 camera sources, Action2 camera sources are available. Also, the ActionSelector parameter can be set to 1 or 2.

To configure the two action signals:

  1. Make sure that the following requirements are met:
    • All cameras on which you want to configure action commands are 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. Set the ActionDeviceKey parameter to a 32-bit number of your choice. The key must be unique among all cameras in the network segment.
  4. Configure the first action signal:
    1. Set the ActionSelector parameter to 1.
    2. Configure the following parameters:
    3. Depending on which task you want to use the first action command for, set the corresponding camera source to Action1.
      Example: If you want to use action commands to acquire images, set the TriggerSource parameter to Action1.
  5. Configure the second action signal:
    1. Set the ActionSelector parameter to 2.
    2. Set the ActionGroupKey parameter or the ActionGroupMask parameter or both to a different value than you entered in step 4.
    3. Depending on which task you want to use the second action command for, set the corresponding camera source to Action2.
      Example: If you want to use action commands to start a timer, set the TimerTriggerSource parameter to Action2.
  6. Repeat steps 2 to 4 on all cameras.
Example#

Your camera is configured as follows:

Device key = 4711

ActionSelector = 1:
 - Group key = 1
 - Group mask = 0xFFFFFFFF

ActionSelector = 2:
 - Group key = 2
 - Group mask = 0xFFFFFFFF

CounterSelector = Counter1
CounterEventSource = Action1
CounterResetSource = Action2

Now, you can call IssueActionCommand(4711, 1, 0xFFFFFFFF) to increase counter 1, and IssueActionCommand(4711, 2, 0xFFFFFFFF) to reset counter 1.

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();
    // Select and enable the Frame Start trigger
    cameras[i].TriggerSelector.SetValue(TriggerSelector_FrameStart);
    cameras[i].TriggerMode.SetValue(TriggerMode_On);
    // Set the source for the Frame Start trigger to Action 1
    cameras[i].TriggerSource.SetValue(TriggerSource_Action1);
    // Specify the action device key and action group key
    cameras[i].ActionDeviceKey.SetValue(4711);
    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 all cameras configured above
GigeTL->IssueActionCommand(4711, 1, 0xffffffff, "192.168.1.255");

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