onix-bonsai.md

uid	title
onix-bonsai	Configure Hardware and Stream Data

Tip

This page provides a description of how workflows involving OpenEphys.Onix1 work. When it comes to writing your own workflows, starting from example workflows for your hardware might be easier and faster than writing a workflow from scratch.

Construct Top-level Configuration Chain

Every workflow in Bonsai that is meant to work with ONIX hardware should contain a hardware configuration chain in its first row. This hardware configuration chain comprises of the following steps:

1. Creating a ONI context (an object that is capable of reading to and writing from ONIX hardware)
2. Writing properties to hardware
3. Starting acquisition

Create a context

An ONI context contains information about the device driver and index where the hardware which enables it to read from and write to hardware. To create a context, place a xref:OpenEphys.Onix1.CreateContext into the workflow. The context's device driver and index can be set by the user by editing CreateContext's properties. The Driver property is typically set to "riffa" which is the name of the PCIe device used by ONIX, and the Index property is typically set to 0 though using multiple ONIX systems on a single PC requires changing this value.

::: workflow :::

The context generated by CreateContext when the workflow starts is a data element named xref:OpenEphys.Onix1.ContextTask.

Configure hardware

Hardware configuration is performed when ContextTask passes through a configuration operator. A configuration operator allows the user to set the values that are written to hardware by editing its properties. There are two types of configuration operators: multi-device configuration operators and single-device configuration operators. Single-device configuration operators allow configuration of a single device contained by a headstage, miniscope, or breakout board whereas multi-device configuration operators allow configuration of all devices contained by a headstage, miniscope, or breakout board. We recommend using multi-device configuration operators for concision and ease-of-use, though single-device operators can be helpful in more advanced workflows that require writing to hardware while the workflow is running.

Any number of configuration operators can be chained following a CreateContext operator. If you use only multi-device configuration operators, you'll probably have between one and three total configuration operators: one for the breakout board and one for each port that is connected to a headstage or miniscope.

::: workflow :::

Start acquisition

The data acquisition process is started when ContextTask passes through xref:OpenEphys.Onix1.StartAcquisition. StartAcquisition allows the user to set parameters that are related to data acquisition such as ReadSize and WriteSize. Setting the ReadSize property for a particular workflow is a balancing act of minimizing latency of data from hardware to software while not letting the ONIX system's hardware buffer accumulate data to maximum capacity.

::: workflow :::

Acquire Data

Streaming data into Bonsai requires a xref:dataio.

Set up data I/O operators

Streaming data from the configured hardware/devices requires placing a data I/O operator and setting its DeviceName property for every device from which you would like to stream. Setting its DeviceName tells the operator from which device to stream data. In these docs, setting the DeviceName is referred to as linking the data I/O operator to a device. The value of each DeviceName property in the workflow must correspond to a device in the configuration chain. Take this workflow for example:

::: workflow :::

The DeviceName property of the AnalogInput operator is set to "BreakoutBoard/AnalogIO". This links the operator to the AnalogIO device on the Breakout Board meaning that the AnalogInput operator will streams data from that device.

Visualize & save data

Each OpenEphys.Onix1 data I/O operator produces a data frame whose members might contain multiple disparate data types. Select the data from the frame you want to save by following the member-selection section of the Visualize Data page.

To save data, place a writer operator (such as xref:Bonsai.Dsp.MatrixWriter, xref:Bonsai.IO.CsvWriter, or xref:Bonsai.Vision.VideoWriter) downstream/to the right of the operator that is producing data you want to save. For example:

::: workflow :::

Tip

• The recommended writer operator for saving particular data is used in the example workflow in the hardware guide for your hardware.
• Each hardware guide has a Python script to load and view data. You can use this is to load and view data from the example workflow or as a starting point for loading data from your own workflow.

Read the relevant sections of the Visualize Data page to visualize this data.

Use Multiple Instances of Identical Hardware

Multiple Headstages/Miniscopes

Linking the data I/O operator to devices when using two identical headstages or miniscopes involves an additional step: aliasing the multi-device configuration operator. Suppose you want to stream orientation data from two Headstage64s through the Bno055Data operator. By default, the ConfigureHeadstage64 operators are both named "Headstage64". This causes their devices to also have identical names, "Headstage64/Bno055". The two headstages and their devices must be disambiguated. The solution is to alias one or both headstages by editing their Name property.

::: workflow :::

In this workflow, each ConfigureHeadstage64 operator previously named "Headstage64" has been suffixed by the port to which the headstage is plugged. Now, the names "Headstage64A/Bno055" and "Headstage64B/Bno055" can be used when setting the DeviceName property in each Bno055Data operator.

Multiple ONIX Systems

If a second ONIX system is used on the same computer, a second configuration chain operator is required. In this case, the Index property of the configuration chain that corresponds to the second system should be set to 1.

::: workflow :::