Class Wulpus

Pipeline block that integrates the Wulpus ultrasound dongle via Python (pythonnet).

JSON configuration

Use these block entries inside a pipeline configuration. Input names must match other blocks in that pipeline; device addresses and file paths must match your setup.

"wulpusPy": {
  "Type": "WulpusPython",
  "Inputs": [],
  "Params": [
    "C:\\path\\to\\uss_config.json",
    "C:\\path\\to\\tx_rx_config.json",
    1,
    false
  ]
}

How Type, Inputs and Params work · Block catalogue and parameter reference

Inheritance
Wulpus
Namespace: MOSAIC.Models.Devices
Assembly: MOSAIC.dll
Syntax
public sealed class Wulpus : BaseBlock, INotifyPropertyChanged, INotifyPropertyChanging, ISubscriber, IPublisher, IBaseBlockProps, IJsonExportable, IDisposable, IAsyncDisposable
Remarks

Uses the wulpus Python package to communicate with the Wulpus hardware (dongle, RX/TX and USS configurations). The Python runtime is managed by PythonNetManager.

Dual-mode triggering: When a ClockBlock is wired as input, acquisition is timer-driven (one read per tick). When no inputs are configured, a dedicated background thread runs a self-triggering read loop — no external timer needed.

Data sending modes:

  • SingleAcquisitionVector (0): Each acquisition is sent as a MathNet.Numerics.LinearAlgebra.Vector<T> regardless of config index.
  • CompleteFrameMatrix (1): Waits for a full frame (all TX/RX configs), then sends as a MathNet.Numerics.LinearAlgebra.Matrix<T>.
  • UpdateSingleAcqMatrix (2): Builds and sends an updating MathNet.Numerics.LinearAlgebra.Matrix<T> on every acquisition for higher frame rate.

JSON configuration:

"wulpusPy": {
  "Type": "WulpusPython",
  "Inputs": [],
  "Params": [
    "C:\\path\\to\\uss_config.json",
    "C:\\path\\to\\tx_rx_config.json",
    1,
    false
  ]
}

Params: [ ussConfigPath, rxTxConfigPath, dataSendingMode (0|1|2), appendMetadata (bool) ]

Constructors

Wulpus(string, double, string, string, DataSendingMode, bool)

Initializes a new Wulpus block.

Declaration
public Wulpus(string name, double desiredRate, string ussConfigPath = "", string rxTxConfigPath = "", Wulpus.DataSendingMode sendingMode = DataSendingMode.SingleAcquisitionVector, bool appendMetadata = true)
Parameters
Type Name Description
string name

Block name used in the pipeline.

double desiredRate

Desired execution rate in Hz.

string ussConfigPath

Path to USS configuration JSON.

string rxTxConfigPath

Path to RX/TX configuration JSON.

Wulpus.DataSendingMode sendingMode

Data sending mode (0, 1, or 2).

bool appendMetadata

Whether to append Wulpus metadata to output.

Fields

ThreadJoinTimeoutMs

Maximum time to wait for the self-trigger thread to terminate during shutdown.

Declaration
private const int ThreadJoinTimeoutMs = 3000
Field Value
Type Description
int

_acquisitionCount

Total acquisitions processed.

Declaration
[ObservableProperty]
private long _acquisitionCount
Field Value
Type Description
long

_appendMetadata

Whether to append Wulpus metadata (config index, acquisition counter) to output.

Declaration
[ObservableProperty]
private bool _appendMetadata
Field Value
Type Description
bool

_assembler

Declaration
private readonly IDataAssembler _assembler
Field Value
Type Description
IDataAssembler

_connection

Declaration
private readonly Connection _connection
Field Value
Type Description
Connection

_dataCount

Declaration
private int _dataCount
Field Value
Type Description
int

_isSelfTriggered

Whether the block is running in self-triggered mode (no external timer).

Declaration
[ObservableProperty]
private bool _isSelfTriggered
Field Value
Type Description
bool

_noStreamWarning

Declaration
private bool _noStreamWarning
Field Value
Type Description
bool

_readThread

Declaration
private Thread? _readThread
Field Value
Type Description
Thread

_running

Declaration
private volatile bool _running
Field Value
Type Description
bool

_sendingMode

Data assembly and publishing mode.

Declaration
[ObservableProperty]
private Wulpus.DataSendingMode _sendingMode
Field Value
Type Description
Wulpus.DataSendingMode

_visualizedConfig

Index of the currently visualized config (for single-channel display).

Declaration
[ObservableProperty]
private int _visualizedConfig
Field Value
Type Description
int

Properties

AcquisitionCount

Total acquisitions processed.

Declaration
[ExcludeFromCodeCoverage]
public long AcquisitionCount { get; set; }
Property Value
Type Description
long

AppendMetadata

Whether to append Wulpus metadata (config index, acquisition counter) to output.

Declaration
[ExcludeFromCodeCoverage]
public bool AppendMetadata { get; set; }
Property Value
Type Description
bool

ConnectedPort

Currently connected COM port name.

Declaration
public string ConnectedPort { get; }
Property Value
Type Description
string

Connection

The underlying connection for direct device control.

Declaration
public Connection Connection { get; }
Property Value
Type Description
Connection

FoundDevices

Human-readable descriptions of found devices.

Declaration
public List<string> FoundDevices { get; }
Property Value
Type Description
List<string>

Heatmap

Standalone heatmap for B-mode display (configs × samples grid).

Declaration
public HeatMapMonitor Heatmap { get; }
Property Value
Type Description
HeatMapMonitor

IsConnected

Whether a COM (dongle) connection is currently open.

Declaration
public bool IsConnected { get; }
Property Value
Type Description
bool

IsSelfTriggered

Whether the block is running in self-triggered mode (no external timer).

Declaration
[ExcludeFromCodeCoverage]
public bool IsSelfTriggered { get; set; }
Property Value
Type Description
bool

IsStreaming

Whether data streaming is currently active.

Declaration
public bool IsStreaming { get; }
Property Value
Type Description
bool

JsonTypeName

Block type identifier for JSON serialization. Override for a custom name.

Declaration
protected override string JsonTypeName { get; }
Property Value
Type Description
string
Overrides
BaseBlock.JsonTypeName

NumChannelConfigs

Number of TX/RX channel configurations.

Declaration
public int NumChannelConfigs { get; }
Property Value
Type Description
int

NumSamples

Number of samples per acquisition.

Declaration
public int NumSamples { get; }
Property Value
Type Description
int

RxTxConfigPath

Path to the RX/TX configuration JSON file.

Declaration
public string RxTxConfigPath { get; }
Property Value
Type Description
string

SendingMode

Data assembly and publishing mode.

Declaration
[ExcludeFromCodeCoverage]
public Wulpus.DataSendingMode SendingMode { get; set; }
Property Value
Type Description
Wulpus.DataSendingMode

Snapshot

Standalone A-mode snapshot monitor (spatial waveform, not time-series).

Declaration
public SnapshotMonitor Snapshot { get; }
Property Value
Type Description
SnapshotMonitor

UssConfigPath

Path to the USS configuration JSON file.

Declaration
public string UssConfigPath { get; }
Property Value
Type Description
string

VisualizedConfig

Index of the currently visualized config (for single-channel display).

Declaration
[ExcludeFromCodeCoverage]
public int VisualizedConfig { get; set; }
Property Value
Type Description
int

Methods

ClosePort()

Closes the current COM connection and stops streaming.

Declaration
public void ClosePort()

ConfigureInput(IServiceProvider, JsonModel)

Creates a Wulpus block from JSON pipeline configuration.

Declaration
public static Wulpus ConfigureInput(IServiceProvider sp, JsonModel m)
Parameters
Type Name Description
IServiceProvider sp

Service provider for dependency injection.

JsonModel m

JSON model containing block configuration.

Returns
Type Description
Wulpus

A fully configured Wulpus block.

Dispose()

Disposes resources: stops streaming, closes port, and cleans up visualization.

Declaration
public override void Dispose()
Overrides
BaseBlock.Dispose()

GetJsonParams()

Block-specific parameters for JSON. Override to provide custom parameters.

Declaration
protected override IReadOnlyList<object>? GetJsonParams()
Returns
Type Description
IReadOnlyList<object>

The values for Params, in the order this block's ConfigureInput reads them, or null when the block takes no parameters.

Overrides
BaseBlock.GetJsonParams()

LoadRxTxConfig(string)

Loads and applies a RX/TX configuration JSON file.

Declaration
public void LoadRxTxConfig(string rxtxPath)
Parameters
Type Name Description
string rxtxPath

Path to the RX/TX config JSON.

LoadUssConfig(string)

Loads and applies a USS configuration JSON file.

Declaration
public void LoadUssConfig(string configPath)
Parameters
Type Name Description
string configPath

Path to the USS config JSON.

NotifyConfigChanged()

Raises PropertyChanged for all delegated config properties.

Declaration
private void NotifyConfigChanged()

NotifyConnectionStateChanged()

Raises PropertyChanged for all delegated connection-state properties so the UI (and ViewModel commands) can react.

Declaration
private void NotifyConnectionStateChanged()

OnAcquisitionCountChanged(long)

Executes the logic for when AcquisitionCount just changed.

Declaration
private void OnAcquisitionCountChanged(long value)
Parameters
Type Name Description
long value

The new property value that was set.

Remarks

This method is invoked right after the value of AcquisitionCount is changed.

OnAcquisitionCountChanged(long, long)

Executes the logic for when AcquisitionCount just changed.

Declaration
private void OnAcquisitionCountChanged(long oldValue, long newValue)
Parameters
Type Name Description
long oldValue

The previous property value that was replaced.

long newValue

The new property value that was set.

Remarks

This method is invoked right after the value of AcquisitionCount is changed.

OnAcquisitionCountChanging(long)

Executes the logic for when AcquisitionCount is changing.

Declaration
private void OnAcquisitionCountChanging(long value)
Parameters
Type Name Description
long value

The new property value being set.

Remarks

This method is invoked right before the value of AcquisitionCount is changed.

OnAcquisitionCountChanging(long, long)

Executes the logic for when AcquisitionCount is changing.

Declaration
private void OnAcquisitionCountChanging(long oldValue, long newValue)
Parameters
Type Name Description
long oldValue

The previous property value that is being replaced.

long newValue

The new property value being set.

Remarks

This method is invoked right before the value of AcquisitionCount is changed.

OnAppendMetadataChanged(bool)

Executes the logic for when AppendMetadata just changed.

Declaration
private void OnAppendMetadataChanged(bool value)
Parameters
Type Name Description
bool value

The new property value that was set.

Remarks

This method is invoked right after the value of AppendMetadata is changed.

OnAppendMetadataChanged(bool, bool)

Executes the logic for when AppendMetadata just changed.

Declaration
private void OnAppendMetadataChanged(bool oldValue, bool newValue)
Parameters
Type Name Description
bool oldValue

The previous property value that was replaced.

bool newValue

The new property value that was set.

Remarks

This method is invoked right after the value of AppendMetadata is changed.

OnAppendMetadataChanging(bool)

Executes the logic for when AppendMetadata is changing.

Declaration
private void OnAppendMetadataChanging(bool value)
Parameters
Type Name Description
bool value

The new property value being set.

Remarks

This method is invoked right before the value of AppendMetadata is changed.

OnAppendMetadataChanging(bool, bool)

Executes the logic for when AppendMetadata is changing.

Declaration
private void OnAppendMetadataChanging(bool oldValue, bool newValue)
Parameters
Type Name Description
bool oldValue

The previous property value that is being replaced.

bool newValue

The new property value being set.

Remarks

This method is invoked right before the value of AppendMetadata is changed.

OnIsSelfTriggeredChanged(bool)

Executes the logic for when IsSelfTriggered just changed.

Declaration
private void OnIsSelfTriggeredChanged(bool value)
Parameters
Type Name Description
bool value

The new property value that was set.

Remarks

This method is invoked right after the value of IsSelfTriggered is changed.

OnIsSelfTriggeredChanged(bool, bool)

Executes the logic for when IsSelfTriggered just changed.

Declaration
private void OnIsSelfTriggeredChanged(bool oldValue, bool newValue)
Parameters
Type Name Description
bool oldValue

The previous property value that was replaced.

bool newValue

The new property value that was set.

Remarks

This method is invoked right after the value of IsSelfTriggered is changed.

OnIsSelfTriggeredChanging(bool)

Executes the logic for when IsSelfTriggered is changing.

Declaration
private void OnIsSelfTriggeredChanging(bool value)
Parameters
Type Name Description
bool value

The new property value being set.

Remarks

This method is invoked right before the value of IsSelfTriggered is changed.

OnIsSelfTriggeredChanging(bool, bool)

Executes the logic for when IsSelfTriggered is changing.

Declaration
private void OnIsSelfTriggeredChanging(bool oldValue, bool newValue)
Parameters
Type Name Description
bool oldValue

The previous property value that is being replaced.

bool newValue

The new property value being set.

Remarks

This method is invoked right before the value of IsSelfTriggered is changed.

OnReceive(object, object)

Called when the upstream timer fires. Only active in timer-driven mode.

Declaration
protected override void OnReceive(object sender, object data)
Parameters
Type Name Description
object sender
object data
Overrides
BaseBlock.OnReceive(object, object)

OnSendingModeChanged(DataSendingMode)

Executes the logic for when SendingMode just changed.

Declaration
private void OnSendingModeChanged(Wulpus.DataSendingMode value)
Parameters
Type Name Description
Wulpus.DataSendingMode value

The new property value that was set.

Remarks

This method is invoked right after the value of SendingMode is changed.

OnSendingModeChanged(DataSendingMode, DataSendingMode)

Executes the logic for when SendingMode just changed.

Declaration
private void OnSendingModeChanged(Wulpus.DataSendingMode oldValue, Wulpus.DataSendingMode newValue)
Parameters
Type Name Description
Wulpus.DataSendingMode oldValue

The previous property value that was replaced.

Wulpus.DataSendingMode newValue

The new property value that was set.

Remarks

This method is invoked right after the value of SendingMode is changed.

OnSendingModeChanging(DataSendingMode)

Executes the logic for when SendingMode is changing.

Declaration
private void OnSendingModeChanging(Wulpus.DataSendingMode value)
Parameters
Type Name Description
Wulpus.DataSendingMode value

The new property value being set.

Remarks

This method is invoked right before the value of SendingMode is changed.

OnSendingModeChanging(DataSendingMode, DataSendingMode)

Executes the logic for when SendingMode is changing.

Declaration
private void OnSendingModeChanging(Wulpus.DataSendingMode oldValue, Wulpus.DataSendingMode newValue)
Parameters
Type Name Description
Wulpus.DataSendingMode oldValue

The previous property value that is being replaced.

Wulpus.DataSendingMode newValue

The new property value being set.

Remarks

This method is invoked right before the value of SendingMode is changed.

OnVisualizedConfigChanged(int)

Executes the logic for when VisualizedConfig just changed.

Declaration
private void OnVisualizedConfigChanged(int value)
Parameters
Type Name Description
int value

The new property value that was set.

Remarks

This method is invoked right after the value of VisualizedConfig is changed.

OnVisualizedConfigChanged(int, int)

Executes the logic for when VisualizedConfig just changed.

Declaration
private void OnVisualizedConfigChanged(int oldValue, int newValue)
Parameters
Type Name Description
int oldValue

The previous property value that was replaced.

int newValue

The new property value that was set.

Remarks

This method is invoked right after the value of VisualizedConfig is changed.

OnVisualizedConfigChanging(int)

Executes the logic for when VisualizedConfig is changing.

Declaration
private void OnVisualizedConfigChanging(int value)
Parameters
Type Name Description
int value

The new property value being set.

Remarks

This method is invoked right before the value of VisualizedConfig is changed.

OnVisualizedConfigChanging(int, int)

Executes the logic for when VisualizedConfig is changing.

Declaration
private void OnVisualizedConfigChanging(int oldValue, int newValue)
Parameters
Type Name Description
int oldValue

The previous property value that is being replaced.

int newValue

The new property value being set.

Remarks

This method is invoked right before the value of VisualizedConfig is changed.

OpenPort(int)

Opens a COM connection to the device at the specified index.

Declaration
public void OpenPort(int deviceIndex)
Parameters
Type Name Description
int deviceIndex

Index into FoundDevices.

ProcessOutput()

Performs a single acquisition cycle: reads data via the assembler, optionally crops metadata, publishes downstream, and feeds visualization.

Declaration
private void ProcessOutput()

ResolveConfigParam(string)

Resolves a USS or TX/RX config path from the pipeline JSON against the application folder.

Declaration
private static string ResolveConfigParam(string path)
Parameters
Type Name Description
string path

The raw Params value. Absolute paths and empty strings pass through.

Returns
Type Description
string

An absolute path, or the input unchanged when it is empty or already rooted.

Remarks

A pipeline shared between machines cannot name an absolute path, and the presets ship beside the executable, so a relative entry like Assets/WulpusConfigs/uss_config_hand_tests.json is resolved from there rather than from the working directory - which is wherever the app happened to be launched from, and is not the same thing.

ScanDevices()

Scans for available Wulpus devices.

Declaration
public int ScanDevices()
Returns
Type Description
int

Number of devices found.

SelfTriggerLoop()

Self-triggering read loop running on a background thread.

Declaration
private void SelfTriggerLoop()

StartStreaming()

Starts streaming: sends config to the dongle, then either launches a self-triggering read loop or waits for external timer ticks.

Declaration
public void StartStreaming()

StopStreaming()

Stops streaming and shuts down the self-trigger thread if running.

Declaration
public void StopStreaming()

Implements

INotifyPropertyChanged
INotifyPropertyChanging
ISubscriber
IPublisher
IBaseBlockProps
IJsonExportable
IDisposable
IAsyncDisposable

Search documentation

Start typing to search the documentation.