deploy: ad41db2

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ce193b7265d4fdb57e87d45842dd043d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/changelog.rst.txt

@@ -0,0 +1,2 @@
+.. include:: ../../CHANGELOG.md
+   :parser: myst_parser.sphinx_

_sources/faq.rst.txt

@@ -0,0 +1,121 @@
+**************************
+Frequently Asked Questions
+**************************
+
+Here we collect common issues and questions regarding IBLRIG.
+
+First Aid
+=========
+
+If your rig is acting up:
+
+*  Employ the **automated test-script** bundled with IBLRIG. This script helps identify common configuration issues.
+   Execute it using PowerShell:
+
+   .. code:: powershell
+
+      C:\iblrigv8\venv\scripts\Activate.ps1
+      validate_iblrig
+
+*  Check `the comprehensive user manual <https://doi.org/10.6084/m9.figshare.11634732.v6>`__ ("Appendix 3" on GoogleDrive).
+   Verify if all connections are secure, and configurations align with the manual's guidelines.
+
+*  Don't hesitate to **contact our developer team** for assistance. We're committed to getting your system back on track.
+
+
+Bug Reports & Feature Requests
+==============================
+
+IBLRIG remains in dynamic development. Your input is invaluable in shaping its direction. `Send us your
+bug reports and feature-requests via GitHub <https://github.com/int-brain-lab/iblrig/issues>`_ - we will do our best to help you.
+
+
+Sound Issues
+============
+
+* Double-check all wiring for loose connections.
+
+* Is ``hardware_settings.yaml`` set up correctly? Valid options for sound ``OUTPUT`` are:
+
+  - ``harp``,
+  - ``xonar``, or
+  - ``sysdefault``.
+
+  Make sure that this value matches the actual soundcard used on your rig.
+
+
+Screen Issues
+=============
+
+General
+^^^^^^^
+
+*  The ribbon cable attaching the screen to the driver board is notoriously finicky. If you are having brightness issues or do not have a signal, try gently repositioning this cable and ensure it is tightly seated in its connection.
+*  Screen and ribbon cable can be easily damaged. It is useful to have backup at hand.
+*  Screen flashing can occur if the power supply does not match the screen specifications. Use a 12V adapter with at least 1A.
+*  If the Bonsai display is appearing on the PC screen when a task starts, try unplugging the rig screen, rebooting and plugging the screen back in. Other variations of screen unplugging and rebooting may also work.
+   Also make sure, that the ``DISPLAY_IDX`` value in ``hardware_settings.yaml`` is set correctly.
+
+Defining Default Position & Size of Bonsai Visualizers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Is the preview window of the video recording showing on the iPad screen instead of the computer's main display during a
+session? To redefine the default position and size of the Bonsai visualizer:
+
+#. Open the Bonsai executable distributed with IBLRIG: ``C:\iblrigv8\Bonsai\Bonsai.exe``.
+#. Open the respective Bonsai workflow:
+
+   .. code::
+
+      C:\iblrigv8\devices\camera_recordings\TrainingRig_SaveVideo_TrainingTasks.bonsai
+
+#. Start the workflow by clicking on the play-button.
+#. Adjust the position and size of the windows as per your preference.
+#. Stop the workflow.
+#. Save the workflow.
+
+
+Camera Issues
+=============
+
+*  If a camera is not detected by the computer or causes intermittent issues it might be an issue with the USB connection.
+
+   *  Ensure that the camera is connected to the computer on a USB3 port (usually indicated by a blue plastic tab in the port).
+      USB2 (black tabs) neither provides the necessary transfer rates nor sufficient current to power the camera.
+   *  Use the `original USB3.1 cable <https://www.flir.com/products/usb-3.1-locking-cable>`_ provided by FLIR.
+      It comes in 3 m or 5 m - stick with the shorter version if possible.
+   *  Try to avoid USB extensions.
+      The original cable (see above) should be sufficiently long in most situations.
+   *  Ideally, use one of the onboard USB3 ports of your computer facing to the back of the machine.
+      Front-facing ports may not be able to provide enough power.
+   *  If you use a USB 3.1 Host Controller Card check if it requires additional powering through a SATA or Molex cable.
+      FLIR offers `a few models <https://www.flir.com/products/usb-3.1-host-controller-card>`_ that should work fine.
+
+
+Frame2TTL
+=========
+
+*  Version 1 of Frame2TTL won't be detected after restarting the computer.
+   Unplugging and replugging the USB cable should make it responsive again.
+*  If IBLRIG complains about not receiving any TTL signals from Frame2TTL:
+
+   *  Ensure Frame2TTL's sensor is positioned over the bottom-right corner of the rig's screen.
+      Secure the sensor's cable to the screen mount with a zip-tie to prevent it from slipping off the screen.
+      Additionally, use a piece of electrical tape to hold the sensor in place.
+
+   *  Verify that the sensor is connected to Frame2TTL with the correct polarity
+
+      *  Version 1: GND = black cable, SIG = white cable
+      *  Version 2 and 3: BLK = black cable, WHT = white cable
+   *  Ensure that Frame2TTL's TTL Output is plugged into Bpod's TTL Input #1.
+      Note that versions 2 and 3 of Frame2TTL have a second BNC output labeled "analog" - this is *not* the TTL output.
+   *  Recalibrate Frame2TTL using the calibration routine in IBLRIG's Tools menu and check for any errors.
+
+*  If the above steps do not resolve the issue, try the following:
+
+   #. Swap out the BNC cable between Frame2TTL and Bpod.
+      Use a single cable without any branches.
+   #. Connect an oscilloscope to the Bpod end of the cable and run a calibration.
+      Look for a voltage step in Frame2TTL's output when the calibration routine switches from dark to light.
+   #. If you *do* see the change in the TTL signal, the Bpod might be faulty. Try using a different Bpod unit.
+   #. If you do *not* see the voltage step, the Frame2TTL might be faulty. Try using a different Frame2TTL unit.

_sources/hardware.rst.txt

@@ -0,0 +1,94 @@
+Hardware Guide
+==============
+
+
+Upgrading Xonar AE to Bpod HiFi Module
+------------------------------------------------
+
+.. note:: The following guide only concerns behavior rigs using `Asus Xonar AE` sound cards.
+   The `Harp` sound cards used in our Ephys and Mesoscope rigs work fine and do not require replacing!
+
+Background
+""""""""""
+
+In their original design, IBL’s behavioral training rigs relied on a consumer-grade sound-card - the `ASUS Xonar AE <https://www.asus.com/motherboards-components/sound-cards/gaming/xonar-ae/>`_ - for delivering auditory cues to the subject. We have identified the Xonar AE as a weak point in the design of the training rig as this choice of hardware has several severe drawbacks:
+
+*  Synchronization between individual components of the rig relies on TTL Signals, a standardized way of communicating between digital devices.
+   With the Xonar sound-card, we emulate TTL pulses on one of the soundcard’s analog audio outputs.
+   The resulting signal does not conform well to the TTL standard since (a) we cannot guarantee the required signal rise-times, and (b) pulse-amplitude depends on the computer’s audio volume and impedance settings. The effects are increased latencies and accidental misconfigurations.
+   The latter have the potential to cause synchronization issues and more problems further down the pipeline.
+*  The ASUS Xonar AE does not seem to be a particularly robust piece of equipment - we’ve experienced several catastrophic failures across our rigs at IBL. Replacement hardware is increasingly hard to come by as the Asus Xonar AE is not being produced anymore.
+*  The soundcard’s driver has been causing issues with specific Windows updates that require manual intervention / rollback of the respective updates.
+*  There is no Windows 11 specific driver available.
+
+For these reasons, we decided to replace the Xonar AE with the `Bpod HiFi Module HD <https://sanworks.io/shop/viewproduct?productID=1033>`_ by Sanworks:
+The HiFi Module is capable of delivering high fidelity sound stimuli at low latencies, supports proper TTL signaling as well as serial communication with the Bpod Finite State Machine and does not require any dedicated drivers.
+The upgrade procedure is straightforward and should take no longer than 5-10 minutes.
+
+Requirements
+""""""""""""
+
+To replace your existing Xonar AE with the Bpod HiFi Module HD you will require the following:
+
+*  1x Bpod HiFi Module HD
+*  1x Micro-USB to USB-A cable
+*  1x Ethernet cable (RJ45)
+*  1x RCA to 3.5 mm audio adapter
+*  1x 3 mm flathead screwdriver
+
+.. warning:: Support for the Bpod HiFi Module was introduced with IBLRIG 8.16.0 and will not be backported to older version of IBLRIG.
+             Make sure to upgrade to the latest version of IBLRIG before continuing with this guide.
+
+Upgrade Procedure
+"""""""""""""""""
+
+1. Use the 3 mm flathead screwdriver to unscrew the BNC to wire adapter from the amplifier board.
+   While the adapter itself is not needed anymore we will continue using the BNC cable.
+   Leave the other end of the BNC cable plugged into the Bpod as it is.
+
+   .. figure:: img/amp2x15_labels.png
+      :width: 100%
+      :class: with-border
+
+      Disconnect the BNC to wire adapter from the amplifier board.
+
+2. Unplug the 3.5 mm audio cable from the Xonar AE sound card on the backside of the rig's computer.
+   Leave the other end of the 3.5 mm audio cable connected to the amplifier board.
+
+   .. figure:: img/xonar_labels.png
+      :width: 100%
+      :class: with-border
+
+      Unplug the 3.5 mm audio cable from the Xonar AE sound card.
+
+3. Connect the Bpod HiFi Module as follows:
+
+   * the BNC cable connects to TTL In 2 of the Bpod (cf. step 1),
+   * the 3.5 mm audio cable connects to the amplifier board via the RCA adapter (cf. step 2),
+   * the USB cable connects to the rig's computer
+   * the Ethernet cable connects to one of the Bpod's Module ports.
+     Warning: Bpod uses identical connectors for its Behavior ports - do not mix them up!
+
+   .. figure:: img/hifi_labels.png
+      :width: 100%
+      :class: with-border
+
+      The Bpod HiFi Modules and its connections.
+
+4. Open `C:/iblrigv8/settings/hardware_settings.yaml` in a text-editor.
+   Find the section `device_sound` and adapt it as follows:
+
+   .. code-block:: yaml
+
+      device_sound:
+        OUTPUT: hifi
+        COM_SOUND: COMx  # replace with the HiFi Module's actual COM port!
+        AMP_TYPE: AMP2X15
+
+   .. tip::
+
+      Use Windows' device manager to identify the HiFi Module's COM port.
+      The device should show up in the section labelled "Ports (COM & LPT)" after plugging it in.
+
+5. Start IBLRIG and make sure that the hardware validation during start-up does not find any issues.
+   Finally, start a session and verify that you can hear the audio cues.

_sources/index.rst.txt

@@ -0,0 +1,29 @@
+.. if-builder:: html
+
+   .. include:: ../../README.md
+      :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   installation
+   usage
+   reference
+   hardware
+   reference_developer_guide
+   faq
+
+.. if-builder:: html
+
+   .. toctree::
+      :hidden:
+
+      changelog
+
+   .. toctree::
+      :caption: Links
+      :hidden:
+
+      IBLRIG on GitHub <https://github.com/int-brain-lab/iblrig>
+      Appendix 3: IBL protocol for setting up the behavioral training rig <https://doi.org/10.6084/m9.figshare.11634732>