ActionCommandTrigger Class#

Provides simplified access to GigE action commands. It can be used to automatically or manually configure the DeviceKey, GroupKey, and GroupMask features for cameras. It can also configure the camera's trigger and set the trigger source to action command. In addition, there are some static methods for issuing and scheduling an action command.

Inheritance Hierarchy#

System.Object
Basler.Pylon.ActionCommandTrigger

Syntax#

C#

public class ActionCommandTrigger

VB

Public Class ActionCommandTrigger

The ActionCommandTrigger type exposes the following members.

Constructors#

	Name	Description
	ActionCommandTrigger	Initializes a new instance of the ActionCommandTrigger class

Properties#

	Name	Description
	ActionId	Provides read access to the action ID.
	BroadcastAddress	Provides read access to the broadcast address.
	DeviceKey	Provides read access to the action device key.
	GroupKey	Provides read access to the action group key.
	GroupMask	Provides read access to the action group mask.

Methods#

	Name	Description
	Configure(ICamera[])	Changes the configuration of the cameras so that it is triggered by the first available action command, for instance "Action 1". For more information, see PLGigECamera.ActionSelector. This configuration enables the frame start trigger and disables all other trigger types. The first available action command is selected as the trigger source, i.e., the camera will be triggered by action commands issued by the application.
	Configure(ICamera[], Int32, Int32, Int32, Int32)	This configuration is only for advanced use cases and changes the configuration of the cameras so that the cameras can be triggered by the given action command ID. Compared to Configure(ICamera()), the configuration of the trigger is up to the camera user.
	GetNow	Determines the timestamp value of the given camera.
	Issue()	Issues an action command via broadcast without acknowledgment of success/failure and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).
	Issue(Int32, Int32, Int32, String)	Issues an action command via broadcast without acknowledgment of success/failure.
	Issue(Int32, Int32, Int32, String, Int32, ActionCommandResult[])	Issues an action command via broadcast with acknowledgment.
	Schedule(Int64)	Issues a scheduled action command via broadcast without acknowledgment of success/failure and and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).
	Schedule(Int32, Int32, Int32, Int64, String)	Issues a scheduled action command via broadcast without acknowledgment of success/failure.
	Schedule(Int32, Int32, Int32, Int64, String, Int32, ActionCommandResult[])	Issues a scheduled action command via broadcast with acknowledgment.

ActionCommandTrigger.Configure Method (ICamera[])#

Changes the configuration of the cameras so that it is triggered by the first available action command, for instance "Action 1". For more information, see PLGigECamera.ActionSelector. This configuration enables the frame start trigger and disables all other trigger types. The first available action command is selected as the trigger source, i.e., the camera will be triggered by action commands issued by the application.

Syntax#

C#

public void Configure(
    ICamera[] cameras
)

VB

Public Sub Configure ( 
    cameras As ICamera()
)

Parameters#

cameras: Type: Basler.Pylon.ICamera[]
The array with cameras to be configured.

Remarks#

Preconditions for updating the camera setting:

The array with cameras must not be empty.
All cameras must be open.
All cameras must support action commands.
All cameras must support the FrameStart trigger.
All cameras must be GigE cameras.
The following features must be writeable: ActionDeviceKey, ActionGroupMask, ActionGroupKey, ActionSelector, TriggerSelector, TriggerMode, TriggerSource, and AcquisitionMode.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions if the preconditions are not met. The configuration uses a randomly generated device and group key for each call. The group mask is fixed to 0x7fffffff. In addition, the best matching subnet limited broadcast address will be set and is readable with the BroadcastAddress parameter. If no match is found, the broadcast address 255.255.255.255 will be used.

ActionCommandTrigger.Configure Method (ICamera[], Int32, Int32, Int32, Int32)#

This configuration is only for advanced use cases and changes the configuration of the cameras so that the cameras can be triggered by the given action command ID. Compared to Configure(ICamera()), the configuration of the trigger is up to the camera user.

Syntax#

C#

public void Configure(
    ICamera[] cameras,
    int deviceKey,
    int actionId,
    int groupKey,
    int groupMask
)

VB

Public Sub Configure ( 
    cameras As ICamera(),
    deviceKey As Integer,
    actionId As Integer,
    groupKey As Integer,
    groupMask As Integer
)

Parameters#

cameras: Type: Basler.Pylon.ICamera[]
The array with cameras to be configured.
deviceKey: Type: System.Int32
The device key addresses the cameras managed by an application. The device key is only known to the application controlling the camera devices and ensures that only this application can trigger the camera devices. Therefore, the device key cannot be read from a camera. An exact match of the deviceKey sent and the device key stored in a camera is required for executing an action.
actionId: Type: System.Int32
The ID of the action command to configure.
groupKey: Type: System.Int32
The group key is used to create groups of cameras or actions. An exact match of the groupKey sent and the group key stored in a camera for an action is required for executing an action.
groupMask: Type: System.Int32
The group mask is a bit mask that allows sending an action to a subgroup of the cameras addressed by the deviceKeygroupKey pair. The result of a bitwise AND operation of groupMask and the group mask stored in a camera for an action must be non-zero for executing an action.

Remarks#

Preconditions for updating the camera setting:

All cameras must be GigE cameras.
The array with cameras must not be empty.
All cameras must be open.
All cameras must support action commands.
The actionId parameter must exist for all cameras.
The action ID must be connected to a properly configured trigger.
All cameras must support the FrameStart trigger.
The following features must be writeable: ActionDeviceKey, ActionGroupMask, ActionGroupKey, and ActionSelector.

Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions if the preconditions are not met. In addition, the best matching subnet limited broadcast address will be set and is readable with the BroadcastAddress parameter. If no match is found, the broadcast address 255.255.255.255 will be used.

ActionCommandTrigger.GetNow Method#

Determines the timestamp value of the given camera.

Syntax#

C#

public static long GetNow(
    ICamera camera
)

VB

Public Shared Function GetNow ( 
    camera As ICamera
) As Long

Parameters#

camera: Type: Basler.Pylon.ICamera
The camera object used for the time enquiry.

Return Value#

Type: Int64
Returns the timestamp value of the given camera.

Remarks#

Preconditions for determining the timestamp:

The camera is a GigE camera.
The camera is open.
The camera supports the "GevTimestampValue" feature.

The timestamp is determined by reading the "GevTimestampValue" timestamp value after latching the "GevTimestampControlLatch" timestamp value. Thread Safety: This method is synchronized with the lock of the camera object.

Error Safety: Can throw exceptions if the preconditions are not met.

ActionCommandTrigger.Issue Method#

Issues an action command via broadcast without acknowledgment of success/failure and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).

Syntax#

C#

public void Issue()

VB

Public Sub Issue

Remarks#

Preconditions:

The GigE transport layer must be available.
The Configure(ICamera()) configuration method must have been called and executed successfully.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time.

ActionCommandTrigger.Issue Method (Int32, Int32, Int32, String)#

Issues an action command via broadcast without acknowledgment of success/failure.

Syntax#

C#

public static void Issue(
    int deviceKey,
    int groupKey,
    int groupMask,
    string broadcastAddress
)

VB

Public Shared Sub Issue ( 
    deviceKey As Integer,
    groupKey As Integer,
    groupMask As Integer,
    broadcastAddress As String
)

Parameters#

deviceKey: Type: System.Int32
The device key addresses the cameras managed by an application. The device key is only known to the application controlling the camera devices and ensures that only this application can trigger the camera devices. Therefore, the device key cannot be read from a camera. An exact match of the deviceKey sent and the device key stored in a camera is required for executing an action.
groupKey: Type: System.Int32
The group key is used to create groups of cameras or actions. An exact match of the groupKey sent and the group key stored in a camera for an action is required for executing an action.
groupMask: Type: System.Int32
The group mask is a bit mask that allows sending an action to a subgroup of the cameras addressed by the device and group key. The result of a bitwise AND operation of groupMask and the group mask stored in a camera for an action must be non-zero for executing an action.
broadcastAddress: Type: System.String
The broadcast address in dot notation where the command will be broadcast to, e.g., 255.255.255.255 (all adapters, default), 192.168.1.255 (all cameras in a single subnet 192.168.1.xxx), 192.168.1.38 (single camera). See the note below.

Remarks#

Preconditions for issuing action commands:

The GigE transport layer must be available.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

ActionCommandTrigger.Issue Method (Int32, Int32, Int32, String, Int32, ActionCommandResult[])#

Issues an action command via broadcast with acknowledgment.

Syntax#

C#

public static bool Issue(
    int deviceKey,
    int groupKey,
    int groupMask,
    string broadcastAddress,
    int timeoutMs,
    ActionCommandResult[] results
)

VB

Public Shared Function Issue ( 
    deviceKey As Integer,
    groupKey As Integer,
    groupMask As Integer,
    broadcastAddress As String,
    timeoutMs As Integer,
    results As ActionCommandResult()
) As Boolean

Parameters#

deviceKey: Type: System.Int32
The device key addresses the cameras managed by an application. The device key is only known to the application controlling the camera devices and ensures that only this application can trigger the camera devices. Therefore, the device key cannot be read from a camera. An exact match of the deviceKey sent and the device key stored in a camera is required for executing an action.
groupKey: Type: System.Int32
The group key is used to create groups of cameras or actions. An exact match of the groupKey sent and the group key stored in a camera for an action is required for executing an action.
groupMask: Type: System.Int32
The group mask is a bit mask that allows sending an action to a subgroup of the cameras addressed by the device and group key. The result of a bitwise AND operation of groupMask and the group mask stored in a camera for an action must be non-zero for executing an action.
broadcastAddress: Type: System.String
The broadcast address in dot notation where the command will be broadcast to, e.g., 255.255.255.255 (all adapters, default), 192.168.1.255 (all cameras in a single subnet 192.168.1.xxx), 192.168.1.38 (single camera). See the note below.
timeoutMs: Type: System.Int32
Time in milliseconds that the call is waiting for acknowledges of the cameras addressed. Waiting for acknowledges is stopped if NumResults have been received.
results: Type: Basler.Pylon.ActionCommandResult[]
Returns the ActionCommandResult action command result status. The initialization of the result items can be done by this method, i.e., all zero items will be initialized.

Return Value#

Type: Boolean
Returns true if all results are Ok. Returns true if no results have been requested.

Remarks#

Preconditions for issuing action commands:

The GigE transport layer must be available.
The length of results array given must not be zero.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

ActionCommandTrigger.Schedule Method (Int32, Int32, Int32, Int64, String)#

Issues a scheduled action command via broadcast without acknowledgment of success/failure.

Syntax#

C#

public static void Schedule(
    int deviceKey,
    int groupKey,
    int groupMask,
    long actiontimeNs,
    string broadcastAddress
)

VB

Public Shared Sub Schedule ( 
    deviceKey As Integer,
    groupKey As Integer,
    groupMask As Integer,
    actiontimeNs As Long,
    broadcastAddress As String
)

Parameters#

deviceKey: Type: System.Int32
The device key addresses the cameras managed by an application. The device key is only known to the application controlling the camera devices and ensures that only this application can trigger the camera devices. Therefore, the device key cannot be read from a camera. An exact match of the deviceKey sent and the device key stored in a camera is required for executing an action.
groupKey: Type: System.Int32
The group key is used to create groups of cameras or actions. An exact match of the groupKey sent and the group key stored in a camera for an action is required for executing an action.
groupMask: Type: System.Int32
The group mask is a bit mask that allows sending an action to a subgroup of the cameras addressed by the deviceKeygroupKey pair. The result of a bitwise AND operation of groupMask and the group mask stored in a camera for an action must be non-zero for executing an action.
actiontimeNs: Type: System.Int64
Time in nanoseconds when the action is to be executed. The actual value depends on the master clock used. A master clock value for a set of synchronized camera devices can be obtained, for instance, by reading the (GevTimestampValue) timestamp value after latching the (GevTimestampControlLatch) timestamp value from one camera device of the set or by calling GetNow(ICamera). The actionTimeNs must be smaller than or equal to INT64_MAX.
broadcastAddress: Type: System.String
The broadcast address in dot notation where the command will be broadcast to, e.g., 255.255.255.255 (all adapters, default), 192.168.1.255 (all cameras in a single subnet 192.168.1.xxx), 192.168.1.38 (single camera). See the note below.

Remarks#

Preconditions for scheduling action commands:

The GigE transport layer must be available.
The actionTimeNs must be smaller than or equal to INT64_MAX.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

ActionCommandTrigger.Schedule Method (Int32, Int32, Int32, Int64, String, Int32, ActionCommandResult[])#

Issues a scheduled action command via broadcast with acknowledgment.

Syntax#

C#

public static bool Schedule(
    int deviceKey,
    int groupKey,
    int groupMask,
    long actiontimeNs,
    string broadcastAddress,
    int timeoutMs,
    ActionCommandResult[] results
)

VB

Public Shared Function Schedule ( 
    deviceKey As Integer,
    groupKey As Integer,
    groupMask As Integer,
    actiontimeNs As Long,
    broadcastAddress As String,
    timeoutMs As Integer,
    results As ActionCommandResult()
) As Boolean

Parameters#

deviceKey: Type: System.Int32
The device key addresses the cameras managed by an application. The device key is only known to the application controlling the camera devices and ensures that only this application can trigger the camera devices. Therefore, the device key cannot be read from a camera. An exact match of the deviceKey sent and the device key stored in a camera is required for executing an action.
groupKey: Type: System.Int32
The group key is used to create groups of cameras or actions. An exact match of the groupKey sent and the group key stored in a camera for an action is required for executing an action.
groupMask: Type: System.Int32
The group mask is a bit mask that allows sending an action to a subgroup of the cameras addressed by the deviceKeygroupKey pair. The result of a bitwise AND operation of groupMask and the group mask stored in a camera for an action must be non-zero for executing an action.
actiontimeNs: Type: System.Int64
Time in nanoseconds when the action is to be executed. The actual value depends on the used master clock. A master clock value for a set of synchronized camera devices can be obtained, for instance, by reading the (GevTimestampValue) timestamp value after latching the (GevTimestampControlLatch) timestamp value from one camera device of the set or by calling GetNow(ICamera). The actionTimeNs must be smaller than or equal to INT64_MAX.
broadcastAddress: Type: System.String
The broadcast address in dot notation where the command will be broadcast to, e.g., 255.255.255.255 (all adapters, default), 192.168.1.255 (all cameras in a single subnet 192.168.1.xxx), 192.168.1.38 (single camera). See the note below.
timeoutMs: Type: System.Int32
Time in milliseconds that the call is waiting for acknowledges of the cameras addressed. Waiting for acknowledges is stopped if NumResults have been received.
results: Type: Basler.Pylon.ActionCommandResult[]
Returns the ActionCommandResult action command result status. The initialization of the result items can be done by this method, i.e., all zero items will be initialized.

Return Value#

Type: Boolean
Returns true if all results are Ok. Returns true if no results have been requested.

Remarks#

Preconditions for scheduling action commands:

The GigE transport layer must be available.
The actionTimeNs must be smaller than or equal to INT64_MAX.
The length of results array given must not be zero.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time. Directed broadcasts (192.168.1.255) or unicasts (192.168.1.38) are only sent if the request subnet matches the subnet of the IP address, i.e., if no gateway or routing are required.

ActionCommandTrigger.Schedule Method (Int64)#

Issues a scheduled action command via broadcast without acknowledgment of success/failure and and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).

Syntax#

C#

public void Schedule(
    long actiontimeNs
)

VB

Public Sub Schedule ( 
    actiontimeNs As Long
)

Parameters#

actiontimeNs: Type: System.Int64
Time in nanoseconds when the action is to be executed. The actual value depends on the master clock used. A master clock value for a set of synchronized camera devices can be obtained, for instance, by reading the (GevTimestampValue) timestamp value after latching the (GevTimestampControlLatch) timestamp value of one camera device of the set or by calling GetNow(ICamera).

Remarks#

Preconditions:

The GigE transport layer must be available.
The Configure(ICamera()) configuration method must have been called and executed successfully.
The actionTimeNs must be smaller than or equal to INT64_MAX.

Thread Safety: This method is thread-safe.

Error Safety: Can throw exceptions if the preconditions are not met. The request is sent via all existing network adapters. If a network adapter has more than one IP address, the request is sent separately for each address. This is not executed simultaneously but consecutively, IP address by IP address. That's why additional latency is added to the execution time.

ActionCommandTrigger Constructor#

Initializes a new instance of the ActionCommandTrigger class

Syntax#

C#

public ActionCommandTrigger()

VB

Public Sub New

ActionCommandTrigger.Configure Method#

Overload List#

	Name	Description
	Configure(ICamera[])	Changes the configuration of the cameras so that it is triggered by the first available action command, for instance "Action 1". For more information, see PLGigECamera.ActionSelector. This configuration enables the frame start trigger and disables all other trigger types. The first available action command is selected as the trigger source, i.e., the camera will be triggered by action commands issued by the application.
	Configure(ICamera[], Int32, Int32, Int32, Int32)	This configuration is only for advanced use cases and changes the configuration of the cameras so that the cameras can be triggered by the given action command ID. Compared to Configure(ICamera()), the configuration of the trigger is up to the camera user.

ActionCommandTrigger.Issue Method#

Overload List#

	Name	Description
	Issue()	Issues an action command via broadcast without acknowledgment of success/failure and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).
	Issue(Int32, Int32, Int32, String)	Issues an action command via broadcast without acknowledgment of success/failure.
	Issue(Int32, Int32, Int32, String, Int32, ActionCommandResult[])	Issues an action command via broadcast with acknowledgment.

ActionCommandTrigger.Schedule Method#

Overload List#

	Name	Description
	Schedule(Int64)	Issues a scheduled action command via broadcast without acknowledgment of success/failure and and has to be used in combination with Configure(ICamera()). In addition, it's possible to create more customizable action command configurations with Configure(ICamera(), Int32, Int32, Int32, Int32).
	Schedule(Int32, Int32, Int32, Int64, String)	Issues a scheduled action command via broadcast without acknowledgment of success/failure.
	Schedule(Int32, Int32, Int32, Int64, String, Int32, ActionCommandResult[])	Issues a scheduled action command via broadcast with acknowledgment.

ActionCommandTrigger.ActionId Property#

Provides read access to the action ID.

Syntax#

C#

public int ActionId { get; }

VB

Public ReadOnly Property ActionId As Integer
    Get

Return Value#

Type: Int32
Returns action name.

Remarks#

The default value of the action ID is 1 but it can be customized with Configure(ICamera(), Int32, Int32, Int32, Int32). Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ActionCommandTrigger.BroadcastAddress Property#

Provides read access to the broadcast address.

Syntax#

C#

public string BroadcastAddress { get; }

VB

Public ReadOnly Property BroadcastAddress As String
    Get

Return Value#

Type: String
Returns the broadcast address.

Remarks#

The broadcast address is set during the camera configuration and is determined automatically. Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ActionCommandTrigger.DeviceKey Property#

Provides read access to the action device key.

Syntax#

C#

public int DeviceKey { get; }

VB

Public ReadOnly Property DeviceKey As Integer
    Get

Return Value#

Type: Int32
Returns action device key.

Remarks#

The default value of the device key is random but also customizable with Configure(ICamera(), Int32, Int32, Int32, Int32). Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ActionCommandTrigger.GroupKey Property#

Provides read access to the action group key.

Syntax#

C#

public int GroupKey { get; }

VB

Public ReadOnly Property GroupKey As Integer
    Get

Return Value#

Type: Int32
Returns action group key.

Remarks#

The default value of the group key is random but also customizable with Configure(ICamera(), Int32, Int32, Int32, Int32). Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ActionCommandTrigger.GroupMask Property#

Provides read access to the action group mask.

Syntax#

C#

public int GroupMask { get; }

VB

Public ReadOnly Property GroupMask As Integer
    Get

Return Value#

Type: Int32
Returns action group mask.

Remarks#

The default value of the group mask is 0x7fffffff but it can be customized with Configure(ICamera(), Int32, Int32, Int32, Int32). Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.