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]>
open-ephys · Aug 9, 2024 · 2703fda · 2703fda
1 parent 9efa668
commit 2703fda
Show file tree

Hide file tree

Showing 52 changed files with 669 additions and 411 deletions.
diff --git a/source/Getting Started/index.rst b/source/Getting Started/index.rst
@@ -34,7 +34,7 @@ Usage Warnings
 
     Read :ref:`Usage Warnings<warnings>` before starting to work with the system to avoid causing damage to system components.
 
-Setting up ONIX
+Setting up your system
 --------------------------------
 
 #. Check that you have all the necessary hardware. A full ONIX setup consists of:
@@ -69,11 +69,8 @@ Setting up ONIX
    :ref:`following these steps <headstage_setup>`. Be sure to read :ref:`this
    page on the voltage supplied to the headstage <tether_voltage>` to prevent
    damaging your headstage.
-#. Test the installation.
-
-   .. todo:: Bonsai workflows for testing each component 
 
 Using ONIX
 --------------------------------
-ONIX uses Bonsai for data acquisition. See the :ref:`bonsai_gettingstarted`
-page to learn how to install Bonsai and use it to acquire from ONIX.
+Have a look at the :ref:`software_guide` page to explore
+software options and for intefacing with ONIX hardware.
diff --git a/source/Getting Started/warnings.rst b/source/Getting Started/warnings.rst
@@ -5,80 +5,31 @@
 
 Usage Warnings
 ==========================================
+
 .. warning::  Improper setup and usage can cause damage to system components.
 
-- Read the following warnings before starting to work with your system. These are crucial 
-  aspects to consider during setup and usage that are included in the documentation but 
-  are listed here for your convenience.
-- Read the complete documentation carefully to understand how the system works and refer 
-  back to these warnings before using it. 
+    - Read the following warnings before starting to work with your system. These
+      are crucial aspects to consider during setup and usage that are included in
+      the documentation but are listed here for your convenience.
+    - Read the complete documentation carefully to understand how the system works
+      and refer back to these warnings before using it.
 
-Hardware
+Breakout Board
 --------------------------------
-- Connecting or disconnecting the breakout board while the PC is on causes damage to the 
-  FMChost. For more details, see :ref:`breakout_setup`.
-
-.. warning::
-   **Power off the PC before connecting/disconnecting the breakout board.**
 
-- Headstage voltage must be configured correctly for operation. The voltage that works 
-  for one headstage can damage another, and depends on your hardware configuration such 
-  as tether length. For more details, see :ref:`tether_voltage`.
-
-.. warning::
-   **Ensure each headstage is configured with the correct voltage according to its 
-   specification before connecting and switching on the headstage port switch.** 
+.. warning:: Connecting or disconnecting the :ref:`breakout` while the PC is on
+    can damage to the :ref:`pcie_host`. For more details, see
+    :ref:`breakout_setup`. **Power off the PC before connecting/disconnecting the
+    breakout board.**
 
-
-Software
+Headstage Voltages
 --------------------------------
-*For the current Bonsai.ONIX library which is being revised to improve usability*
-
-- Headstage port voltage configuration is managed via the :ref:`bonsai_onicontext` node 
-  or the :ref:`bonsai_headstageportcontroldev` node. The changes you make using these 
-  nodes apply immediately and persist in hardware even if the Bonsai workflow is not 
-  running. Headstage port voltage is reset to the default 4.9V only on a power cycle 
-  (power off and on — not reboot).
 
 .. warning::
-   **Keep the headstage port switches off until you have configured each port correctly.**
-
-.. warning::
-   **Remember to set the headstage voltage to the desired value after a power cycle.**
-
-- The :ref:`bonsai_onicontext` provides a dynamic window to read and write to hardware,
-  but parameters such as device voltage are not saved in the node when the workflow is 
-  saved. The :ref:`bonsai_headstageportcontroldev` node also reads and writes to hardware, 
-  but parameters are saved with the workflow. On loading a workflow, Bonsai writes the 
-  parameter values set when the workflow was last saved.
+   **Ensure each headstage is configured with the correct voltage.** Although
+   headstages are quite tolerate of over-voltage and under-voltage conditions,
+   they are only guaranteed to function within a specified range.  When using
+   long and/or thin tethers, the voltage drop across the cable can become
+   significant. For more details, see :ref:`tether_voltage`.
 
-.. warning::
-   When you configure the voltage, the :ref:`bonsai_onicontext` node shows that value 
-   and when you save the workflow this value is not saved. Therefore, that value will 
-   not be set to hardware when you load the workflow again. On loading the workflow, 
-   the :ref:`bonsai_onicontext` node will be reading the voltage that is already set 
-   on the hardware and showing this  in the ``LinkVoltage`` field.
-
-.. warning::
-   When you configure the voltage, the :ref:`bonsai_headstageportcontroldev` node shows 
-   that value and when you save the workflow this value is saved. Therefore, that value 
-   will be set to hardware when you load the workflow again. If you make changes to the 
-   voltage value (with any node) and save the workflow, they will be saved in the 
-   ``LinkVoltage`` property of the :ref:`bonsai_headstageportcontroldev` node.
-
-- Any workflows containing the :ref:`bonsai_NeuropixelsV1edev` node require the 
-  :ref:`headstage_neuropix1e` to be connected before the workflows can be opened or 
-  loaded into Bonsai.
-
-.. warning::
-   Check that the voltage set to the headstage port is correct for the 
-   :ref:`headstage_neuropix1e` by using a workflow of a single :ref:`bonsai_onicontext` 
-   node to configure it before connecting the headstage in order to open a workflow that 
-   contains the :ref:`bonsai_NeuropixelsV1edev` node.
-
-- An :ref:`bonsai_onicontext` node or any device node in a workflow can override device 
-  settings in another workflow if device addresses are not distinct, because these nodes 
-  read/write directly to hardware.
 
-.. warning::
-   **Only have one workflow open at a time.**
diff --git a/source/Getting Started/whatisonix.rst b/source/Getting Started/whatisonix.rst
@@ -6,9 +6,9 @@
 What is ONIX?
 ==========================================
 ONIX is a data acquisition system for neuroscience, composed of various pieces
-of hardware. ONIX differs from other acquisition systems in three major points:
+of hardware. ONIX differs from other acquisition systems in three ways:
 
-1. Standards
+1. Standards & Interoperability
 --------------------------------
 All acquisition systems follow specific sets of rules that outline how data is
 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
 add to their experiment. Additionally, for those who want to develop new tools
 to study the brain, ONIX provides a powerful hardware backend and software
 infrastructure that can be reused to control almost any type of recoding
-instrument.  
+instrument.
 
-2. Tethers
---------------------------------
+2. Thin Tethers & Zero Torque Commutation
+-------------------------------------------
 There is a growing appreciation of experiments that examine the natural
 behaviours of animals. This often means using larger and more intricate
 (perhaps 3D) experimental setups. It also means that the animal should be
 impaired as little as possible by the recording setup. To achieve this it is of
 course important to reducing the weight of the headstage, but the weight of the
 tether that connects the headstage to the acquisition system is often
-overlooked. As the animal explores the arena, the centre of mass of the tether
+overlooked. As the animal explores the arena, the center of mass of the tether
 is rarely directly above the animal. Instead, it is off to one side,
-introducing a rotational force on the animal. The animal must compensate for
-this torque in order to keep its head up straight.  Because the ONI
-specification allows communication over a single wire, ONIX uses a single
+introducing a rotational force (torque) on the animal. The animal must
+compensate for this torque in order to keep its head up straight.  Because the
+ONI specification allows communication over a single wire, ONIX uses a single
 coaxial cable, making ONIX tethers lighter and thinner compared to classic
 acquisition systems. ONIX tethers are 0.1 to 0.4 mm in diameter and are
 extremely flexible.
@@ -56,28 +56,37 @@ becoming twisted. Commutators are hardware devices that allow the tether to
 rotate while maintaining an electrical connection to the rest of the path to
 the acquisition system. As the animal moves through the arena, the ONIX
 commutator receives 3D tracking information from the headstage and drives  a
-motor to actively rotate the tether, preventing twisting.
+motor to actively rotate the tether, preventing twisting. Importantly, this
+process is driven by real-time measurement of headstage rotation, *not by
+torque transmitted by the tether*. This allows nearly zero-torque commutation
+and the use of tethers that are so thin, they would not not function in systems
+that require torque measurements to drive active commutation.
 
-3. Latencies
+3. Low Latencies
 --------------------------------
 In closed-loop experiments, data is not only acquired, but also processed and
 acted upon. For instance, one can provide optogenetic stimulation to a brain
 area every time a certain type of event is detected by an extracellular probe.
 The closed-loop latency of the acquisition system describes how much time
-passes between the initial event and the response of the system. In classic
-acquisition systems, this time is primarily spent on transmitting and
-processing acquired data, which becomes more and more challenging as the number
-of channels on a probe increases. A short latency allows the user to respond on
-the timescale of the biological event; for instance, within the integration
-window of a neuron.
+passes between the physical event and the response of the real-time system. A
+short latency allows the user to respond on the timescale of the biological
+event; for instance, within the integration window of a neuron.
+
+Many acquisition systems rely on a USB connection between the acquisition board
+and PC. Or, they rely on closed-source 3rd-party drivers and APIs that are not
+optimized for low response latencies. The slower transfer characteristics of
+USB means that a typical closed-loop latency is in the range of several
+to tens of milliseconds. This is a considerable duration for the brain, as it
+is notably longer than the average action potential duration of around 1 ms. On
+average, ONIX provides much shorter latencies, of around 150 microseconds, because:
+
+- ONIX is transfers data to the host computer without the CPU via DMA over PCIe.
+- ONIX uses a custom device driver optimized for low latency.
+- The ONI API allows explicit control over a single parameter to governs the
+  trade off between data latency and overall bandwidth.
 
-Many classic acquisition systems rely on a USB connection between the
-acquisition board and PC. The slower transfer characteristics of USB means that
-a typical closed-loop latency would be in the range of several to tens of
-milliseconds. This is a considerable duration for the brain, as it is notably
-longer than the average action potential duration of around 1 ms. ONIX has much
-shorter latencies, of around 150 microseconds, because the host board of ONIX
-is directly connected to the acquisition PC, in a PCIe slot. This means that
-the system can respond quickly to detected events. It also means that time is
-freed up for this detection itself; by reducing the overhead time, more complex
-analysis can be run to extract the phenomenon you are interested in.
+This permits the user to optimize their system's response time for a given
+experiment.  In all, this means that the system can respond quickly to detected
+events. It also means that time is freed up for this detection itself; by
+reducing the overhead time, more complex analysis can be run to extract the
+phenomenon you are interested in.
diff --git a/source/Hardware Guide/Commutators/index.rst b/source/Hardware Guide/Commutators/index.rst
@@ -2,14 +2,16 @@
 
 Coaxial Commutators
 ===================================
-Active, near-zero torque commutators to prevent tether twisting during
-freely moving recordings with headstages and/or miniscopes.
-This page provides a very brief overview of the commutators; for a more extensive
-walkthrough, please follow the documentation link for `Commutators <https://open-ephys.github.io/commutator-docs/index.html>`__.
+Active, near-zero torque commutators prevent tether twisting during freely
+moving recordings with headstages and/or miniscopes.  This page provides a very
+brief overview of the commutators; for a more extensive walkthrough, please
+follow the documentation link for `Commutators
+<https://open-ephys.github.io/commutator-docs/index.html>`__.
 
 :Design Repository: https://github.com/open-ephys/commutators
-:Compatibility: :ref:`pcie_host`, :ref:`headstage_64`,
-                :ref:`headstage_neuropix1`, :ref:`miniscopes`
+:Compatibility: All coaxial headstags (e.g. :ref:`headstage_64`,
+                :ref:`headstage_neuropix2e`, :ref:`miniscopes`)
+:Documentation: https://open-ephys.github.io/commutator-docs/index.html
 
 .. _commutators_overview:
 
@@ -24,11 +26,11 @@ Overview
 ONIX uses an active commutator to prevents tether twisting during freely moving
 recordings.  A inertial measurement unit (IMU) on the headstage or miniscope
 sends orientation data to the host computer. Because the real-time orientation
-of the animal is known, software (e.g. Bonsai) can be used to send commands to
-the commutator via its USB interface, and the motor in the commutator will turn
-when the animal does. A high-quality radio-frequency rotary joint inside the
-commutator maintains electrical connectivity for both power and high-frequency
-data signals between the tether leading to the headstage and the coaxial cable
+of the animal is known, software can be used to send commands to the commutator
+via its USB interface, and the motor in the commutator will turn when the
+animal does. A high-quality radio-frequency rotary joint inside the commutator
+maintains electrical connectivity for both power and high-frequency data
+signals between the tether leading to the headstage and the coaxial cable
 leading to the PCIe host board while turning.
 
 Features

diff --git a/source/Hardware Guide/Datasheets/fmc-link-control.rst b/source/Hardware Guide/Datasheets/fmc-link-control.rst
@@ -12,8 +12,8 @@ Description
 *******************************************
 The **FMC Host Link Controller** is used to control and monitor DS90UB9x-based
 serialized connections to hubs connected to a host such as headstages and
-miniscopes. It can control power provided to those hubs and receives RF lock,
-CRC error, and other information.
+miniscopes. It can control the voltage provided to those hubs and receives RF
+lock, CRC error, and other diagnostic information.
 
 .. note::
 

diff --git a/source/Hardware Guide/Headstages/headstage-rhs2116.rst b/source/Hardware Guide/Headstages/headstage-rhs2116.rst
@@ -0,0 +1,97 @@
+#################
+RHS2116 Headstage
+#################
+
+.. image:: /_static/images/rhs2116/rhs2116.webp
+    :align: center
+    :height: 300px
+    :alt: ONIX rhs2116
+
+|
+
+The RHS2116 Headstage is a serialized headstage for small animals with 32
+bi-direcional channels which each can be used to deliver electrical stimuli.
+The RHS2116 Headstage can be used with passive probes (e.g. silicon arrays, EEG/ECOG
+arrays, etc) using a 36-Channel Omnetics EIB. 
+
+********
+Features
+********
+
+* Two RHS2116 ICs for a combined 32 bi-directional ephys channels
+* ~1 millisecond active stimuls artifact recovery
+* Max stimulator current: 2.55mA @ +/-7V compliance. 
+* Sample rate: 30193.2367 Hz 
+* Stimulus active and stimulus trigger pins
+* On-board Lattice Crosslink™ FPGA for real-time data arbitration
+
+..  _rhs2116_data_link_serialization:
+
+***********************
+Data Link Serialization
+***********************
+
+For details on data serialization and headstage gateware, have a look at the
+:ref:`serialization` page, which describes how coax headstages operate in
+general terms. The RHS2116 headstage has the following coaxial link properties:
+
+.. table::
+    :widths: 50 80 50 50 50
+
+    +------------------------+--------------------+----------+----------+----------+
+    | Parameter              | Value              | Min      | Max      | Unit/    |
+    |                        |                    |          |          | Type     |
+    +========================+====================+==========+==========+==========+
+    | FPGA                   | LIF-MD6000-6UMG64I |          |          |          |
+    +------------------------+--------------------+----------+----------+----------+
+    | Serializer             | TI DS90UB933       |          |          | Coaxial  |
+    +------------------------+--------------------+----------+----------+----------+
+    | Supply Voltage         | 4.0                | 3.4      | 5.0*     | Volts    |
+    +------------------------+--------------------+----------+----------+----------+
+    | Hub Clock Frequency    | 50                 |          |          | MHz      |
+    +------------------------+--------------------+----------+----------+----------+
+
+.. warning:: \*Do not exceed 5.0 VDC at the coaxial input to the headstage.
+   Make sure you make this measurement at the headstage (see
+   :ref:`measure_voltage`) to account for a potential voltage drop in the
+   tether. 
+
+.. note:: Have a look at the :ref:`tethers` page for more details on micro-coax
+   headstage tethers
+
+*****************
+Electrophysiology
+*****************
+
+RHS2116 headstage uses two 16-channel `Intan RHS2116
+<https://intantech.com/>`__ bioamplifier chip. The chip is operated at a fixed
+sampling rate of ~30 kHz/channel. These 32 ephys channels are exposed via a 36
+pin `Omnetics connector
+<https://www.omnetics.com/wp-content/uploads/2022/01/A79025-001.pdf>`__ at the
+edge of the headstage and can record from most passive probes (e.g. tetrodes,
+silicon probe arrays, tungsten microwires, steel EEG wires, etc.) as well as
+stimulate.
+
+.. 
+    RHS2116 Pinout
+    ==============
+
+    ..  image:: /_static/images/rhs2116/rhs2116-omnetics-pinout.webp
+        :align: center
+        :height: 300px
+        :alt: ONIX rhs2116 omnetics
+
+    |
+
+    ..  image:: /_static/images/rhs2116/rhs2116-bottom-pinout.webp
+        :align: center
+        :height: 300px
+        :alt: ONIX rhs2116 bottom pinout
+
+*****************
+Bill of Materials
+*****************
+
+- `Interactive BoM <../../_static/boms/headstage-rhs2116_bom.html>`__ (a csv BoM can be downloaded from this page)
+
+.. note:: Have a look at the :ref:`tether_voltage` page for more details on probing and verifying headstage power voltages 
diff --git a/source/Hardware Guide/Headstages/index.rst b/source/Hardware Guide/Headstages/index.rst
@@ -10,13 +10,13 @@ Here you will find information on **ONIX headstages**.
     setup
     serialization
     tethers
+    tether-voltage
     headstage-64/index
     headstage-neuropix-1
     headstage-neuropix-1e
     headstage-neuropix-2e-beta
     headstage-neuropix-2e
-    rhs2116.rst
-    tether-voltage
+    headstage-rhs2116.rst
 
 .. important:: ONIX expands the concept of a headstage compared to what you
     might be used to. ONIX headstages are head-borne systems of sensors and