rvc: getstarted : add Realsense2 GMSL camera setup page

robotics-ai-suite/robot-vision-control/docs/source/getstarted.rst

@@ -12,6 +12,8 @@ The following steps will help you get started with using RVC in a reference setu
 
    getstarted/requirements
    getstarted/supported_hw
+   getstarted/camera_setup.rst
+   getstarted/camera_setup_gmsl.rst
    getstarted/prepare_system
    getstarted/install
 

robotics-ai-suite/robot-vision-control/docs/source/getstarted/camera_setup.rst

@@ -0,0 +1,92 @@
+Camera USB Setup
+====================
+
+RVC supports |Realsense| |D4xx| cameras, with many `Exemplary Use Cases <../use_cases.html>`_ utilizing  
+the `D415 <https://realsenseai.com/stereo-depth-cameras/stereo-depth-camera-d415/>`_. Therefore, choosing the 
+D415 for your project ensures most example use cases will run with minimal configuration. 
+
+
+Initial Setup
+~~~~~~~~~~~~~
+Out of the box the |Realsense| cameras need to be updated to the latest firmware version. The most straight forward way to 
+accomplish this is by using the RealSense Viewer. This software, part of the `Intel® RealSense™ SDK 2.0 <https://github.com/IntelRealSense/librealsense>`_,  
+is a graphical user interface allowing one to view camera streams, edit configuration files, update firmware, and much more. 
+
+If you are running the exemplary use cases their docker containers have the **realsense-viewer** application installed, along with the entire **librealsense2-util** library. This
+is great for testing your camera from within the container but firmware updates are not supported in this manner. Therefore this action must be completed on your host machine, let's start by 
+checking if the tool is installed in your environment.
+
+.. code-block:: bash
+
+    # try to open the viewer 
+    realsense-viewer
+
+Did the software launch? If yes, containue to the :ref:`firmware-update` section. Otherwise, continue to :ref:`realsense-installation`.
+
+
+.. _realsense-installation:
+
+RealSense Installation
+^^^^^^^^^^^^^^^^^^^^^^
+
+On Ubuntu 22.04, one can build the **librealsense2-utils** and assoictaed libraries from source or install each via the Advanced Package Tool (apt). APT 
+is fairly straighforward and the recommended approach. if you require more fine-grained control, please review the documentation foumd on the library's
+`GitHub page <https://github.com/IntelRealSense/librealsense>`_.
+
+
+.. code-block:: bash
+
+   # Ensure apt-transport-https is installed to allow apt to handle HTTPS repositories.
+   sudo apt-get install apt-transport-https
+
+   # Next, add the Intel RealSense GPG key and repository to your system.
+   sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key F6E65AC044F831AC80A06380C8B3A55A6F3EFCDE
+   sudo add-apt-repository "deb https://librealsense.intel.com/Debian/apt-repo $(lsb_release -cs) main"
+
+   # After adding the repository, update your package lists to include the new sources
+   sudo apt update
+
+   # Finally, install librealsense2-utils and other required packages.
+   sudo apt-get install librealsense2-dkms librealsense2-utils librealsense2-dev
+
+
+If your selected camera is not plugged-in, do so now. Then run the realsense-viewer:
+
+.. code-block:: bash
+
+   realsense-viewer
+
+
+.. _firmware-update:
+
+Firmware Update
+^^^^^^^^^^^^^^^
+
+With the RealSense Viewer now launched, your attached camera configuration is displayed in the left menu, along with its avilable streams. Pay close 
+attention to the camera title, it is imperative that you are using a cable which supports USB 3.2. This can be verified by ensuring "3.2" appears after 
+your camera name (e.g. D415 USB 3.2) as is seen in the below image.
+
+.. figure:: images/firmware_update_request.png
+   :alt: RealSense with firmware out of date message
+   :width: 600px
+
+   RealSense Viewer launched
+
+
+Notice in the above image there is also a firmware notification informing the user the camera needs an update. Click **install** and expand the update window 
+to reveal the progress. You will be greeted with a pop-up window scrolling detailed information regarding the installation as seen below. 
+
+.. figure:: images/firmware_updating.png
+   :alt: Firmware update progress display
+   :width: 600px
+
+   Firmware update progress display
+
+Once the process has completed, select **2D** from the navigation bar in the upper right, then turn on each stream (e.g. stereo, RGB, motion) to reveal
+the outoput tiled within the window. See example output from updating a D455f below:
+
+.. figure:: images/firmware_success.png
+   :alt: Stereo, RGB, and Motion all working
+   :width: 600px
+
+   Stereo, RGB, and Motion sensors functioning as designed