Context#

class oni.Context : IDisposable#

Open Neuro Interface (ONI) compliant acquisition context.

Public Functions

Context (string driver, int index)#

Initializes a new instance of Context with the specified hardware translation driver and host hardware index.

Param driver:

A string specifying the device driver used by the context to control hardware. This string corresponds a compiled implementation of onidriver.h that has the name onidriver_<drv_name>.so/dll.

Param index:

An index specifying the physical location within the host that the host hardware resides. A value of -1 will use the default location.

Throws System.InvalidProgramException:

Thrown when the specified driver cannot be found or is invalid.

Throws ONIException:

Thrown when there is an error during hardware initialization (e.g. an invalid device table).

void SetCustomOption (int option, int value)#

Set an the value of implementation-specific context option (those beyond ONI-specified options).

Param option:

Implementation-specific option to set.

Param value:

Option value

int GetCustomOption (int option)#

Retrieve the value of an implementation-specific context option.

Param option:

Context option to retrieve.

Throws ONIException:

Thrown when option is invalid.

Return:

Value of the context option.

void Start (bool reset_frame_clock = true)#

Start data acquisition.

Param reset_frame_clock:

If true, the acquisition clock counter is reset synchronously to the start of data acquisition in hardware (see AcquisitionClockHz). This is equivalent to calling this function and ResetFrameClock at precisely the same moment, which is impossible in software.

void Stop ()#

Stop data acquisition.

void ResetFrameClock ()#

Reset the acquisition clock counter to 0 (AcquisitionClockHz).

uint ReadRegister (uint dev_index, uint register_address)#

Read the value of a configuration register from a specific device within the current oni.Context.DeviceTable. This can be used to verify the success of calls to Context.ReadRegister(uint, uint) or to obtain state information about devices managed by the current acquisition context. Register specifications (addresses, read- and write-access, and descriptions are provided on the ONI-device datasheet).

Param dev_index:

Fully-qualified device index within the Context.DeviceTable

Param register_address:

Address of register to be read.

Throws ONIException:

Thrown if the device and/or register address in invalid or if register is write only.

Return:

Value of the register.

void WriteRegister (uint dev_index, uint register_address, uint value)#

Change the value of a configuration register from specific devices within the current Context.DeviceTable. Register specifications (addresses, read- and write-access, acceptable values, and descriptions are provided on the ONI device datasheet).

Param dev_index:

Fully-qualified device index within the Context.DeviceTable

Param register_address:

Address of register to write to.

Param value:

Value to write to the register.

Throws ONIException:

Thrown if the device and/or register address in invalid or if register is read only.

Frame ReadFrame ()#

Read a device data frame from the high-bandwidth data input channel. This call will block until either enough data available on the stream to construct an underlying block buffer (see Context.BlockReadSize). This function is zero-copy.

Throws ONIException:

Thrown if there is an error reading a frame.

Return:

A device data frame.

void Write<T> (uint dev_index, T value)#

Write a single value to a particular device within the Context.DeviceTable using the high-bandwidth output channel.

Tparam T:

Type of the value to be written. Must be an unmanaged type.

Param dev_index:

Fully-qualified device index within the oni.Context.DeviceTable

Param value:

Value to write to the device.

Throws ONIException:

Throw if data is an invalid size or the selected device does not accept write data.

void Write<T> (uint dev_index, T[] data)

Write an array to a particular device within the Context.DeviceTable using the high-bandwidth output channel.

Tparam T:

Type of the value to be written. Must be an unmanaged type.

Param dev_index:

Fully-qualified device index within the Context.DeviceTable

Param data:

Data array to write to the device.

Throws ONIException:

Throw if data array is an invalid size or the selected device does not accept write data.

void Write (uint dev_index, IntPtr data, int data_size)

Write data at an IntPtr to a particular device within the Context.DeviceTable using the high-bandwidth output channel.

Param dev_index:

Fully-qualified device index within the Context.DeviceTable

Param data:

Pointer to data to write to the device.

Param data_size:

Size of data pointed to by data in bytes.

Throws ONIException:

Throw if data_size is an invalid size or the selected device does not accept write data.

void Dispose ()#

Dispose this Context.

Hub GetHub (uint device_address)#

Retrieve the hub that a given Device resides in.

Param device_address:

The fully specified Device.Address to retrieve the hub for.

Return:

A Hubcontaining hub metadata.

Public Members

readonly uint SystemClockHz#

Host system clock frequency in Hz. This describes the frequency of the clock governing the host hardware.

readonly uint AcquisitionClockHz#

Host system acquisition clock frequency in Hz, derived from SystemClockHz. This describes the frequency of the clock used to drive the acquisition counter which is used timestamp data frames.

readonly uint MaxReadFrameSize#

The maximal size of a frame produced by a call to ReadFrame in bytes. This number is the maximum sized frame that can be produced across every device within the device table that generates read data.

readonly uint MaxWriteFrameSize#

The maximal size of consumed by a call to Write in bytes. This number is the maximum sized frame that can be consumed across every device within the device table that accepts write data.

readonly Dictionary<uint, Device> DeviceTable#

ONI specified device table containing the full device hierarchy governed by this acquisition context. This IDictionary maps a fully-qualified Device.Address to a Device instance.

Properties

bool Running { get; set; }#

Indicates whether or not data acquisition is running.

int HardwareAddress { get; set; }#

The address of the host hardware within the acquisition computer. Determines the synchronization role of the hardware in multi-host systems.

int BlockReadSize { get; set; }#

Number of bytes read during each driver access to the high-bandwidth read channel using Context.ReadFrame. This option allows control over a fundamental trade-off between closed-loop response time and overall bandwidth. The minimum (default) value will provide the lowest response latency. Larger values will reduce syscall frequency and may improve processing performance for high-bandwidth data sources. This minimum size of this option is determined by Context.MaxReadFrameSize.

int BlockWriteSize { get; set; }#

Number of bytes pre-allocated for calls to Write<T>(uint, T), Write<T>(uint, T[]), and Write(uint, IntPtr, int). A larger size will reduce the average amount of dynamic memory allocation system calls but increase the cost of each of those calls. The minimum size of this option is determined by Context.MaxWriteFrameSize.