diff --git a/docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst b/docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst index 4eada3be..ec3ee620 100644 --- a/docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst +++ b/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 `. -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 `. +.. _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 `__ -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 `. +.. _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 `. +.. _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 diff --git a/docs/source/control_hard_compon/rc_components/hub/ports/ch-ports.rst b/docs/source/control_hard_compon/rc_components/hub/ports/ch-ports.rst index ba015df7..9df6539b 100644 --- a/docs/source/control_hard_compon/rc_components/hub/ports/ch-ports.rst +++ b/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 ````. +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 `_ + 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 ````. +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. diff --git a/docs/source/control_hard_compon/rc_components/hub/ports/images/CH-HUB-FRONT.png b/docs/source/control_hard_compon/rc_components/hub/ports/images/CH-HUB-FRONT.png index 83a19d10..7d579b0d 100644 Binary files a/docs/source/control_hard_compon/rc_components/hub/ports/images/CH-HUB-FRONT.png and b/docs/source/control_hard_compon/rc_components/hub/ports/images/CH-HUB-FRONT.png differ diff --git a/docs/source/control_hard_compon/rc_components/hub/ports/std-ports.rst b/docs/source/control_hard_compon/rc_components/hub/ports/std-ports.rst index 65c4c97a..57a4caf9 100644 --- a/docs/source/control_hard_compon/rc_components/hub/ports/std-ports.rst +++ b/docs/source/control_hard_compon/rc_components/hub/ports/std-ports.rst @@ -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 `_ +The yellow `XT30 `_ 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 `_. 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 ````, -:ref:`Game Manual Part 1 `. For more information on this port please see +For more information on these ports please see the `REV Documentation `_. +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 `_. + +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 `_ +specific to expanding the pins on the XT30 connector. +For more information on this process please watch this `YouTube video `_. +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,8 +49,9 @@ 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 -````, :ref:`Game Manual Part 1 `. 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 `_ for approved servo power devices. +For more information on this port please see `REV Servo Port Documentation `_. +5V Power Ports @@ -54,10 +59,10 @@ please see `REV Servo Port Documentation `_ and -:ref:`Game Manual Part 1 `. +the Power Distribution section of the `Competition Manual `_. Analog Ports -------------- @@ -87,8 +92,8 @@ I2C Ports These 4-pin `JST-PH `_ 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 `. 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 `_. @@ -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*. diff --git a/docs/source/control_hard_compon/rc_components/uvc/uvc.rst b/docs/source/control_hard_compon/rc_components/uvc/uvc.rst index 06f28c7f..1c82202a 100644 --- a/docs/source/control_hard_compon/rc_components/uvc/uvc.rst +++ b/docs/source/control_hard_compon/rc_components/uvc/uvc.rst @@ -1,6 +1,13 @@ 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) `_ +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 @@ -8,49 +15,51 @@ UVC Webcam :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 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 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 `_ -(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 -````. 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 ` - :ref:`Connecting UVC Camera directly to REV Control Hub ` -- :ref:`USB Port Overview ` +- :ref:`USB Port Overview ` - :ref:`Vision in FIRST Tech Challenge ` + diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam.rst index 98d06dd7..114262eb 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/configuring-external-webcam.rst @@ -5,7 +5,7 @@ Introduction ------------ The Competition Manual allows the use of USB Video Class (UVC) compatible -cameras for computer vision-related tasks. See rule R715 for the full details. +cameras for computer vision-related tasks. If you are using a REV Robotics Control Hub, then you will need to use an external webcam, since the Control Hub does not include a built-in camera. This document describes how to connect, @@ -18,16 +18,13 @@ 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: -- `Logitech C270 HD - Webcam `__ -- `Logitech C310 HD - Webcam `__ -- `Logitech C920 HD - Webcam `__ +- :ref:`logitech_c270_label` +- :ref:`logitech_c310_label` +- :ref:`logitech_c920_label` Calibrating a UVC camera is an optional, advanced task. Instructions for creating a calibration file are in the comments of the @@ -39,11 +36,22 @@ for an online copy of the file). Connecting the Camera --------------------- -The UVC camera plugs directly into the USB 2.0 port on the REV Control +The UVC camera can plug directly into the USB 3.0 port on the REV Control Hub. Unlike the REV Expansion Hub, there is no need for an external powered USB hub. .. image:: images/USB-camera-Control-Hub.jpg + :alt: Control Hub with UVC camera connected. + +.. 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 `_ + 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 -------------------- @@ -58,6 +66,7 @@ activity should detect the webcam and give it a default name of “Webcam 1”. .. image:: images/webcam-config-CH.jpg + :alt: Screen shot showing the Scan button circled in yellow and the resulting USB device listed as Webcam 1. You can keep this default name (the sample Op Modes reference this name) or change it. If you change the webcam name, make sure your Op Modes @@ -95,12 +104,14 @@ at this time, during which the game pads and START button are disabled for safety. .. image:: images/DS-webcam-preview-CH-1.jpg + :alt: Driver Station screen shot showing the menu with the Camera Stream option circled in yellow. The camera image will appear on the DRIVER STATION screen. Manually touch the image to refresh it. To preserve bandwidth, only one frame is sent at a time. .. image:: images/DS-webcam-preview-CH-2.jpg + :alt: Driver Station screen shot showing the camera image. This option may be used to adjust the camera, with frequent manual image refreshing as needed. When finished, open the main menu and select @@ -109,18 +120,19 @@ close, the game pads will be enabled, and the START button may be pressed to continue running the Op Mode. .. image:: images/DS-webcam-preview-CH-3.jpg + :alt: Driver Station screen shot showing the menu with the Camera Stream option circled in yellow. **Important Note:** Because the Camera Stream feature is only available during the INIT phase of an Op Mode, you must ensure that the VisionPortal is activated in your Op Mode **before** the waitForStart command: .. image:: images/activateBeforeWaitForStart.png - :alt: The init code for the webcam must be called before waitForStart. + :alt: Blocks code showing the INIT code for the webcam is called before wait for start. If you do not see the Camera Stream option in your main menu on your DRIVER STATION, then verify that the VisionPortal is activated before the waitForStart command in your Op Mode. Also make sure you’ve -given the system enough time to initialize the Vuforia software before +given the system enough time to initialize the VisionPortal software before you check to see if Camera Stream is available. Scrcpy @@ -129,19 +141,19 @@ Scrcpy To view the camera output from a computer while an OpMode is running, you can use `scrcpy `__. To do this, you will first need to obtain an ADB connection with your Control Hub. -This can be done by connecting a USB-A - USB-C cable to the USB-C port +This can be done by connecting a USB-A to USB-C cable to the USB-C port on your Control Hub. If on Windows, you may also connect to your Control Hub WiFi network and open the `REV Hardware Client `__. Once connected, use `these instructions `__ to install and run scrcpy on your computer. .. image:: images/webcamWithScrcpy.jpg - :alt: The camera output viewed with scrcpy. + :alt: Screen shot showing the camera output viewed with scrcpy. **Important Note:** While scrcpy is a great way to view the camera output outside of competitions, the Competition Manual does not allow teams to have any devices other than the DRIVER STATION connected to your Control -Hub during a match. See rule R708 for the full details. +Hub during a match. External HDMI Monitor --------------------- @@ -150,6 +162,7 @@ Alternatively, camera output can be viewed on a display monitor or other device plugged into the HDMI port on the REV Control Hub. .. image:: images/HDMIMonitor.jpg + :alt: Photo showing an external HDMI monitor displaying the camera output from a connected control hub. **Important Note:** While a portable display monitor can be used to view or troubleshoot the camera stream on your Control Hub, teams are not @@ -166,3 +179,56 @@ For custom streams, advanced users of Android Studio may consult the and `CameraStreamSource `__ 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 `_ 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 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 REV Control Hub with a powered USB hub and two webcams. + + 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 `_ 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. + + diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/two-webcams.jpg b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/two-webcams.jpg new file mode 100644 index 00000000..31325e99 Binary files /dev/null and b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/two-webcams.jpg differ diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/webcam-and-limelight-3a.jpg b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/webcam-and-limelight-3a.jpg new file mode 100644 index 00000000..291fd82a Binary files /dev/null and b/docs/source/hardware_and_software_configuration/configuring/configuring_external_webcam/images/webcam-and-limelight-3a.jpg differ diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_uvc_camera/configuring-uvc-camera.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_uvc_camera/configuring-uvc-camera.rst index 076e81d3..240455c2 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_uvc_camera/configuring-uvc-camera.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_uvc_camera/configuring-uvc-camera.rst @@ -5,7 +5,7 @@ Introduction ------------ The Competition Manual allows the use of USB Video Class (UVC) compatible -cameras for computer vision-related tasks. See rule R715 for the full details. +cameras for computer vision-related tasks. Teams who are using an Android smartphone as their ROBOT CONTROLLER have the option of using an externally connected camera instead of the built-in camera for computer vision tasks. @@ -23,15 +23,18 @@ run properly. What type of External Camera can be Used? ----------------------------------------- -The system supports a “UVC” or USB Video Device Class cameras. +The system supports 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 @@ -39,17 +42,23 @@ ftc_app project folder (visit this `link `__ 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 @@ -57,26 +66,28 @@ used for this task since its data transfer speed is not fast enough to work with the USB-connected webcam. Also note that the Competition Manual permits the use of a powered USB -hub to make this connection. See rule R617 for the full details. If a +hub to make this connection. If a team uses a powered USB hub, the power to operate the USB hub can only come from either of the following sources: -1. An externally connected COTS USB Battery Pack in compliance with the - Competition Manual. See rule R602 for the full details. +1. An externally connected commercially available off-the-shelf (COTS) USB Battery Pack in compliance with the + Competition Manual. 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 `__. .. 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 + diff --git a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1269-ResistiveGroundingStrap.jpg b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1269-ResistiveGroundingStrap.jpg index 9d9d6875..ffbe5b77 100644 Binary files a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1269-ResistiveGroundingStrap.jpg and b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1269-ResistiveGroundingStrap.jpg differ diff --git a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1385-AndersonPowerPoleToXT30.png b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1385-AndersonPowerPoleToXT30.png index 740611fa..de9071c7 100644 Binary files a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1385-AndersonPowerPoleToXT30.png and b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/REV-31-1385-AndersonPowerPoleToXT30.png differ diff --git a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/heavydutystaticide.jpg b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/heavydutystaticide.jpg index 5e5fd21a..fe910cf7 100644 Binary files a/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/heavydutystaticide.jpg and b/docs/source/hardware_and_software_configuration/configuring/managing_esd/images/heavydutystaticide.jpg differ diff --git a/docs/source/hardware_and_software_configuration/configuring/managing_esd/managing-esd.rst b/docs/source/hardware_and_software_configuration/configuring/managing_esd/managing-esd.rst index 1394b8b4..5f9b0e3b 100644 --- a/docs/source/hardware_and_software_configuration/configuring/managing_esd/managing-esd.rst +++ b/docs/source/hardware_and_software_configuration/configuring/managing_esd/managing-esd.rst @@ -11,12 +11,11 @@ will disable or damage a robot’s control system. Note that this section only provides a brief overview of the physical phenomenon that causes ESD disruptions. You can use the following link -to view an in-depth white paper, written by Mr. Eric Chin (a FIRST +to view an in-depth white paper, written by Mr. Eric Chin (a *FIRST* alumnus and a 2018 summer engineering intern), which examines and quantifies the efficacy of various ESD mitigation techniques: -`Eric Chin’s White Paper on ESD Mitigation Techniques and their -Efficacy `__ +`ESD Mitigation Techniques For FTC (PDF 1.7MB) `__ Special thanks to Doug Chin, Eric Chin, and Greg Szczeszynski for the work they did to model the problems caused by ESD and to evaluate different techniques to @@ -39,9 +38,10 @@ accumulated on one object flows through a conductive path to the neutral or oppositely charged object. .. figure:: images/positivelyChargedRobot.png + :alt: A positively charged robot touching a neutral field wall. :align: center - - Positively charged robot next to neutral field wall. + + Example of an ESD event, current will flow from the robot to the field wall. How Robots Become Charged ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -55,8 +55,9 @@ uneven. When the surfaces are taken apart, they can become charged. This is called the triboelectric effect. .. figure:: images/triboelectric.png + :alt: Illustration of a wheel on a floor with a close up portion showing how electrons in the floor can become attached to the wheel. :align: center - + Robots become charged due to the triboelectric effect. A robot’s wheels moving on field tiles build charge on the robot frame just @@ -86,14 +87,15 @@ If the potential difference is high enough, it is also possible for current to flow through the air in the form of an electrical arc. Arcing occurs when the air between two differently charged conductors becomes ionized and allows current to flow from one conductor to the other. Arcs -at voltages seen on FIRST Tech Challenge robots can jump air gaps of +at voltages seen on *FIRST* Tech Challenge robots can jump air gaps of more than 3/8” (1 cm). Arcs behave almost like direct contact, so they can carry a significant amount of current. Visible sparks go with large electrostatic arcs. .. figure:: images/discharging.png + :alt: Illustration showing two circles and the current flow from positive to negative. :align: center - + Electric arc between two spheres of opposite charge. What Steps can be Taken to Mitigate the Risk of an ESD Disruption? @@ -108,8 +110,11 @@ anti-static spray. Anti-static spray increases electrical conductivity of the surface of the tiles. This helps prevent the build-up of electrostatic charge on the robots as the move across the tile floor. -.. figure:: images/heavydutystaticide.jpg +.. image:: images/heavydutystaticide.jpg + :alt: A gallon jug and a quart spray bottle of ACL Heavy Duty Staticide. :align: center + +| *FIRST* recommends the use of `ACL Heavy Duty Staticide `__ @@ -130,11 +135,10 @@ ESD event. This can reduce the risk of damage to or disruption of electrical components when a sensor or other peripheral device receives a shock. -.. figure:: images/ferritechoke.jpg +.. image:: images/ferritechoke.jpg + :alt: A snap-on ferrite choke. :align: center - A snap-on ferrite choke. - Using ferrite chokes can be a very effective method for mitigating the effects of ESD: @@ -148,7 +152,7 @@ effects of ESD: Step 3: Electrically Isolating the Electronics from the Metal Frame of the Robot ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As a robot moves back and forth across the tile floor during a FIRST +As a robot moves back and forth across the tile floor during a *FIRST* Tech Challenge match, charge can accumulate on the metallic frame of the robot due to the triboelectric effect. If a charge builds up on the frame of the robot, but the electronics that make up the Control System @@ -169,8 +173,11 @@ Using a non-conductive, rigid panel can also help with wire management and strain relieving. .. figure:: images/mountonplywood.jpg + :alt: An expansion hub mounted on a plywood sheet. :align: center + The plywood sheet has holes drilled in it and wires are secured with cable ties to the plywood. + Sub Step B: Isolate Exposed or Poorly Insulated Parts of the Electronics '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' @@ -179,8 +186,9 @@ are poorly insulated. If these parts are placed too close to the metal frame, a shock can occur if a charge accumulates on the frame. .. figure:: images/poorlyinsulated.jpg + :alt: A sensor with 4-wire connector and a servo wire extension connection, the 4-wire connector and extension connection are are circled in red. :align: center - + Electrostatic shocks can occur at poorly insulated or exposed portions of the electronics. @@ -190,27 +198,38 @@ charge accumulates on the metal frame of the robot, and the end of sensor cable is placed close to the frame, a shock can occur and this shock can disrupt or even damage the I2C port of an Expansion Hub. -Similarly, some servo extension cables (see figure above) have exposed +Similarly, some servo extension cables have exposed portions of metal that could be vulnerable to ESD unless properly isolated or insulated. +Moving these vulnerable areas of the electronics system away from the +frame (with an air gap greater than 3/8” or 10mm) can help reduce the +risk of an ESD disruption. + .. figure:: images/keepawayfromframe.jpg + :alt: A sensor with an air gap between the frame and the 4-wire connector. :align: center + + Keep exposed portions of the electronics away from the frame. - Keep exposed portions of the electronics more than 3/8” (10mm) away from - the frame. - -Moving these vulnerable areas of the electronics system away from the -frame (with an air gap greater than 3/8” or 10mm) can help reduce the -risk of an ESD disruption. Using electrical tape to insulate these areas -can be equally effective and may be easier to implement. +Using electrical tape to insulate these areas can be equally effective and may be easier to implement. .. figure:: images/tapepoorlyinsulated.jpg + :alt: A servo wire extension connection wrapped in electrical tape and a sensor mounted on a frame where the frame is wrapped in electrical tape. :align: center - + Electrical tape can be used to insulate exposed or poorly insulated metal. +.. warning:: An 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 `_ + 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. + Step 3: Covering Exterior Metal Features with Electrically Insulated Material ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -222,8 +241,9 @@ electrical potential and trigger an ESD event. Wooden bumpers, electrical tape, and other non-conductive coatings are all effective. .. figure:: images/coverwithtape.jpg + :alt: A robot claw mechanism where the metal claws are wrapped in electrical tape. :align: center - + Insulating portions of the robot that touch other metallic objects on the field can help. @@ -240,14 +260,16 @@ the electronics. Doing this can help reduce the risk that a shock can occur between the frame of a robot and the Control System electronics. .. figure:: images/REV-31-1269-ResistiveGroundingStrap.jpg + :alt: The REV Resistive Grounding Strap has a XT30 connection on one end and an eye loop connector on the other end. :align: center The REV Resistive Grounding Strap (REV-31-1269) is an approved grounding cable. It is important that the grounding **only be done using a -FIRST-approved, commercially manufactured cable** (i.e., the REV-31-1269 -Resistive Grounding Strap). A FIRST-approved cable has an appropriately +FIRST-approved, commercially manufactured cable** +(see the competition manual for the currently approved cables). +A *FIRST*-approved cable has an appropriately sized inline resistor. This resistor is critical because it acts as a safeguard to prevent excessive current from flowing through the frame of the robot if a “hot” (positive) wire of the electronics system is @@ -261,19 +283,20 @@ need to use the REV Robotics Anderson Powerpole to XT30 Adapter cable in conjunction with REV Robotics’ Resistive Grounding Strap: .. figure:: images/REV-31-1385-AndersonPowerPoleToXT30.png + :alt: REV Robotics Anderson Powerpole to XT30 Adapter cable :align: center - + The REV-31-1385 adapter is approved for use with REV’s Resistive Grounding Strap. - -To ground the electronics, plug one end of the FIRST-approved cable into +To ground the electronics, plug one end of the *FIRST*-approved cable into a spare XT30 port on the Control System electronics. Then bolt the other end using a conductive (i.e., metal) bolt to the frame of the robot. .. figure:: images/groundtheelectronics.png + :alt: An expansion hub with a grounding cable connected to the XT30 port and bolted to the metal frame of the robot. :align: center - + Ground the electronics to the frame using a FIRST-approved cable. It might initially seem contradictory to both insulate the electronic