update alt text and add Cameras and USB Hubs section with new images.

Author: acharraggi

docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam.rst

@@ -18,7 +18,7 @@ Type of External Camera
 -----------------------
 
 Theoretically, any USB Video Class (UVC) camera should work with the 
-system. However, FIRST recommends using UVC web cameras from Logitech.
+system. However, *FIRST* recommends using UVC web cameras from Logitech.
 The following cameras have been tested and calibrated to work accurately
 with SDK software:
 
@@ -53,6 +53,8 @@ powered USB hub.
    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. 
+   
+If you wish to connect two webcams see `Cameras and USB Hubs`_.
 
 Camera Configuration
 --------------------
@@ -180,3 +182,56 @@ For custom streams, advanced users of Android Studio may consult the
 and
 `CameraStreamSource <https://javadoc.io/doc/org.firstinspires.ftc/RobotCore/latest/org/firstinspires/ftc/robotcore/external/stream/CameraStreamSource.html>`__
 classes.
+
+Cameras and USB Hubs 
+^^^^^^^^^^^^^^^^^^^^
+
+You can already connect a UVC webcam into the USB 3.0 port of a Control Hub.
+But what if you want to use two webcams?
+Perhaps you want the robot to be able to look forward and/or behind without having to spin the robot. 
+In order to use two webcams on the Control Hub's USB 3.0 port you can add a USB Hub.
+This avoid the ESD issue with devices on the USB 2.0 port.
+
+.. note:: If you're using two standard UVC webcams you are not required to use a powered USB hub.
+
+Another use case for a USB hub is if you have a `Limelight 3A <https://limelightvision.io/products/limelight-3a>`_ camera. 
+This device has its own processor on board and one drawback of this is that the camera always draws power, even when an opMode is not running.
+By adding a powered USB hub the Limelight will not drain your robot's battery.
+
+One suitable powered USB hub is the Acer ODK350 5-IN-1 USB 3.0 Hub. 
+It provides USB 3.0 data speeds to all ports and it has a USB C port that can supply power to all connected devices.
+
+.. note:: At the time this was written, the Acer ODK350 hub was not listed on Acer's website, but was available on Amazon's website.
+   
+   Not all USB hubs are powered hubs.
+   Typically, you can't just plug a power bank into any of the USB hub's ports. It must be a port that is designed to supply power.
+   So if you looking for a powered USB hub there should be a note in the specifications something like the following:
+   *Note: This USB C port (with IN 5V printed) can not be used for data transfer and charge other devices. It can only supply power for the other 4 USB ports.*
+
+.. figure:: images/two-webcams.jpg
+   :alt: A USB hub with two webcams is connected to a REV Control Hub.
+   
+   Acer ODK350 USB hub
+   
+   The USB Hub is connected to the USB 3.0 port of the Control Hub.
+   A powerbank is connected to the USB C port on the USB hub to supply power to the connected devices.
+   Two Logitech 920 webcams are connected to the USB hub.
+
+See the `AprilTag Switchable Cameras <https://github.com/FIRST-Tech-Challenge/FtcRobotController/blob/master/FtcRobotController/src/main/java/org/firstinspires/ftc/robotcontroller/external/samples/ConceptAprilTagSwitchableCameras.java>`_ sample program that demonstrates swapping between the two cameras to detect AprilTags.
+
+The other use case is using a Limelight a with a powered USB hub to reduce robot battery drain.
+This example shows both a Limelight and a webcam.
+
+.. figure:: images/webcam-and-limelight-3a.jpg
+   :alt: A USB hub with a webcam and a Limelight 3A connected to a REV Control Hub.
+
+   Acer ODK350 USB hub
+     
+   The USB Hub is connected to the USB 3.0 port of the Control Hub.
+   A powerbank is connected to the USB C port on the USB hub to supply power to the connected devices.
+   A Logitech 270 webcam and a Limelight 3A are connected to the USB hub.
+
+The Limelight 3A is not a compatible VisionPortal device. So you can't use the AprilTag switchable camera sample code.
+But you can still get results from either the Limelight and/or the VisionPortal webcam and use them as required.
+
+

docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/two-webcams.jpg

@@ -23,33 +23,42 @@ run properly.
 What type of External Camera can be Used?
 -----------------------------------------
 
-The system supports a “UVC” or USB Video Device Class cameras.
+The system supports a UVC cameras.
 Theoretically, if a camera is UVC compliant, then it should work with
 the system. However, there are a couple of recommended web cameras that
-have been tested with the FIRST Tech Challenge software and have been
+have been tested with the *FIRST* Tech Challenge software and have been
 calibrated to work accurately with this software:
 
 -  Logitech HD Webcam C310
 -  Logitech HD Pro Webcam C920
 
+There are notes on :doc:`other UVC webcams <../../../apriltag/vision_portal/visionportal_webcams/visionportal-webcams>`
+that teams can use.
+
 Note that calibrating a UVC camera is an advanced task. Details on how
 to create a calibration file can be found in the comments of the
 *teamwebcamcalibrations.xml* file that is available as part of the
 ftc_app project folder (visit this
 `link <https://github.com/ftctechnh/ftc_app/blob/master/TeamCode/src/main/res/xml/teamwebcamcalibrations.xml>`__
 for an online copy of the file).
 
+REV Expansion Hub and Phone
+---------------------------
+
+For teams using an Android phone and an Expansion Hub you are required to add a USB Hub to use a webcam.
+
 .. image:: images/uvcdiagram.png
+   :alt: A REV expansion hub connected to an Android phone and a webcam via a USB Hub.
 
 USB Hub
--------
+^^^^^^^
 
 Teams who would like to use an external camera will need a USB hub to
 connect their Android Robot Controller to the external camera and the
 REV Robotics Expansion Hub. To work properly, the USB hub should meet
 the following requirements:
 
-1. Compatible with USB 2.0.
+1. Compatible with USB 2.0. Note: a USB 3.0 hub will still work, just not at the faster speed.
 2. Supports a data transfer rate of 480Mbps.
 
 Note that the Modern Robotics Core Power Distribution Module cannot be
@@ -66,17 +75,19 @@ come from either of the following sources:
 2. The 5V DC Aux power port of a REV Robotics Expansion Hub (note that
    this requires advanced skills to implement).
 
-FIRST has tested a few USB 2.0 powered hubs and recommends one from
+*FIRST* has tested a few USB 2.0 powered hubs and recommends one from
 Anker. At the time this document was written, this hub was available
 from `Anker.com <https://www.anker.com/products/a7516>`__.
 
 .. image:: images/ankerhub.jpg
+   :alt: Hub with charger and cable.
 
 The Anker 4-port powered hub is convenient because it has a Micro USB
 port that is used to connect the hub to a 5V power source (highlighted
 with orange circle in figure below).
 
 .. image:: images/ankerpowerport.jpg
+   :alt: USB Hub with Micro USB port.
 
 This port allows a user to plug a standard USB type B Micro Cable into
 the hub, and then connect the other end of the cable (which has a USB
@@ -86,14 +97,25 @@ pack. In the image below, the Anker 4 port hub is powered by a
 USB Micro cable. Note the battery is highlighted by the yellow outline
 in the figure below.
 
-.. image:: images/limefuel.png
+.. figure:: images/limefuel.png
+   :alt: A complete setup for using a phone and webcam.
+   
+   The USB hub is drawing power from a power bank.
+
+The USB hub is connected via it's Type A connector and cable to an OTG cable which connects to the phone.
+The power bank is connected to the USB type B Micro port on the USB hub.
+The webcam is connected to one of the USB type A ports on the USB hub.
+A USB Type A to USB Mini B cable connects the USB hub to the REV Expansion Hub.
 
 A USB hub can also draw power from the 5V auxiliary ports on the REV
 Robotics Expansion Hub. This configuration requires that the user have a
 special cable that on one end can be plugged into the 5V Auxiliary port
 and on the other end can be plugged into the power port of the USB hub.
 
-.. image:: images/5vauxcable.png
+.. figure:: images/5vauxcable.png
+   :alt: :alt: A complete setup for using a phone and webcam.
+   
+   The USB hub is connected to the 5V Auxiliary port.
 
 Note that teams can create this special cable using one end of a servo
 extension cable (to plug into the 5V aux port) and one end of a Micro
@@ -105,10 +127,10 @@ special cable. If the polarity is reversed it could damage your
 electronic equipment.**
 
 Sample Op Modes
----------------
+^^^^^^^^^^^^^^^
 
 There are sample Blocks and Java Op Modes that demonstrate how to use
-the external UVC web camera for Vuforia or TensorFlow operations. Before
+the external UVC web camera for VisionPortal operations. Before
 a team can use the external UVC camera, a configuration file must be
 configured with the external camera defined as one of the USB-connected
 devices.
@@ -118,3 +140,5 @@ programmer can use the external UVC camera, instead of the internal
 Android cameras, for vision-related tasks.
 
 .. image:: images/blockswebcam.png
+   :alt: Sample Blocks code
+