A single channel of an instrument. More...

#include <InstrumentChannel.h>

Inheritance diagram for InstrumentChannel:

[legend]

Collaboration diagram for InstrumentChannel:

[legend]

Public Types
enum	PhysicalConnector { CONNECTOR_BANANA_DUAL , CONNECTOR_BMA , CONNECTOR_BNC , CONNECTOR_K , CONNECTOR_K_DUAL , CONNECTOR_N , CONNECTOR_SMA }

enum	VisibilityMode { VIS_HIDE , VIS_AUTO , VIS_SHOW }
	Selects how the channel should be displayed in e.g. the ngscopeclient filter graph editor.

enum	DownloadState { DOWNLOAD_UNKNOWN , DOWNLOAD_NONE , DOWNLOAD_WAITING , DOWNLOAD_IN_PROGRESS , DOWNLOAD_FINISHED }
	Enum values to be mapped to GetDownloadState() int result value for specific channel download states. More...

Public Types inherited from FlowGraphNode
enum	DataLocation { LOC_CPU , LOC_GPU , LOC_DONTCARE }

typedef std::map< std::string, FilterParameter >	ParameterMapType
	Short name for a map of strings to parameters.

Public Member Functions
	InstrumentChannel (Instrument *inst, const std::string &hwname, const std::string &color="#808080", Unit xunit=Unit(Unit::UNIT_FS), size_t index=0)

	InstrumentChannel (Instrument *inst, const std::string &hwname, const std::string &color="#808080", Unit xunit=Unit(Unit::UNIT_FS), Unit yunit=Unit(Unit::UNIT_VOLTS), Stream::StreamType stype=Stream::STREAM_TYPE_ANALOG, size_t index=0)

virtual void	SetDisplayName (std::string name)
	Sets the human-readable nickname for this channel, as displayed in the GUI. More...

virtual std::string	GetDisplayName ()
	Gets the human-readable nickname for this channel, as displayed in the GUI. More...

std::string	GetHwname ()
	Gets the hardware name of the channel (m_hwname)

size_t	GetIndex ()
	Gets the (zero based) index of the channel.

Instrument *	GetInstrument ()
	Gets the instrument this channel is part of (if any)

void	ClearCachedDisplayName ()
	Sets the display name to an empty string, causing a fetch from hardware. More...

virtual PhysicalConnector	GetPhysicalConnector ()

void	SetData (WaveformBase *pNew, size_t stream)
	Sets the waveform data for a given stream, replacing any previous waveform. More...

virtual Unit	GetXAxisUnits ()
	Returns the X axis unit for this channel.

virtual Unit	GetYAxisUnits (size_t stream)
	Returns the Y axis unit for a specified stream.

virtual void	SetXAxisUnits (const Unit &rhs)
	Changes the X axis unit for this channel. More...

virtual void	SetYAxisUnits (const Unit &rhs, size_t stream)
	Changes the X axis unit for a specified stream. More...

Stream::StreamType	GetType (size_t stream)
	Returns the type of a specified stream.

size_t	GetStreamCount ()
	Get the number of data streams.

std::string	GetStreamName (size_t stream)
	Gets the name of a stream (for display in the UI)

WaveformBase *	GetData (size_t stream)
	Get the contents of a data stream.

uint8_t	GetStreamFlags (size_t stream)
	Get the flags of a data stream.

float	GetScalarValue (size_t stream)
	Gets the value of a scalar data stream.

void	SetScalarValue (size_t stream, float value)
	Sets the value of a scalar data stream.

WaveformBase *	Detach (size_t stream)
	Detach the capture data from this channel. More...

virtual bool	ShouldPersistWaveform ()
	Determine whether the channel's waveform(s) should be persisted to a session file. More...

virtual DownloadState	GetDownloadState ()
	Returns the current download state of this channel. More...

virtual float	GetDownloadProgress ()
	returns the current completion of the download (on the range [0, 1]), if not DOWNLOAD_UNKNOWN More...

virtual double	GetDownloadStartTime ()
	returns the start time of a download, if we are DOWNLOAD_IN_PROGRESS; undefined, otherwise More...

Public Member Functions inherited from FlowGraphNode
void	DetachInputs ()
	Disconnects all inputs from the node without releasing them. More...

size_t	GetInputCount ()

std::string	GetInputName (size_t i)

void	SetInput (size_t i, StreamDescriptor stream, bool force=false)
	Connects a stream to the input of this node. More...

void	SetInput (const std::string &name, StreamDescriptor stream, bool force=false)

virtual bool	ValidateChannel (size_t i, StreamDescriptor stream)

StreamDescriptor	GetInput (size_t i)
	Gets the descriptor for one of our inputs.

FilterParameter &	GetParameter (std::string s)

bool	HasParameter (std::string s)
	Checks if we have a parameter with a given name. More...

ParameterMapType::iterator	GetParamBegin ()
	Returns an iterator to the beginning of our parameter map.

ParameterMapType::iterator	GetParamEnd ()
	Returns an iterator to the end of our parameter map.

size_t	GetParamCount ()
	Returns the number of parameter we have.

virtual YAML::Node	SerializeConfiguration (IDTable &table)
	Serializes this trigger's configuration to a YAML string. More...

virtual void	LoadParameters (const YAML::Node &node, IDTable &table)
	Load configuration from a save file. More...

virtual void	LoadInputs (const YAML::Node &node, IDTable &table)

bool	IsDownstreamOf (std::set< FlowGraphNode * > nodes)
	Determines if this node is downstream of any of the specified other nodes. More...

virtual DataLocation	GetInputLocation ()
	Gets the desired location of the nodes's input data. More...

virtual void	Refresh ()
	Evaluates a filter graph node. More...

virtual void	Refresh (vk::raii::CommandBuffer &cmdBuf, std::shared_ptr< QueueHandle > queue)

sigc::signal< void()>	signal_parametersChanged ()

sigc::signal< void()>	signal_inputsChanged ()

Public Attributes
std::string	m_displaycolor
	Display color (HTML hex notation with optional alpha channel: #RRGGBB or ##RRGGBBAA)

enum InstrumentChannel::VisibilityMode	m_visibilityMode

Protected Member Functions
virtual void	ClearStreams ()
	Clears out any existing streams. More...

virtual size_t	AddStream (Unit yunit, const std::string &name, Stream::StreamType stype, uint8_t flags=0)
	Adds a new data stream to the channel. More...

Protected Member Functions inherited from FlowGraphNode
virtual void	OnInputChanged (size_t i)
	Called when a new input is connected to the node. More...

WaveformBase *	GetInputWaveform (size_t i)
	Gets the waveform attached to the specified input. More...

SparseAnalogWaveform *	GetSparseAnalogInputWaveform (size_t i)
	Gets the analog waveform attached to the specified input.

UniformAnalogWaveform *	GetUniformAnalogInputWaveform (size_t i)
	Gets the analog waveform attached to the specified input.

SparseDigitalWaveform *	GetSparseDigitalInputWaveform (size_t i)
	Gets the digital waveform attached to the specified input.

UniformDigitalWaveform *	GetUniformDigitalInputWaveform (size_t i)
	Gets the digital waveform attached to the specified input.

SparseDigitalBusWaveform *	GetSparseDigitalBusInputWaveform (size_t i)
	Gets the digital bus waveform attached to the specified input.

void	CreateInput (const std::string &name)
	Creates and names an input signal.

std::string	GetInputDisplayName (size_t i)
	Gets the display name for one of our inputs. More...

Protected Attributes
Instrument *	m_instrument
	The instrument we're part of (may be null in the case of filters etc)

std::string	m_hwname
	Hardware name of the channel. More...

std::string	m_displayname
	Display name (user defined, defaults to m_hwname). More...

size_t	m_index
	Zero based index of the channel within the instrument.

Unit	m_xAxisUnit
	Unit of measurement for our horizontal axis (common to all streams)

std::vector< Stream >	m_streams
	Configuration data for each of our output streams.

Protected Attributes inherited from FlowGraphNode
std::vector< std::string >	m_signalNames
	Names of signals we take as input.

std::vector< StreamDescriptor >	m_inputs
	The channel (if any) connected to each of our inputs.

ParameterMapType	m_parameters

sigc::signal< void()>	m_parametersChangedSignal
	Signal emitted when the set of parameters changes.

sigc::signal< void()>	m_inputsChangedSignal
	Signal emitted when the set of inputs changes.

Detailed Description

A single channel of an instrument.

A "channel" generally refers to a single physical connector on the front panel of the device, however sometimes multiple connectors (e.g. multimeter positive and negative probes) are logically considered one channel.

Channels may be input or output, and may have multiple functions.

For example, consider a mixed signal oscilloscope with multimeter and function generator option: Four analog inputs, each are usable as oscilloscope or multimeter inputs One trigger input Sixteen logic analyzer inputs One function generator output

This instrument implements three device classes (oscilloscope, multimeter, and function generator) across a total of 22 channels, however no one channel supports all three APIs.

This base class implements functionality which is common to channels from any kind of instrument

Member Enumeration Documentation

◆ DownloadState

enum InstrumentChannel::DownloadState

Enum values to be mapped to GetDownloadState() int result value for specific channel download states.

Enumerator
DOWNLOAD_NONE	No download is pending (e.g. the scope is in stop mode)
DOWNLOAD_WAITING	This channel is waiting to be downloaded (i.e. scope is triggered but previous channels are currently beeing downloaded)
DOWNLOAD_IN_PROGRESS	Download has started.
DOWNLOAD_FINISHED	Download is finished.

Member Function Documentation

◆ AddStream()

size_t InstrumentChannel::AddStream	(	Unit	yunit,
		const std::string &	name,
		Stream::StreamType	stype,
		uint8_t	flags = `0`
	)

protectedvirtual

Adds a new data stream to the channel.

Returns: Index of the new stream

Reimplemented in BERTInputChannel, and Filter.

◆ ClearCachedDisplayName()

void InstrumentChannel::ClearCachedDisplayName ( )

inline

Sets the display name to an empty string, causing a fetch from hardware.

This should only be used by instrument driver implementations.

◆ ClearStreams()

void InstrumentChannel::ClearStreams ( )

protectedvirtual

Clears out any existing streams.

Reimplemented in BERTInputChannel, and Filter.

◆ Detach()

WaveformBase * InstrumentChannel::Detach ( size_t stream )

inline

Detach the capture data from this channel.

Once this function is called, the waveform is now owned by the caller and not the channel object.

◆ GetDisplayName()

string InstrumentChannel::GetDisplayName ( )

virtual

Gets the human-readable nickname for this channel, as displayed in the GUI.

Reimplemented in OscilloscopeChannel.

◆ GetDownloadProgress()

float InstrumentChannel::GetDownloadProgress ( )

virtual

returns the current completion of the download (on the range [0, 1]), if not DOWNLOAD_UNKNOWN

Reimplemented in OscilloscopeChannel.

◆ GetDownloadStartTime()

double InstrumentChannel::GetDownloadStartTime ( )

virtual

returns the start time of a download, if we are DOWNLOAD_IN_PROGRESS; undefined, otherwise

Reimplemented in OscilloscopeChannel.

◆ GetDownloadState()

InstrumentChannel::DownloadState InstrumentChannel::GetDownloadState ( )

virtual

Returns the current download state of this channel.

The returned int value can either be an integer ranging from 0 to 100 corresponding to the percentage of the waveform that has already been downloaded or a (negative) int value to be mapped to the OscilloscopeChannel::DownloadState enum

Reimplemented in OscilloscopeChannel.

◆ SetData()

void InstrumentChannel::SetData	(	WaveformBase *	pNew,
		size_t	stream
	)

Sets the waveform data for a given stream, replacing any previous waveform.

Calling this function with pNew == GetData() is a legal no-op.

Any existing waveform is deleted, unless it is the same as pNew.

◆ SetDisplayName()

void InstrumentChannel::SetDisplayName ( std::string name )

virtual

Sets the human-readable nickname for this channel, as displayed in the GUI.

Reimplemented in DigitalInputChannel, DigitalIOChannel, DigitalOutputChannel, and OscilloscopeChannel.

◆ SetXAxisUnits()

virtual void InstrumentChannel::SetXAxisUnits ( const Unit & rhs )

inlinevirtual

Changes the X axis unit for this channel.

This function is intended for filter/driver implementations. No actual conversion of data is performed, so calling this with an incorrect unit may lead to confusing results.

◆ SetYAxisUnits()

virtual void InstrumentChannel::SetYAxisUnits	(	const Unit &	rhs,
		size_t	stream
	)

inlinevirtual

Changes the X axis unit for a specified stream.

This function is intended for filter/driver implementations. No actual conversion of data is performed, so calling this with an incorrect unit may lead to confusing results.

◆ ShouldPersistWaveform()

bool InstrumentChannel::ShouldPersistWaveform ( )

virtual

Determine whether the channel's waveform(s) should be persisted to a session file.

Reimplemented in Filter, MemoryFilter, and TrendFilter.

Member Data Documentation

◆ m_displayname

std::string InstrumentChannel::m_displayname

protected

Display name (user defined, defaults to m_hwname).

Note that this is mostly used for filters; channels that belong to an instrument typically store the display name in the driver so that it can be synchronized with the instrument front panel display.

◆ m_hwname

std::string InstrumentChannel::m_hwname

protected

Hardware name of the channel.

This is normally whatever the channel is called via SCPI, so it can be directly used to build SCPI queries. For non-SCPI instruments, use a reasonable default name for the channel.

The documentation for this class was generated from the following files:

lib/scopehal/InstrumentChannel.h
lib/scopehal/InstrumentChannel.cpp

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ DownloadState

Member Function Documentation

◆ AddStream()

◆ ClearCachedDisplayName()

◆ ClearStreams()

◆ Detach()

◆ GetDisplayName()

◆ GetDownloadProgress()

◆ GetDownloadStartTime()

◆ GetDownloadState()

◆ SetData()

◆ SetDisplayName()

◆ SetXAxisUnits()

◆ SetYAxisUnits()

◆ ShouldPersistWaveform()

Member Data Documentation

◆ m_displayname

◆ m_hwname