Merge branch 'upsidedownlabs:main' into course-module2

.github/workflows/sphinx.yml

@@ -2,8 +2,7 @@ name: "Sphinx: Render docs"
 
 on: 
   push:
-    branches:
-      main
+    branches: ["*"]
 
 jobs:
   build:

guides/index.rst

@@ -3,10 +3,12 @@
 Guides
 ######################
 
-In this section, you'll find easy-to-follow guides that will help you while using either BioAmp hardware or any of our :ref:`upsidedownlabs-kits`.
+Welcome to the **Guides** section, where you'll find comprehensive resources that can help you while using :ref:`BioAmp hardware <upsidedownlabs_hardware_home>`  and :ref:`DIY neuroscience kits <upsidedownlabs-kits>`. If you encounter issues, our troubleshooting guides will walk you through common challenges and provide solutions to get you back on track quickly. We also welcome community contributions to enrich this documentation—whether you’ve created your own guide, identified an improvement, or found a new use case, we encourage you to share your insights and be part of building a valuable resource for fellow enthusiasts and learners.
 
 .. only:: html
 
+   **User Guides:**
+
    .. grid:: 2 2 2 2
       :margin: 4 4 0 0 
       :gutter: 2
@@ -26,15 +28,56 @@ In this section, you'll find easy-to-follow guides that will help you while usin
          :link: using-gel-electrodes
          :link-type: ref
 
+   **Troubleshooting**
+
+   .. grid:: 2 2 2 2
+      :margin: 4 4 0 0 
+      :gutter: 2
+
+      .. grid-item-card:: Tips for better signal acquisition
+         :text-align: center
+         :link: tips
+         :link-type: ref
+
+      .. grid-item-card:: Fixing hardware setup
+         :text-align: center
+         :link: fix-hardware-setup
+         :link-type: ref
+
+      .. grid-item-card:: Resolving software issues
+         :text-align: center
+         :link: resolve-software-issues
+         :link-type: ref
+
+   **Contribution Guide**
+
+   .. grid:: 1 1 1 1
+      :margin: 4 4 0 0 
+      :gutter: 2
+
+      .. grid-item-card:: Contribute to documentation
+         :text-align: center
+         :link: upsidedownlabs_contribute
+         :link-type: ref
+
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Hardware Guides
+   :caption: User Guides
 
    usage-guides/skin-preparation/index
    usage-guides/using-bioamp-bands/index
    usage-guides/using-gel-electrodes/index
 
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Troubleshoot
+
+   troubleshoot/tips/index
+   troubleshoot/fix-hardware-setup/index
+   troubleshoot/resolve-software-issues/index
+
 .. toctree::
    :hidden:
    :maxdepth: 1

guides/troubleshoot/fix-hardware-setup/index.rst

@@ -0,0 +1,14 @@
+.. _fix-hardware-setup:
+
+Fixing hardware setup
+#############################
+
+- Make sure that the pins of jumper cables are properly connected to the development board as well as to the Bioamp hardware as mentioned in the documentation.
+
+.. warning:: Take precautions while connecting to power, if power pins are to be swapped, your BioAmp Hardware will be fried and it’ll become unusable (DIE).
+
+- Use the jumper cables that are provided in the kit as we thoroughly test them before packing everything. To check if jumper cables are working correctly then you can do a `continuity test using a multimeter <https://www.wikihow.com/Test-Continuity-with-a-Multimeter>`_.
+- There can be a case where you are trying to upload the code on the development board using Arduino IDE but continuously getting “Uploading” status for some time without getting any errors. To resolve this you can:
+
+  - Change the USB cable connecting the development board to the laptop as some USB cables are only meant for charging but may not work as USB to transfer data bidirectionally. So it is always better to use the USB cable which came with the development board itself.
+  - If the issue still persists then you can try inserting the USB cable in another USB port. There can be cases where the issue is with your USB port so it is better to try using another USB port to resolve the issue.

guides/troubleshoot/resolve-software-issues/index.rst

@@ -0,0 +1,63 @@
+.. _resolve-software-issues:
+
+Resolving software issues
+#############################
+
+:bdg-info:`Arduino IDE`
+
+- **Better signal visualization:** Many people find it difficult to visualize the biopotential signals in the serial plotter even if everything is correct because the serial plotter of the latest version (v2.0) of Arduino IDE plots very few data points per frame and this is why you may find it moving very fast. To resolve this issue you can either:
+
+  - Use `Chords application <chords.upsidedownlabs.tech>`_ to visualise the data. :bdg-success-line:`Recommended`  
+  - Download the Arduino IDE version 1.8.X (Legacy IDE) in which the serial plotter plots more data points per frame so it moves comparatively slow as compared to the latest version.
+
+- **COM Port selection:** Make sure you have selected the correct COM port of the development board connected to your laptop. If you are unable to detect the COM port, follow the steps given below:
+
+  .. card::
+
+    :fab:`windows;pst-color-primary` For Windows
+
+    ^^^^^^^^^^^^^^^^^^
+
+    - Connect the development board to your laptop via USB.
+    - Press Win + X and select Device Manager.
+    - Expand the Ports (COM & LPT) section.
+    - Look for an entry like "USB Serial Device (COMx)" where "x" is the COM port number.
+
+  .. card::
+
+    :fab:`linux;pst-color-primary` For Linux
+
+    ^^^^^^^^^^^^^^^^^^
+
+    - Connect the development board to your laptop via USB.
+    - Open a terminal.
+    - Run the following command to list the connected devices:
+
+      .. code-block::
+
+        dmesg | grep tty
+
+    - Look for lines that show something like ``/dev/ttyUSB0`` or ``/dev/ttyACM0``, which indicates the COM port.
+
+  .. card:: For macOS
+
+    :fab:`apple;pst-color-primary` For macOS
+
+    ^^^^^^^^^^^^^^^^^^
+
+    - Connect the development board to your laptop via USB.
+    - Open the Terminal.
+    - Run the following command: 
+
+      .. code-block::
+
+        ls /dev/tty.*
+
+    - This will list all serial devices. Look for something like ``/dev/tty.usbserial-XXXX`` or ``/dev/tty.usbmodemXXXX``.
+
+- **Development board selection:** Select the correct board in Arduino IDE. To select the board, go to tools from the menu bar, select the board option and then select the development board that you have connected to the laptop.
+
+  .. note:: While using Cytron Technologies Maker Uno make sure you are selecting a board as Arduino Uno as it is an Arduino Uno compatible board.
+
+- **Set baudrate:** Make sure you have selected the correct baud rate (i.e. 115200) while visualizing the biopotential signals on the serial plotter of Arduino IDE.
+

guides/troubleshoot/tips/index.rst

@@ -0,0 +1,28 @@
+.. _tips:
+
+Tips for best signal acquisition
+#################################
+
+- When recording biopotential signals (EEG, ECG, EOG, or EMG), ensure your laptop **is not connected to its charger** 
+  and maintain a **minimum distance of 5 meters** from any AC-powered appliances (e.g., motors, refrigerators) to 
+  minimize interference noise and get better signal acquisition. Our body is essentially a "bag of salt water", when electodes are connected to our body it acts like an antenna picking up surrounding electromagnetic signals also known as Radio/AC interference noise. This interference noise includes radio waves (usually filtered in hardware) and 50Hz/60Hz AC noise from appliances, which is typically removed through software 
+  filtering.
+
+  .. figure:: ../media/precaution-measures-for-better-signals.*
+     :align: center
+     :alt: tip for better signal acquisition
+
+     tip for better signal acquisition
+- Before placing electrodes on your body, prepare your skin thoroughly using `Nuprep skin preparation gel <https://store.upsidedownlabs.tech/product/nuprep-gel/>`_ to remove dead skin cells, 
+  oils, & other substances. This will enhance the connection of electrodes to the skin surface and also decrease the 
+  skin-electrode impedance which results in better signal acquisition. For more information, you can check out the complete :ref:`skin-preparation`.
+
+- The electrode placements are different for recording different biopotential signals. So make sure you are placing the 
+  electrodes at the correct positions. For more information, you can check out :ref:`gel electrodes usage guide <using-gel-electrodes>`.
+
+- Gel electrodes are meant to be used only once and then discarded afterwards.
+
+- Ensure that gel electrodes are properly in contact with the skin. If the electrodes start to peel off during extended 
+  use, it’s time to replace them with new ones. Usually it happens when you are sweating.
+
+- Sit stable while recording the biopotential signals as swinging or moving BioAmp Cable can induce cable movement noise.

guides/usage-guides/using-gel-electrodes/index.rst

@@ -100,6 +100,30 @@ Connect the BioAmp Snap/Alligator Cable on the gel electrodes.
 
 Peel of the plastic backing and place the electrodes on your targeted skin surface as per the connections directed with every BioAmp hardware.
 
+.. figure:: media/electrode-placement-eog.*
+    :align: center
+    :alt: Electrode placement for EOG
+
+    Gel electrodes placement for EOG signal recording
+
+.. figure:: media/electrode-placement-emg.*
+    :align: center
+    :alt: Electrode placement for EMG
+
+    Gel electrodes placement for EMG signal recording
+
+.. figure:: media/electrode-placement-ecg.*
+    :align: center
+    :alt: Electrode placement for ECG
+
+    Gel electrodes placement for ECG signal recording
+
+.. figure:: media/electrode-placement-eeg.*
+    :align: center
+    :alt: Electrode placement for EEG
+
+    Gel electrodes placement for EEG signal recording
+
 .. tip:: While placing the gel electrodes on the skin, make sure to place the non-sticky tab of the electrode in the direction opposite to your hair growth. This allows you to remove the electrodes easily without pulling off much body hair.
 
 Removing the electrodes