Skip to content

Commit 12b9bde

Browse files
cjshaChucklesOnGitHub
cjsha
and
ChucklesOnGitHub
authored
Add commutator tutorial (#38)
Co-authored-by: ChucklesOnGitHub <ceci.herbert@hotmail.com>
1 parent 8c031b8 commit 12b9bde

File tree

7 files changed

+177
-4
lines changed

7 files changed

+177
-4
lines changed

‎source/Hardware-Guide/Headstages.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,8 +95,8 @@ calibrated to yield precise acceleration per `this application note <https://in
9595

9696
.. _3dcap:
9797

98-
3D capabilities
99-
----------------
98+
Inertial Measurement Unit (IMU)
99+
--------------------------------
100100

101101
Our 3D capable headstages are unique in that they can accurately monitor absolute head orientation thanks to an embedded 9-axis inertial measurement unit (IMU). This technology senses rotational movements (pitch, yaw, and roll) which can be used to correlate neural activity with behavioral states.
102102

‎source/Tutorials/Commutator.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Automated Tether Commutation
2+
============================
3+
4+
.. note::
5+
Following this tutorial requires a 3D capable headstage, an Open Ephys SPI commutator, and a 3D
6+
capable data acquisition system (e.g. a Gen 3 Acquisition Board).
7+
8+
Most acquisition systems rely on a tether to transmit power and data between the headstage and the
9+
data acquisition system. This can be problematic during freely behaving experiments because the
10+
animal is liable to twist and tangle the tether while it moves around which can end up exerting
11+
torque on the animal. This is mitigated by using a commutator, a device that untwists the tether as
12+
the animal moves around while maintaining electrical continuity between the animal and data
13+
acquisition system. This encourages more naturalistic behaviors.
14+
15+
This tutorial demonstrates how to automate commutation using an Open Ephys Acquisition Board, the Open Ephys GUI, a 3D-capable
16+
headstage, and an Open Ephys SPI commutator.
17+
18+
Connect the Acquisition Board and the Commutator
19+
###################################################
20+
21+
#. Refer to the :doc:`/Hardware-Guide/Cables` page to make the following acquisition board connections:
22+
23+
- USB 3.0 connection between the acquisition board and the PC.
24+
25+
- +5V connection between the acquisition board and an AC power source.
26+
27+
#. Follow the `SPI Commutator Connections section
28+
<https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=spi#connecting>`__
29+
of the commutator docs to make the following commutator connections:
30+
31+
- SPI connection between the commutator's stator and the acquisition board.
32+
33+
- SPI connection between the commutator's rotor and the 3D capable headstage.
34+
35+
- USB connection between the commutator and the PC.
36+
37+
Build the Signal Chain for the Open Ephys GUI
38+
##############################################
39+
40+
#. `Install the Open Ephys GUI <https://open-ephys.github.io/gui-docs/User-Manual/Installing-the-GUI.html>`_ if you haven't already.
41+
42+
#. Open the GUI.
43+
44+
.. note::
45+
- If this is your first time opening the GUI, you will be queried to load a default
46+
signal chain. Choose the "Acquisition Board" signal chain.
47+
- If the Open Ephys GUI already has a signal chain loaded you would like to keep, make sure to
48+
`save it <https://open-ephys.github.io/gui-docs/User-Manual/Exploring-the-user-interface.html#file>`_
49+
before proceeding because the next steps overwrite the current signal chain.
50+
51+
#. Download the following :download:`signal chain </_static/files/acq-board-commutator-signal-chain>`:
52+
53+
.. image:: /_static/images/tutorials/acq-board-commutator-signal-chain.png
54+
:alt: Acquisition Board Signal Chain for commutation
55+
56+
#. `Open <https://open-ephys.github.io/gui-docs/User-Manual/Exploring-the-user-interface.html#file>`_
57+
the downloaded signal chain in the GUI.
58+
59+
.. tip::
60+
After opening the signal chain, confirm that "IMU" occupies one of the slots in headstage port indicator in the Acquisition Board processor. If "IMU" does not occupy one of those slots, the acquisition board did not detect a 3D-capable device.
61+
62+
#. Refer to `Commutator Control plugin page
63+
<https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Commutator-Control.html>`_
64+
to configure the Commutator Control processor.
65+
66+
- Select the COM port to which your commutator is connected.
67+
68+
- Selected the stream that has the 3D capable headstage you want to use to drive your commutator, if not the default.
69+
70+
- Keep the rotation axis at +Z. For an off-the-shelf Open Ephys 3D capable headstage, adjusting this is not necessary.
71+
72+
#. Click the ▶ play button in the top-right corner of the GUI. The commutator should now follow the
73+
rotation of the headstage around the axis of the tether.
74+
75+
76+
.. raw:: html
77+
78+
<center><video width="560" height="340" controls>
79+
<source src="../_static/videos/SPI_commutator.mp4" type="video/mp4">
80+
</video></center>
81+
82+
83+
#. Continue `building the signal chain
84+
<https://open-ephys.github.io/gui-docs/User-Manual/Building-a-signal-chain.html>`_ with the plugins you need to get the functionality you want.

‎source/Tutorials/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Tutorials
1212

1313
Troubleshooting-noise
1414
Measuring-latency
15+
Commutator
1516
Multiple-boards
1617
Ephys-with-behavioural-camera
1718
bonsai-acquisition

‎source/User-Manual/Quickstart-guide.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ The I/O ports on the Acquisition Board are as follows:
4545
:width: 70%
4646
:align: center
4747

48-
.. note:: Other external hardware interfacing with the acquisition system can be directly connected to the PC for operation. Follow the connection guide for the specific piece of hardware. In the case of our SPI commutator, connect it to USB and connect the two SPI cables. You can find more information in its `connection guide <https://open-ephys.github.io/commutator-docs/index.html>`_.
48+
.. note:: Other external hardware interfacing with the acquisition system can be directly connected to the PC for operation. Follow the connection guide for the specific piece of hardware. In the case of our SPI commutator, connect it to USB and connect the two SPI cables. You can find more information in its `connection guide <https://open-ephys.github.io/commutator-docs/user-guide/mount-connect.html?commutator=spi#connecting>`_.
4949

5050
Grounding your system
5151
-------------------------------------------
@@ -95,7 +95,8 @@ This section provides the basic steps needed in the Open Ephys GUI to get starte
9595

9696
- A `Record Node <https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Record-Node.html>`_
9797

98-
.. - (optional) An OE Commutator processor
98+
- (optional) An `OE Commutator processor <https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Commutator-Control.html>`_
99+
(downloaded using the Plugin Installer) to use the Open Ephys torque-free SPI Commutator
99100

100101
3. Click the Play button to start data acquisition. Click Record to record.
101102

‎source/_static/files/acq-board-commutator-signal-chain‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
3+
<SETTINGS>
4+
<INFO>
5+
<VERSION>1.0.0-alpha.4</VERSION>
6+
<PLUGIN_API_VERSION>10</PLUGIN_API_VERSION>
7+
<DATE>24 Jun 2025 16:04:40</DATE>
8+
<OS>Windows 11</OS>
9+
<MACHINE name="open-ephys-workstation" cpu_model="12th Gen Intel(R) Core(TM) i9-12900K"
10+
cpu_num_cores="24"/>
11+
</INFO>
12+
<SIGNALCHAIN>
13+
<PROCESSOR name="Acquisition Board" insertionPoint="0" pluginName="Acquisition Board"
14+
type="4" index="0" libraryName="Acquisition Board" libraryVersion="1.0.0"
15+
processorType="2" nodeId="100">
16+
<PROCESSOR_PARAMETERS/>
17+
<STREAM name="acquisition_board" description="Continuous and event data from an Open Ephys Acquisition Board"
18+
sample_rate="0.0" channel_count="16">
19+
<PARAMETERS/>
20+
</STREAM>
21+
<CUSTOM_PARAMETERS/>
22+
<EDITOR isCollapsed="0" isDrawerOpen="0" displayName="Acquisition Board"
23+
activeStream="0" Type="Visualizer" tabText="Acq Board" SampleRate="0"
24+
LowCut="0.1067253621401625" HighCut="89.37806065831884" AUXsOn="0"
25+
ADCsOn="0" AudioOutputL="-1" AudioOutputR="-1" NoiseSlicer="0"
26+
TTLFastSettle="0" DAC_TTL="0" DAC_HPF="0" DSPOffset="0" DSPCutoffFreq="0.1457129257077072"
27+
LEDs="1" ClockDivideRatio="1" Channel_Naming_Scheme="0">
28+
<TAB Active="1"/>
29+
<WINDOW Active="0"/>
30+
<HSOPTIONS index="0" hs1_full_channels="0" hs2_full_channels="0"/>
31+
<HSOPTIONS index="1" hs1_full_channels="0" hs2_full_channels="0"/>
32+
<HSOPTIONS index="2" hs1_full_channels="0" hs2_full_channels="0"/>
33+
<HSOPTIONS index="3" hs1_full_channels="0" hs2_full_channels="0"/>
34+
<VISUALIZER_PARAMETERS/>
35+
<CUSTOM_PARAMETERS/>
36+
</EDITOR>
37+
</PROCESSOR>
38+
<PROCESSOR name="Commutator Control" insertionPoint="1" pluginName="Commutator Control"
39+
type="1" index="10" libraryName="Commutator Control" libraryVersion="1.0.0"
40+
processorType="3" nodeId="102">
41+
<PROCESSOR_PARAMETERS current_stream="10008" serial_name="COM8"/>
42+
<STREAM name="acquisition_board" description="Continuous and event data from an Open Ephys Acquisition Board"
43+
sample_rate="0.0" channel_count="16">
44+
<PARAMETERS/>
45+
</STREAM>
46+
<CUSTOM_PARAMETERS/>
47+
<EDITOR isCollapsed="0" isDrawerOpen="0" displayName="Commutator Control"
48+
activeStream="0" COM_PORT="" OVERRIDE_STATUS="0" OVERRIDE_AXIS="+Z"/>
49+
</PROCESSOR>
50+
</SIGNALCHAIN>
51+
<CONTROLPANEL isOpen="0" recordPath="C:\Users\open-ephys\Documents\Open Ephys"
52+
recordEngine="BINARY" clockMode="0" clockReferenceTime="0" forceNewDirectory="0"/>
53+
<AUDIOEDITOR isMuted="0" volume="50.0" noiseGate="0.0"/>
54+
<FILENAMECONFIG>
55+
<PREPEND state="0" value=""/>
56+
<MAIN state="1" value="YYYY-MM-DD_HH-MM-SS"/>
57+
<APPEND state="0" value=""/>
58+
</FILENAMECONFIG>
59+
<EDITORVIEWPORT selectedTab="0" scroll="0"/>
60+
<GRAPHVIEWER>
61+
<NODE id="100" isProcessorInfoVisible="0">
62+
<STREAM key="100|acquisition_board" isStreamVisible="0" isParamsVisible="0"/>
63+
</NODE>
64+
<NODE id="102" isProcessorInfoVisible="0">
65+
<STREAM key="100|acquisition_board" isStreamVisible="0" isParamsVisible="0"/>
66+
</NODE>
67+
</GRAPHVIEWER>
68+
<DATAVIEWPORT>
69+
<TABBEDCOMPONENT index="0" selectedTabNodeId="1">
70+
<TAB nodeId="0"/>
71+
<TAB nodeId="1"/>
72+
<TAB nodeId="100"/>
73+
</TABBEDCOMPONENT>
74+
</DATAVIEWPORT>
75+
<PROCESSORLIST>
76+
<COLOUR ID="801" R="50" G="50" B="50"/>
77+
<COLOUR ID="804" R="241" G="90" B="41"/>
78+
<COLOUR ID="802" R="0" G="174" B="239"/>
79+
<COLOUR ID="803" R="0" G="166" B="81"/>
80+
<COLOUR ID="805" R="90" G="110" B="110"/>
81+
<COLOUR ID="806" R="255" G="0" B="0"/>
82+
<COLOUR ID="807" R="0" G="0" B="0"/>
83+
</PROCESSORLIST>
84+
<UICOMPONENT isProcessorListOpen="0" isEditorViewportOpen="1" consoleOpenInWindow="0"/>
85+
<AUDIO sampleRate="48000.0" bufferSize="1024" deviceType="Windows Audio"/>
86+
<MESSAGES/>
87+
</SETTINGS>

‎source/_static/images/tutorials/acq-board-commutator-signal-chain.png‎

44.9 KB
Loading

‎source/_static/videos/SPI_commutator.mp4‎

37.4 MB
Binary file not shown.

0 commit comments

Comments
 (0)