Skip to content

Commit 112b1ce

Browse files
cjshaChucklesOnGitHub
cjsha
and
ChucklesOnGitHub
authored
Add commutator tutorial for both acq board and ONIX (#89)
Co-authored-by: Ceci Herbert <[email protected]>
1 parent 12546c7 commit 112b1ce

File tree

12 files changed

+623
-53
lines changed

12 files changed

+623
-53
lines changed

‎Pipfile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@ verify_ssl = true
77
sphinx = "*"
88
pydata-sphinx-theme = "0.13.3"
99
sphinx-tabs = "*"
10-
make = "*"
10+
make = "*"
11+
sphinx-design = "*"

‎Pipfile.lock‎

Lines changed: 54 additions & 49 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎source/Tutorials/Commutator.rst‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. _commutator:
2+
3+
.. role:: raw-html-m2r(raw)
4+
:format: html
5+
6+
Automating Tether Commutation
7+
==============================
8+
9+
.. note::
10+
Following this tutorial requires a 3D capable headstage, an Open Ephys SPI
11+
commutator, and a 3D capable data acquisition system (e.g. a Gen 3
12+
Acquisition Board or ONIX).
13+
14+
.. raw:: html
15+
16+
<center>
17+
<figure>
18+
<video width="560" height="340" controls muted>
19+
<source src="../_static/images/SPI_commutator.mp4" type="video/mp4">
20+
</video>
21+
<figcaption>
22+
A demonstration of automated commutation using an <a href="url"
23+
src="https://open-ephys.org/acquisition-system/oeps-9029">
24+
Acquisition Board Gen 3</a> (not shown), a <a href="url"
25+
src="https://open-ephys.org/acquisition-system/oeps-6570-6571">
26+
Low-profile 3D capable 64ch headstage</a>, and an <a href="url"
27+
src="https://open-ephys.org/commutators/oeps-7761">SPI
28+
commutator</a>.
29+
</figcaption>
30+
</figure>
31+
</center>
32+
33+
Most acquisition systems rely on a tether to transmit power and data between the
34+
headstage and the data acquisition controller. As the animal moves around during
35+
freely behaving experiments, the tether can get twisted and tangled which risks
36+
exerting torque on the animal. This can be is mitigated by using a commutator, a
37+
device that untwists the tether as the animal moves around while maintaining
38+
electrical continuity between the headstage on the animal and data acquisition
39+
controller. Our commutators don't require tether torque measurements to know in
40+
which direction to compensate for the twists. Instead, they use information from
41+
absolute orientation sensors on our 3D capable headstages. Torque-free automatic
42+
commutation relieves strain from the animal, encouraging more naturalistic
43+
behaviors and enabling long-term recordings.
44+
45+
This tutorial demonstrates how to automate commutation using the Open Ephys
46+
GUI, a 3D capable headstage, and an Open Ephys commutator.
47+
48+
Hardware Configuration
49+
#######################
50+
51+
.. tab-set::
52+
:sync-group: acquisition-hardware
53+
54+
.. tab-item:: Acquisition Board
55+
:sync: acquisition-board
56+
57+
Make sure you have a `3D capable SPI headstage <https://open-ephys.github.io/acq-board-docs/Hardware-Guide/Headstages.html#open-ephys-headstages>`__ which have an Inertial Measurement Unit (IMU).
58+
59+
#. Follow the `Acquisition Board Quick Start Guide
60+
<https://open-ephys.github.io/acq-board-docs/User-Manual/Quickstart-guide.html#connecting-the-usb-cable-and-power-supply>`__
61+
to establish the following necessary acquisition board connections:
62+
63+
- USB 3.0 connection between the acquisition board and the PC.
64+
65+
- +5V connection between the acquisition board and an AC power
66+
source.
67+
68+
#. Follow the `SPI Commutator Connections section
69+
<https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=spi#connecting>`__
70+
of the commutator hardware docs to establish the following necessary
71+
commutator connections:
72+
73+
- SPI connection between the commutator's stator and the
74+
`acquisition board <https://open-ephys.github.io/acq-board-docs/User-Manual/Quickstart-guide.html#connecting-the-headstages>`_.
75+
76+
- SPI connection between the commutator's rotor and the 3D capable
77+
headstage.
78+
79+
- USB connection between the commutator and the PC.
80+
81+
.. tab-item:: ONIX
82+
:sync: onix
83+
84+
Make sure you have a `3D capable ONIX headstage <https://open-ephys.github.io/onix-docs/Hardware%20Guide/Headstages/index.html>`__ which have an Inertial Measurement Unit (IMU), specifically, a BNO055 device.
85+
86+
#. Follow the `ONIX Hardware Guide
87+
<https://open-ephys.github.io/onix-docs/Hardware%20Guide/Breakout%20Board/setup.html>`__
88+
to establish the following necessary ONIX connections:
89+
90+
- 2x (A & B) coaxial connections between the breakout board and
91+
the PCIe host.
92+
93+
- SDR connection between the breakout board and the PCIe host.
94+
95+
#. Follow the `Coax Commutator Connections section
96+
<https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=coax#connecting>`__
97+
of the commutator hardware docs to establish the following necessary
98+
commutator connections:
99+
100+
- Coaxial connection(s) between the commutator's stator(s) and the
101+
acquisition board.
102+
103+
- Coaxial connection(s) between the commutator's rotor(s) and the 3D
104+
capable headstage.
105+
106+
- USB connection between the commutator and the PC.
107+
108+
Software Configuration
109+
####################################
110+
111+
#. In the Open Ephys GUI, download the source processor for your hardware
112+
(:doc:`/User-Manual/Plugins/Acquisition-Board` or
113+
:doc:`/User-Manual/Plugins/Onix-Source`) via “File > Plugin Installer”.
114+
115+
#. Download the signal chain that corresponds to which hardware you are using.
116+
117+
.. tab-set::
118+
:sync-group: acquisition-hardware
119+
120+
.. tab-item:: Acquisition Board
121+
:sync: acquisition-board
122+
123+
:download:`Acquisition Board Commutator Signal Chain </_static/downloads/tutorials/commutator-signal-chain_acq-board>`
124+
125+
.. image:: /_static/images/tutorials/commutator/commutator-signal-chain_acq-board.webp
126+
:alt: Acquisition Board Signal Chain for commutation
127+
128+
.. tab-item:: ONIX
129+
:sync: onix
130+
131+
:download:`ONIX Commutator Signal Chain </_static/downloads/tutorials/commutator-signal-chain_onix-source>`
132+
133+
.. image:: /_static/images/tutorials/commutator/commutator-signal-chain_onix-source.webp
134+
:alt: ONIX Signal Chain for commutation
135+
136+
#. :ref:`Open <file>` the downloaded signal chain in the GUI.
137+
138+
.. tab-set::
139+
:sync-group: acquisition-hardware
140+
141+
.. tab-item:: Acquisition Board
142+
:sync: acquisition-board
143+
144+
Confirm that "IMU" occupies one of the slots in headstage port
145+
indicator in the Acquisition Board processor after the
146+
Acquisition Board is initialized and headstage ports are
147+
scanned.
148+
149+
.. tab-item:: ONIX
150+
:sync: onix
151+
152+
Confirm that one of the data devices on your headstage is a
153+
"BNO055" and that it is enabled using the processor's
154+
configuration canvas.
155+
156+
#. Refer to the :doc:`/User-Manual/Plugins/Commutator-Control` page to
157+
configure the Commutator Control processor.
158+
159+
- The selected Serial port should correspond to the COM port in which the commutator is connected.
160+
161+
- The selected Stream should correspond to a 3D data stream. If multiple
162+
3D capable headstages are used, dual commutators, multiple 3D data
163+
streams could be available. Select the one you want to use.
164+
165+
- For typical usage of an off-the-shelf Open Ephys 3D capable headstage,
166+
adjusting the rotation axis is not necessary. If you mount the headstage
167+
in a non-conventional location, refer to the `IMU Data
168+
<https://github.com/open-ephys/wiki/wiki/IMU-Data>`_ article and
169+
`channel maps docs <https://open-ephys.github.io/channel-maps-docs/headstages/index.html>`_
170+
for your particular hardware to figure out how to set the rotation axis.
171+
172+
#. Make sure the GUI has connected to the acquisition system and click the ▶
173+
play button in the top-right corner. The commutator now follows the rotation
174+
of the headstage.
175+

0 commit comments

Comments
 (0)