Skip to content

Commit 133dce5

Browse files
cjshacjsha
committed
Initial commutator tutorial progress
1 parent 12546c7 commit 133dce5

File tree

7 files changed

+195
-52
lines changed

7 files changed

+195
-52
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: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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+
.. image:: commutator-demo-video
15+
16+
Most acquisition systems rely on a tether to transmit power and data between the
17+
headstage and the data acquisition system. This can be problematic during freely
18+
behaving experiments because the animal is liable to twist and tangle the tether
19+
while it moves around which can end up exerting torque on the animal. This can
20+
be is mitigated by using a commutator, a device that untwists the tether as the
21+
animal moves around while maintaining electrical continuity between the
22+
headstage and data acquisition system. This encourage more naturalistic
23+
behaviors.
24+
25+
This tutorial demonstrates how to automate commutation using a the Open Ephys
26+
GUI, a 3D-capable headstage, and an Open Ephys commutator.
27+
28+
Hardware connections
29+
#####################
30+
31+
.. tab-set::
32+
:sync-group: acquisition-hardware
33+
34+
.. tab-item:: Acquisition Board
35+
:sync: acquisition-board
36+
37+
#. Follow the `Acquisition Board Quick Start Guide
38+
<https://open-ephys.github.io/acq-board-docs/User-Manual/Quickstart-guide.html#connecting-the-usb-cable-and-power-supply>`__
39+
to establish the following necessary acquisition board connections:
40+
41+
- USB 3.0 connection between the acquisition board and the PC.
42+
43+
- +5V connection between the acquisition board and an AC power
44+
source.
45+
46+
#. Follow the `SPI Commutator Connections section
47+
<https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=spi#connecting>`__
48+
of the commutator hardware docs to establish the following necessary
49+
commutator connections:
50+
51+
- SPI connection between the commutator's stator and the
52+
`acquisition board <https://open-ephys.github.io/acq-board-docs/User-Manual/Quickstart-guide.html#connecting-the-headstages>`_.
53+
54+
- SPI connection between the commutator's rotor and the 3D capable
55+
headstage.
56+
57+
- USB connection between the commutator and the PC.
58+
59+
.. tab-item:: ONIX
60+
:sync: onix
61+
62+
#. Follow the `ONIX Hardware Guide
63+
<https://open-ephys.github.io/onix-docs/Hardware%20Guide/Breakout%20Board/setup.html>`__
64+
to establish the following necessary ONIX connections:
65+
66+
- 2x (A & B) coaxial connections between the breakout board and
67+
the PCIe host.
68+
69+
- SDR connection between the breakout board and the PCIe host.
70+
71+
#. Follow the `Coax Commutator Connections section
72+
<https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=coax#connecting>`__
73+
of the commutator hardware docs to establish the following necessary
74+
commutator connections:
75+
76+
- Coaxial connection between the commutator's stator and the
77+
acquisition board.
78+
79+
- Coaxial connection between the commutator's rotor and the 3D
80+
capable headstage.
81+
82+
- USB connection between the commutator and the PC.
83+
84+
Install GUI and prepare signal chain
85+
####################################
86+
87+
#. :doc:`Install the Open Ephys GUI </User-Manual/Installing-the-GUI>` if you
88+
haven't already and open it.
89+
90+
#. Download one following signal chains depending on which hardware you are
91+
using.
92+
93+
.. tab-set::
94+
:sync-group: acquisition-hardware
95+
96+
.. tab-item:: Acquisition Board
97+
:sync: acquisition-board
98+
99+
:download:`Acquisition Board Signal Chain`
100+
101+
.. image:: /_static/images/tutorials/commutator/onix-signal-chain.png
102+
:alt: Acquisition Board Signal Chain for commutation
103+
104+
.. tab-item:: ONIX
105+
:sync: onix
106+
107+
:download:`ONIX Signal Chain`
108+
109+
.. image:: /_static/images/tutorials/commutator/onix-signal-chain.png
110+
:alt: ONIX Signal Chain for commutation
111+
112+
#. :ref:`Open <file>` the downloaded signal chain in the GUI.
113+
114+
#. Refer to :doc:`/User-Manual/Plugins/Commutator-Control` page to configure
115+
the Commutator Control processor.
116+
117+
- The selected stream should correspond to a port that is connected to a
118+
3D capable headstage.
119+
120+
- The selected COM port should correspond to the port that is connected to
121+
the commutator.
122+
123+
- For typical usage of an off-the-shelf Open Ephys 3D capable headstage,
124+
adjusting the rotation axis is not necessary.
125+
.. If you mount the headstage in a non-conventional location, refer to
126+
the `IMU Data <https://github.com/open-ephys/wiki/wiki/IMU-Data>`_
127+
article and `headstage docs
128+
<https://open-ephys.github.io/headstage_docs.html>`_ for your particular
129+
hardware to figure out how to set the rotation axis.
130+
131+
#. Click the ▶ play button in the top-right corner of the GUI. The commutator
132+
now follows the rotation of the headstage.
133+

‎source/Tutorials/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ The following tutorials are available for the Open Ephys GUI:
1818

1919
Closed-Loop-Latency
2020
Data-Synchronization
21+
Commutator
2122
How-To-Make-Your-Own-Plugin
2223
Making-Your-Own-Visualizer-Plugin
2324

‎source/User-Manual/Exploring-the-user-interface.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ Menu items
8787

8888
Below you'll find documentation for all of the commands available from the GUI's menu:
8989

90+
.. _file:
91+
9092
File
9193
-----
9294
* **Open**: Browse for a previously saved signal chain XML file, and load it into the GUI.

‎source/User-Manual/Plugins/Commutator-Control.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Commutator Control
99
.. image:: ../../_static/images/plugins/commutatorcontrol/oecommutator.png
1010
:alt: Annotated settings interface for the Commutator Control plugin
1111

12-
.. csv-table:: Prevents twist in the tether connecting a moving animal to a stationary `Open Ephys Acquisition Board Gen 3 <https://open-ephys.org/acq-board>`__.
12+
.. csv-table:: Prevents twist in the tether connecting a moving animal to a stationary `Open Ephys acquisition board Gen3 <https://open-ephys.org/acq-board>`__ using orientation data collected from a 3D-capable headstage.
1313
:widths: 18, 80
1414

1515
"*Plugin Type*", "Sink"

‎source/conf.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@
4141
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4242
# ones.
4343
extensions = ["sphinx.ext.todo",
44-
"sphinx.ext.githubpages"]
44+
"sphinx.ext.githubpages",
45+
"sphinx_design"]
4546

4647

4748
# Add any paths that contain templates here, relative to this directory.

0 commit comments

Comments
 (0)