Triggers

Zaber controllers and X-series devices are able to execute actions based on certain conditions automatically, and without the need to be connected to a computer. Triggers eliminate the communication delays inherent with control over a serial port, as all the logic is contained directly on the controller. The Triggers API offers the functionality to define and control triggers.

For more information on Triggers, see this Technical Note.

Accessing a Trigger

Once you have a device reference in code, you can access the device's triggers property. This allows you to get information on the triggers for this device, and get an individual trigger object. Note that triggers are numbered starting from 1:

triggers = device.triggers
print("Number of triggers available: ", triggers.get_number_of_triggers())
print("Number of actions per trigger: ", triggers.get_number_of_actions())

trigger = triggers.get_trigger(1)

var triggers = device.Triggers;
Console.WriteLine($"Number of triggers available: {triggers.GetNumberOfTriggers()}");
Console.WriteLine($"Number of actions per trigger: {triggers.GetNumberOfActions()}");

var trigger = triggers.GetTrigger(1);

Triggers triggers = device.getTriggers();
std::cout << "Number of triggers available: " << triggers.getNumberOfTriggers() << std::endl;
std::cout << "Number of actions per trigger: " << triggers.getNumberOfActions() << std::endl;

Trigger trigger = triggers.getTrigger(1);

const triggers = device.triggers;
console.log('Number of triggers available: ', await triggers.getNumberOfTriggers());
console.log('Number of actions per trigger: ', await triggers.getNumberOfActions());

const trigger = triggers.getTrigger(1);

Triggers triggers = device.getTriggers();
System.out.println(String.format("Number of triggers available: %d", triggers.getNumberOfTriggers()));
System.out.println(String.format("Number of actions per trigger: %d", triggers.getNumberOfActions()));

Trigger trigger = triggers.getTrigger(1);

triggers = device.getTriggers();
fprintf("Number of triggers available: %d\n", triggers.getNumberOfTriggers());
fprintf("Number of actions per trigger: %d\n", triggers.getNumberOfActions());

trigger = triggers.getTrigger(1);

fprintf("Number of triggers available: %d\n", device.Triggers.getNumberOfTriggers());
fprintf("Number of actions per trigger: %d\n", device.Triggers.getNumberOfActions());

trigger = device.Triggers.getTrigger(1);

Setting up a trigger

Each trigger has a condition for firing, which can be set using a condition-setting function. Conditions can be based on a position change, a setting value, a time interval, or an I/O change.

For example, here's how to set the condition for a trigger to when the position for axis 1 is greater than or equal to 100mm:

trigger.fire_when_setting(1, "pos", TriggerCondition.GE, 100, Units.LENGTH_MILLIMETRES)

trigger.FireWhenSetting(1, "pos", TriggerCondition.GE, 100, Units.Length_Millimetres);

trigger.fireWhenSetting(1, "pos", TriggerCondition::GE, 100, Units::LENGTH_MILLIMETRES);

await trigger.fireWhenSetting(1, 'pos', TriggerCondition.GE, 100, Length.MILLIMETRES);

trigger.fireWhenSetting(1, "pos", TriggerCondition.GE, 100, Units.LENGTH_MILLIMETRES);

trigger.fireWhenSetting(1, "pos", TriggerCondition.GE, 100, Units.LENGTH_MILLIMETRES);

trigger.fireWhenSetting(1, "pos", TriggerCondition.GE, 100, Units.Length("mm"));

Each trigger has multiple actions that happen immediately when the condition for that trigger is met. An action can be set to run a command or update a setting. Not all commands are supported by triggers, for a full list please see the ASCII Protocol Manual.

For example, here's how to set an action on a trigger to move axis 1 to position 0:

trigger.on_fire(TriggerAction.A, 1, "move abs 0")

trigger.OnFire(TriggerAction.A, 1, "move abs 0");

trigger.onFire(TriggerAction::A, 1, "move abs 0");

await trigger.onFire(TriggerAction.A, 1, "move abs 0");

trigger.onFire(TriggerAction.A, 1, "move abs 0");

trigger.onFire(TriggerAction.A, 1, "move abs 0");

trigger.onFire(TriggerAction.A, 1, "move abs 0");

Enabling and disabling a trigger

Once you have set a condition and at least one action for a particular trigger, it must be enabled before the trigger will fire. A trigger is enabled indefinitely by default, but it can optionally be enabled for a specific number of fires, after which the trigger will automatically disable itself.

# Enable trigger indefinitely
trigger.enable()

# Enable trigger 10 times
trigger.enable(10)

# Disable trigger
trigger.disable()

// Enable trigger indefinitely
trigger.Enable();

// Enable trigger 10 times
trigger.Enable(10);

// Disable trigger
trigger.Disable();

// Enable trigger indefinitely
trigger.enable();

// Enable trigger 10 times
trigger.enable(10);

// Disable trigger
trigger.disable();

// Enable trigger indefinitely
trigger.enable();

// Enable trigger 10 times
await trigger.enable(10);

// Disable trigger
await trigger.disable();

// Enable trigger indefinitely
trigger.enable();

// Enable trigger 10 times
trigger.enable(10);

// Disable trigger
trigger.disable();

% Enable trigger indefinitely
trigger.enable();

% Enable trigger 10 times
trigger.enable(10);

% Disable trigger
trigger.disable();

% Enable trigger indefinitely
trigger.enable();

% Enable trigger 10 times
trigger.enable(10);

% Disable trigger
trigger.disable();

It's possible to check if a trigger is enabled and how many times it will continue to fire. Note that a trigger that is enabled indefinitely will report -1 fires remaining. For example:

enabled_state = trigger.get_enabled_state()
if enabled_state.enabled:
    print("Trigger is enabled ", end="")
    if enabled_state.fires_remaining == -1:
        print("indefinitely")
    else:
        print(f"for {enabled_state.fires_remaining} more fires")
else:
    print("Trigger is disabled")

var enabledState = trigger.GetEnabledState();
if (enabledState.Enabled) {
    Console.Write("Trigger is enabled ");
    if (enabledState.FiresRemaining == -1) {
        Console.WriteLine("indefinitely");
    } else {
        Console.WriteLine($"for {enabledState.FiresRemaining} more fires");
    }
} else {
    Console.WriteLine("Trigger is disabled");
}

TriggerEnabledState enabledState = trigger.getEnabledState();
if (enabledState.getEnabled()) {
    std::cout << "Trigger is enabled ";
    if (enabledState.getFiresRemaining() == -1) {
        std::cout << "indefinitely" << std::endl;
    } else {
        std::cout << "for " << enabledState.getFiresRemaining() << " more fires" << std::endl;
    }
} else {
    std::cout << "Trigger is disabled" << std::endl;
}

const enabledState = await trigger.getEnabledState();
if (enabledState.enabled) {
    process.stdout.write("Trigger is enabled ");
    if (enabledState.firesRemaining == -1) {
        console.log('indefinitely');
    } else {
        console.log(`for ${enabledState.firesRemaining} more fires`);
    }
} else {
    console.log("Trigger is disabled");
}

TriggerEnabledState enabledState = trigger.getEnabledState();
if (enabledState.getEnabled()) {
    System.out.print("Trigger is enabled ");
    if (enabledState.getFiresRemaining() == -1) {
        System.out.println("indefinitely");
    } else {
        System.out.println(String.format("for %d more fires", enabledState.getFiresRemaining()));
    }
} else {
    System.out.println("Trigger is disabled");
}

enabledState = trigger.getEnabledState();
if enabledState.getEnabled()
    fprintf("Trigger is enabled ");
    if enabledState.getFiresRemaining() == -1
        fprintf("indefinitely\n");
    else
        fprintf("for %d more fires\n", enabledState.getFiresRemaining());
    end
else
    fprintf("Trigger is disabled\n");
end

enabledState = trigger.getEnabledState();
if enabledState.Enabled
    fprintf("Trigger is enabled ");
    if enabledState.FiresRemaining == -1
        fprintf("indefinitely\n");
    else
        fprintf("for %d more fires\n", enabledState.FiresRemaining);
    end
else
    fprintf("Trigger is disabled\n");
end

Example: Triggering a Camera

The example here describes how to set up a trigger to toggle the digital output of a controller as an automated shutter release for a camera. This can be done with a distance condition and a command action. For example, here's how to set a trigger to output a 50ms LOW-HIGH-LOW pulse on digital output 1 every 5mm of travel on axis 1. We will then enable this trigger to fire 500 times:

trigger.fire_when_distance_travelled(1, 5, Units.LENGTH_MILLIMETRES)
trigger.on_fire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0")
trigger.enable(500)

trigger.FireWhenDistanceTravelled(1, 5, Units.Length_Millimetres);
trigger.OnFire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0");
trigger.Enable(500);

trigger.fireWhenDistanceTravelled(1, 5, Units::LENGTH_MILLIMETRES);
trigger.onFire(TriggerAction::A, 0, "io set do 1 1 schedule 50 0");
trigger.enable(500);

await trigger.fireWhenDistanceTravelled(1, 5, Length.MILLIMETRES);
await trigger.onFire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0");
await trigger.enable(500);

trigger.fireWhenDistanceTravelled(1, 5, Units.LENGTH_MILLIMETRES);
trigger.onFire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0");
trigger.enable(500);

trigger.fireWhenDistanceTravelled(1, 5, Units.LENGTH_MILLIMETRES);
trigger.onFire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0");
trigger.enable(500);

trigger.fireWhenDistanceTravelled(1, 5, Units.Length("mm"));
trigger.onFire(TriggerAction.A, 0, "io set do 1 1 schedule 50 0");
trigger.enable(500);

Triggers

Accessing a Trigger

Setting up a trigger

Enabling and disabling a trigger

Example: Triggering a Camera

Resources