`analyzer2`¶

Caution

To use this applet with Sigrok, you must use our fork of libsigrok that includes the necessary drivers and bug fixes. (The binary packages include the correct build of libsigrok.)

CLI reference¶

glasgow run analyzer2¶

Capture values of digital inputs as a time series sequence.

At the moment, this applet is designed primarily for use with external tools or in script/REPL mode. When ran normally, it listens on a TCP port and exposes an open protocol that frontend applications like Sigrok can use.

First, configure the probes and voltage level:

glasgow run analyzer2 -V A=3.3 CMD=A0 CLK=A1 DAT=A2:5

Then, run Sigrok:

sigrok-cli -d glasgow:conn=tcp-raw/127.0.0.1/5555 -c samplerate=12m --samples 10000

Or, run PulseView (you can also configure the connection in the GUI):

pulseview -d glasgow:conn=tcp-raw/127.0.0.1/5555

usage: glasgow run analyzer2 [-h] [-V SPEC] [--buffer-size SIZE]
                             [--listen [ENDPOINT]]
                             PROBES [PROBES ...]

probes¶: probe I/O lines PROBES, optionally naming them (e.g.: A0, A0:1, DATA=B0)

-h, --help¶: show this help message and exit

-V <spec>, --voltage <spec>¶: configure I/O port voltage to SPEC (e.g.: ‘3.3’, ‘A=5.0,B=3.3’, ‘A=SA’)

--buffer-size <size>¶: use SIZE bytes for capture buffer (e.g. 0x100000 for 1 MB)

--listen <endpoint>¶: listen at ENDPOINT, either unix:PATH or tcp:HOST:PORT (default: tcp:localhost:5555)

API reference¶

class glasgow.applet.interface.analyzer2.DataFormat¶

Base class for data format descriptions.

abstract property fourcc: int¶: FourCC identifier of this format.

class glasgow.applet.interface.analyzer2.DigitalFormat(width: int, stride: int)¶

Data words with digital samples only.

width: int¶: Size of each sample, in bits.

stride: int¶: Distance between sample LSBs, in bits.

enum glasgow.applet.interface.analyzer2.DigitalTrigger(value)¶

Trigger condition for a single digital input.

Valid values are as follows:

Disabled = <DigitalTrigger.Disabled: 0>¶

FallingEdge = <DigitalTrigger.FallingEdge: 1>¶

RisingEdge = <DigitalTrigger.RisingEdge: 5>¶

AnyEdge = <DigitalTrigger.AnyEdge: 9>¶

LowLevel = <DigitalTrigger.LowLevel: 3>¶

HighLevel = <DigitalTrigger.HighLevel: 7>¶

enum glasgow.applet.interface.analyzer2.Marker(value)¶

Block metadata classifier.

Valid values are as follows:

Normal = <Marker.Normal: 0>¶

Discard = <Marker.Discard: 1>¶

Trigger = <Marker.Trigger: 4>¶

Overflow = <Marker.Overflow: 2>¶

Complete = <Marker.Complete: 6>¶

class glasgow.applet.interface.analyzer2.SampleBlock(*, samples: array[int], marker: Marker, offset: int = 0)¶

A block of captured sample data.

samples: array[int]¶

32-bit words containing sample data.

Use AnalyzerInterface.get_data_format() to determine the meaning of bits within each word.

marker: Marker¶: Indicator of the special nature of the last word of sample data.

offset: int = 0¶

Sub-word location of the marker, as a bit offset from LSB.

Only meaningful if marker == Marker.Trigger.

exception glasgow.applet.interface.analyzer2.AnalyzerError¶

class glasgow.applet.interface.analyzer2.AnalyzerInterface(logger: Logger, assembly: AbstractAssembly, *, probes: list[GlasgowPin] | dict[str, GlasgowPin], buffer_size: int | None = None)¶

async identify() → bytes¶

Identify the protocol version.

See the documentation for the IDENTIFY protocol command.

Returns GLA0.

async get_probe_names() → None | list[str]¶

Retrieve the probe names, if any.

See the documentation for the GET_METADATA protocol command.

Returns a list of probe names, or None if none were provided. This list is fixed for a particular analyzer instance.

async get_ref_frequency() → int¶

Retrieve the reference frequency.

See the documentation for the GET_CLK_FREQUENCY protocol command.

Returns the reference frequency in Hz. This value is fixed for a particular analyzer instance.

async get_sampling_rate() → float¶

Retrieve the configured sample rate.

See the documentation for the GET_CLK_DIVISOR protocol command.

Returns the sampling frequency in Hz. This value can be changed with set_sampling_rate().

async set_sampling_rate(rate: float, *, tolerance=0.05)¶

Configure the sampling rate.

See the documentation for the SET_CLK_DIVISOR protocol command.

Sets the sampling frequency to rate Hz.

Raises:

AnalyzerError – If the sample rate achieved via an integer divisor has an error of more than tolerance (5% by default).
AnalyzerError – If the sample rate cannot be achieved because the required data transfer rate exceeds available memory bandwidth.
AnalyzerError – If the sample rate cannot be achieved because the divisor register is not sufficiently wide in this analyzer instance.

async get_buffer_size() → int¶

Retrieve the size of the sampling buffer.

See the documentation for the GET_BUFFER_SIZE protocol command.

Returns the size of the sampling buffer in 32-bit words. This value is fixed for a particular analyzer instance.

async set_prolog_size(size: int)¶

Configure the size of the prolog.

See the documentation for the SET_PROLOG_SIZE protocol command.

Sets the size of the pre-trigger sampling interval, also known as the prolog, to size 32-bit words. The minimum size of the prolog is 1 word, and the hardware will clamp a size of zero words to that minimum value.

Raises:

AnalyzerError – If size is negative.
AnalyzerError – If size is greater than or equal to the sampling buffer size.

async set_epilog_size(size: int)¶

Configure the size of the epilog.

See the documentation for the SET_EPILOG_SIZE protocol command.

Sets the size of the post-trigger sampling interval, also known as the epilog, to size 32-bit words. The minimum size of the epilog is 1 word, and the hardware will clamp a size of zero words to that minimum value.

Raises:: AnalyzerError – If size is negative or too large.

async use_streaming()¶

Configure the epilog to continue indefinitely.

See the documentation for the SET_EPILOG_SIZE protocol command.

Causes the post-trigger sampling interval to extend indefinitely. The sample read-out, in this case, is only interrupted by a pipeline overflow or an explicit interrupt() call.

async get_data_format() → DataFormat¶

Retrieve the format of sample data words.

See the documentation for the GET_DATA_FORMAT protocol command.

Returns a value describing how to interpret the bits in each 32-bit sample word. The following data formats exist:

DigitalFormat

async use_basic_trigger(condition: dict[int, DigitalTrigger])¶

Configure the basic trigger module.

See the documentation for the SET_TRIGGER, TRIG_BASIC_SET_ACTIVE, TRIG_BASIC_SET_LEVEL, TRIG_BASIC_SET_VALUE, and TRIG_BASIC_SET_ANYEDGE protocol commands.

Configures the analyzer to trigger when any (logic OR) of the per-probe trigger conditions match the sampled values.

async arm_trigger()¶

Enable the trigger module.

See the documentation for the ARM_TRIGGER protocol command.

The trigger module is disabled after it encounters samples matching the configured condition and starting the sample read-out process.

async force_trigger()¶

Force a trigger condition to occur.

See the documentation for the FORCE_TRIGGER protocol command.

The trigger module is disabled after starting the sample read-out process.

async disarm_trigger()¶

Disable the trigger module.

See the documentation for the ARM_TRIGGER protocol command.

async interrupt()¶

Interrupt the sample read-out process and flush pipeline.

See the documentation for the INTERRUPT protocol command.

async read_sample_block() → SampleBlock¶

Read captured samples.

See the protocol documentation for the sample data sequences.

Currently, this function must be used to read out all sample data before another command will execute correctly. This is a limitation of the Python API.

Protocol reference¶

The protocol used by this applet is described in a separate document. If you’ve integrated this applet with a new application, please let us know!