radiens_core.allego_client

AllegoClient — real-time data acquisition client.

Attributes

Classes

AllegoClient

Bases: BaseClient

Client for real-time data acquisition and streaming.

Auto-discovers running servers. Falls back to well-known allego ports if server discovery is unavailable (no radiensserver running).

Usage::

with AllegoClient() as client:
    params = client.get_stim_params()

Functions

close

close()

Close all gRPC channels managed by this client.

disable_all_triggers

disable_all_triggers()

Disable all trigger channels simultaneously.

Sends the T_NONE sentinel to the hardware, which instructs it to clear all active trigger channel assignments.

Raises:

Type	Description
RadiensError	On communication failure or server error.

disable_trigger

disable_trigger(*, channel, port=None)

Disable a specific digital trigger channel.

Parameters:

Name	Type	Description	Default
channel	TriggerChannel	The digital input/output channel to disable. Must not be TriggerChannel.T_NONE — use :meth:disable_all_triggers to disable all triggers at once.	required
port	Port | None	Hardware port the channel belongs to. Only meaningful in split-ports mode. See :meth:enable_trigger for details.	None

Raises:

Type	Description
ValueError	If channel is TriggerChannel.T_NONE.
RadiensError	On communication failure or server error.

enable_trigger

enable_trigger(*, channel, port=None)

Enable a digital trigger channel to start or stop recording.

When enabled, a voltage transition on channel will automatically start or stop recording on the hardware.

Parameters:

Name	Type	Description	Default
channel	TriggerChannel	The digital input/output channel to use as a trigger. Must not be TriggerChannel.T_NONE — use :meth:disable_all_triggers to disable all triggers at once.	required
port	Port | None	Hardware port the channel belongs to. Only meaningful when the hardware is configured for split-ports mode (SplitFilesByPort). In standard single-port mode the server ignores this value and controls recording across all ports, so None is the correct default.	None

Raises:

Type	Description
ValueError	If channel is TriggerChannel.T_NONE.
RadiensError	On communication failure or server error.

flash_sinaps

flash_sinaps(bitfile)

Flash new firmware to the Sinaps probe FPGA.

Parameters:

Name	Type	Description	Default
bitfile	str	Path to the FPGA bitfile to flash.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_channel_metadata

get_channel_metadata()

Get current channel metadata for all connected channels.

Returns:

Type	Description
ChannelMetadata	Complete channel metadata including probe geometry, signal types,
ChannelMetadata	channel indices, and site positions for all channels.

Raises:

Type	Description
RadiensError	On communication failure or server error

get_core_config

get_core_config()

Get core hardware configuration settings.

Returns:

Type	Description
CoreConfig	Current core hardware configuration including sampling frequency,
CoreConfig	loop duration, and cable delays.

Raises:

Type	Description
RadiensError	On communication failure or server error

get_dac_reg

get_dac_reg()

Get current DAC (Analog Output) register settings.

Returns:

Type	Description
AnalogOutRegister	The complete DAC register state, including gain, high-pass
AnalogOutRegister	filter configuration, and channel mappings.

Raises:

Type	Description
RadiensError	On communication failure or server error

get_default_spike_sorter_id

get_default_spike_sorter_id()

Return the active spike sorter ID.

Allego runs a single sorter at a time. This is a convenience wrapper around get_spike_sorter_ids() that returns the first (and typically only) ID.

Returns:

Type	Description
str	The active spike sorter ID.

Raises:

Type	Description
RadiensError	If no spike sorter is currently active.

get_detect_params

get_detect_params(spike_sorter_id, channels=None)

Fetch active detection configurations per channel.

Parameters:

Name	Type	Description	Default
spike_sorter_id	str	Unique ID of the spike sorter.	required
channels	list[int] | None	Optional list of native channel indices. If None, returns params for all configured channels.	None

Returns:

Type	Description
dict[int, SpikeDetectParams]	Map from native channel index to its SpikeDetectParams.

get_dio_reg

get_dio_reg()

Get current DIO (Digital Output) register settings.

Returns:

Type	Description
DigitalOutRegister	The complete DIO register state, including current mode and
DigitalOutRegister	per-channel configurations.

Raises:

Type	Description
RadiensError	On communication failure or server error

get_dsp_group

get_dsp_group(
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Get current DSP filter configurations.

Parameters:

Name	Type	Description	Default
stream_group_id	str	The stream group to query (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

Returns:

Type	Description
DSPGroup	The current hardware and software filter parameters.

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_intan_impedance

get_intan_impedance(port)

Measure impedance for all channels on a specific port.

Parameters:

Name	Type	Description	Default
port	Port	The hardware port to measure (e.g., Port.A)	required

Returns:

Type	Description
Impedance	Impedance measurements for all channels on the specified port.

Raises:

Type	Description
RadiensError	On communication failure or server error

get_kpi_metrics

get_kpi_metrics(
    metrics,
    channel_indices=None,
    time_range=None,
    signal_type=SignalType.AMP,
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Retrieve computed KPI signal metrics from the live cache.

Parameters:

Name	Type	Description	Default
metrics	list[KpiMetricId]	List of KPI metric identifiers to compute.	required
channel_indices	list[int] | None	Native channel indices (ntvIdxs) to query. None returns metrics for all channels.	None
time_range	FlexTimeRange | None	Time range spec. Use [duration, float('nan')] for a lookback window or [start, end] for an absolute range. None defaults to a 5-second lookback window.	None
signal_type	SignalType	Signal type to query (default AMP).	AMP
stream_group_id	str	Stream group to query (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

Returns:

Type	Description
KpiMetricsResult	Metric values as a (n_channels, n_metrics) numpy array
KpiMetricsResult	with row/column labels.

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_kpi_status

get_kpi_status(
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Get the current KPI cache status.

Parameters:

Name	Type	Description	Default
stream_group_id	str	Stream group to query (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

Returns:

Type	Description
KpiStatus	Number of packets in cache, packet duration, update period,
KpiStatus	memory usage, and tracking state.

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_recording_config

get_recording_config()

Get current recording configuration settings.

Returns:

Type	Description
RecordingConfig	Current recording configuration including file paths, naming,
RecordingConfig	and recording type settings

Raises:

Type	Description
RadiensError	On communication failure or server error

get_signals

get_signals(time_range, signals=None)

Retrieve signal data from the primary live cache.

Parameters:

Name	Type	Description	Default
time_range	FlexTimeRange	Time range spec. Most common: TimeRangeSpec.lookback(5.0) or shorthand [duration, float('nan')]. Also accepts [start, end] for absolute SUBSET requests.	required
signals	FlexSignalSpec | None	Channel selection — list of amp indices, SignalSpec.amp([...]), or dict for multi-type. None returns all amplifier channels.	None

Returns:

Type	Description
SignalArrays	Signal data as numpy arrays (channels x samples).

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_sinaps_status_registers

get_sinaps_status_registers()

Get the current Sinaps probe status registers.

Returns:

Type	Description
SinapsStatusRegisters	Current status registers including calibration state, active pixel
SinapsStatusRegisters	counts per shank, reference voltages, error flags, and probe
SinapsStatusRegisters	identification information.

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_spike_sorter_dashboard

get_spike_sorter_dashboard(spike_sorter_id, elements=None)

Get the spike sorter dashboard for real-time monitoring.

Parameters:

Name	Type	Description	Default
spike_sorter_id	str	Unique ID of the spike sorter to query.	required
elements	list[DashElement] | None	Optional list of dashboard elements to include. If None, returns all default elements.	None

Returns:

Type	Description
SpikeSorterDashboard	Comprehensive dashboard data including summary metrics and port status.

get_spike_sorter_ids

get_spike_sorter_ids()

Get the IDs of all active spike sorters.

Returns:

Type	Description
list[str]	List of active spike sorter IDs.

get_spike_sorter_state

get_spike_sorter_state(spike_sorter_id)

Get the current state and progress of a spike sorter.

Parameters:

Name	Type	Description	Default
spike_sorter_id	str	Unique ID of the spike sorter to query.	required

Returns:

Type	Description
SpikeSorterState	Current state including system status, progress, and messages.

get_status

get_status()

Get comprehensive system status.

Returns:

Type	Description
BackboneStatus	Current streaming status, recording status, port information,
BackboneStatus	connection state, and GPIO channel counts.

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_stim_params

get_stim_params()

Get stimulation parameters for all configured channels.

Returns:

Type	Description
dict[int, StimParams]	Stimulation parameters keyed by system channel index (ntvAbsKeyIdx).

Raises:

Type	Description
RadiensError	On communication failure or server error.

get_stim_step

get_stim_step()

Get current stimulation step size setting.

Returns:

Type	Description
StimStepState	Current stimulation step configuration

Raises:

Type	Description
RadiensError	On communication failure or server error

get_trigger_state

get_trigger_state()

Get current trigger channel configuration.

Returns:

Type	Description
TriggerState	Current trigger state showing enabled channels and ports

Raises:

Type	Description
RadiensError	On communication failure or server error

healthcheck

healthcheck(service=ServiceEndpoint.ALLEGO_LIFECYCLE)

Perform lightweight system health verification.

Parameters:

Name	Type	Description	Default
service	ServiceEndpoint	Which gRPC service to probe. Defaults to ALLEGO_LIFECYCLE; ALLEGO_CORE is also supported.	ALLEGO_LIFECYCLE

Raises:

Type	Description
RadiensError	If the health check fails or the server is unresponsive.

load_all_mosi

load_all_mosi(register_vals)

Load all MOSI register values into the Sinaps probe.

Parameters:

Name	Type	Description	Default
register_vals	list[int]	List of 32-bit register values to load.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

manual_stim_trigger

manual_stim_trigger(request)

Manually trigger stimulation.

Deprecated

Use set_stim_trigger() instead.

Parameters:

Name	Type	Description	Default
request	ManualStimTriggerRequest	Manual trigger configuration	required

Raises:

Type	Description
RadiensError	On communication failure or server error

manual_stim_trigger_toggle

manual_stim_trigger_toggle(request)

Toggle manual stimulation trigger.

Deprecated

Use toggle_stim_trigger() instead.

Parameters:

Name	Type	Description	Default
request	ManualStimTriggerToggleRequest	Manual trigger toggle configuration	required

Raises:

Type	Description
RadiensError	On communication failure or server error

read_wire_out

read_wire_out(wire_out_address)

Read a wire-out register value from the Sinaps FPGA.

Parameters:

Name	Type	Description	Default
wire_out_address	int	Address of the wire-out register to read.	required

Returns:

Type	Description
int	Integer value read from the specified wire-out register.

Raises:

Type	Description
RadiensError	On communication failure or server error.

restart

restart(*, mode)

Restart the system with the specified backbone mode.

Parameters:

Name	Type	Description	Default
mode	BackboneMode	The backbone hardware mode to restart with.	required

Raises:

Type	Description
RadiensError	If the restart fails.

scan_ports

scan_ports()

Scan all hardware ports to determine connected headstages and probes.

Returns:

Type	Description
ChannelMetadata	Updated channel metadata based on the newly discovered hardware.

Raises:

Type	Description
RadiensError	On communication failure or server error

set_core_config

set_core_config(request)

Update core hardware configuration settings.

Deprecated

Use update_core_config() instead.

Parameters:

Name	Type	Description	Default
request	SetCoreConfigRequest	Configuration parameters to update.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_dac_gain

set_dac_gain(gain)

Set DAC (Analog Output) gain.

Parameters:

Name	Type	Description	Default
gain	int	The gain value to set.	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dac_highpass

set_dac_highpass(enable, cutoff_freq)

Configure DAC (Analog Output) high-pass filter.

Parameters:

Name	Type	Description	Default
enable	bool	Whether to enable the high-pass filter.	required
cutoff_freq	float	The cutoff frequency in Hz.	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dac_off

set_dac_off()

Turn off all DAC (Analog Output) streams.

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dac_stream

set_dac_stream(dac_idx, ntv_chan_idx)

Map a source channel to a DAC (Analog Output) channel.

Parameters:

Name	Type	Description	Default
dac_idx	int	The DAC channel index to configure.	required
ntv_chan_idx	int	The source channel index to output.	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_detect_params

set_detect_params(spike_sorter_id, params, channels)

Bulk-apply threshold, shadow, and window updates to targeted channels.

Fields in params that are None will not be modified.

Parameters:

Name	Type	Description	Default
spike_sorter_id	str	Unique ID of the spike sorter.	required
params	SpikeDetectParams	The detection parameters to apply.	required
channels	list[int]	List of native channel indices to apply the parameters to.	required

set_dio_events

set_dio_events(chan_idx, threshold, polarity)

Configure DIO channel to trigger on analog threshold crossings.

Parameters:

Name	Type	Description	Default
chan_idx	int	Native channel index.	required
threshold	float	Event threshold in microvolts (μV).	required
polarity	bool	Event polarity (True for positive-going, False for negative-going).	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dio_gated

set_dio_gated(polarity)

Set DIO gated mode polarity.

Parameters:

Name	Type	Description	Default
polarity	bool	Gated polarity (True for high-active, False for low-active).	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dio_manual

set_dio_manual(chan_idx, state)

Set DIO channel state manually.

Note

The DIO mode must be set to MANUAL for this to take effect.

Parameters:

Name	Type	Description	Default
chan_idx	int	Native channel index.	required
state	bool	Desired state (True for high, False for low).	required

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dio_pulse

set_dio_pulse(interval_sec, duration_sec, chan_idx=-1)

Configure DIO channel(s) for pulse mode.

Parameters:

Name	Type	Description	Default
interval_sec	float	Pulse interval in seconds.	required
duration_sec	float	Pulse duration in seconds.	required
chan_idx	int	Native channel index (-1 for all channels).	-1

Raises:

Type	Description
RadiensError	On communication failure or server error

set_dsp_group

set_dsp_group(
    *,
    stage,
    params,
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Update DSP filter configuration for a specific stage.

The server applies per-stage partial updates rather than replacing the full DSPGroup. Use get_dsp_group() to read the current state before making targeted changes.

Parameters:

Name	Type	Description	Default
stage	FilterStage	The filter stage to update (e.g. FilterStage.STAGE1).	required
params	list[DSPParams]	Filter parameters for this stage.	required
stream_group_id	str	The stream group to update (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

set_kpi_packet_dur

set_kpi_packet_dur(
    packet_dur,
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Set the KPI packet duration (integration window).

Parameters:

Name	Type	Description	Default
packet_dur	float	Duration of each KPI packet in seconds.	required
stream_group_id	str	Stream group to configure (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_kpi_update_period

set_kpi_update_period(
    update_period,
    stream_group_id=PRIMARY_CACHE_STREAM_GROUP_ID,
)

Set how often the KPI cache is refreshed from the live signal stream.

Parameters:

Name	Type	Description	Default
update_period	float	Update interval in seconds.	required
stream_group_id	str	Stream group to configure (default "default").	PRIMARY_CACHE_STREAM_GROUP_ID

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_record_state

set_record_state(request)

Set data recording state.

Deprecated

Use start_recording() or stop_recording() instead.

Parameters:

Name	Type	Description	Default
request	RecordStateRequest	Record state configuration specifying the desired mode and optional port	required

Raises:

Type	Description
RadiensError	If the record state change fails

set_recording_config

set_recording_config(config)

Set recording configuration settings.

Deprecated

Use update_recording_config() instead.

Parameters:

Name	Type	Description	Default
config	RecordingConfig	Recording configuration.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_stim_params

set_stim_params(params)

Update stimulation parameters for specified channels.

Parameters:

Name	Type	Description	Default
params	dict[int, StimParams]	Map from system channel indices to their new stimulation parameters. Each StimParams defines waveform shape, timing, amplitudes, trigger settings, pulse trains, and recovery parameters for that channel.	required

Raises:

Type	Description
RadiensError	On communication failure or server error

Note

The underlying gRPC API sets parameters for one channel at a time. This method calls SetStimParams once per channel in the provided dictionary.

Usage

Update stimulation parameters for multiple channels::

# Define stimulation parameters
stim_params = StimParams(
    stim_shape=StimShape.BIPHASIC,
    stim_polarity=StimPolarity.CATHODIC_FIRST,
    first_phase_duration=100.0,  # 100 µs
    second_phase_duration=100.0,  # 100 µs
    interphase_delay=50.0,  # 50 µs
    first_phase_amplitude=100.0,  # 100 µA
    second_phase_amplitude=-100.0,  # 100 µA (opposite polarity)
    baseline_voltage=0.0,
    trigger_edge_or_level=StimTriggerEdge.EDGE,
    trigger_high_or_low=StimTriggerLevel.HIGH,
    enabled=True,
    post_trigger_delay=1000.0,  # 1 ms = 1000 µs
    pulse_or_train=StimPulseMode.SINGLE_PULSE,
    number_of_stim_pulses=1,
    pulse_train_period=20000.0,  # 20 ms = 50 Hz
    refractory_period=10000.0,  # 10 ms
    pre_stim_amp_settle=1000.0,  # 1 ms
    post_stim_amp_settle=1000.0,  # 1 ms
    maintain_amp_settle=False,
    enable_amp_settle=True,
    post_stim_charge_recov_on=1000.0,  # 1 ms
    post_stim_charge_recov_off=0.0,
    enable_charge_recovery=True,
    trigger_source_is_keypress=False,
    trigger_source_idx=0,
    stim_sys_chan_idx=42,
)

# Update channels 42 and 43
client.set_stim_params({
    42: stim_params,
    43: stim_params.model_copy(update={'first_phase_amplitude': 150.0}),
})

set_stim_step

set_stim_step(*, step)

Set the stimulation step size.

Parameters:

Name	Type	Description	Default
step	StimStep	The stimulation step size to set.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_stim_trigger

set_stim_trigger(*, trigger, on)

Set the state of a stimulation keypress trigger.

Parameters:

Name	Type	Description	Default
trigger	StimKeypressIndex	The keypress trigger index (1-8).	required
on	bool	True to activate the trigger, False to deactivate.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

set_stream_state

set_stream_state(request)

Set data streaming state.

Deprecated

Use start_streaming() or stop_streaming() instead.

Parameters:

Name	Type	Description	Default
request	StreamStateRequest	Stream state configuration specifying the desired mode	required

Raises:

Type	Description
RadiensError	If the stream state change fails

set_trigger_state

set_trigger_state(*, channel, enabled, port)

Set trigger channel state for stimulation control.

.. deprecated:: Use :meth:enable_trigger, :meth:disable_trigger, or :meth:disable_all_triggers instead.

Parameters:

Name	Type	Description	Default
channel	TriggerChannel	Trigger channel identifier.	required
enabled	bool	Whether the channel should be enabled.	required
port	Port	Hardware port identifier.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

spike_sorter_command

spike_sorter_command(
    spike_sorter_id,
    cmd,
    *,
    sub_cmd=SpikeSorterSubCommand.NULL,
    clusterer_params=None,
    feature_params=None,
)

Send a command to an active spike sorter.

Parameters:

Name	Type	Description	Default
spike_sorter_id	str	Unique ID of the spike sorter to control.	required
cmd	SpikeSorterCommand	The command to execute (e.g., ON, OFF, REBASE).	required
sub_cmd	SpikeSorterSubCommand	Optional sub-command (e.g., DETECT_ONLY).	NULL
clusterer_params	SpikeSorterClustererParams | None	Optional parameters for the clustering algorithm.	None
feature_params	SpikeSorterFeatureParams | None	Optional parameters for feature extraction.	None

start_recording

start_recording(*, port=None)

Start recording data to disk.

Parameters:

Name	Type	Description	Default
port	Port | None	Optional port to start recording on. If omitted, applies system-level control.	None

Raises:

Type	Description
RadiensError	If the record state change fails.

start_streaming

start_streaming()

Start data streaming from the hardware.

Raises:

Type	Description
RadiensError	If the stream state change fails.

stop_recording

stop_recording(*, port=None)

Stop recording data to disk.

Parameters:

Name	Type	Description	Default
port	Port | None	Optional port to stop recording on. If omitted, applies system-level control.	None

Raises:

Type	Description
RadiensError	If the record state change fails.

stop_streaming

stop_streaming()

Stop data streaming from the hardware.

Raises:

Type	Description
RadiensError	If the stream state change fails.

toggle_stim_trigger

toggle_stim_trigger(*, trigger)

Toggle a stimulation keypress trigger.

Parameters:

Name	Type	Description	Default
trigger	StimKeypressIndex	The keypress trigger index (1-8) to toggle.	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

transmit_mosi

transmit_mosi()

Transmit the loaded MOSI registers to the Sinaps probe.

Raises:

Type	Description
RadiensError	On communication failure or server error.

update_core_config

update_core_config(
    *,
    samp_freq=None,
    loop_dur=None,
    pcache_persistence=None,
    cable_delay=None,
)

Update core hardware configuration settings.

All parameters are optional — only the fields you supply are changed. Fields left as None are not sent to the server and remain unchanged.

Parameters:

Name	Type	Description	Default
samp_freq	float | None	Target sampling frequency in Hz.	None
loop_dur	float | None	Target stream loop duration in milliseconds.	None
pcache_persistence	float | None	PCache persistence duration.	None
cable_delay	CableDelay | None	Cable delay configuration for a specific port.	None

Raises:

Type	Description
RadiensError	On communication failure or server error.

update_recording_config

update_recording_config(config)

Update recording configuration settings.

The server applies the provided config as a partial update — only the fields present in config are changed. Retrieve the current config with get_recording_config(), modify the fields you need, and pass it back here.

Parameters:

Name	Type	Description	Default
config	RecordingConfig	Recording configuration specifying file paths, naming, and recording type (continuous/spikes/both).	required

Raises:

Type	Description
RadiensError	On communication failure or server error.

Example

Update the output directory while keeping other settings::

config = client.get_recording_config()
config = config.model_copy(update={"base_file_path": "/new/path"})
client.update_recording_config(config)

Functions