Merge pull request #50 from open-ephys/issue-49

Add troubleshooting guide

Author: ChucklesOnGitHub

Pipfile

@@ -8,3 +8,4 @@ sphinx = "*"
 pydata-sphinx-theme = "0.13.3"
 sphinx-tabs = "*"
 make = "*"
+sphinx-design = "*"

Pipfile.lock

@@ -8,7 +8,7 @@ Some of the required cables can be built in the lab:
 
 Custom fine wire tether
 -----------------------------------
-If you want something even more lightweight and flexible, it's possible to build your own cables. We did this by soldering wires to two 12-pin Omnetics PZN-12 `polarized nano connectors <https://www.omnetics.com/products/polarized-nano>`__. Here, we've used `Cooner <http://www.coonerwire.com/>`__ CZ 1187 wire, FEP Insulation 38AWG with 0.012" diameter and 0.720Ω/foot. This is the standard wire for analog tethers because it is very flexible and light, but also durable. The cables sold by Intan are 0.423Ω/ft for the LVDS and 0.172Ω/ft for ground and power, so we're at the upper end of the possible resistance values, but it seems possible that the 40AWG version of the wire could work for the LVDS pairs. For the GND and VCC traces using two 38AWG wires or going to a thicker wire with <0.2Ω/foot is recommended unless the tether is pretty short. This limit is more unforgiving if you're intending to run two headstages on one cable.
+If you want something even more lightweight and flexible, it's possible to build your own cables. We did this by soldering wires to two 12-pin Omnetics PZN-12 `polarized nano connectors <https://www.omnetics.com/product/polarized-nano-horizontal-smt-aa/>`__. Here, we've used `Cooner <https://www.coonerwire.com/>`__ CZ 1187 wire, FEP Insulation 38AWG with 0.012" diameter and 0.720Ω/foot. This is the standard wire for analog tethers because it is very flexible and light, but also durable. The cables sold by Intan are 0.423Ω/ft for the LVDS and 0.172Ω/ft for ground and power, so we're at the upper end of the possible resistance values, but it seems possible that the 40AWG version of the wire could work for the LVDS pairs. For the GND and VCC traces using two 38AWG wires or going to a thicker wire with <0.2Ω/foot is recommended unless the tether is pretty short. This limit is more unforgiving if you're intending to run two headstages on one cable.
 
 The wiring diagram of the cable is simple: There are two rows, each with 6 conductors. Each pair consists of a 'top' and 'bottom' conductor which must be wired straight to the same pair, except with the top and bottom cables switched at the opposite end. Alternatively, as shown below, if one connector is flipped upside down, then all wires just go straight to the opposing pin. This includes gnd/power.
 

source/Build-Instructions/Custom-cables.rst

@@ -14,7 +14,7 @@ Clone the `acquisition-board <https://github.com/open-ephys/acquisition-board>`_
 Acquire the raw materials and tools
 ###################################
 
-Open up BOM.csv in Excel or a text editor (or `view it on Google Docs <https://docs.google.com/spreadsheet/ccc?key=0An1VoeoG8K6AdHhqNjhneGZWWkR5R2hZcDFOd243dHc#gid=0>`__). This is a list of all the parts that are necessary to populate the acquisition board PCB. Most of them can be ordered from DigiKey, but some are only available from other distributors. The quantities (column B) are for one acquisition board, so take that into account if you're trying to build multiple boards.
+Open up BOM.csv in Excel or a text editor (or `view it on Google Docs <https://docs.google.com/spreadsheets/d/1ywzGieWArYGw0-nE7zoQLTEWNAr0ZzdUiqCSY4VL7uM/edit>`__). This is a list of all the parts that are necessary to populate the acquisition board PCB. Most of them can be ordered from DigiKey, but some are only available from other distributors. The quantities (column B) are for one acquisition board, so take that into account if you're trying to build multiple boards.
 
 .. image:: ../_static/images/buildinstructions/samtec.png
 

source/Build-Instructions/Ordering-parts.rst

@@ -10,7 +10,7 @@ FAQs
 
 **What products are compatible with the Acquisition Board?**
 
-This `compatibility matrix <https://open-ephys.org/product-compatibility>`_ shows compatible products sold through the Open Ephys store. Any RHD2000-series headstages sold by Intan will work with the Acquisition Board.
+Besides our own :ref:`headstages`, any RHD2000-series headstage with an SPI protocol and 12-pin polarized nano-connector such as those sold by Intan will work with the Acquisition Board.
 
 |
 

source/FAQ/index.rst

@@ -38,7 +38,7 @@ For the original acquisition board, we chose to use the Opal Kelly XEM6310 USB 3
 
    The Open Ephys FT600 USB board FPGA module developed by the Open Ephys team. 
 
-Our Open Ephys FPGA module uses the same footprint as the previous Opal Kelly one so it can be replaced directly on the existing acquisition boards, although it uses a different FPGA, a Lattice EPC5. Its `design is open source <https://github.com/open-ephys/ECP5U85-BSE-USB>`_ and PC communication is compliant with the our `ONI standard <https://open-ephys.github.io/ONI/>`_ for common interfaces in neuro tools, which is the same standard that powers our more advanced system `ONIX <http://open-ephys.github.io/onix-docs/>`_. The Open Ephys FPGA modules are used for all Acquisition Boards Gen 2 and above.
+Our Open Ephys FPGA module uses the same footprint as the previous Opal Kelly one so it can be replaced directly on the existing acquisition boards, although it uses a different FPGA, a Lattice EPC5. Its `design is open source <https://github.com/open-ephys/ECP5U85-BSE-USB>`_ and PC communication is compliant with the our `ONI standard <https://open-ephys.github.io/ONI/>`_ for common interfaces in neuro tools, which is the same standard that powers our more advanced system `ONIX <https://open-ephys.github.io/onix-docs/>`_. The Open Ephys FPGA modules are used for all Acquisition Boards Gen 2 and above.
 
 The FPGA itself is programmed in a language called Verilog. Verilog is a type of "hardware description language," because it specifies the actions of registers and logic gates, rather than functions and variables. Verilog is compiled to a "bitfile," which must be uploaded to the FPGA each time it's used. Compiling the bitfile can take several minutes, but uploading it occurs almost instantaneously. In the original Opal Kelly module, the bitfile is uploaded by the OE GUI each time the board is recognized, while in the new Open Ephys FPGA module, the bitfile resides permanently on the board. The gateware on Open Ephys FPGA modules can be updated by following :doc:`these instructions </User-Manual/Gateware-Update>`. An onboard bitfile makes it easier to use the acquisition board across different software like Bonsai as it avoids bitfile path issues. The Verilog code that runs on the acquisition board FPGA is our custom version of the "Rhythm" interface developed by Intan. We had to change a few things in order to communicate with our analog-to-digital converters (we're using Texas Instruments ADCs, rather than Analog Devices) and control the 8 LEDs on the board. If you're interested, you can take a look at the `source code <https://github.com/open-ephys/rhythm>`_ (but this is not recommended unless you have some prior Verilog experience).
 

source/Hardware-Guide/How-it-works.rst

@@ -163,7 +163,7 @@ Some applications require to generate (or read) digital channels on the host-PC
 
 The arduino shield for I/O from the host-pc can generate up to 8 channels of digital I/O. Each channel can be assigned as in or out and assigned to an event channel in the GUI.
 
-On the Arduino, this is implemented via the `Firmata firmware <http://playground.arduino.cc/Interfacing/Firmata>`_). This makes it simple for a computer to access the state of the Arduino pins via USB.
+On the Arduino, this is implemented via the `Firmata firmware <https://github.com/firmata/arduino>`_). This makes it simple for a computer to access the state of the Arduino pins via USB.
 
 For a similar, but much more powerful signal output device, check out the `PulsePal <https://sanworks.io/shop/viewproduct?productID=1102>`_) which also works seamlessly with the Open Ephys GUI.
 

source/Hardware-Guide/Peripheral-devices.rst

@@ -10,7 +10,7 @@ To process, record, and visualize data from the Acquisition Board, we recommend
 
 1. The Open Ephys GUI
 ###################################
-The **Open Ephys GUI** is an open-source, plugin-based application built specifically for acquiring extracellular electrophysiology data, available for download `from the Open Ephys website <https://open-ephys.org/gui>`_. The GUI has its own `documentation site <https://open-ephys.github.io/gui-docs/>`_.
+The **Open Ephys GUI** is an open-source, plugin-based application built specifically for acquiring extracellular electrophysiology data, available for download `from the Open Ephys website <https://open-ephys.org/gui>`_. The GUI has its own `documentation site <https://open-ephys.github.io/gui-docs/>`_. Install the Open Ephys GUI will install the Acquisition Board drivers/configure board permissions, so it is the most straightforward way to get started.
 
 2. Bonsai
 ###################################

source/User-Manual/Acquisition-software.rst

@@ -3,14 +3,12 @@
 Driver installation
 =====================================================
 
-Here are the instructions to install the drivers to use the Acquisition Board.
+Drivers are distributed with the Open Ephys GUI, so you will usually be able to complete the driver installation during the `Open Ephys GUI installation <https://open-ephys.github.io/gui-docs/User-Manual/Installing-the-GUI.html>`_. If you run into issues or need to install them independently, please follow the instructions below. 
 
 .. note:: Different Acquisition Board generations use different drivers. See :ref:`this section <genids>` to identify what generation board you have.
 
 Make sure you have the drivers installed correctly before using the Acquisition Board.
 
-Drivers are distributed with the Open Ephys GUI, so you will usually be able to complete the driver installation during the Open Ephys GUI installation. If you need to install them independently, please follow the instructions below. 
-
 Driver installation for Generations 2 and above
 -----------------------------------------------------------------------------------
 
@@ -25,7 +23,7 @@ On Windows
 On MacOS 
 ********************
 
-#. Download the `MacOS driver <https://github.com/open-ephys-plugins/rhythm-oni-plugin/raw/refs/heads/main/Resources/Drivers/libftd3xx.dylib>`__.
+#. Download the `MacOS driver <https://github.com/open-ephys-plugins/acquisition-board/blob/main/Resources/Drivers/libftd3xx.dylib>`__.
 #. Copy the file ``libftd3xx.dylib`` to ``/usr/local/lib`` (you can use ``sudo cp libftd3xx.dylib /usr/local/lib``)
 
 Some security features on mac might prevent the driver from loading.
@@ -42,6 +40,19 @@ The steps to solve this are:
 #. Near the bottom of the page, the library error will appear, click on allow
 #. Run the updater again, if a window appears, it will have an ``open`` option now
 
+On Linux
+********************
+
+Linux does not require a driver, but the board permissions need to be configured. These are configured during the Open Ephys GUI installation, but if you need to configure board permissions independently, you can manually copy the rules file from the `zip version of the installer <https://open-ephys.github.io/gui-docs/User-Manual/Installing-the-GUI.html#via-zip-file-all-distros>`_ or your own build. 
+
+#. Open a terminal and set your working directory to the main folder of the GUI source code.
+
+#. Enter :code:`sudo cp Resources/Scripts/40-open-ephys.rules /etc/udev/rules.d`. The console might then ask for your password.
+
+#. Enter :code:`service udev restart` on Ubuntu/Debian or :code:`sudo udevadm control --reload-rules` on Fedora/CentOS/Gentoo to allow the GUI to communicate with the Open Ephys acquisition board.
+
+The changes will take effect the next time the Acquisition Board is connected to USB.
+
 Driver installation for Generations 0 and 1
 -----------------------------------------------------------------------------------
 

source/User-Manual/Driver-installation.rst

@@ -62,15 +62,15 @@ Updating gateware
 .. warning:: Do not attempt to update the board gateware while the GUI or any other software using
     the board is in use. Do not open any software that uses the board while an update is in process.
 
-#. Be sure that the correct :doc:`device drivers are already installed</User-Manual/Driver-installation>`
+#. Make sure that the correct and latest :doc:`device drivers are installed </User-Manual/Driver-installation>`
 
-#. Download the :ref:`gwupdate_latest` of the gateware
+#. Connect the acquisition board to the computer via USB 3.0 and connect it to power using the power supply provided.
 
-#. Extract the contents of the file 
+#. Confirm that the device is recognized by the operating system. If not, follow the :ref:`Troubleshooting Guide <isitrecognized>`. 
 
-#. Connect the acquisition board to the computer via USB 3.0 and connect it to power using the power supply provided
+#. Download the :ref:`gwupdate_latest` of the gateware and extract the contents of the file.
 
-#. Run the updater
+#. Run the updater:
 
    * On Windows: Double click on the file ``UpdateFPGA_v1_0.bat``
    * On Linux or Mac: Execute the file ``UpdateFPGA_v1_0.sh``