Digital output instrument

The DigitalOut instrument provides multiple channels of digital output on devices that support it, such as the Analog Discovery, Analog Discovery 2, Analog Discovery 3, Analog Discovery Pro, and Digital Discovery. It provides the functionality normally associated with a stand-alone digital pattern generator.

Todo

This section is currently incomplete.

It lacks a detailed discussion of how all the settings work.

Using the digital output instrument

To use the DigitalOut functionality you first need to initialize a DwfLibrary instance. Next, you open a specific device. The device’s DigitalOut functionality can now be accessed via its digitalOut attribute, which is an instance of the DigitalOut class.

For example:

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

with openDwfDevice(dwf) as device:

    # Get a reference to the device's DigitalOut instrument.
    digitalOut = device.digitalOut

    # Use the DigitalOut instrument.
    digitalOut.reset()

Important

Both the DigitalIO and DigitalOut instruments provide an API to drive the same digital outputs. The former provides a very simple API that can be used in cases where precise timing or realtime behavior is not relevant, while the latter provides a more powerful, but also more complicated API that provides far greater control over timing.

The rule for which device gets precedence is explained in a topic on the Digilent forum. In summary:

For DIO channels where the DigitalIO instrument sets outputEnable to 1, the behavior of the channel is determined by the DigitalIO instrument.
For DIO channels where the DigitalIO instrument sets outputEnable to 0, and the output is set to 1, the channel is in high-impedance (‘Z’) state.
For DIO channels where the DigitalIO instrument sets outputEnable to 0, and the output is set to 0, the behavior of the channel is determined by the DigitalOut instrument.

Thus, in order to use the DigitalOut instrument for a specific channel, the user must ensure that the DigitalIO instrument sets both the outputEnable and output configuration bits to 0. In most circumstances it is not necessary to do this explicitly, since this is the default setting of the DigitalIO instrument for each channel.

The DigitalOut instrument state machine

The DigitalOut instrument is controlled by a state machine. As an output sequence is prepared and executed, the instrument goes through its various states.

The current state of the instrument is returned by the digitalOut.status() method, and is of type DwfState.

The figure below shows the states used by the DigitalOut instrument and the transitions between them:

digraph { rankdir=LR; // nodes node [color="#243f60"; fillcolor="#4581bd"; style="filled"]; st_ready [label="Ready"]; st_armed [label="Armed"]; st_wait [label="Wait"]; st_running [label="Running"]; st_repeat [label="Repeat" shape="rectangle"]; st_done [label="Done"]; // edges edge [color="#4579b8"]; st_ready -> st_armed [label="Start?"]; st_armed -> st_wait [label="Trigger?"]; st_wait -> st_running; st_running -> st_repeat; st_repeat -> st_armed [style="dashed"]; st_repeat -> st_wait [style="dashed"]; st_repeat -> st_done; }

States of the DigitalOut instrument

The DigitalOut states are used as follows:

Ready

In this preparatory state, instrument settings can be changed that specify the behavior of the instrument in the coming output sequence. If the auto-configure setting of the device is enabled (the default), setting changes will automatically be transferred to the device. If not, an explicit call to the digitalOut.configure() method is needed to transfer updated settings to the device.

Once the instrument is properly configured, an output sequence can be started by calling the digitalOut.configure() with the start parameter set to True. This will start the first stage of the output sequence by entering the Armed state.
Armed

In this state the instrument continuously monitors the configured trigger input. As soon as a trigger event is detected, the instrument proceeds to the Wait state.
Wait

In this state, the digital outputs are driven according to their Idle settings. The duration of the wait state is configurable. Once this duration has passed, the instrument proceeds to the Running state.
Running

In this state, the digital outputs are driven according to their individual configurations. This continues until the run duration has been reached. The channel then proceeds to the Repeat state.
Repeat

Note

This is not a true state, in that there is no DwfState value that represents it. It is included here to explain the control flow of the DigitalOut instrument state machine.

When an output run is finished, the repeat count is decremented.

If, after decrementing, the repeat count is unequal to zero, more output must be produced. If the repeat trigger setting is True, the instrument proceeds to the Armed state; in that case, a trigger is needed to start each of the output runs. If the repeat trigger setting is False, the instrument proceeds immediately to the Wait state to start another output sequence; a trigger is only required before the very first output run.

If, after decrementing, the repeat count did reach zero, the instrument becomes idle and proceeds to the Done state.
Done

This state indicates that an output sequence has finished. In this state, the outputs are driven according to their Idle setting.

From this state, it is possible to go back to the Ready state by performing any kind of configuration, or to start a new output sequence.

DigitalOut instrument API overview

The DigitalOut instrument is quite complicated; 53 methods are provided to control its behavior. Below, we categorize these methods and shortly introduce them. Detailed information on all methods can be found in the DigitalOut class reference that follows.

Instrument control

Like all instruments supported by the Digilent Waveforms library, the DigitalOut instrument provides reset(), configure(), and status() methods.

The reset() method resets the instrument.

The configure() method is used to explicitly transfer settings to the instrument, and/or to start a configured operation.

The status() method returns the current DwfState of the DigitalOut instrument.

Instrument control (4 methods)
control operation	type/unit	methods
reset instrument	n/a	`reset()`
configure instrument	n/a	`configure()`
request instrument status	`DwfState`	`status()`
request instrument output status	unknown	`statusOutput()`

Channel count

This method returns the number of digital output channels.

Channel count (1 method)
property	type/unit	method
channel count	int	`count()`

Instrument-level state machine settings

These settings determine the duration of the Wait and Running states, how many times the Wait/Running cycle should be repeated, and whether a trigger must precede each Wait/Running cycle.

State machine settings (13 methods)
setting	type/unit	methods
wait duration	float [s]	`waitInfo()` , `–Set()` , `–Get()`
run duration	float [s]	`runInfo()` , `–Set()` , `–Get()` , `–Status()`
repeat trigger	bool	`repeatTriggerSet()` , `–Get()`
repeat count	int [-]	`repeatInfo()` , `–Set()` , `–Get()` , `–Status()`

Trigger configuration

These settings configure the instrument trigger.

Trigger configuration (5 methods)
setting	type/unit	methods
trigger source	`DwfTriggerSource`	`triggerSourceInfo()` , `–Set()` , `–Get()`
trigger slope	`DwfTriggerSlope`	`triggerSlopeSet()` , `–Get()`

Note

The triggerSourceInfo() method is obsolete. Use the generic DwfDevice.triggerInfo() method instead.

Output settings

These settings determine the output behavior.

Output settings (11 methods)
setting	type/unit	methods
enable	bool	`enableSet()` , `–Get()`
output	`DwfDigitalOutOutput`	`outputInfo()` , `–Set()` , `–Get()`
type	`DwfDigitalOutType`	`typeInfo()` , `–Set()` , `–Get()`
idle	`DwfDigitalOutIdle`	`idleInfo()` , `–Set()` , `–Get()`

Output pattern timing definition

These settings determine the per-channel output pattern timing in the Running state.

Output pattern definition (14 methods)
setting	type/unit	methods
clock info	float [Hz]	`internalClockInfo()`
divider	int [-]	`dividerInfo()` , `–Set()` , `–Get()`
divider init	int [-]	`dividerInitSet()` , `–Get()`
counter	int [-]	`counterInfo()` , `–Set()` , `–Get()`
counter init	int [-]	`counterInitSet()` , `–Get()`
repetitition count	int [-]	`repetitionInfo()` , `–Set()` , `–Get()`

Data playback

These methods provide data upload playback by the DigitalOut instrument.

Data playback (4 methods)
operation	type/unit	methods
data upload	complicated	`dataInfo()` , `–Set()`
play data upload	bit string	`playDataSet()`
play rate	float [Hz]	`playRateSet()`

DigitalOut reference

class DigitalOut

The DigitalOut class provides access to the digital output (pattern generator) instrument of a DwfDevice.

Attention

Users of pydwf should not create instances of this class directly.

It is instantiated during initialization of a DwfDevice and subsequently assigned to its public digitalOut attribute for access by the user.

reset() → None

Reset the DigitalOut instrument.

Raises:: DwfLibraryError – An error occurred while executing the reset operation.

configure(start: bool) → None

Start or stop the DigitalOut instrument.

Parameters:: start (int) – Whether to start/stop the instrument.
Raises:: DwfLibraryError – An error occurred while executing the configure operation.

status() → DwfState

Return the status of the DigitalOut instrument.

This method performs a status request to the DigitalOut instrument and receives its response.

Returns:: The status of the DigitalOut instrument.
Return type:: DwfState
Raises:: DwfLibraryError – An error occurred while executing the status operation.

statusOutput() → Tuple[int, int]

Get status output.

Notice:: This function is not documented in the official documentation, but it is present in the C header file.

Returns:: The first entry is labeled ‘value’, the second is labeled ‘enable’ in the C header file.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – An error occurred while executing the statusOutput operation.

count() → int

Get the DigitalOut instrument channel (digital pin) count.

Returns:: The number of digital output channels.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

waitInfo() → Tuple[float, float]

Get the DigitalOut instrument range for the Wait state duration, in seconds.

Returns:: A tuple containing the minimal and maximal configurable Wait state duration, in seconds.
Return type:: Tuple[float, float]
Raises:: DwfLibraryError – An error occurred while executing the operation.

waitSet(wait_duration: float) → None

Set the DigitalOut instrument Wait state duration, in seconds.

Parameters:: wait_duration (float) – Digital-out Wait state duration, in seconds.
Raises:: DwfLibraryError – An error occurred while executing the operation.

waitGet() → float

Get DigitalOut instrument Wait state duration, in seconds.

Returns:: The Wait state duration, in seconds.
Return type:: float
Raises:: DwfLibraryError – An error occurred while executing the operation.

runInfo() → Tuple[float, float]

Get the DigitalOut instrument range for the Running state duration, in seconds.

Returns:: A tuple containing the minimal and maximal Running state duration, in seconds.
Return type:: Tuple[float, float]
Raises:: DwfLibraryError – An error occurred while executing the operation.

runSet(run_duration: float) → None

Set the DigitalOut instrument Running state duration, in seconds.

Parameters:

run_duration –

The Running state duration, in seconds.

The value 0 is special; it means forever.

Raises:

DwfLibraryError – An error occurred while executing the operation.

runGet() → float

Get the DigitalOut instrument Running state duration, in seconds.

Returns:: The Running state duration, in seconds.
Return type:: float
Raises:: DwfLibraryError – An error occurred while executing the operation.

runStatus() → int

Get the DigitalOut instrument Running state duration time left, in clock cycles.

This value is internally expressed as an integer with 48-bit resolution, and is measured in integer clock cycles. The C API returns it as a double-precision floating point number, to avoid using 64-bit integers.

Use the internalClockInfo() method to retrieve the clock frequency.

Returns:: The number of clock cycles until the nest state transition of the DigitalOut instrument’s state machine.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

repeatTriggerSet(repeat_trigger_flag: bool) → None

Specify if each DigitalOut pulse sequence run should wait for its own trigger.

Parameters:: repeat_trigger_flag (bool) – If True, not only the first, both also every successive run of the pulse output sequence will wait until it receives a trigger.
Raises:: DwfLibraryError – An error occurred while executing the operation.

repeatTriggerGet() → bool

Get if each DigitalOut pulse sequence run should wait for its own trigger.

Returns:: If True, not only the first, both also every successive run of the pulse output sequence will wait until it receives a trigger.
Return type:: bool

repeatInfo() → Tuple[int, int]

Get the DigitalOut minimal and maximal repeat count for pulse-sequence runs.

Returns:: A tuple containing the minimal and maximal repeat count for digital-out pulse-sequence runs.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – An error occurred while executing the operation.

repeatSet(repeat: int) → None

Set the DigitalOut repeat count for pulse-sequence runs.

Parameters:: repeat (int) – Repeat count. The value 0 is special; it means forever.
Raises:: DwfLibraryError – An error occurred while executing the operation.

repeatGet() → int

Set the DigitalOut repeat count for pulse-sequence runs.

Returns:: Repeat count. The value 0 is special; it means forever.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

repeatStatus() → int

Get the DigitalOut count of repeats remaining for the currently active output sequence.

This number counts down as a digital output sequence is active.

Returns:: The repeat count status.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

triggerSourceInfo() → List[DwfTriggerSource]

Get the valid DigitalOut trigger sources.

Warning

This method is obsolete.

Use the generic DeviceControl.triggerInfo() method instead.

Returns:: A list of valid the trigger sources.
Return type:: List[DwfTriggerSource]
Raises:: DwfLibraryError – An error occurred while executing the operation.

triggerSourceSet(trigger_source: DwfTriggerSource) → None

Set the DigitalOut trigger source.

Parameters:: trigger_source (DwfTriggerSource) – The trigger source to be configured.
Raises:: DwfLibraryError – An error occurred while executing the operation.

triggerSourceGet() → DwfTriggerSource

Get the currently selected instrument trigger source.

Returns:: The currently selected instrument trigger source.
Return type:: DwfTriggerSource
Raises:: DwfLibraryError – An error occurred while executing the operation.

triggerSlopeSet(trigger_slope: DwfTriggerSlope) → None

Select the DigitalOut instrument trigger slope.

Parameters:: trigger_slope (DwfTriggerSlope) – The trigger slope to be selected.
Raises:: DwfLibraryError – An error occurred while executing the operation.

triggerSlopeGet() → DwfTriggerSlope

Get the currently configured DigitalOut instrument trigger slope.

Returns:: The currently selected DigitalOut instrument trigger slope.
Return type:: DwfTriggerSlope
Raises:: DwfLibraryError – An error occurred while executing the operation.

enableSet(channel_index: int, enable_flag: bool) → None

Enable or disable a DigitalOut channel (pin).

Parameters:

channel_index (int) – The digital pin to enable or disable.
enable_flag (bool) – Whether to enable or disable the digital output.

Raises:

DwfLibraryError – An error occurred while executing the operation.

enableGet(channel_index: int) → bool

Check if a specific DigitalOut channel (pin) is enabled for output.

Parameters:: channel_index (int) – The digital pin.
Returns:: Whether the digital pin is enabled as an output.
Return type:: bool
Raises:: DwfLibraryError – An error occurred while executing the operation.

outputInfo(channel_index: int) → List[DwfDigitalOutOutput]

Get valid DigitalOut output choices (e.g. Push/Pull, tristate).

Returns:: A list of valid output settings.
Return type:: List[DwfDigitalOutOutput]
Raises:: DwfLibraryError – An error occurred while executing the operation.

outputSet(channel_index: int, output_value: DwfDigitalOutOutput) → None

Set DigitalOut output choice (e.g. Push/Pull, tristate).

Parameters:

channel_index (int) – The digital pin.
output_value (DwfDigitalOutOutput) – The digital output setting.

Raises:

DwfLibraryError – An error occurred while executing the operation.

outputGet(channel_index: int) → DwfDigitalOutOutput

Get currently configured DigitalOut output (e.g. Push/Pull, tristate).

Parameters:: channel_index (int) – The digital pin.
Returns:: The digital output setting.
Return type:: DwfDigitalOutOutput
Raises:: DwfLibraryError – An error occurred while executing the operation.

typeInfo(channel_index: int) → List[DwfDigitalOutType]

Get a list of valid DigitalOut output channel types.

Returns:: A list of valid digital output channel types.
Return type:: List[DwfDigitalOutType]
Raises:: DwfLibraryError – An error occurred while executing the operation.

typeSet(channel_index: int, output_type: DwfDigitalOutType) → None

Select the DigitalOut output channel type.

Parameters:

channel_index (int) – The digital pin.
output_type (DwfDigitalOutType) – The digital output channel type.

Raises:

DwfLibraryError – An error occurred while executing the operation.

typeGet(channel_index: int) → DwfDigitalOutType

Get the currently selected DigitalOut output channel type.

Parameters:: channel_index (int) – The digital pin.
Returns:: The digital output channel type.
Return type:: DwfDigitalOutType
Raises:: DwfLibraryError – An error occurred while executing the operation.

idleInfo(channel_index: int) → List[DwfDigitalOutIdle]

Get valid DigitalOut idle output values.

Returns:: A list of valid idle output values.
Return type:: List[DwfDigitalOutIdle]
Raises:: DwfLibraryError – An error occurred while executing the operation.

idleSet(channel_index: int, idle_mode: DwfDigitalOutIdle) → None

Set the DigitalOut idle output value.

Parameters:

channel_index (int) – The digital pin.
idle_mode (DwfDigitalOutIdle) – The idle output value.

Raises:

DwfLibraryError – An error occurred while executing the operation.

idleGet(channel_index: int) → DwfDigitalOutIdle

Get the currently configured idle output value.

Parameters:: channel_index (int) – The digital pin.
Returns:: The currently configured idle output value.
Return type:: DwfDigitalOutIdle
Raises:: DwfLibraryError – An error occurred while executing the operation.

internalClockInfo() → float

Get the DigitalOut instrument clock frequency.

Returns:: The digital-out clock frequency, in Hz.
Return type:: float
Raises:: DwfLibraryError – An error occurred while executing the operation.

dividerInfo(channel_index: int) → Tuple[int, int]

Get the DigitalOut divider value range.

Returns:: The range of valid divider settings.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – An error occurred while executing the operation.

dividerSet(channel_index: int, divider: int) → None

Set the DigitalOut divider value.

Parameters:

channel_index (int) – The digital pin.
divider (int) – The divider setting.

Raises:

DwfLibraryError – An error occurred while executing the operation.

dividerGet(channel_index: int) → int

Get the currently configured DigitalOut divider value.

Parameters:: channel_index (int) – The digital pin.
Returns:: The divider setting.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

dividerInitSet(channel_index: int, divider_init_value: int) → None

Set the DigitalOut initial divider value.

Parameters:

channel_index (int) – The digital pin.
divider_init_value (int) – The initial divider counter value.

Raises:

DwfLibraryError – An error occurred while executing the operation.

dividerInitGet(channel_index: int) → int

Get the currently configured DigitalOut initial divider value.

Parameters:: channel_index (int) – The digital pin.
Returns:: The divider init setting.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

counterInfo(channel_index: int) → Tuple[int, int]

Get the DigitalOut counter value range.

Parameters:: channel_index (int) – The digital pin.
Returns:: The range of valid counter settings.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – An error occurred while executing the operation.

counterSet(channel_index: int, low_count: int, high_count: int) → None

Set the DigitalOut counter durations for both the low and high signal output levels.

Parameters:

channel_index (int) – The digital pin.
low_count (int) – The number of cycles the signal should be Low.
high_count (int) – The number of cycles the signal should be High.

Raises:

DwfLibraryError – An error occurred while executing the operation.

counterGet(channel_index: int) → Tuple[int, int]

Get the DigitalOut counter durations for both the low and high signal output levels.

Parameters:: channel_index (int) – The digital pin.
Returns:: The number of cycles the signal should be Low, High.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – An error occurred while executing the operation.

counterInitSet(channel_index: int, high_flag: bool, counter_init_value: int) → None

Set the DigitalOut initial signal value and initial counter value.

Parameters:

channel_index (int) – The digital pin.
high (bool) – Whether to start High (True) or Low (False).
counter_init (int) – The initial counter setting.

Raises:

DwfLibraryError – An error occurred while executing the operation.

counterInitGet(channel_index: int) → Tuple[bool, int]

Get the DigitalOut initial signal value and initial counter value.

Parameters:: channel_index (int) – The digital pin.
Returns:: Whether to start High (True) or Low (False), and the initial counter setting.
Return type:: Tuple [bool, int]
Raises:: DwfLibraryError – An error occurred while executing the operation.

repetitionInfo(channel_index: int) → int

Get maximum repetition count value.

The repetition count specifies how many times the counter should be reloaded. For pulse signals set twice the desired value since each pulse is generated by two counter loads, low and high. It is available with ADP3X50 and newer devices.

Parameters:: channel_index (int) – The digital pin.
Returns:: The maximum repetition value that can be configured.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

repetitionSet(channel_index: int, repeat: int) → None

Set repetition count value.

The repetition count specifies how many times the counter should be reloaded. For pulse signals set twice the desired value since each pulse is generated by two counter loads, low and high. It is available with ADP3X50 and newer devices.

Parameters:: channel_index (int) – The digital pin.
Returns:: The maximum repetition value that can be configured.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

repetitionGet(channel_index: int) → int

Get repetition count value.

The repetition count specifies how many times the counter should be reloaded. For pulse signals set twice the desired value since each pulse is generated by two counter loads, low and high. It is available with ADP3X50 and newer devices.

dataInfo(channel_index: int) → int

Return the maximum buffer size for the specified DigitalOut channel, i.e., the number of custom data bits.

Parameters:: channel_index (int) – the channel for which to obtain the data bits count.
Returns:: The number of custom data bits that can be specified for the channel.
Return type:: int
Raises:: DwfLibraryError – An error occurred while executing the operation.

dataSet(channel_index: int, bits: str, tristate: bool = False) → None

Set the DigitalOut arbitrary output data.

This function also sets the counter initial, low and high value, according to the number of bits. The data-bits are sent out in LSB-first order.

Parameters:

channel_index (int) – the channel for which to set the output data.
bits (str) – The bits, as a string.
tristate (bool) – Whether to interpret the string as a tristate signal.

Raises:

DwfLibraryError – An error occurred while executing the operation.

playDataSet(bits: str, bits_per_sample: int, count_of_samples: int) → None

Set the DigitalOut playback data.

The output can be PushPull, OpenDrain, or OpenSource. Tristate data is not supported.

Note

The DWF documentation explicitly states that this function is supported by the Digital Discovery. (So, by implication, it’s probably not supported on anything else.)

Parameters:

bits (str) – string of ‘0’ and ‘1’ characters. Its length should be (bits_per_sample * count_of_samples).
bits_per_sample (int) – Bits per sample, should be 1, 2, 4, 8, or 16.
count_of_samples (int) – Number of samples.

Raises:

DwfLibraryError – An error occurred while executing the operation.

playUpdateSet(bits: str, index_of_sample: int, count_of_samples: int) → None: Set the DigitalOut playback data.

Todo

This function is not sufficiently documented at this time.

playRateSet(playback_rate: float) → None

Set the DigitalOut playback rate, in Hz.

Note

The DWF documentation explicitly states that this function is supported by the Digital Discovery. (So, by implication, it’s probably not supported on anything else.)

Parameters:: playback_rate (float) – The playback rate, in Hz.
Raises:: DwfLibraryError – An error occurred while executing the operation.

property device

Return the DwfDevice instance of which we are an attribute.

This is useful if we have a variable that contains a reference to a DwfDevice attribute, but we need the DwfDevice itself.

Returns:: The DwfDevice instance that this attribute belongs to.
Return type:: DwfDevice