# API Reference v10.3.1 (Python)

## Trigger (class)

Module: zaber_motion.ascii

A handle for a trigger with this number on the device. Triggers allow setting up actions that occur when a certain condition has been met or an event has occurred. Please note that the Triggers API is currently an experimental feature.

Requires at least Firmware 7.06.

To use this type, add `from zaber_motion.ascii import Trigger` to the top of your source code.

Related Guides:

- [Triggers](https://software.zaber.com/motion-library/docs/guides/device_features/triggers.md)

### Properties

#### `device` (read-only)

`trigger.device`

Type: [`Device`](https://software.zaber.com/motion-library/api/py/ascii/device.md)

Device that this trigger belongs to.

#### `trigger_number` (read-only)

`trigger.trigger_number`

Type: `int`

Number of this trigger.

### Methods

#### `clear_action()` (async available)

`trigger.clear_action(action = TriggerAction.ALL)`

Clear a trigger action.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `action` | [`TriggerAction`](https://software.zaber.com/motion-library/api/py/ascii/triggeraction.md) | The action number to clear. The default option is to clear all actions. |

#### `disable()` (async available)

`trigger.disable()`

Disables the trigger. Once disabled, the trigger will not fire and trigger actions will not run, even if trigger conditions are met.

#### `enable()` (async available)

`trigger.enable(count = 0)`

Enables the trigger. Once a trigger is enabled, it will fire whenever its condition transitions from false to true. If a trigger condition is true when a disabled trigger is enabled, the trigger will fire immediately.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `count` | `int` | Number of times the trigger will fire before disabling itself. If count is not specified, or 0, the trigger will fire indefinitely. |

#### `fire_at_interval()` (async available)

`trigger.fire_at_interval(interval, unit = Units.NATIVE)`

Set a trigger condition based on a time interval.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `interval` | `float` | The time interval between trigger fires. |
| `unit` | [`TimeUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of time. |

#### `fire_when()` (async available)

`trigger.fire_when(condition)`

Set a generic trigger condition.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `condition` | `str` | The condition to set for this trigger. |

#### `fire_when_absolute_setting()` (async available)

`trigger.fire_when_absolute_setting(axis, setting, trigger_condition, value, unit = Units.NATIVE)`

Set a trigger condition based on an absolute setting value.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `axis` | `int` | The axis to monitor for this condition. Set to 0 for device-scope settings. |
| `setting` | `str` | The setting to monitor. |
| `trigger_condition` | [`TriggerCondition`](https://software.zaber.com/motion-library/api/py/ascii/triggercondition.md) | Comparison operator. |
| `value` | `float` | Comparison value. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of value. |

#### `fire_when_distance_travelled()` (async available)

`trigger.fire_when_distance_travelled(axis, distance, unit = Units.NATIVE)`

Set a trigger condition for when an axis position has changed by a specific distance.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `axis` | `int` | The axis to monitor for this condition. May be set to 0 on single-axis devices only. |
| `distance` | `float` | The measured distance between trigger fires. |
| `unit` | [`LengthUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of dist. |

#### `fire_when_encoder_distance_travelled()` (async available)

`trigger.fire_when_encoder_distance_travelled(axis, distance, unit = Units.NATIVE)`

Set a trigger condition for when an encoder position has changed by a specific distance.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `axis` | `int` | The axis to monitor for this condition. May be set to 0 on single-axis devices only. |
| `distance` | `float` | The measured encoder distance between trigger fires. |
| `unit` | [`LengthUnits`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of dist. |

#### `fire_when_io()` (async available)

`trigger.fire_when_io(port_type, channel, trigger_condition, value)`

Set a trigger condition based on an IO channel value.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `port_type` | [`IoPortType`](https://software.zaber.com/motion-library/api/py/ascii/ioporttype.md) | The type of IO channel to monitor. |
| `channel` | `int` | The IO channel to monitor. |
| `trigger_condition` | [`TriggerCondition`](https://software.zaber.com/motion-library/api/py/ascii/triggercondition.md) | Comparison operator. |
| `value` | `float` | Comparison value. |

#### `fire_when_setting()` (async available)

`trigger.fire_when_setting(axis, setting, trigger_condition, value, unit = Units.NATIVE)`

Set a trigger condition based on a setting value.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `axis` | `int` | The axis to monitor for this condition. Set to 0 for device-scope settings. |
| `setting` | `str` | The setting to monitor. |
| `trigger_condition` | [`TriggerCondition`](https://software.zaber.com/motion-library/api/py/ascii/triggercondition.md) | Comparison operator. |
| `value` | `float` | Comparison value. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of value. |

#### `get_enabled_state()` (async available)

`trigger.get_enabled_state()`

Gets the enabled state of the trigger.

##### Return Value

Type: [`TriggerEnabledState`](https://software.zaber.com/motion-library/api/py/ascii/triggerenabledstate.md)

Whether the trigger is enabled and the number of times it will fire.

#### `get_label()` (async available)

`trigger.get_label()`

Returns the label for the trigger.

##### Return Value

Type: `str`

The label for the trigger.

#### `get_state()` (async available)

`trigger.get_state()`

Gets the state of the trigger.

##### Return Value

Type: [`TriggerState`](https://software.zaber.com/motion-library/api/py/ascii/triggerstate.md)

Complete state of the trigger.

#### `on_fire()` (async available)

`trigger.on_fire(action, axis, command)`

Set a command to be a trigger action.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `action` | [`TriggerAction`](https://software.zaber.com/motion-library/api/py/ascii/triggeraction.md) | The action number to assign the command to. |
| `axis` | `int` | The axis to on which to run this command. Set to 0 for device-scope settings or to run command on all axes. |
| `command` | `str` | The command to run when the action is triggered. |

#### `on_fire_set()` (async available)

`trigger.on_fire_set(action, axis, setting, operation, value, unit = Units.NATIVE)`

Set a trigger action to update a setting.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `action` | [`TriggerAction`](https://software.zaber.com/motion-library/api/py/ascii/triggeraction.md) | The action number to assign the command to. |
| `axis` | `int` | The axis on which to change the setting. Set to 0 to change the setting for the device. |
| `setting` | `str` | The name of the setting to change. |
| `operation` | [`TriggerOperation`](https://software.zaber.com/motion-library/api/py/ascii/triggeroperation.md) | The operation to apply to the setting. |
| `value` | `float` | Operation value. |
| `unit` | [`UnitsAndLiterals`](https://software.zaber.com/motion-library/api/py/root/units.md) | Units of value. |

#### `on_fire_set_to_setting()` (async available)

`trigger.on_fire_set_to_setting(action, axis, setting, operation, from_axis, from_setting)`

Set a trigger action to update a setting with the value of another setting.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `action` | [`TriggerAction`](https://software.zaber.com/motion-library/api/py/ascii/triggeraction.md) | The action number to assign the command to. |
| `axis` | `int` | The axis on which to change the setting. Set to 0 to change the setting for the device. |
| `setting` | `str` | The name of the setting to change. Must have either integer or boolean type. |
| `operation` | [`TriggerOperation`](https://software.zaber.com/motion-library/api/py/ascii/triggeroperation.md) | The operation to apply to the setting. |
| `from_axis` | `int` | The axis from which to read the setting. Set to 0 to read the setting from the device. |
| `from_setting` | `str` | The name of the setting to read. Must have either integer or boolean type. |

#### `set_label()` (async available)

`trigger.set_label(label)`

Sets the label for the trigger.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `label` | `Optional[str]` | The label to set for this trigger. If no value or an empty string is provided, this label is deleted. |
