Skip to content

Commit 2703fda

Browse files
cjshajonnew
andauthored
Deprecate Bonsai.Onix Library (#62)
* Deprecate Bonsai.Onix Library - Add deprecation-notice.rst to every page in the Bonsai.ONIX directory - Modify TOC to put Bonsai.ONIX as last entry, mark it as deprecated, and replace with OpenEphys.Onix1 to improve clarity - Add section for OpenEphys.Onix1 under Bonsai page - Clarifications to general docs content - "library" -> "package" --------- Co-authored-by: jonnw <[email protected]>
1 parent 9efa668 commit 2703fda

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+669
-411
lines changed

source/Getting Started/index.rst

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Usage Warnings
3434

3535
Read :ref:`Usage Warnings<warnings>` before starting to work with the system to avoid causing damage to system components.
3636

37-
Setting up ONIX
37+
Setting up your system
3838
--------------------------------
3939

4040
#. Check that you have all the necessary hardware. A full ONIX setup consists of:
@@ -69,11 +69,8 @@ Setting up ONIX
6969
:ref:`following these steps <headstage_setup>`. Be sure to read :ref:`this
7070
page on the voltage supplied to the headstage <tether_voltage>` to prevent
7171
damaging your headstage.
72-
#. Test the installation.
73-
74-
.. todo:: Bonsai workflows for testing each component
7572

7673
Using ONIX
7774
--------------------------------
78-
ONIX uses Bonsai for data acquisition. See the :ref:`bonsai_gettingstarted`
79-
page to learn how to install Bonsai and use it to acquire from ONIX.
75+
Have a look at the :ref:`software_guide` page to explore
76+
software options and for intefacing with ONIX hardware.

source/Getting Started/warnings.rst

Lines changed: 17 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -5,80 +5,31 @@
55

66
Usage Warnings
77
==========================================
8+
89
.. warning:: Improper setup and usage can cause damage to system components.
910

10-
- Read the following warnings before starting to work with your system. These are crucial
11-
aspects to consider during setup and usage that are included in the documentation but
12-
are listed here for your convenience.
13-
- Read the complete documentation carefully to understand how the system works and refer
14-
back to these warnings before using it.
11+
- Read the following warnings before starting to work with your system. These
12+
are crucial aspects to consider during setup and usage that are included in
13+
the documentation but are listed here for your convenience.
14+
- Read the complete documentation carefully to understand how the system works
15+
and refer back to these warnings before using it.
1516

16-
Hardware
17+
Breakout Board
1718
--------------------------------
18-
- Connecting or disconnecting the breakout board while the PC is on causes damage to the
19-
FMChost. For more details, see :ref:`breakout_setup`.
20-
21-
.. warning::
22-
**Power off the PC before connecting/disconnecting the breakout board.**
2319

24-
- Headstage voltage must be configured correctly for operation. The voltage that works
25-
for one headstage can damage another, and depends on your hardware configuration such
26-
as tether length. For more details, see :ref:`tether_voltage`.
27-
28-
.. warning::
29-
**Ensure each headstage is configured with the correct voltage according to its
30-
specification before connecting and switching on the headstage port switch.**
20+
.. warning:: Connecting or disconnecting the :ref:`breakout` while the PC is on
21+
can damage to the :ref:`pcie_host`. For more details, see
22+
:ref:`breakout_setup`. **Power off the PC before connecting/disconnecting the
23+
breakout board.**
3124

32-
33-
Software
25+
Headstage Voltages
3426
--------------------------------
35-
*For the current Bonsai.ONIX library which is being revised to improve usability*
36-
37-
- Headstage port voltage configuration is managed via the :ref:`bonsai_onicontext` node
38-
or the :ref:`bonsai_headstageportcontroldev` node. The changes you make using these
39-
nodes apply immediately and persist in hardware even if the Bonsai workflow is not
40-
running. Headstage port voltage is reset to the default 4.9V only on a power cycle
41-
(power off and on — not reboot).
4227

4328
.. warning::
44-
**Keep the headstage port switches off until you have configured each port correctly.**
45-
46-
.. warning::
47-
**Remember to set the headstage voltage to the desired value after a power cycle.**
48-
49-
- The :ref:`bonsai_onicontext` provides a dynamic window to read and write to hardware,
50-
but parameters such as device voltage are not saved in the node when the workflow is
51-
saved. The :ref:`bonsai_headstageportcontroldev` node also reads and writes to hardware,
52-
but parameters are saved with the workflow. On loading a workflow, Bonsai writes the
53-
parameter values set when the workflow was last saved.
29+
**Ensure each headstage is configured with the correct voltage.** Although
30+
headstages are quite tolerate of over-voltage and under-voltage conditions,
31+
they are only guaranteed to function within a specified range. When using
32+
long and/or thin tethers, the voltage drop across the cable can become
33+
significant. For more details, see :ref:`tether_voltage`.
5434

55-
.. warning::
56-
When you configure the voltage, the :ref:`bonsai_onicontext` node shows that value
57-
and when you save the workflow this value is not saved. Therefore, that value will
58-
not be set to hardware when you load the workflow again. On loading the workflow,
59-
the :ref:`bonsai_onicontext` node will be reading the voltage that is already set
60-
on the hardware and showing this in the ``LinkVoltage`` field.
61-
62-
.. warning::
63-
When you configure the voltage, the :ref:`bonsai_headstageportcontroldev` node shows
64-
that value and when you save the workflow this value is saved. Therefore, that value
65-
will be set to hardware when you load the workflow again. If you make changes to the
66-
voltage value (with any node) and save the workflow, they will be saved in the
67-
``LinkVoltage`` property of the :ref:`bonsai_headstageportcontroldev` node.
68-
69-
- Any workflows containing the :ref:`bonsai_NeuropixelsV1edev` node require the
70-
:ref:`headstage_neuropix1e` to be connected before the workflows can be opened or
71-
loaded into Bonsai.
72-
73-
.. warning::
74-
Check that the voltage set to the headstage port is correct for the
75-
:ref:`headstage_neuropix1e` by using a workflow of a single :ref:`bonsai_onicontext`
76-
node to configure it before connecting the headstage in order to open a workflow that
77-
contains the :ref:`bonsai_NeuropixelsV1edev` node.
78-
79-
- An :ref:`bonsai_onicontext` node or any device node in a workflow can override device
80-
settings in another workflow if device addresses are not distinct, because these nodes
81-
read/write directly to hardware.
8235

83-
.. warning::
84-
**Only have one workflow open at a time.**

source/Getting Started/whatisonix.rst

Lines changed: 36 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66
What is ONIX?
77
==========================================
88
ONIX is a data acquisition system for neuroscience, composed of various pieces
9-
of hardware. ONIX differs from other acquisition systems in three major points:
9+
of hardware. ONIX differs from other acquisition systems in three ways:
1010

11-
1. Standards
11+
1. Standards & Interoperability
1212
--------------------------------
1313
All acquisition systems follow specific sets of rules that outline how data is
1414
structured and transmitted between parts of the system. For instance, Intan
@@ -32,21 +32,21 @@ money purchasing separate acquisition systems for each extra tool they wish to
3232
add to their experiment. Additionally, for those who want to develop new tools
3333
to study the brain, ONIX provides a powerful hardware backend and software
3434
infrastructure that can be reused to control almost any type of recoding
35-
instrument.
35+
instrument.
3636

37-
2. Tethers
38-
--------------------------------
37+
2. Thin Tethers & Zero Torque Commutation
38+
-------------------------------------------
3939
There is a growing appreciation of experiments that examine the natural
4040
behaviours of animals. This often means using larger and more intricate
4141
(perhaps 3D) experimental setups. It also means that the animal should be
4242
impaired as little as possible by the recording setup. To achieve this it is of
4343
course important to reducing the weight of the headstage, but the weight of the
4444
tether that connects the headstage to the acquisition system is often
45-
overlooked. As the animal explores the arena, the centre of mass of the tether
45+
overlooked. As the animal explores the arena, the center of mass of the tether
4646
is rarely directly above the animal. Instead, it is off to one side,
47-
introducing a rotational force on the animal. The animal must compensate for
48-
this torque in order to keep its head up straight. Because the ONI
49-
specification allows communication over a single wire, ONIX uses a single
47+
introducing a rotational force (torque) on the animal. The animal must
48+
compensate for this torque in order to keep its head up straight. Because the
49+
ONI specification allows communication over a single wire, ONIX uses a single
5050
coaxial cable, making ONIX tethers lighter and thinner compared to classic
5151
acquisition systems. ONIX tethers are 0.1 to 0.4 mm in diameter and are
5252
extremely flexible.
@@ -56,28 +56,37 @@ becoming twisted. Commutators are hardware devices that allow the tether to
5656
rotate while maintaining an electrical connection to the rest of the path to
5757
the acquisition system. As the animal moves through the arena, the ONIX
5858
commutator receives 3D tracking information from the headstage and drives a
59-
motor to actively rotate the tether, preventing twisting.
59+
motor to actively rotate the tether, preventing twisting. Importantly, this
60+
process is driven by real-time measurement of headstage rotation, *not by
61+
torque transmitted by the tether*. This allows nearly zero-torque commutation
62+
and the use of tethers that are so thin, they would not not function in systems
63+
that require torque measurements to drive active commutation.
6064

61-
3. Latencies
65+
3. Low Latencies
6266
--------------------------------
6367
In closed-loop experiments, data is not only acquired, but also processed and
6468
acted upon. For instance, one can provide optogenetic stimulation to a brain
6569
area every time a certain type of event is detected by an extracellular probe.
6670
The closed-loop latency of the acquisition system describes how much time
67-
passes between the initial event and the response of the system. In classic
68-
acquisition systems, this time is primarily spent on transmitting and
69-
processing acquired data, which becomes more and more challenging as the number
70-
of channels on a probe increases. A short latency allows the user to respond on
71-
the timescale of the biological event; for instance, within the integration
72-
window of a neuron.
71+
passes between the physical event and the response of the real-time system. A
72+
short latency allows the user to respond on the timescale of the biological
73+
event; for instance, within the integration window of a neuron.
74+
75+
Many acquisition systems rely on a USB connection between the acquisition board
76+
and PC. Or, they rely on closed-source 3rd-party drivers and APIs that are not
77+
optimized for low response latencies. The slower transfer characteristics of
78+
USB means that a typical closed-loop latency is in the range of several
79+
to tens of milliseconds. This is a considerable duration for the brain, as it
80+
is notably longer than the average action potential duration of around 1 ms. On
81+
average, ONIX provides much shorter latencies, of around 150 microseconds, because:
82+
83+
- ONIX is transfers data to the host computer without the CPU via DMA over PCIe.
84+
- ONIX uses a custom device driver optimized for low latency.
85+
- The ONI API allows explicit control over a single parameter to governs the
86+
trade off between data latency and overall bandwidth.
7387

74-
Many classic acquisition systems rely on a USB connection between the
75-
acquisition board and PC. The slower transfer characteristics of USB means that
76-
a typical closed-loop latency would be in the range of several to tens of
77-
milliseconds. This is a considerable duration for the brain, as it is notably
78-
longer than the average action potential duration of around 1 ms. ONIX has much
79-
shorter latencies, of around 150 microseconds, because the host board of ONIX
80-
is directly connected to the acquisition PC, in a PCIe slot. This means that
81-
the system can respond quickly to detected events. It also means that time is
82-
freed up for this detection itself; by reducing the overhead time, more complex
83-
analysis can be run to extract the phenomenon you are interested in.
88+
This permits the user to optimize their system's response time for a given
89+
experiment. In all, this means that the system can respond quickly to detected
90+
events. It also means that time is freed up for this detection itself; by
91+
reducing the overhead time, more complex analysis can be run to extract the
92+
phenomenon you are interested in.

source/Hardware Guide/Commutators/index.rst

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,16 @@
22

33
Coaxial Commutators
44
===================================
5-
Active, near-zero torque commutators to prevent tether twisting during
6-
freely moving recordings with headstages and/or miniscopes.
7-
This page provides a very brief overview of the commutators; for a more extensive
8-
walkthrough, please follow the documentation link for `Commutators <https://open-ephys.github.io/commutator-docs/index.html>`__.
5+
Active, near-zero torque commutators prevent tether twisting during freely
6+
moving recordings with headstages and/or miniscopes. This page provides a very
7+
brief overview of the commutators; for a more extensive walkthrough, please
8+
follow the documentation link for `Commutators
9+
<https://open-ephys.github.io/commutator-docs/index.html>`__.
910

1011
:Design Repository: https://github.com/open-ephys/commutators
11-
:Compatibility: :ref:`pcie_host`, :ref:`headstage_64`,
12-
:ref:`headstage_neuropix1`, :ref:`miniscopes`
12+
:Compatibility: All coaxial headstags (e.g. :ref:`headstage_64`,
13+
:ref:`headstage_neuropix2e`, :ref:`miniscopes`)
14+
:Documentation: https://open-ephys.github.io/commutator-docs/index.html
1315

1416
.. _commutators_overview:
1517

@@ -24,11 +26,11 @@ Overview
2426
ONIX uses an active commutator to prevents tether twisting during freely moving
2527
recordings. A inertial measurement unit (IMU) on the headstage or miniscope
2628
sends orientation data to the host computer. Because the real-time orientation
27-
of the animal is known, software (e.g. Bonsai) can be used to send commands to
28-
the commutator via its USB interface, and the motor in the commutator will turn
29-
when the animal does. A high-quality radio-frequency rotary joint inside the
30-
commutator maintains electrical connectivity for both power and high-frequency
31-
data signals between the tether leading to the headstage and the coaxial cable
29+
of the animal is known, software can be used to send commands to the commutator
30+
via its USB interface, and the motor in the commutator will turn when the
31+
animal does. A high-quality radio-frequency rotary joint inside the commutator
32+
maintains electrical connectivity for both power and high-frequency data
33+
signals between the tether leading to the headstage and the coaxial cable
3234
leading to the PCIe host board while turning.
3335

3436
Features

source/Hardware Guide/Datasheets/fmc-link-control.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ Description
1212
*******************************************
1313
The **FMC Host Link Controller** is used to control and monitor DS90UB9x-based
1414
serialized connections to hubs connected to a host such as headstages and
15-
miniscopes. It can control power provided to those hubs and receives RF lock,
16-
CRC error, and other information.
15+
miniscopes. It can control the voltage provided to those hubs and receives RF
16+
lock, CRC error, and other diagnostic information.
1717

1818
.. note::
1919

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
#################
2+
RHS2116 Headstage
3+
#################
4+
5+
.. image:: /_static/images/rhs2116/rhs2116.webp
6+
:align: center
7+
:height: 300px
8+
:alt: ONIX rhs2116
9+
10+
|
11+
12+
The RHS2116 Headstage is a serialized headstage for small animals with 32
13+
bi-direcional channels which each can be used to deliver electrical stimuli.
14+
The RHS2116 Headstage can be used with passive probes (e.g. silicon arrays, EEG/ECOG
15+
arrays, etc) using a 36-Channel Omnetics EIB.
16+
17+
********
18+
Features
19+
********
20+
21+
* Two RHS2116 ICs for a combined 32 bi-directional ephys channels
22+
* ~1 millisecond active stimuls artifact recovery
23+
* Max stimulator current: 2.55mA @ +/-7V compliance.
24+
* Sample rate: 30193.2367 Hz
25+
* Stimulus active and stimulus trigger pins
26+
* On-board Lattice Crosslink™ FPGA for real-time data arbitration
27+
28+
.. _rhs2116_data_link_serialization:
29+
30+
***********************
31+
Data Link Serialization
32+
***********************
33+
34+
For details on data serialization and headstage gateware, have a look at the
35+
:ref:`serialization` page, which describes how coax headstages operate in
36+
general terms. The RHS2116 headstage has the following coaxial link properties:
37+
38+
.. table::
39+
:widths: 50 80 50 50 50
40+
41+
+------------------------+--------------------+----------+----------+----------+
42+
| Parameter | Value | Min | Max | Unit/ |
43+
| | | | | Type |
44+
+========================+====================+==========+==========+==========+
45+
| FPGA | LIF-MD6000-6UMG64I | | | |
46+
+------------------------+--------------------+----------+----------+----------+
47+
| Serializer | TI DS90UB933 | | | Coaxial |
48+
+------------------------+--------------------+----------+----------+----------+
49+
| Supply Voltage | 4.0 | 3.4 | 5.0* | Volts |
50+
+------------------------+--------------------+----------+----------+----------+
51+
| Hub Clock Frequency | 50 | | | MHz |
52+
+------------------------+--------------------+----------+----------+----------+
53+
54+
.. warning:: \*Do not exceed 5.0 VDC at the coaxial input to the headstage.
55+
Make sure you make this measurement at the headstage (see
56+
:ref:`measure_voltage`) to account for a potential voltage drop in the
57+
tether.
58+
59+
.. note:: Have a look at the :ref:`tethers` page for more details on micro-coax
60+
headstage tethers
61+
62+
*****************
63+
Electrophysiology
64+
*****************
65+
66+
RHS2116 headstage uses two 16-channel `Intan RHS2116
67+
<https://intantech.com/>`__ bioamplifier chip. The chip is operated at a fixed
68+
sampling rate of ~30 kHz/channel. These 32 ephys channels are exposed via a 36
69+
pin `Omnetics connector
70+
<https://www.omnetics.com/wp-content/uploads/2022/01/A79025-001.pdf>`__ at the
71+
edge of the headstage and can record from most passive probes (e.g. tetrodes,
72+
silicon probe arrays, tungsten microwires, steel EEG wires, etc.) as well as
73+
stimulate.
74+
75+
..
76+
RHS2116 Pinout
77+
==============
78+
79+
.. image:: /_static/images/rhs2116/rhs2116-omnetics-pinout.webp
80+
:align: center
81+
:height: 300px
82+
:alt: ONIX rhs2116 omnetics
83+
84+
|
85+
86+
.. image:: /_static/images/rhs2116/rhs2116-bottom-pinout.webp
87+
:align: center
88+
:height: 300px
89+
:alt: ONIX rhs2116 bottom pinout
90+
91+
*****************
92+
Bill of Materials
93+
*****************
94+
95+
- `Interactive BoM <../../_static/boms/headstage-rhs2116_bom.html>`__ (a csv BoM can be downloaded from this page)
96+
97+
.. note:: Have a look at the :ref:`tether_voltage` page for more details on probing and verifying headstage power voltages

source/Hardware Guide/Headstages/index.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ Here you will find information on **ONIX headstages**.
1010
setup
1111
serialization
1212
tethers
13+
tether-voltage
1314
headstage-64/index
1415
headstage-neuropix-1
1516
headstage-neuropix-1e
1617
headstage-neuropix-2e-beta
1718
headstage-neuropix-2e
18-
rhs2116.rst
19-
tether-voltage
19+
headstage-rhs2116.rst
2020

2121
.. important:: ONIX expands the concept of a headstage compared to what you
2222
might be used to. ONIX headstages are head-borne systems of sensors and

0 commit comments

Comments
 (0)