Action Commands#
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:
- Action device key
- Action group key
- Action group mask
- Broadcast address (optional, default: 255.255.255.255)
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 (C++) code sample in the pylon API Documentation
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.
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.
- 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.
- Open the connection to one of the cameras that you want to control using action commands.
- Set the
ActionDeviceKey
parameter to a 32-bit number of your choice. The key must be unique among all cameras in the network segment. - Configure the following parameters:
- 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 theTriggerSource
parameter toAction1
.
Example 2: If you want to use action commands to reset a counter, set theCounterResetSource
parameter toAction1
. - 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:
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:
- 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.
- Open one of the cameras that you want to control using action commands.
- Set the
ActionDeviceKey
parameter to a 32-bit number of your choice. The key must be unique among all cameras in the network segment. - Configure the first action signal:
- Set the
ActionSelector
parameter to 1. - Configure the following parameters:
- 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 theTriggerSource
parameter toAction1
.
- Set the
- Configure the second action signal:
- Set the
ActionSelector
parameter to 2. - Set the
ActionGroupKey
parameter or theActionGroupMask
parameter or both to a different value than you entered in step 4. - 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 theTimerTriggerSource
parameter toAction2
.
- Set the
- 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.
External Links#
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.