Skip to content

Triggers

The start-condition hierarchy assigned to TaskSpec.trigger, plus ReferenceTrigger (for pre/post-trigger captures) and RetriggerSpec. See the Triggers guide for usage.

dtollib.tasks.triggers

Trigger specifications — full start-trigger hierarchy.

Beyond :class:SoftwareStart, this module provides the other start-trigger kinds (ExternalDigitalStart, AnalogThresholdStart, SyncBusStart) plus :class:ReferenceTrigger for pre-/about-trigger acquisition. :class:RetriggerSpec (triggered-scan retrigger) lives in tasks/spec.py.

Design reference: docs/design.md §8.8.

AnalogThresholdStart dataclass 

AnalogThresholdStart(*, channel, level, slope=Edge.RISING)

Bases: TriggerSpec

Analog threshold start (OL_TRG_THRESHPOS / OL_TRG_THRESHNEG).

Acquisition starts when the configured monitor channel's voltage crosses level in the direction given by slope. Edge.RISING selects OL_TRG_THRESHPOS; Edge.FALLING selects OL_TRG_THRESHNEG.

Attributes:

Name Type Description
channel int

Physical channel index to monitor for the threshold crossing.
level float

Threshold voltage (volts).
slope Edge

RISING for cross-from-below; FALLING for cross-from-above.

__post_init__ 

__post_init__()

Validate the channel index is non-negative.

Source code in src/dtollib/tasks/triggers.py 
86
87
88
89
90
91
92
93
94
95
def __post_init__(self) -> None:
    """Validate the channel index is non-negative."""
    if self.channel < 0:
        raise DtolValidationError(
            f"AnalogThresholdStart.channel must be >= 0 (got {self.channel})",
            context=ErrorContext(
                operation="AnalogThresholdStart.__post_init__",
                channel=self.channel,
            ),
        )

ExternalDigitalStart dataclass 

ExternalDigitalStart(*, edge=Edge.RISING)

Bases: TriggerSpec

External digital edge start (OL_TRG_EXTERN).

Acquisition starts on the configured edge of the board's external trigger input. Use to synchronise capture with an external event (laser shutter, mechanical contact, sibling-board sync line).

ReferenceTrigger dataclass 

ReferenceTrigger(*, source, post_scan_count)

Reference-trigger composition — pre/about-trigger acquisition.

Composes onto a :class:TaskSpec via TaskSpec.reference (not yet supported). The source trigger establishes the reference event; the SDK then collects post_scan_count samples after that event before stopping.

Attributes:

Name Type Description
source TriggerSpec

The trigger kind that marks the reference event.
post_scan_count int

Samples to collect after the reference event.

__post_init__ 

__post_init__()

Validate post_scan_count is positive.

Source code in src/dtollib/tasks/triggers.py 
128
129
130
131
132
133
134
def __post_init__(self) -> None:
    """Validate ``post_scan_count`` is positive."""
    if self.post_scan_count <= 0:
        raise DtolValidationError(
            f"ReferenceTrigger.post_scan_count must be positive (got {self.post_scan_count})",
            context=ErrorContext(operation="ReferenceTrigger.__post_init__"),
        )

SoftwareStart dataclass 

SoftwareStart()

Bases: TriggerSpec

Software-triggered start (OL_TRG_SOFT).

The default trigger for every :class:~dtollib.tasks.TaskSpec. The SDK accepts the configured task on olDaStart immediately without waiting for an external edge.

SyncBusStart dataclass 

SyncBusStart()

Bases: TriggerSpec

Sync-bus start (OL_TRG_SYNCBUS).

Acquisition starts on a sync-bus edge — used to coordinate multiple boards sharing a common back-plane sync line. Multi-board coordination via olDaSetSyncMode (not yet supported) builds on top of this trigger kind.

TriggerSpec

Marker base class for every trigger specification.

Sealed-ish via the kind ClassVar discriminator; concrete subclasses override. :class:SoftwareStart and the rest of the start-trigger hierarchy subclass this base.