included breakout board firmware update procedure and files (#59)

* included breakout board firmware update procedure and files

* added new fw page to toctree

source/Hardware Guide/Breakout Board/index.rst

@@ -10,6 +10,7 @@ data IO.
     :hidden:
 
     setup
+    updating-breakout-firmware
 
 :Design Repository: https://github.com/open-ephys/onix-breakout
 :Compatibility: :ref:`pcie_host`, :ref:`headstage_64`,

source/Hardware Guide/Breakout Board/setup.rst

@@ -36,6 +36,17 @@ each of these signal lines are acquired.
     links, but the breakout board provides four. This is is by design. The breakout
     is designed to be compatible with future host hardware.
 
+Reset Button
+________________________
+
+There are two holes on the breakout board that allow access to the onboard FPGA reset button and status LED.
+The reset hole is located just below the 'Digital Out' marking, and can be used to access the reset button on the onboard FPGA by inserting a thin wire or pin.
+The onboard FPGA status can be inspected by looking into the status LED hole.
+
+.. image:: /_static/images/breakout/breakout_reset.png
+    :width: 50%
+    :align: center
+
 
 SDR Cable
 ________________________
@@ -55,8 +66,7 @@ Plug in the SDR cable for analog and digital I/O.
   .. attention:: Some boards have a bug in the power on sequence that means a
      reset is required before the board will work. This has been fixed in later
      revisions. If the RGB LEDs remain off after plugging in the SDR cable,
-     reset the Breakout Board by inserting a thin wire or screw driver into the
-     small hole just below the 'Digital Out' marking to reset the onboard FPGA.
+     reset the Breakout Board by pressing the onboard FPGA reset button (see above).
 
 MMCX Cables
 ________________________
@@ -124,15 +134,8 @@ The breakout board contains a `TinyFPGA BX <https://github.com/tinyfpga/TinyFPGA
 digital input serialization, digital output deserialization, interpreting user
 input, and driving indication LEDs. The `breakout board gateware
 <https://github.com/open-ephys/onix-breakout/tree/main/gateware>`__ is
-impelemented using an open-source toolchain (`Yosys
+implemented using an open-source toolchain (`Yosys
 <https://yosyshq.net/yosys/>`__ and `NextPnR
 <https://github.com/YosysHQ/nextpnr>`__).
 
-
-Updating the Gateware
-_________________________
-If Open Ephys team have provided you with an updated firmware file for the
-Breakout Board, the micro-USB port on the Breakout Board (labelled 'config')
-can be used to update the firmware on the board.
-
-.. todo:: Link and instructions
+Follow the instructions in :ref:`Updating Breakout Board Firmware <breakout_firmware_update>` to update the breakout board firmware to the latest version.

source/Hardware Guide/Breakout Board/updating-breakout-firmware.rst

@@ -0,0 +1,65 @@
+.. _breakout_firmware_update:
+
+.. toctree::
+    :hidden:
+
+Updating Breakout Board Firmware in Windows
+###############################################
+
+.. warning::
+     Connecting or disconnecting the breakout board while the PC is on causes damage to the FMChost.
+
+#. Power off the PC to which the breakout board is connected.
+
+#. Disconnect the breakout board from the PC by disconnecting the digital and analog I/O grey SDR cable.
+
+#. Connect a USB-microUSB from the PC you will use to perform the firmware update to the Config port on the side of the breakout board.
+
+#. Verify the Breakout Board version by looking at the specifications on the product.
+
+   .. figure:: /_static/images/breakout/breakout_1r5_fw.png
+        :align: center
+        :width: 60%
+
+        Breakout Board version 1.5 has four headstage ports (only two are enabled).
+
+   .. figure:: /_static/images/breakout/breakout_1r6_fw.png
+        :align: center
+        :width: 60%
+
+        Breakout Board version 1.6 has two headstage ports.
+
+#. Download the latest :ref:`firmware image <breakout_image_download>` for your hardware version. 
+
+   .. warning::
+         Make sure that the host firmware image you download matches the Breakout Board hardware version
+         you verified in the previous step. An incorrect firmware version will not report any error while updating but will cause failures during operation.
+
+#. Download the :ref:`breakout_updater_download` utilities package and unzip
+   it. Navigate to this folder using a console. Place the firmware image you downloaded in the previous step in the same folder.
+
+#. Press the onboard FPGA reset button (using a thin tool that fits the reset hole) to put the device into bootloader mode. The onboard FPGA status LED will breathe to indicate it is ready to be programmed.
+
+   .. figure:: /_static/images/breakout/tinyfpga_breathing.gif
+        :align: center
+        :width: 40%
+
+#. From the console, use the following command with the correct name of the firmware image you downloaded to program the device: 
+
+   .. code-block:: console
+
+        $ tinyprog.exe -p breakout_firmware_image_filename.bit
+
+#. Check that the breakout board firmware was programmed successfully
+
+   .. figure:: /_static/images/breakout/tinyprog_success.jpg
+        :align: center
+        :width: 80%
+
+#. Disconnect the USB-microUSB cable from the breakout board
+
+#. Power off the PC to which the breakout board will be connected.
+
+#. Connect the breakout board to the PC using the digital and analog I/O grey SDR cable, and any necessary headstage links as per the :ref:`setup guide <breakout_setup>`.
+
+.. #. Test the breakout board works by using the DigitalIO node to test communication from the board by using the buttons and the AnalogIO to test communication to the board by toggling the configuration between input and output.

source/Resources/downloads.rst

@@ -47,6 +47,27 @@ PCIe Host Updater
 
 -----------------
 
+.. _breakout_updater_download:
+
+Breakout Board Updater
+----------------------------------------------
+
+.. note:: Please see :ref:`Updating Breakout Board Firmware
+    <breakout_firmware_update>` for instructions on how to use these files.
+
+.. list-table:: Breakout Board update tools
+   :widths: 15 25 60
+   :header-rows: 1
+
+   * - Version
+     - Release Date
+     - Release Notes
+   * - :download:`1.0.0 <../_static/downloads/onix-software-releases/tinyprog.zip>`
+     - 2024.07.05
+     - Initial release.
+
+-----------------
+
 .. _riffa_driver_download:
 
 RIFFA Device Driver
@@ -107,3 +128,27 @@ PCIe Host Firmware
 ..      - 2022.11.27
 ..      - Remove unnecessary breakout board PLL reset during context initialization which could cause LEDs to turn off.
  
+
+.. _breakout_image_download:
+
+Breakout Board Firmware
+----------------------------------------------
+.. note:: Please see :ref:`Updating Breakout Board Firmware
+    <breakout_firmware_update>` for instructions on how to use these files.
+
+.. warning::
+      Make sure that the breakout board firmware image you download matches the breakout board hardware version you have
+      as shown in the table below. An incorrect firmware version will not report any error while updating but will cause failures during operation.
+
+.. table::
+    :widths: 50 50
+
+    +-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
+    |            Breakout Board Hardware version            |                             Breakout Board Firmware latest version                                          |
+    |                 as per product specs                  |                                   to download and update                                                    |
+    +=======================================================+=============================================================================================================+
+    | Hardware Revision 1.5  (four headstage ports)         | :download:`Firmware version 1.3 <../_static/downloads/onix-gateware-images/breakout-rev1.5-fw1.3.bin>`      |
+    +-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
+    | Hardware Revision 1.6  (two headstage ports)          | :download:`Firmware version 1.3 <../_static/downloads/onix-gateware-images/breakout-rev1.6-fw1.3.bin>`      |
+    +-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
+