Merge pull request #340 from acharraggi/update-esd-page

Update Alt text for the ESD mitigation page. Update pages to mention possible ESD on USB 2.0 ports with webcams, use USB 3.0 port instead.

Author: acharraggi

docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst

@@ -6,25 +6,32 @@ This is a short list of common webcams that are known to work with the
 and the 
 :ref:`FTC Camera Controls <apriltag/vision_portal/visionportal_camera_controls/visionportal-camera-controls:visionportal camera controls>`.
 
-VisionPortal is a comprehensive new interface for FTC vision processing,
-including AprilTag and TensorFlow Object Detection (TFOD).
+VisionPortal is a comprehensive interface for FTC vision processing.
+Example use cases for a webcam are:
+
+- :doc:`detecting <../../../apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values>` an AprilTag,
+- determining where the robot is :doc:`located <../../../apriltag/vision_portal/apriltag_localization/apriltag-localization>` on the field,
+- using OpenCV to :doc:`detect colors or shapes <../../../color_processing/index>` of game elements.
 
 Many more webcams can work with the FTC VisionPortal; this is a short
 list of models with built-in calibrations suitable for AprilTag 
 :ref:`pose estimation <apriltag/vision_portal/apriltag_pose/apriltag-pose:aprilTag pose>`.
 
+.. _logitech_c270_label:
+
 Logitech C270
 -------------
 
 .. figure:: images/010-C270.png
    :align: center
    :width: 55%
+   :class: no-scaled-link
    :alt: C270 Camera
 
    Logitech C270 Camera
 
 The `Logitech C270 <https://www.logitech.com/en-us/products/webcams/c270-hd-webcam.960-000694.html>`__
-is available at the FIRST Storefront for new FTC teams, and at many
+is available at the *FIRST* Storefront for new FTC teams, and at many
 online retailers.
 
 **FTC Hot Take:**
@@ -45,12 +52,15 @@ The FTC SDK provides **built-in calibration values** for the FTC
 VisionPortal default resolution of 640x480, and no others. Learn more at
 :ref:`AprilTag Camera Calibration <apriltag/vision_portal/apriltag_camera_calibration/apriltag-camera-calibration:apriltag camera calibration>`.
 
+.. _logitech_c310_label:
+
 Logitech C310
 -------------
 
 .. figure:: images/030-C310.png
    :align: center
    :width: 55%
+   :class: no-scaled-link
    :alt: C310 Camera
 
    Logitech C310 Camera
@@ -77,12 +87,15 @@ The FTC SDK provides **built-in calibration values** for the FTC
 VisionPortal default resolution of 640x480, and for 640x360. Learn more at
 :ref:`AprilTag Camera Calibration <apriltag/vision_portal/apriltag_camera_calibration/apriltag-camera-calibration:apriltag camera calibration>`.
 
+.. _logitech_c920_label:
+
 Logitech C920
 -------------
 
 .. figure:: images/020-C920.png
    :align: center
    :width: 55%
+   :class: no-scaled-link
    :alt: C920 Camera
 
    Logitech C920 Camera
@@ -119,6 +132,7 @@ Microsoft LifeCam HD-3000 v1/v2
 .. figure:: images/040-LifeCam-3000.png
    :align: center
    :width: 55%
+   :class: no-scaled-link
    :alt: LifeCam-3000 Camera
 
    Microsoft LifeCam HD-3000 v1/v2
@@ -184,6 +198,7 @@ Arducam Global Shutter 120 FPS
 .. figure:: images/050-Arducam.png
    :align: center
    :width: 55%
+   :class: no-scaled-link
    :alt: Arducam GS 120 Camera
 
    Arducam GS 120 Camera

docs/source/control_hard_compon/rc_components/hub/ports/ch-ports.rst

@@ -3,39 +3,63 @@ Control Hub Ports
 
 .. figure:: images/CH-HUB.png
     :align: center
-    :alt: Control Hub
+    :alt: REV Control Hub
 
-    REV Control Hub (REV-31-1595)
+    Part number REV-31-1595
 
 .. include:: std-ports.rst
 
 
 .. figure:: images/CH-HUB-FRONT.png
     :align: center
-    :alt: Control Hub Ports
+    :alt: The ports from left to right are: USB 2.0, USB 3.0, USB C, USB Mini (below the USB C port),  HDMI, and Micro SD.
 
     Control Hub Front Ports
 
+USB Ports
+---------
 
-USB-A Ports
------------
+Universal Serial Bus (USB) is an industry standard that allows data exchange and delivery of power between many types of electronics.
+The control hub has four USB ports described below. 
 
-A Control Hub has both a USB 2.0 and 3.0 Type-A female port. This is primarily
-used for connecting UVC Cameras in acccordance with ``<RE14>``.
+USB 2.0 and USB 3.0 refer to the USB specifications that relate to data exchange rate and power delivery.
 
-USB-B Port
-----------
+USB Type-A and USB-C and USB Mini-B refer to the type of connector. 
 
-On a Control Hub, the USB-mini-B port is used only to communicate directly to
-the I/O system. In this case, it is only for the purpose of uploading firmware
-to the device.
+- USB Type-A is a larger rectangular connector.
+- USB-C is a smaller oval connector.
+- USB Mini-B is a smaller rectangular connector with a beveled edge.
+
+USB 2.0
+^^^^^^^
+
+This is a female USB Type-A port that implements USB 2.0 and can be used for connecting USB devices as allowed for in the Competition Manual.
+
+.. warning:: An electrostatic discharge (ESD) event on the USB 2.0 port on the Control Hub can cause Wi-Fi disconnects.
+
+   The REV Control Hub has a 
+   `known ESD issue <https://docs.revrobotics.com/duo-control/troubleshooting-the-control-system/troubleshooting-the-control-system#esd-mitigation-techniques>`_
+   with devices plugged into the USB 2.0 port. 
+   Using the USB 2.0 Port may cause ESD to affect your Control Hub's Wi-Fi Chip (causing Wi-Fi disconnects with the driver hub). 
+   Ensure that you plug USB devices, such as a Camera, into the USB 3.0 Port on your Control Hub. 
+
+USB 3.0
+^^^^^^^
 
-USB-C Ports
------------
+This is a female USB Type-A port that implements USB 3.0 and is primarily used for connecting USB video device class (UVC) cameras (webcams).
 
-A Control Hub has a USB-C port. This is primarily used for connecting to a
-laptop for loading the SDK but can also be used with a UVC Camera in
-acccordance with ``<RE14>``.
+USB C
+^^^^^
+
+A Control Hub has a female USB-C port that implements USB 2.0. This is primarily used for connecting to a
+laptop for loading the SDK but can also be used with a UVC Camera.
+
+MINI USB
+^^^^^^^^
+
+This is a female USB Mini-B port that implements USB 2.0. It is used only to communicate directly to
+the I/O system. In this case, it is only for the purpose of uploading firmware
+to the device.
 
 HDMI
 -----
@@ -44,3 +68,7 @@ The Control Hub lacks a display of its own even though it is a fully-fledged
 Android device. The Control Hub has an HDMI port that provides video output for
 the device; this HDMI port can be used to connect to an external display.
 
+MICRO SD
+--------
+
+This is a port for a Micro SD memory card. It is not normally used.

docs/source/control_hard_compon/rc_components/hub/ports/images/CH-HUB-FRONT.png

@@ -5,15 +5,19 @@ Battery Ports
    **Never** connect a battery charger directly to the battery port. This will
    void your warranty and fry your hub.
 
-These `XT-30 <https://docs.revrobotics.com/duo-control/control-system-overview/cables-and-connectors/xt-30-power-cable>`_ 
+The yellow `XT30 <https://docs.revrobotics.com/duo-control/control-system-overview/cables-and-connectors/xt-30-power-cable>`_ 
 connectors are used to power your REV Hub as well as all the devices connected to it. 
-As the connector is known for its fragility it is highly recommended you be careful when using it.
-It is also recommended that you expand your connector prongs periodically. For more information on this 
-process please watch this `video <https://www.youtube.com/watch?v=UYXTiSeVmB0>`_. While this video features an XT60, a larger version 
-of the XT-30, and a drone the advice is much the same. This port may also be used 
-to connect a grounding strap. For more information on legal grounding straps see ``<RE15>``, 
-:ref:`Game Manual Part 1 <manuals/game_manuals/game_manuals:game manuals>`. For more information on this port please see 
+For more information on these ports please see the
 `REV Documentation <https://docs.revrobotics.com/duo-control/control-system-overview/control-hub-basics#input-power-specifications>`_.
+One of these ports may also be used to connect a grounding strap. For more information on legal grounding straps see 
+the Power Distribution section of the `Competition Manual <https://ftc-resources.firstinspires.org/file/ftc/game/manual>`_.
+
+As the XT30 connector is known for its fragility it is highly recommended you be careful when using it.
+It is also recommended that you expand your connector prongs periodically. 
+REV has a `troubleshooting article <https://docs.revrobotics.com/duo-control/troubleshooting-the-control-system/control-hub-troubleshooting#xt30-pins-are-compressed>`_ 
+specific to expanding the pins on the XT30 connector.
+For more information on this process please watch this `YouTube video <https://www.youtube.com/watch?v=UYXTiSeVmB0>`_. 
+While this video features an XT60 connector, a larger version of the XT30, and a drone, the advice is much the same. 
 
 Motor Ports
 -------------
@@ -45,19 +49,20 @@ Servo Ports
 
 These 0.1” Header pins are used to power and control your servos. There are 6 ports on each hub and they are numbered from 0-5. 
 Be mindful of matching the polarity of the device attached to this port as it is possible to flip the connector. 
-For increasing the power supplied to these servos it is possible to use a Servo Power Module that is in compliance with 
-``<RE05>``, :ref:`Game Manual Part 1 <manuals/game_manuals/game_manuals:game manuals>`. For more information on this port 
+For increasing the power supplied to these servos it is possible to use a Servo Power Module. 
+See the Motors & Actuators section of the `Competition Manual <https://ftc-resources.firstinspires.org/file/ftc/game/manual>`_ for approved servo power devices.
+For more information on this port 
 please see `REV Servo Port Documentation <https://docs.revrobotics.com/duo-control/control-system-overview/control-hub-basics#servo-port-specifications>`_.
 
 +5V Power Ports
 ---------------
 
 These 0.1” Header pins are used to power and control various appliances. There
 are two ports on each hub. These connectors can be used for a limited range of
-applications in FIRST Tech Challenge, such as powering powered USB hubs. For more
+applications in *FIRST* Tech Challenge, such as powering powered USB hubs. For more
 information on this port please see 
 `REV +5V Power Port Documentation <https://docs.revrobotics.com/duo-control/control-system-overview/control-hub-basics#id-5v-power-port-specifications>`_ and 
-:ref:`Game Manual Part 1 <manuals/game_manuals/game_manuals:game manuals>`.
+the Power Distribution section of the `Competition Manual <https://ftc-resources.firstinspires.org/file/ftc/game/manual>`_.
 
 Analog Ports
 --------------
@@ -87,8 +92,8 @@ I2C Ports
 
 These 4-pin `JST-PH <https://docs.revrobotics.com/duo-control/control-system-overview/cables-and-connectors/jst-ph-sensors-and-rs485>`_ 
 style connectors are used for connecting I2C sensors. Each port is a single I2C bus where multiple sensors can be 
-attached. Using sensors with identical addresses on the same bus can cause problems. The range of I2C sensors that can be connected is limited 
-by :ref:`Game Manual Part 1 <manuals/game_manuals/game_manuals:game manuals>`. While it is possible to use a large range of 
+attached. Using sensors with identical addresses on the same bus can cause problems. 
+While it is possible to use a large range of 
 sensors, the vast majority of I2C sensors do not have drivers built into the SDK. It is possible to use community drivers 
 or create your own. For more information on this port please see 
 `REV I2C Port Documentation <https://docs.revrobotics.com/duo-control/control-system-overview/control-hub-basics#i2c-port-specifications>`_.
@@ -106,5 +111,5 @@ UART
 -----
 
 This connector is used only for **Developer** (non end user) debugging. Its use is not supported 
-by FIRST.
+by *FIRST*.
 

docs/source/control_hard_compon/rc_components/hub/ports/std-ports.rst

@@ -1,56 +1,65 @@
 UVC Webcam
 ===========
 
+A webcam is a device that provides visual images of the surrounding environment. 
+UVC, or USB Video Class, is a standard that allows USB devices, like webcams and digital cameras, to stream video to computers without needing special drivers. 
+For use as part of *FIRST* Tech Challenge teams must use a commercially available off-the-shelf (COTS)
+USB Video Class `(UVC) <https://www.usb.org/document-library/video-class-v15-document-set>`_ 
+compatible camera. This device can be connected directly to
+the REV Control Hub or to the Robot Control system via a USB hub.
+
 .. grid:: 1 2 2 2
    :gutter: 2
 
    .. grid-item-card::
       :class-header: sd-bg-dark font-weight-bold sd-text-white
       :class-body: sd-text-left body
 
-      Logitech C270
+      Budget Webcam
 
       ^^^
 
       .. figure:: images/C270.jpg
          :align: center
          :width: 50 %
-         :alt: C270
+         :class: no-scaled-link
+         :alt: Example budget UVC webcam
 
       +++
 
-      Logitech C270
+      :ref:`logitech_c270_label`
 
    .. grid-item-card::
       :class-header: sd-bg-dark font-weight-bold sd-text-white
       :class-body: sd-text-left body
 
-      Logitech C920
+      Mid-range Webcam
 
       ^^^
 
       .. figure:: images/C920.jpg
          :align: center
          :width: 50 %
-         :alt: C920
+         :class: no-scaled-link
+         :alt: Example mid-range UVC webcam
 
       +++
 
-      Logitech C920
+      :ref:`logitech_c920_label`
+
+Webcams are intended to be used in computer vision related tasks.
+Example use cases for a webcam are:
 
-A webcam is a device that provides visual images of the surrounding
-environment. For use as part of *FIRST* Tech Challenge teams must use a COTS 
-`UVC <https://www.usb.org/document-library/video-class-v15-document-set>`_ 
-(USB Video Class) Compatible Camera. This device can be connected directly to
-the REV Control Hub or to the Robot Control system via a powered USB hub
-``<RE14>``. This device is intended to be used in vision related tasks. An
-example use case of a webcam is reading the state of the barcode after
-randomization, a vision task in *Freight Frenzy*, 2021-2022.
+- :doc:`detecting <../../../apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values>` an AprilTag,
+- determining where the robot is :doc:`located <../../../apriltag/vision_portal/apriltag_localization/apriltag-localization>` on the field,
+- using OpenCV to :doc:`detect colors or shapes <../../../color_processing/index>` of game elements.
 
 Additional Resources
 --------------------
 
+- A :doc:`list of webcams <../../../apriltag/vision_portal/visionportal_webcams/visionportal-webcams>` known to be compatible with VisionPortal.
 - :ref:`Connecting UVC Camera via Powered USB Hub <hardware_and_software_configuration/configuring/configuring_uvc_camera/configuring-uvc-camera:configuring an external uvc camera and a powered usb hub>`
 - :ref:`Connecting UVC Camera directly to REV Control Hub <hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam:configuring an external webcam with a control hub>`
-- :ref:`USB Port Overview <control_hard_compon/rc_components/hub/ports/ch-ports:USB-A Ports>`
+- :ref:`USB Port Overview <control_hard_compon/rc_components/hub/ports/ch-ports:USB Ports>`
 - :ref:`Vision in FIRST Tech Challenge <programming_resources/index:vision programming>`
+