Class StimulationController

Host-agnostic wrapper around the full stimulation stack (core → params → model). Provides the same API surface as the Unity Stimulation MonoBehaviour but manages initialization, ticking, and shutdown inside a plain .NET application.

Inheritance

object

StimulationController

Namespace: HFI.Wss

Assembly: HFI_WSS_Csharp_Implementation.dll

Syntax

public sealed class StimulationController

Remarks

This type starts a background tick loop when Initialize() completes. The public API is primarily intended for single-threaded use; avoid calling stimulation methods concurrently with Shutdown().

Constructors

StimulationController(StimulationOptions)

Creates a controller instance with the provided stimulation configuration options.

Declaration

public StimulationController(StimulationOptions options)

Parameters

Type	Name	Description
StimulationOptions	options	Options that control transport selection, config paths, and tick behavior without exposing transport implementation details to the caller.

Exceptions

Type	Condition
ArgumentNullException	Thrown when options is null.
ArgumentException	Thrown when an option value is invalid.
ArgumentOutOfRangeException	Thrown when an option value is out of range.

Properties

BasicSupported

True if the underlying core exposes basic-stimulation APIs.

Declaration

public bool BasicSupported { get; }

Property Value

Type	Description
bool

started

True after this controller issues a successful StartStimulation() request.

Declaration

public bool started { get; }

Property Value

Type	Description
bool

Remarks

This is a controller-managed flag and may temporarily differ from Started(), which queries the underlying WSS stack for its current state.

Methods

AddOrUpdateStimParam(string, float)

Adds or updates a stimulation parameter value.

Declaration

public void AddOrUpdateStimParam(string key, float value)

Parameters

Type	Name	Description
string	key	Parameter key (e.g., "stim.ch.1.amp").
float	value	Parameter value (units depend on the key).

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

Dispose()

Shuts down the controller and releases any underlying resources.

Declaration

public void Dispose()

Remarks

This method performs synchronous shutdown and waits for the background tick loop to stop before returning.

DisposeAsync()

Shuts down the controller and releases any underlying resources.

Declaration

public ValueTask DisposeAsync()

Returns

Type	Description
ValueTask

Remarks

Disposal is performed synchronously by calling Shutdown(). The returned System.Threading.Tasks.ValueTask is already complete when this method returns.

GetAllStimParams()

Gets a copy of all known stimulation parameters.

Declaration

public Dictionary<string, float> GetAllStimParams()

Returns

Type	Description
Dictionary<string, float>	A dictionary mapping parameter keys to their values.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetChannelAmp(string)

Gets the channel amplitude.

Declaration

public float GetChannelAmp(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
float	Amplitude in milliamps.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetChannelIPI(string)

Gets the inter-pulse interval for a channel.

Declaration

public int GetChannelIPI(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
int	Inter-pulse interval in milliseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetChannelPWMax(string)

Gets the maximum pulse width for a channel.

Declaration

public int GetChannelPWMax(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
int	Pulse width in microseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetChannelPWMin(string)

Gets the minimum pulse width for a channel.

Declaration

public int GetChannelPWMin(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
int	Pulse width in microseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetCoreConfigCTRL()

Gets the core configuration controller.

Declaration

public CoreConfigController GetCoreConfigCTRL()

Returns

Type	Description
CoreConfigController	The core configuration controller instance.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetModelConfigCTRL()

Gets the model configuration controller.

Declaration

public ModelConfigController GetModelConfigCTRL()

Returns

Type	Description
ModelConfigController	The model configuration controller instance.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetStimIntensity(string)

Gets the current stimulation intensity for the specified channel.

Declaration

public int GetStimIntensity(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
int	The current intensity value (device/model-specific units).

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

GetStimParam(string)

Gets a stimulation parameter value.

Declaration

public float GetStimParam(string key)

Parameters

Type	Name	Description
string	key	Parameter key.

Returns

Type	Description
float	The parameter value.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

Initialize()

Builds the full stimulation stack and initializes the hardware connection. Automatically starts the background tick loop.

Declaration

public void Initialize()

Remarks

The controller creates the transport internally based on Transport: test mode uses TestModeTransport, serial uses SerialPortTransport, and BLE uses BleNusTransport. This method is idempotent and returns immediately when the controller is already initialized. Initialization failures from the underlying WSS stack propagate to the caller.

IsFingerValid(string)

Checks whether a finger name or channel alias resolves to a valid channel for the current configuration.

Declaration

public bool IsFingerValid(string finger)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").

Returns

Type	Description
bool	true when the channel is in range; otherwise false.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

LoadCoreConfigFile()

Reloads the core configuration JSON.

Declaration

public void LoadCoreConfigFile()

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

LoadParamsJson()

Loads stimulation parameters from the default JSON path.

Declaration

public void LoadParamsJson()

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

LoadParamsJson(string)

Loads stimulation parameters from a JSON file or directory.

Declaration

public void LoadParamsJson(string pathOrDir)

Parameters

Type	Name	Description
string	pathOrDir	File path or directory path; directory inputs use the library default filename.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

Ready()

Gets whether the underlying stack reports a ready state.

Declaration

public bool Ready()

Returns

Type	Description
bool	true when ready; otherwise false. Returns false before initialization.

Save()

Persists basic-stimulation configuration to all devices.

Declaration

public void Save()

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

Save(int)

Persists basic-stimulation configuration to the target device.

Declaration

public void Save(int targetWSS)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

SaveParamsJson()

Persists stimulation parameters to the default JSON path.

Declaration

public void SaveParamsJson()

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

SetChannelAmp(string, float)

Sets the channel amplitude.

Declaration

public void SetChannelAmp(string finger, float mA)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
float	mA	Amplitude in milliamps.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

SetChannelIPI(string, int)

Sets the inter-pulse interval for a channel.

Declaration

public void SetChannelIPI(string finger, int ms)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
int	ms	Inter-pulse interval in milliseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

SetChannelPWMax(string, int)

Sets the maximum pulse width for a channel.

Declaration

public void SetChannelPWMax(string finger, int us)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
int	us	Pulse width in microseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

SetChannelPWMin(string, int)

Sets the minimum pulse width for a channel.

Declaration

public void SetChannelPWMin(string finger, int us)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
int	us	Pulse width in microseconds.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

Shutdown()

Stops the background tick loop and tears down the active connection.

Declaration

public void Shutdown()

Remarks

This method blocks until the current tick loop exits and then shuts down and disposes the active WSS stack. It is safe to call multiple times; calls made before initialization return without error.

StartStimulation()

Broadcasts a start-stimulation command and marks started as true.

Declaration

public void StartStimulation()

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

Started()

Gets whether the underlying stack reports stimulation started.

Declaration

public bool Started()

Returns

Type	Description
bool	true when started; otherwise false. Returns false before initialization.

StimWithMode(string, float)

Sends a stimulation request interpreted by the active mode (model/params-dependent).

Declaration

public void StimWithMode(string finger, float magnitude)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
float	magnitude	Magnitude value interpreted by the active mode.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

StimulateAnalog(string, int, int, int)

Sends a direct (basic) analog stimulation request for a channel.

Declaration

public void StimulateAnalog(string finger, int PW, int amp = 3, int IPI = 10)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
int	PW	Pulse width (device-specific; commonly microseconds).
int	amp	Amplitude setting (device-specific).
int	IPI	Inter-pulse interval (device-specific; commonly milliseconds).

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

StimulateNormalized(string, float)

Sends a normalized stimulation magnitude for the specified channel.

Declaration

public void StimulateNormalized(string finger, float magnitude)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
float	magnitude	Normalized magnitude (device/model-specific convention).

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

StopStimulation()

Broadcasts a stop-stimulation command and marks started as false.

Declaration

public void StopStimulation()

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

TryGetStimParam(string, out float)

Attempts to get a stimulation parameter value.

Declaration

public bool TryGetStimParam(string key, out float v)

Parameters

Type	Name	Description
string	key	Parameter key.
float	v	Receives the parameter value when present.

Returns

Type	Description
bool	true when the parameter exists; otherwise false.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

UpdateChannelParams(string, int, int, int)

Updates a channel's max/min pulse width and amplitude parameters using the conventional parameter keys.

Declaration

public void UpdateChannelParams(string finger, int max, int min, int amp)

Parameters

Type	Name	Description
string	finger	Finger name (e.g., "thumb", "index") or channel alias (e.g., "ch1").
int	max	Maximum pulse width (units depend on the parameter schema; commonly microseconds).
int	min	Minimum pulse width (units depend on the parameter schema; commonly microseconds).
int	amp	Amplitude value (units depend on the parameter schema).

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.
ArgumentOutOfRangeException	Thrown when finger resolves to an out-of-range channel.

UpdateIPD(int, int)

Updates the inter-phase delay for an event on all devices.

Declaration

public void UpdateIPD(int ipd, int eventID)

Parameters

Type	Name	Description
int	ipd	Inter-phase delay (device-specific; commonly microseconds).
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

UpdateIPD(int, int, int)

Updates the inter-phase delay for an event on the target device.

Declaration

public void UpdateIPD(int targetWSS, int ipd, int eventID)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
int	ipd	Inter-phase delay (device-specific; commonly microseconds).
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

WaveformSetup(int, WaveformBuilder, int)

Performs waveform setup for an event on the target device.

Declaration

public void WaveformSetup(int targetWSS, WaveformBuilder wave, int eventID)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
WaveformBuilder	wave	Waveform builder instance.
int	eventID	Event identifier to configure.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

WaveformSetup(WaveformBuilder, int)

Performs waveform setup for an event on all devices.

Declaration

public void WaveformSetup(WaveformBuilder wave, int eventID)

Parameters

Type	Name	Description
WaveformBuilder	wave	Waveform builder instance.
int	eventID	Event identifier to configure.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

isModeValid()

Gets whether the current stimulation mode is valid for the loaded configuration.

Declaration

public bool isModeValid()

Returns

Type	Description
bool	true when the mode is valid; otherwise false.

Exceptions

Type	Condition
InvalidOperationException	Thrown when Initialize() has not been called.

load()

Loads basic-stimulation configuration from all devices.

Declaration

public void load()

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

load(int)

Loads basic-stimulation configuration from the target device.

Declaration

public void load(int targetWSS)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

loadWaveform(string, int)

Loads a waveform file into the specified event slot.

Declaration

public void loadWaveform(string fileName, int eventID)

Parameters

Type	Name	Description
string	fileName	Waveform file path (as expected by the underlying WSS library).
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

releaseRadio()

Explicitly releases the active radio connection.

Declaration

public void releaseRadio()

Remarks

This is equivalent to calling Shutdown() and has the same blocking and idempotent behavior.

request_Configs(int, int, int)

Requests a configuration payload from the target device.

Declaration

public void request_Configs(int targetWSS, int command, int id)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
int	command	Command identifier (device-specific).
int	id	Config identifier (device-specific).

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

resetRadio()

Performs a radio reset by shutting down and re-initializing the connection.

Declaration

public void resetRadio()

Remarks

This method stops the current tick loop, reinitializes the underlying WSS stack in place, and then starts ticking again. If the controller has not been initialized yet, this method does nothing.

updateWaveform(int, int, int)

Updates an event shape using cathodic/anodic waveform identifiers on all devices.

Declaration

public void updateWaveform(int cathodicWaveform, int anodicWaveform, int eventID)

Parameters

Type	Name	Description
int	cathodicWaveform	Cathodic waveform identifier.
int	anodicWaveform	Anodic waveform identifier.
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

updateWaveform(int, int, int, int)

Updates an event shape using cathodic/anodic waveform identifiers on the target device.

Declaration

public void updateWaveform(int targetWSS, int cathodicWaveform, int anodicWaveform, int eventID)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
int	cathodicWaveform	Cathodic waveform identifier.
int	anodicWaveform	Anodic waveform identifier.
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

updateWaveform(int, int[], int)

Updates a waveform definition on the target device.

Declaration

public void updateWaveform(int targetWSS, int[] waveform, int eventID)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
int[]	waveform	Waveform samples (device-specific representation).
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

updateWaveform(int, WaveformBuilder, int)

Updates a waveform definition on the target device.

Declaration

public void updateWaveform(int targetWSS, WaveformBuilder waveform, int eventID)

Parameters

Type	Name	Description
int	targetWSS	0 = broadcast; 1-3 = specific device. Other values map to device 1.
WaveformBuilder	waveform	Waveform builder instance.
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

updateWaveform(int[], int)

Updates a waveform definition on all devices.

Declaration

public void updateWaveform(int[] waveform, int eventID)

Parameters

Type	Name	Description
int[]	waveform	Waveform samples (device-specific representation).
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.

updateWaveform(WaveformBuilder, int)

Updates a waveform definition on all devices.

Declaration

public void updateWaveform(WaveformBuilder waveform, int eventID)

Parameters

Type	Name	Description
WaveformBuilder	waveform	Waveform builder instance.
int	eventID	Event identifier to update.

Remarks

If the basic-stimulation API is unavailable, including before initialization, this method logs an error and returns without throwing.