diff --git a/.cspell/ftc-dictionary.txt b/.cspell/ftc-dictionary.txt index 3491ed326..6356bf9b5 100644 --- a/.cspell/ftc-dictionary.txt +++ b/.cspell/ftc-dictionary.txt @@ -33,12 +33,18 @@ controlhub Deadaxle deadwheel driverhub +drivetrain +drivetrains durometer durometers +feedforward +Feedforward gamepads Gamepads gearmotor gearmotors +handwheel +handwheels hardstop holonomic hotend @@ -47,6 +53,8 @@ hotends Hotends mecanum Mecanum +microcontroller +microcontrollers navx odometry Odometry diff --git a/docs/source/_static/css/ftc-rtd.css b/docs/source/_static/css/ftc-rtd.css index a3341f31f..bfd95976c 100644 --- a/docs/source/_static/css/ftc-rtd.css +++ b/docs/source/_static/css/ftc-rtd.css @@ -1277,7 +1277,47 @@ div.ethical-footer { } /* -------------------------------------------------------------------------- - 16. Dark mode surfaces + 16. Glossary + -------------------------------------------------------------------------- */ + +/* Glossary entries that have more than one name. + An entry such as "IMU" / "Inertial Measurement Unit" has to be written as + consecutive terms in the glossary directive, so that each name gets its own + anchor and can be linked with :term:. (Writing them comma-separated on one + line would make the comma part of a single term name, and :term:`IMU` would + then fail to resolve.) Sphinx renders each name as its own
, so join + them onto one line here, separated by a slash. */ +.rst-content dl.glossary > dt { + display: inline; +} + +.rst-content dl.glossary > dt + dt::before { + content: "/"; + margin: 0 0.45em; /* equal space either side of the slash */ + font-weight: 400; + opacity: 0.55; +} + +/* Each name carries a permalink that the theme leaves in the layout when it is + not hovered (opacity: 0, not display: none), so its glyph plus its 0.5em + margin would open a gap between the name and the slash. Drop the margin, and + keep the permalink itself only on the last name of an entry. */ +.rst-content dl.glossary > dt .headerlink { + margin-left: 0.25em; +} + +.rst-content dl.glossary > dt:has(+ dt) .headerlink { + display: none; +} + +/* The definition still needs to start on its own line. */ +.rst-content dl.glossary > dd { + display: block; + margin-top: 6px; +} + +/* -------------------------------------------------------------------------- + 17. Dark mode surfaces -------------------------------------------------------------------------- */ html[data-theme='dark'] body, @@ -1384,7 +1424,7 @@ html[data-theme='dark'] .rst-content footer { } /* -------------------------------------------------------------------------- - 17. Responsive + 18. Responsive -------------------------------------------------------------------------- */ @media screen and (max-width: 1100px) { diff --git a/docs/source/ai/innovation_corner/innovation-corner.rst b/docs/source/ai/innovation_corner/innovation-corner.rst index 633c9c79e..98359947d 100644 --- a/docs/source/ai/innovation_corner/innovation-corner.rst +++ b/docs/source/ai/innovation_corner/innovation-corner.rst @@ -103,7 +103,7 @@ you'd like to see. to put this ability to good use in *FIRST* Tech Challenge? In *FIRST* Tech Challenge, one of the first tasks teams have to do is to read - and understand the *FIRST* Tech Challenge Competition Manual. This can be a + and understand the *FIRST* Tech Challenge :term:`Competition Manual`. This can be a very painstaking task, and even a skilled reader can miss subtle nuances provided by the manual. However, an AI can break down and analyze the manual in a matter of seconds, usually preserving the nuance provided in the @@ -197,7 +197,7 @@ you'd like to see. Examples of difficult questions: - * What is the maximum score for an alliance? + * What is the maximum score for an :term:`alliance `? * Can ROBOTS pick up an opposing ALLIANCE'S SAMPLES? * How many matches does a team play at an event? diff --git a/docs/source/apriltag/opmode_test_images/opmode-test-images.rst b/docs/source/apriltag/opmode_test_images/opmode-test-images.rst index 37dfda0e3..3cd6a0c96 100644 --- a/docs/source/apriltag/opmode_test_images/opmode-test-images.rst +++ b/docs/source/apriltag/opmode_test_images/opmode-test-images.rst @@ -6,7 +6,7 @@ Introduction In the 2023-2024 season, `FIRST Tech Challenge has introduced AprilTags `__ into -the season-unique competition. AprilTags were developed by the April +the season-unique competition. :term:`AprilTags ` were developed by the April Robotics Laboratory at the University of Michigan and are a visual fiducial tagging system, built on a similar concept as QR codes, useful for a wide variety of tasks including augmented reality, robotics, and diff --git a/docs/source/apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values.rst b/docs/source/apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values.rst index 08d13ec2c..f4e974afd 100644 --- a/docs/source/apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values.rst +++ b/docs/source/apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values.rst @@ -6,13 +6,13 @@ Understanding AprilTag Detection Values Introduction ------------ -When an AprilTag is detected by the new SDK vision processing system, the core +When an :term:`AprilTag` is detected by the new SDK vision processing system, the core code returns a collection of raw data that is often not easily interpreted. However, the data can be further transformed into a familiar frame of reference to make it more easily utilized. In the *FIRST* Tech Challenge SDK, the AprilTag API will present the Team -OpMode with a collection of translation and rotation values, called *ftcPose*, +:term:`OpMode` with a collection of translation and rotation values, called *ftcPose*, that represent the Tag’s position in 3D space. To understand how to interpret these values, it’s easier to consider a simpler @@ -98,7 +98,7 @@ horizontally (parallel to the ground). The AprilTag video preview image from the Camera Stream preview is shown below. The left tag has an ID of 0 and the right tag has an ID of 1. This video is -being captured by a Logitech C920 Pro HD webcam, running at 648x480 resolution. +being captured by a Logitech C920 Pro HD :term:`webcam `, running at 648x480 resolution. In this mode the camera has Field-Of-View (FOV) of 60 degrees. The physical tags are 3.4” square. diff --git a/docs/source/apriltag/vision_portal/apriltag_advanced_use/apriltag-advanced-use.rst b/docs/source/apriltag/vision_portal/apriltag_advanced_use/apriltag-advanced-use.rst index bc1cfbbaa..02e7637e1 100644 --- a/docs/source/apriltag/vision_portal/apriltag_advanced_use/apriltag-advanced-use.rst +++ b/docs/source/apriltag/vision_portal/apriltag_advanced_use/apriltag-advanced-use.rst @@ -5,13 +5,13 @@ Overview -------- This page will offer tips for *FIRST* Tech Challenge teams seeking more info -about specialized features of the new VisionPortal. +about specialized features of the new :term:`VisionPortal`. Optional Metadata ----------------- -An AprilTag Library tag can store two optional **Metadata** fields (of -these Blocks/Java types): +An :term:`AprilTag` Library tag can store two optional **Metadata** fields (of +these :term:`Blocks`/Java types): - ``fieldPosition``: tag location on the game field (``VectorF``) - ``fieldOrientation``: tag orientation on the game field (``Quaternion``) @@ -32,7 +32,7 @@ apply to **every game, every season**: Image Credit: Phil Malone With a tag’s **field position** and **orientation** specified in advance -as Metadata, the tag’s pose data could be used by an advanced OpMode to +as Metadata, the tag’s pose data could be used by an advanced :term:`OpMode` to calculate the robot’s position on the field. This conversion math, an exercise for the reader, can allow a robot to use the tag’s pose data in real-time to navigate to the desired location on the field. @@ -41,10 +41,10 @@ Raw Pose Values --------------- The frame of reference described at the **AprilTag Reference Frame** -page is provided **by default** in the new 8.2 SDK. +page is provided **by default** in the new 8.2 :term:`SDK`. Advanced teams may prefer to perform their own pose calculations, based -on **raw values** from the AprilTag/EasyOpenCV pipeline. +on **raw values** from the AprilTag/:term:`EasyOpenCV` pipeline. Those raw values are available to Java and Blocks programmers. The Java version is shown here: @@ -111,7 +111,7 @@ Other features of this Test OpMode include: - All controls are independent, to explore the combinations and their effect on frame rate (FPS). - The previews can be observed, and detections/recognitions can be monitored - via annotations and Telemetry. + via annotations and :term:`Telemetry`. - Frame rate is provided in LiveView and DS Telemetry. - The Telemetry functions include an alternate for getting **all** or **only fresh** detections/recognitions. @@ -131,7 +131,7 @@ zoom in. VisionPortal Example OpMode The OpMode uses "Webcam 1", or change ``USE_WEBCAM`` for a built-in RC phone -camera. For Control Hub, set up an HDMI monitor or `scrcpy +camera. For :term:`Control Hub`, set up an HDMI monitor or `scrcpy `__. Follow the DS gamepad button guide. At that **VisionPortal CPU and Bandwidth** page, four tools mentioned were not diff --git a/docs/source/apriltag/vision_portal/apriltag_id_code/apriltag-id-code.rst b/docs/source/apriltag/vision_portal/apriltag_id_code/apriltag-id-code.rst index 634540563..367e44061 100644 --- a/docs/source/apriltag/vision_portal/apriltag_id_code/apriltag-id-code.rst +++ b/docs/source/apriltag/vision_portal/apriltag_id_code/apriltag-id-code.rst @@ -1,8 +1,8 @@ AprilTag ID Codes ================= -After the AprilTag Processor and VisionPortal have been **initialized**, your -OpMode can begin tag detection. +After the :term:`AprilTag` Processor and :term:`VisionPortal` have been **initialized**, your +:term:`OpMode` can begin tag detection. Let's start with the simple task of retrieving the **ID code** of a detected AprilTag. For tag family 36h11, the numeric ID code ranges from 0 to 586. The @@ -88,7 +88,7 @@ detection, ending with only the **last tag's value**. By default, the FTC SDK recognizes the ID code of **any** 36h11 AprilTag, even if the OpMode did not place that tag in the AprilTag Library. Some tags are placed in the Library automatically by the SDK: for example, ID codes 583-586 -used by Sample OpModes. +used by :term:`Sample OpModes `. An OpMode can also place other tags in a Library, to supplement or overwrite default tags. This is covered further at the **Library** page. diff --git a/docs/source/apriltag/vision_portal/apriltag_intro/apriltag-intro.rst b/docs/source/apriltag/vision_portal/apriltag_intro/apriltag-intro.rst index 68d2018d8..25f2b49a5 100644 --- a/docs/source/apriltag/vision_portal/apriltag_intro/apriltag-intro.rst +++ b/docs/source/apriltag/vision_portal/apriltag_intro/apriltag-intro.rst @@ -16,25 +16,25 @@ especially those programming in Java. Photo Credit: Mike Silversides -Those POWERPLAY teams, including those using FTC Blocks, learned how to use +Those POWERPLAY teams, including those using FTC :term:`Blocks`, learned how to use several resources: -- AprilTag: an open-source technology for evaluating +- :term:`AprilTag`: an open-source technology for evaluating formatted images -- EasyOpenCV: a *FIRST* Tech Challenge-optimized interface with OpenCV, an +- :term:`EasyOpenCV`: a *FIRST* Tech Challenge-optimized interface with :term:`OpenCV`, an image processing library -- myBlocks: custom Blocks created in OnBot Java (OBJ) +- myBlocks: custom Blocks created in :term:`OnBot Java` (OBJ) Now these three areas are provided, or bundled, in the *FIRST* **Tech Challenge Software Development Kit (SDK), starting with version 8.2**. Namely, key capabilities of **AprilTag** and **EasyOpenCV** are -available to the Robot Controller (RC) and Driver Station (DS) apps, +available to the :term:`Robot Controller` (RC) and :term:`Driver Station` (DS) apps, without special downloads. And AprilTag features are included in **FTC Blocks**, without needing custom myBlocks. -The AprilTag features work on webcams and on Android RC phone cameras. -A single OpMode can use AprilTag and Color Processing. +The AprilTag features work on :term:`webcams ` and on Android RC phone cameras. +A single :term:`OpMode` can use AprilTag and Color Processing. In *FIRST* Tech Challenge, AprilTag is ready for the spotlight! @@ -85,7 +85,7 @@ recognizes and overlays the ID code onto the image (small blue rectangle Stream output showing the detected tag ID 02 The above image shows a camera preview image, called LiveView, from a -Robot Controller device (Control Hub or RC phone). +Robot Controller device (:term:`Control Hub` or RC phone). The AprilTag family 36h11 has a capacity of 587 ID codes. To see them all, follow this link: @@ -179,8 +179,8 @@ The SDK supports **multiple cameras**, switchable or simultaneous. This can help if the robot changes direction, or you wish to navigate using another AprilTag (or Color Processing). -Other sensors can also be used for navigation, such as drive motor encoders, -REV Hub IMU, deadwheel encoders, color/distance sensors, ultrasonic sensors, +Other :term:`sensors ` can also be used for navigation, such as drive motor :term:`encoders `, +REV Hub :term:`IMU`, deadwheel encoders, color/distance sensors, ultrasonic sensors, and more. It’s also possible to evaluate **non-AprilTag images** from the same camera @@ -268,7 +268,7 @@ The SDK provides AprilTag **rotation** data as follows: - **Pitch** is the measure of rotation about the X axis - **Roll** is the measure of rotation about the Y axis -- Heading, or **Yaw**, is the measure of rotation about the Z axis +- :term:`Heading`, or **Yaw**, is the measure of rotation about the Z axis Rotation follows the traditional right-hand rule: with the thumb pointing along the positive axis, the fingers curl in the direction of diff --git a/docs/source/apriltag/vision_portal/apriltag_library/apriltag-library.rst b/docs/source/apriltag/vision_portal/apriltag_library/apriltag-library.rst index f74da30fc..0986d9823 100644 --- a/docs/source/apriltag/vision_portal/apriltag_library/apriltag-library.rst +++ b/docs/source/apriltag/vision_portal/apriltag_library/apriltag-library.rst @@ -1,7 +1,7 @@ AprilTag Library ================ -For a *FIRST* Tech Challenge match, your OpMode has a known set of AprilTags to +For a *FIRST* Tech Challenge :term:`match `, your :term:`OpMode` has a known set of :term:`AprilTags ` to detect. They are preloaded by default or specified by you, with or without custom tags. @@ -52,7 +52,7 @@ Default Libraries The SDK uses two core Libraries of predefined AprilTags: -- tags used only in Sample OpModes +- tags used only in :term:`Sample OpModes ` - tags used only in the Robot Game (competition) The first Library, called ``SampleTagLibrary``, is available now with @@ -120,7 +120,7 @@ tags. Completing Builder - These are the first and last Blocks in the ``AprilTagProcessor.Builder`` + These are the first and last :term:`Blocks` in the ``AprilTagProcessor.Builder`` toolbox. The remaining Blocks are used to set optional features of the Processor. Here we are setting only the Library. diff --git a/docs/source/apriltag/vision_portal/apriltag_localization/apriltag-localization.rst b/docs/source/apriltag/vision_portal/apriltag_localization/apriltag-localization.rst index 07dfd93d9..247dfc9c0 100644 --- a/docs/source/apriltag/vision_portal/apriltag_localization/apriltag-localization.rst +++ b/docs/source/apriltag/vision_portal/apriltag_localization/apriltag-localization.rst @@ -4,11 +4,11 @@ AprilTag Localization Introduction ------------ -In *FIRST Tech Challenge* (FTC), **localization** uses sensor inputs to +In *FIRST Tech Challenge* (FTC), **localization** uses :term:`sensor ` inputs to determine the robot's current place **on the game field**. Since 2023, an FTC OpMode can read the **pose** (position and orientation) of -an AprilTag, **relative to the camera**. An OpMode can also read that +an :term:`AprilTag`, **relative to the camera**. An :term:`OpMode` can also read that AprilTag's **global** pose (on the FTC game field), stored as metadata. .. figure:: images/05-ITD-tags.png @@ -37,7 +37,7 @@ and rotation, based on sensing one or more fixed landmarks -- AprilTags in this case. This capability is provided in 2024 with FTC SDK version 10.0, including a -Sample OpMode, thanks to `Dryw Wade `_. This +:term:`Sample OpMode`, thanks to `Dryw Wade `_. This tutorial describes how to use that OpMode. Configuration @@ -48,8 +48,8 @@ Configuration * *the active robot configuration already contains "Webcam 1", or* * *using the built-in camera of an Android phone as Robot Controller.* -Before starting the programming, REV Control Hub users should make a robot -configuration that includes the USB webcam to be used for AprilTag +Before starting the programming, REV :term:`Control Hub` users should make a robot +configuration that includes the USB :term:`webcam ` to be used for AprilTag localization. For now, use the default webcam name, "Webcam 1". If a different name is @@ -57,12 +57,12 @@ preferred, edit the Sample OpMode to agree with the exact webcam name in the robot configuration. **Save and activate** that configuration; its name should appear on the paired -Driver Station screen. +:term:`Driver Station` screen. Open the Sample OpMode ---------------------- -To learn about opening the Sample OpMode, select and read the Blocks **or** +To learn about opening the Sample OpMode, select and read the :term:`Blocks` **or** Java section below: .. tab-set:: @@ -86,7 +86,7 @@ Java section below: .. tab-item:: Java :sync: java - Open your choice of OnBot Java or Android Studio. + Open your choice of :term:`OnBot Java` or :term:`Android Studio`. In the ``teamcode`` folder, add/create a new OpMode with a name such as "AprilTagLocalization_Oscar_v01.java", and select the Sample OpMode @@ -100,7 +100,7 @@ Java section below: Run the Sample OpMode --------------------- -On the Driver Station, select the TeleOp OpMode that you just saved or built. +On the Driver Station, select the :term:`TeleOp ` OpMode that you just saved or built. Aim the camera at an AprilTag from the current FTC game. @@ -125,7 +125,7 @@ physical size** (4 x 4 inches, in this example): Partial AprilTag Sheet -**Touch INIT only.** No telemetry will appear, but at this moment the DS +**Touch INIT only.** No :term:`telemetry ` will appear, but at this moment the DS **Camera Stream** preview can be accessed. See the next section re. previews. After using the preview to aim at the AprilTag, touch the DS Start arrow. The @@ -177,7 +177,7 @@ Telemetry. RC Preview ---------- -The Robot Controller (RC) device also makes a preview, called ``LiveView``. +The :term:`Robot Controller` (RC) device also makes a preview, called ``LiveView``. This is full video, and is shown automatically on the screen of an RC phone. .. figure:: images/30-LiveView.png @@ -236,7 +236,7 @@ Reference Frames ---------------- In the above example. the yaw angle is given as (approximately) -90 degrees. -But the camera is facing in the negative X direction, thus has a heading or yaw +But the camera is facing in the negative X direction, thus has a :term:`heading ` or yaw angle of -180 degrees in the official FTC :ref:`field coordinate system ` : @@ -251,7 +251,7 @@ angle of -180 degrees in the official FTC This sample OpMode uses a reference frame (coordinate system) that may be different than what you expect from other FTC navigation applications, including :ref:`IMU or robot axes ` -, odometry device axes, and the FTC field system (shown above). These +, :term:`odometry ` device axes, and the FTC field system (shown above). These differences typically result in basic and obvious changes in axis direction, axis swapping, and orthogonal angles (90-degree increments). @@ -400,7 +400,7 @@ AprilTags on the field. This is done by combining three elements: * the camera's pose on the robot. AprilTag localization uses a reference frame (coordinate system) that may -differ from others, such as IMU or robot axes, odometry device axes, and the +differ from others, such as :term:`IMU` or robot axes, odometry device axes, and the FTC field system. Adjust as needed. Evaluate this navigation tool against other choices, and plan a robot strategy diff --git a/docs/source/apriltag/vision_portal/apriltag_metadata/apriltag-metadata.rst b/docs/source/apriltag/vision_portal/apriltag_metadata/apriltag-metadata.rst index 0016f1f50..4cc162062 100644 --- a/docs/source/apriltag/vision_portal/apriltag_metadata/apriltag-metadata.rst +++ b/docs/source/apriltag/vision_portal/apriltag_metadata/apriltag-metadata.rst @@ -5,7 +5,7 @@ Introduction ------------ A Library tag stores **Metadata**, a collection of at least 4 fields (of these -Blocks/Java types): +:term:`Blocks`/Java types): - ID code (number/``int``) - tag name (text/``String``) @@ -20,7 +20,7 @@ page. For now it's enough to know the 4 basic elements of Metadata. Tag Contents ------------ -The SDK 8.2 Sample OpModes use AprilTags with these Metadata values: +The SDK 8.2 :term:`Sample OpModes ` use :term:`AprilTags ` with these Metadata values: - ``583, Nemo, 4, DistanceUnit.INCH`` - ``584, Jonah, 4, DistanceUnit.INCH`` @@ -73,7 +73,7 @@ page for sample ``for()`` loop code. Unlike tag ID code, a detected AprilTag might have **no tag name** -- if it was not placed into the Library by default or with the custom Builder pattern. -To avoid logic errors, an OpMode can check the Metadata for a **null** +To avoid logic errors, an :term:`OpMode` can check the Metadata for a **null** condition before attempting to process a tag name. This is illustrated in these Sample OpModes: diff --git a/docs/source/apriltag/vision_portal/apriltag_pose/apriltag-pose.rst b/docs/source/apriltag/vision_portal/apriltag_pose/apriltag-pose.rst index a64901302..d445e40c9 100644 --- a/docs/source/apriltag/vision_portal/apriltag_pose/apriltag-pose.rst +++ b/docs/source/apriltag/vision_portal/apriltag_pose/apriltag-pose.rst @@ -5,7 +5,7 @@ The SDK can evaluate a **flat AprilTag** (not curved) to estimate **pose**, the combination of: - relative position **from the camera lens center to the AprilTag center**, and -- orientation of the AprilTag **in the camera's reference frame** +- orientation of the :term:`AprilTag` **in the camera's reference frame** As described at the previous page **FTC Reference Frame**, position is expressed as (X, Y, Z). Orientation is expressed as rotation about (X, Y, Z), @@ -14,7 +14,7 @@ called Pitch, Roll and Yaw respectively. The tag must be in the Library, which ensures that tag size (with units) is defined. Estimating pose requires knowing the tag size. -As demonstrated in the Sample OpModes, here are ways to retrieve the estimated +As demonstrated in the :term:`Sample OpModes `, here are ways to retrieve the estimated pose values. .. tab-set:: @@ -28,7 +28,7 @@ pose values. AprilTag Pose Blocks - Use each of these green Blocks to pass a Pose value to a Telemetry Block, or to a Variable: + Use each of these green Blocks to pass a Pose value to a :term:`Telemetry` Block, or to a Variable: .. tab-item:: Java :sync: java @@ -93,11 +93,11 @@ was not placed into the Library by default or with the custom Builder pattern. Namely, the tag might lack Metadata including **tag size**, required for pose estimation. -To avoid logic errors, an OpMode can check the Metadata for a **null** +To avoid logic errors, an :term:`OpMode` can check the Metadata for a **null** condition before attempting to process pose data. This is illustrated in these Sample OpModes: -- Blocks: `ConceptAprilTag` +- :term:`Blocks`: `ConceptAprilTag` - Java: `ConceptAprilTag.java` More discussion of AprilTag pose data is available here: diff --git a/docs/source/apriltag/vision_portal/apriltag_reference_frame/apriltag-reference-frame.rst b/docs/source/apriltag/vision_portal/apriltag_reference_frame/apriltag-reference-frame.rst index 5fe5301b4..2c1f06542 100644 --- a/docs/source/apriltag/vision_portal/apriltag_reference_frame/apriltag-reference-frame.rst +++ b/docs/source/apriltag/vision_portal/apriltag_reference_frame/apriltag-reference-frame.rst @@ -4,7 +4,7 @@ AprilTag Reference Frame Introduction ------------ -Before discussing AprilTag **pose** (at the next page), the **FTC axes** or +Before discussing :term:`AprilTag` **pose** (at the next page), the **FTC axes** or reference frame must be described. Pose data is based on the **camera's point of view**, and requires a **flat AprilTag**. @@ -32,7 +32,7 @@ is described in that reference frame as (X, Y, Z) position, also called displacement or translation. This is illustrated with a camera preview image, called LiveView, from a Robot -Controller device (Control Hub or RC phone). +Controller device (:term:`Control Hub` or RC phone). .. figure:: images/200-CH-LiveView-offsets-crop.png :width: 75% diff --git a/docs/source/apriltag/vision_portal/vision_multiportal/vision-multiportal.rst b/docs/source/apriltag/vision_portal/vision_multiportal/vision-multiportal.rst index 0f915dd69..3f07a61f0 100644 --- a/docs/source/apriltag/vision_portal/vision_multiportal/vision-multiportal.rst +++ b/docs/source/apriltag/vision_portal/vision_multiportal/vision-multiportal.rst @@ -2,9 +2,9 @@ Vision MultiPortal ================== The SDK can accommodate two portals, each with full features -including AprilTag and Color processors, and even switchable cameras. USB -Bandwidth must be considered, especially for webcams sharing an external -USB hub. +including :term:`AprilTag` and Color processors, and even switchable cameras. USB +Bandwidth must be considered, especially for :term:`webcams ` sharing an external +:term:`USB hub `. Viewport ID ~~~~~~~~~~~ diff --git a/docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst b/docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst index 3e1856a61..28d024fff 100644 --- a/docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst +++ b/docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst @@ -4,10 +4,10 @@ Vision Processor Initialization Processor Initialization - Overview ----------------------------------- -Your OpMode must **first prepare** for using AprilTag and/or +Your :term:`OpMode` must **first prepare** for using :term:`AprilTag` and/or Color Processing commands, or methods. -In the INIT portion of your Java or Blocks code, before ``waitForStart()``, use +In the INIT portion of your Java or :term:`Blocks` code, before ``waitForStart()``, use these steps: - **Step 1.** *Optional:* @@ -37,7 +37,7 @@ AprilTag Initialization - Easy **Step 2** is creating the **AprilTag Processor**, software that evaluates frames streaming in from the camera. -The SDK provides an "easy" way to create the processor, using only **defaults** and not mentioning a "Builder": +The :term:`SDK` provides an "easy" way to create the processor, using only **defaults** and not mentioning a "Builder": .. tab-set:: .. tab-item:: Blocks diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/blocks/blocks.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/blocks/blocks.rst index 290a9d99d..ffd73c56e 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/blocks/blocks.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/blocks/blocks.rst @@ -1,7 +1,7 @@ Camera Controls in Blocks ------------------------- -All of the camera controls described in this tutorial are available in Blocks, +All of the camera controls described in this tutorial are available in :term:`Blocks`, under **Webcam Controls**. A few Blocks-specific details are worth knowing. Setter Blocks @@ -62,7 +62,7 @@ See this Block with the NEW operator (green oval): Examples of Pan/Tilt Blocks -It's **not needed** if the OpMode will call ``getPanTilt()`` and assign +It's **not needed** if the :term:`OpMode` will call ``getPanTilt()`` and assign it to the variable, as shown above (yellow arrow). It **is needed** if instead the OpMode will next try to get (or set) diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/eval/eval.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/eval/eval.rst index 629201a96..d36d6ca5a 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/eval/eval.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/eval/eval.rst @@ -1,7 +1,7 @@ Evaluating Your Webcam ---------------------- -The firmware of a specific webcam may or may not support certain +The :term:`firmware ` of a specific :term:`webcam ` may or may not support certain features described here. The SDK provides some methods to query the webcam and/or return values that indicate whether a valid response was available. @@ -88,7 +88,7 @@ Here are two methods to query focus and and a specific focus mode: The following methods return a **negative value** if the requested focus value is unavailable. For example, -1 is returned by the Logitech C270 -and the Microsoft LifeCam VX-5000. The Javadoc also mentions a field +and the Microsoft LifeCam VX-5000. The :term:`Javadoc` also mentions a field ``unknownFocusLength`` of type double. - getFocusLength() @@ -144,7 +144,7 @@ Some Caveats **darker** up to 30-40 - Logitech C920 **gain** value (0-255) greatly influences preview quality, comparable to **exposure** (0-204) -- restarting the RC app is sometimes needed after a webcam OpMode +- restarting the RC app is sometimes needed after a webcam :term:`OpMode` crashes - firmware versions may vary among webcams of the same model number @@ -154,4 +154,4 @@ of an external library such as `OpenCV `__ or is not covered in this basic tutorial. A separate tutorial covers the general use of `External Libraries `__ -in Blocks and OnBot Java. \ No newline at end of file +in :term:`Blocks` and :term:`OnBot Java`. \ No newline at end of file diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/auto_exposure/auto-exposure.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/auto_exposure/auto-exposure.rst index a486fe74a..04f8f30cd 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/auto_exposure/auto-exposure.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/auto_exposure/auto-exposure.rst @@ -5,7 +5,7 @@ Auto-Exposure Priority is a setting within the ExposureControl interface. It’s listed here at the end, not likely to be needed in since it it operates in very low lighting. -What does it do? Imagine that the webcam is operating at its default +What does it do? Imagine that the :term:`webcam ` is operating at its default frame rate, for example 30 frames per second (fps). *Note that frame rate is not covered in this basic tutorial.* diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/control/control.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/control/control.rst index 9d2d6fa55..313eae960 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/control/control.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/control/control.rst @@ -1,11 +1,11 @@ Exposure Control ---------------- -Exposure is the amount of light that reaches the webcam sensor. It is an +Exposure is the amount of light that reaches the :term:`webcam ` sensor. It is an important part of how bright or dark your image appears. Exposure varies directly with the amount of time that the shutter is -open, allowing light to enter and reach the sensor. So, the +open, allowing light to enter and reach the :term:`sensor `. So, the interface ExposureControl uses a single value of **duration**, in units of time that you specify, typically ``TimeUnit.MILLISECONDS``. @@ -25,7 +25,7 @@ These can be retrieved with: - getMaxExposure(TimeUnit.MILLISECONDS) There are no ``set()`` methods for min and max exposure; these are -hard-coded in the webcam’s firmware. Note that firmware settings may +hard-coded in the webcam’s :term:`firmware `. Note that firmware settings may vary among different versions of the same webcam model. These and other exposure methods are called on an ExposureControl diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/mode/mode.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/mode/mode.rst index 5eac0318a..f24040297 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/mode/mode.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/mode/mode.rst @@ -4,7 +4,7 @@ Exposure Control Mode :java:extdoc:`org.firstinspires.ftc.robotcore.external.hardware.camera.controls` -A webcam may operate in one of various exposure modes. +A :term:`webcam ` may operate in one of various exposure modes. Many common webcams offer only some of these modes. To directly control the exposure, set the webcam to Manual mode. diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/samples/samples.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/samples/samples.rst index a8b5d2cfb..67167adcc 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/samples/samples.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/exposure/samples/samples.rst @@ -1,7 +1,7 @@ Exposure Control Code Samples ----------------------------- -1. Import the interface. This line is automatically added by OnBot Java +1. Import the interface. This line is automatically added by :term:`OnBot Java` when the interface is used (coded). - ``import org.firstinspires.ftc.robotcore.external.hardware.camera.controls.ExposureControl;`` @@ -10,7 +10,7 @@ Exposure Control Code Samples - ``ExposureControl myExposureControl;`` -3. Assign the VisionPortal's camera control to your control object, in +3. Assign the :term:`VisionPortal`'s camera control to your control object, in ``runOpMode()``. Wait until the Portal reports ``STREAMING`` before doing this; the control is not available until the camera is actually open. diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/control/control.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/control/control.rst index 47d0799c8..eb921f0bd 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/control/control.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/control/control.rst @@ -4,7 +4,7 @@ Focus Control :java:extdoc:`org.firstinspires.ftc.robotcore.external.hardware.camera.controls.FocusControl` At a distance called “focus length”, a subject’s image (light rays) -converge from the lens to form a clear image on the webcam sensor. +converge from the lens to form a clear image on the :term:`webcam ` sensor. If supported by the webcam, focus can be managed with these FocusControl methods: @@ -23,7 +23,7 @@ length. These can be retrieved with: - getMaxFocusLength() There are no ``set()`` methods for min and max focus length; these are -hard-coded in the webcam’s firmware. Note that firmware settings may +hard-coded in the webcam’s :term:`firmware `. Note that firmware settings may vary among different versions of the same webcam model. These and other focus methods are called on a FocusControl object, as diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/mode/mode.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/mode/mode.rst index a32b4cf10..8b1ba396b 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/mode/mode.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/focus/mode/mode.rst @@ -3,7 +3,7 @@ Focus Control Mode :java:extdoc:`org.firstinspires.ftc.robotcore.external.hardware.camera.controls.FocusControl.Mode` -A webcam may operate in one of various focus modes. To directly control +A :term:`webcam ` may operate in one of various focus modes. To directly control the focus length, set the webcam to Fixed mode. The SDK supports these values of FocusControl.Mode: diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/control/control.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/control/control.rst index 3bd30cafb..683964284 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/control/control.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/control/control.rst @@ -4,7 +4,7 @@ Gain Control :java:extdoc:`org.firstinspires.ftc.robotcore.external.hardware.camera.controls` Gain is a digital camera setting that controls the amplification of the -signal from the webcam sensor. This amplifies the whole signal, +signal from the :term:`webcam ` sensor. This amplifies the whole signal, including any associated background noise. Gain **must** be managed together with exposure. Autoexposure mode manages @@ -31,7 +31,7 @@ values of gain. These can be retrieved with: - getMaxGain() There are no ``set()`` methods for min and max gain; these are -hard-coded in the webcam’s firmware. Note that firmware settings may +hard-coded in the webcam’s :term:`firmware `. Note that firmware settings may vary among different versions of the same webcam model. These and other gain methods are called on a GainControl object, as diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex1/ex1.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex1/ex1.rst index b8f6fed46..c6e99eea7 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex1/ex1.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex1/ex1.rst @@ -6,7 +6,7 @@ described so far: ExposureControl and GainControl. .. note:: These measurements were taken with the TensorFlow Object Detection - (TFOD) processor and the Freight Frenzy game elements. TFOD was removed + (:term:`TFOD`) processor and the Freight Frenzy game elements. TFOD was removed from the SDK in 2024, so you cannot reproduce this experiment as written. The **pattern** it shows is the point, and it applies just as well to today's VisionPortal processors: recognition quality rises with exposure diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex2/ex2.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex2/ex2.rst index 03639a646..f10975e59 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex2/ex2.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/gain/ex2/ex2.rst @@ -35,4 +35,4 @@ gain effect was similar to the exposure effect. These two charts suggest that vision processing results are affected by, and can perhaps be optimized by, setting specific values for exposure and gain. A team should compare this with the default or automatic performance of -their robot and webcam, in the full range of expected match conditions. \ No newline at end of file +their robot and :term:`webcam `, in the full range of expected match conditions. \ No newline at end of file diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/index.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/index.rst index fc1e4d4ff..0ff1f5cab 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/index.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/index.rst @@ -1,12 +1,12 @@ VisionPortal Camera Controls ============================ -Clearer camera images can improve AprilTag and Color Processing results. The +Clearer camera images can improve :term:`AprilTag` and Color Processing results. The SDK offers eight **camera controls** (Exposure, Gain, White Balance, Focus and Pan/Tilt/Zoom), available in Blocks, OnBot Java and Android Studio. These controls can be applied under various lighting conditions. -The webcam itself is opened by a :ref:`VisionPortal +The :term:`webcam ` itself is opened by a :ref:`VisionPortal `, which also provides the control objects described here. @@ -35,8 +35,8 @@ Summary Camera controls in the SDK could potentially improve AprilTag detections and Color Processor results. Exposure, gain and other values could be -pre-programmed in team autonomous OpModes. It's also possible to manually -enter such values before a match begins, based on anticipated lighting, +pre-programmed in team autonomous :term:`OpModes `. It's also possible to +manually enter such values before a :term:`match ` begins, based on anticipated lighting, starting position and other game-time factors. You are encouraged to submit other webcam reports and examples that diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/observing/observing.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/observing/observing.rst index 5e41022f1..ddff99e04 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/observing/observing.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/observing/observing.rst @@ -2,10 +2,10 @@ Observing Controls ------------------ Teams wanting to optimize their vision processing with camera controls -should watch the Robot Controller preview directly, using an HDMI monitor -plugged into the Control Hub, or `scrcpy `__. +should watch the :term:`Robot Controller` preview directly, using an HDMI monitor +plugged into the :term:`Control Hub`, or `scrcpy `__. -Optimizing via the Driver Station Camera Stream will be less effective and +Optimizing via the :term:`Driver Station` Camera Stream will be less effective and less efficient. DS Camera Stream shows the same images as ``scrcpy``, namely with Exposure and Gain affecting recognitions. But the image is a snapshot only, and adjustments cannot be made in real time, with gamepads disabled diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/overview/overview.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/overview/overview.rst index f25c07606..b46cc3173 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/overview/overview.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/overview/overview.rst @@ -1,7 +1,7 @@ Software Overview ----------------- -The SDK contains a superinterface called CameraControl, which +The :term:`SDK` contains a superinterface called CameraControl, which contains 5 interfaces: - :doc:`ExposureControl ` @@ -10,7 +10,7 @@ contains 5 interfaces: - :doc:`FocusControl ` - :doc:`PtzControl ` -Similar to Java classes, Java interfaces provide methods. A webcam can +Similar to Java classes, Java interfaces provide methods. A :term:`webcam ` can be controlled using methods of these 5 interfaces. PtzControl allows control of 3 related features: virtual pan, tilt and @@ -29,14 +29,14 @@ left column. That page provides links to the 5 interfaces listed above. -The methods described here can be used in Android Studio, OnBot Java or +The methods described here can be used in :term:`Android Studio`, :term:`OnBot Java` or :doc:`Blocks `. You will see **VisionPortal** mentioned here, and in the :doc:`sample OpModes `. **Why VisionPortal?** These controls act on a camera that is already open and streaming, and in the SDK it's the -VisionPortal that opens the camera and manages its stream. So the Portal is +:term:`VisionPortal` that opens the camera and manages its stream. So the Portal is also where you ask for a control object: .. code:: java diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/index.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/index.rst index a020d1d76..9d6400106 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/index.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/index.rst @@ -6,7 +6,7 @@ Pan-Tilt-Zoom Control The SDK provides methods for virtual pan (horizontal motion), tilt (vertical motion), and zoom (enlargement and reduction of image size). This is **virtual** PTZ since the actions are digitally simulated, -within the full original image captured by the webcam. Pan and tilt are +within the full original image captured by the :term:`webcam `. Pan and tilt are possible only to the extent that zoom has provided extra image space to move in that direction. diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/pan_tilt/pan-tilt.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/pan_tilt/pan-tilt.rst index 18643a895..c4b625c3f 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/pan_tilt/pan-tilt.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/ptz/pan_tilt/pan-tilt.rst @@ -1,7 +1,7 @@ Pan and Tilt ============= -A webcam does not typically express pan and tilt values in *pixels*, the +A :term:`webcam ` does not typically express pan and tilt values in *pixels*, the smallest unit of image capture by the webcam sensor. For example, the Logitech C920 and the Microsoft LifeCam VX-5000 have a range of +/-36,000 units, far greater than the pixel count in each axis. @@ -43,7 +43,7 @@ be retrieved as follows: - ``maxPanTiltHolder = getMaxPanTilt();`` There are no ``set()`` methods for min and max pan/tilt values; these -are hard-coded in the webcam’s firmware. Note that firmware settings may +are hard-coded in the webcam’s :term:`firmware `. Note that firmware settings may vary among different versions of the same webcam model. These pan and tilt methods are called on a PtzControl object, as diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/samples/samples.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/samples/samples.rst index 79df39b0c..a3b222f36 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/samples/samples.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/samples/samples.rst @@ -5,7 +5,7 @@ The intent of this tutorial is to describe the available camera controls, allowing programmers to **develop their own solutions** guided by the SDK API (Javadoc). -Rather than reproduce sample code here, this page points to the OpModes in +Rather than reproduce sample code here, this page points to the :term:`OpModes ` in the `FtcRobotController repository `__, which are maintained alongside the SDK and updated each season. The same diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/webcam_states/webcam-states.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/webcam_states/webcam-states.rst index 45509c589..1c4ef6b34 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/webcam_states/webcam-states.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/webcam_states/webcam-states.rst @@ -1,10 +1,10 @@ Webcam States ------------- -Camera controls cannot be used until the webcam has reached the state +Camera controls cannot be used until the :term:`webcam ` has reached the state ``CAMERA_DEVICE_READY``. -The VisionPortal reports these camera states: +The :term:`VisionPortal` reports these camera states: - OPENING_CAMERA_DEVICE - CAMERA_DEVICE_READY @@ -30,7 +30,7 @@ Notes and Guidelines for Enums - ``STARTING_STREAM`` - no processing is happening -- ``STREAMING`` - Frames are available for processing (AprilTag detections +- ``STREAMING`` - Frames are available for processing (:term:`AprilTag` detections and/or Color Processing results) and preview (RC preview and DS Camera Stream) - ``STOPPING_STREAM`` - processing may or may not be happening. This @@ -39,4 +39,4 @@ Notes and Guidelines for Enums - ``CLOSING_CAMERA_DEVICE`` - no processing is happening - ``CAMERA_DEVICE_CLOSED`` - nothing is running, USB comms are closed. - Once closed, don't open camera again during this OpMode. + Once closed, don't open camera again during this :term:`OpMode`. diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/control/control.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/control/control.rst index bfdef1ff7..b4ea6fafb 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/control/control.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/control/control.rst @@ -25,7 +25,7 @@ units of degrees Kelvin, of Java type integer. Here are the methods: - setWhiteBalanceTemperature(int temperature) - getWhiteBalanceTemperature() -As with exposure and gain, the webcam may support minimum and maximum +As with exposure and gain, the :term:`webcam ` may support minimum and maximum allowed values of white balance temperature. These can be retrieved with: @@ -33,7 +33,7 @@ with: - getMaxWhiteBalanceTemperature() There are no ``set()`` methods for min and max temperature values; these -are hard-coded in the webcam’s firmware. Note that firmware settings may +are hard-coded in the webcam’s :term:`firmware `. Note that firmware settings may vary among different versions of the same webcam model. The Logitech C920 webcam has a min value of 2000 and a max value of diff --git a/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/mode/mode.rst b/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/mode/mode.rst index 2b8012922..4f26d2905 100644 --- a/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/mode/mode.rst +++ b/docs/source/apriltag/vision_portal/visionportal_camera_controls/white_balance/mode/mode.rst @@ -5,11 +5,11 @@ White Balance Control Mode This interface supports 3 values of WhiteBalanceControl.Mode: -- AUTO +- :term:`AUTO` - MANUAL - UNKNOWN -To directly control the color balance temperature, set the webcam to +To directly control the color balance temperature, set the :term:`webcam ` to Manual mode. Mode is managed with these WhiteBalanceControl methods: - setMode(WhiteBalanceControl.Mode.MODE) diff --git a/docs/source/apriltag/vision_portal/visionportal_cpu_and_bandwidth/visionportal-cpu-and-bandwidth.rst b/docs/source/apriltag/vision_portal/visionportal_cpu_and_bandwidth/visionportal-cpu-and-bandwidth.rst index 13383645c..e6800628f 100644 --- a/docs/source/apriltag/vision_portal/visionportal_cpu_and_bandwidth/visionportal-cpu-and-bandwidth.rst +++ b/docs/source/apriltag/vision_portal/visionportal_cpu_and_bandwidth/visionportal-cpu-and-bandwidth.rst @@ -6,24 +6,24 @@ Introduction Vision processing can consume significant **CPU resources** and USB communications **bandwidth**. Reaching such limits may affect previews, and -cause an OpMode or Robot Controller to slow down, or freeze, or crash. +cause an :term:`OpMode` or :term:`Robot Controller` to slow down, or freeze, or crash. Teams can balance the benefits of higher resolution and speed (frames-per-second) against the risk of overloading CPU and bandwidth resources. -The 8.2 SDK provides numerous tools to manage this balance: +The 8.2 :term:`SDK` provides numerous tools to manage this balance: - disable and enable the RC preview (called LiveView) - "Level 1" - disable and enable a vision processor - "Level 2" - stop and resume the camera stream - "Level 3" -- close VisionPortal - "Level 4" +- close :term:`VisionPortal` - "Level 4" - monitor frames-per-second (FPS) - select a compressed video streaming format - select the camera resolution - set decimation (down-sampling) - select a pose solver algorithm -- get all or only fresh detections from the AprilTag Processor +- get all or only fresh detections from the :term:`AprilTag` Processor The first four actions are informally rated for benefit and response: @@ -67,7 +67,7 @@ About Previews -------------- As noted at the **Previews** page, LiveView refers only to the **Robot -Controller** preview. It's completely separate from the Driver Station (DS) +Controller** preview. It's completely separate from the :term:`Driver Station` (DS) **Camera Stream**, which still operates normally even if LiveView is stopped (manually or automatically). @@ -129,7 +129,7 @@ refresh) remains available. Pause LiveView - Indirect ------------------------- -The SDK also offers an **indirect** control of LiveView, available in Blocks +The SDK also offers an **indirect** control of LiveView, available in :term:`Blocks` and Java: .. code-block:: java @@ -366,7 +366,7 @@ can be a concern for **dual webcams**. .. note:: Internal phone cameras have an independent high-speed interconnect (not - USB), unaffected by an added USB webcam. + USB), unaffected by an added USB :term:`webcam `. The two webcams do *not* need to use the same format or resolution. @@ -375,7 +375,7 @@ For dual webcams **plugged directly into the Control Hub**, the USB 2.0 and USB capacity, although higher resolution can cause the auto-optimized frame rate to reduce. -Using the Control Hub's two USB ports, the choice of stream format has little +Using the :term:`Control Hub`'s two USB ports, the choice of stream format has little impact. But the USB 2.0 bus also carries the Control Hub's **WiFi radio**; adding a webcam may affect its reliability. diff --git a/docs/source/apriltag/vision_portal/visionportal_init/visionportal-init.rst b/docs/source/apriltag/vision_portal/visionportal_init/visionportal-init.rst index d922586cc..3bb949d70 100644 --- a/docs/source/apriltag/vision_portal/visionportal_init/visionportal-init.rst +++ b/docs/source/apriltag/vision_portal/visionportal_init/visionportal-init.rst @@ -4,8 +4,8 @@ VisionPortal Initialization Overview -------- -Here we describe Step 3, **creating a VisionPortal**, to allow an OpMode to use -AprilTag and/or Color Processing. This continues from the +Here we describe Step 3, **creating a VisionPortal**, to allow an :term:`OpMode` to use +:term:`AprilTag` and/or Color Processing. This continues from the previous page :doc:`Vision Processor Initialization <../vision_processor_init/vision-processor-init>`, which described Step 2: creating an AprilTag Processor and/or a Color Locator or Color Sensor @@ -32,11 +32,11 @@ and not mentioning a "Builder": :align: center :alt: Easy VisionPortal Initialization - The FTC Blocks VisionPortal toolbox, or palette, offers "Easy Create" Blocks + The FTC :term:`Blocks` VisionPortal toolbox, or palette, offers "Easy Create" Blocks combining: - the available Processors, singly or together - - webcam, built-in RC phone camera, or "Switchable Camera Name" + - :term:`webcam `, built-in RC phone camera, or "Switchable Camera Name" .. tab-item:: Java :sync: java diff --git a/docs/source/apriltag/vision_portal/visionportal_overview/visionportal-overview.rst b/docs/source/apriltag/vision_portal/visionportal_overview/visionportal-overview.rst index 939c7048c..d200a95e5 100644 --- a/docs/source/apriltag/vision_portal/visionportal_overview/visionportal-overview.rst +++ b/docs/source/apriltag/vision_portal/visionportal_overview/visionportal-overview.rst @@ -4,7 +4,7 @@ VisionPortal Overview **FIRST Tech Challenge** introduces **VisionPortal**, a comprehensive new interface for vision processing. -- For **FTC Blocks and Java** teams, VisionPortal offers key capabilities of +- For **FTC Blocks and Java** teams, :term:`VisionPortal` offers key capabilities of **AprilTag**, **EasyOpenCV** and the **Color Processors** – at the same time! @@ -21,7 +21,7 @@ interface for vision processing. orientation, relative to the camera. - **Camera Controls**, which can improve vision processing performance for - webcam, are now fully available to **FTC Blocks** users. + :term:`webcam `, are now fully available to **FTC Blocks** users. - **Multiple cameras** can operate at the same time – phone camera and/or webcam. diff --git a/docs/source/apriltag/vision_portal/visionportal_previews/visionportal-previews.rst b/docs/source/apriltag/vision_portal/visionportal_previews/visionportal-previews.rst index 4e575d8cf..d1b0a9943 100644 --- a/docs/source/apriltag/vision_portal/visionportal_previews/visionportal-previews.rst +++ b/docs/source/apriltag/vision_portal/visionportal_previews/visionportal-previews.rst @@ -4,7 +4,7 @@ VisionPortal Previews Introduction ------------ -Managing AprilTag and Color Processing performance is greatly enhanced with visual +Managing :term:`AprilTag` and Color Processing performance is greatly enhanced with visual feedback of the camera’s view. .. figure:: images/040-RC-preview-2-webcams-Moto-e4.png @@ -14,7 +14,7 @@ feedback of the camera’s view. LiveView demonstrating multiple camera support -The Driver Station and Robot Controller apps offer a camera preview on both devices: +The :term:`Driver Station` and :term:`Robot Controller` apps offer a camera preview on both devices: - **LiveView** on Robot Controller (RC) device – RC phone or Control Hub (see below) @@ -43,7 +43,7 @@ RC preview. There remain two instances of old names: LiveView on Control Hub ----------------------- -The Control Hub does generate an RC preview, despite not having a +The :term:`Control Hub` does generate an RC preview, despite not having a built-in screen. LiveView can be seen in two ways: - Plug an HDMI monitor into the Control Hub’s (full-size) HDMI port @@ -56,11 +56,11 @@ Camera Controls --------------- Images in LiveView and Camera Stream are both affected by Camera -Controls, for webcam. Changing values of Exposure and Gain, for example, +Controls, for :term:`webcam `. Changing values of Exposure and Gain, for example, do affect the displayed image and the actual recognitions. During Camera Stream, manual adjustments to Camera Controls cannot be -made in real time (with visible feedback) since gamepads are disabled. +made in real time (with visible feedback) since :term:`gamepads ` are disabled. Thus teams wanting to optimize AprilTag or Color Processing recognitions with Camera Controls should use ``scrcpy`` or an HDMI monitor. Doing this via Camera 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 880022018..aa7982b0e 100644 --- a/docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst +++ b/docs/source/apriltag/vision_portal/visionportal_webcams/visionportal-webcams.rst @@ -1,17 +1,17 @@ Webcams for Vision Portal ========================= -This is a short list of common webcams that are known to work with the +This is a short list of common :term:`webcams ` that are known to work with the :ref:`FTC VisionPortal ` and the :ref:`FTC Camera Controls `. -VisionPortal is a comprehensive interface for FTC vision processing. +:term:`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, +- :doc:`detecting <../../../apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values>` an :term:`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. +- using :term:`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 @@ -217,7 +217,7 @@ is available at some online retailers, including needing color should look elsewhere. * The Arducam OV9281 is fantastic in low-light scenarios, and has a very low-distortion lens making it perfect for object tracking and motion detection. -* The Arducam required a patch to the SDK and EasyOpenCV to work properly at high +* The Arducam required a patch to the SDK and :term:`EasyOpenCV` to work properly at high speeds, so it is not guaranteed to work properly with the FTC SDK prior to SDK 9.0. * The FTC software have been observed to not function properly with more than one Arducam OV9281 at a time. If you encounter this issue please refer to the `Serial Number Tool ` diff --git a/docs/source/booklets/index.rst b/docs/source/booklets/index.rst index 5eeac7843..ffbde8754 100644 --- a/docs/source/booklets/index.rst +++ b/docs/source/booklets/index.rst @@ -1,7 +1,7 @@ Booklets ======== -More 'bite-sized' versions of the FTC Docs. These are meant to be printed out and used as a reference for teams. +More 'bite-sized' versions of the :term:`FTC Docs`. These are meant to be printed out and used as a reference for teams. .. In order to add a booklet, add a link to the booklet in the list below. The link should be in the format of: diff --git a/docs/source/cad_resources/autodesk/autodesk.rst b/docs/source/cad_resources/autodesk/autodesk.rst index bd8191949..c8517e078 100644 --- a/docs/source/cad_resources/autodesk/autodesk.rst +++ b/docs/source/cad_resources/autodesk/autodesk.rst @@ -6,7 +6,7 @@ designers, engineers, and revolutionizers to lead in the Future of Work. With advanced technologies and workflows accelerating change in industries and careers, we at Autodesk are excited to partner with you on your professional journey. We invest in students by offering our broad portfolio of cloud-based -integrated CAD/CAM platform technologies because we believe your ideas and +integrated :term:`CAD`/CAM platform technologies because we believe your ideas and innovation have the power to make this world a better place for everyone. Lead the change and change the world. diff --git a/docs/source/cad_resources/index.rst b/docs/source/cad_resources/index.rst index 8dab166b4..3e8b167a8 100644 --- a/docs/source/cad_resources/index.rst +++ b/docs/source/cad_resources/index.rst @@ -9,7 +9,7 @@ CAD Resources `Computer Aided Design (CAD) `__ and 3D animation software is used in *FIRST* Tech Challenge by teams to design and visualize -complex systems prior to manufacturing. There are many software options for CAD +complex systems prior to manufacturing. There are many software options for :term:`CAD` and there's no way to list them all. Some software is provided free of charge, some software is provided for a fee, and some require subscriptions. However, many organizations provide free access to "premium" CAD software to *FIRST* teams. diff --git a/docs/source/cad_resources/ptc/ptc.rst b/docs/source/cad_resources/ptc/ptc.rst index d5662017a..668496a6c 100644 --- a/docs/source/cad_resources/ptc/ptc.rst +++ b/docs/source/cad_resources/ptc/ptc.rst @@ -3,7 +3,7 @@ PTC CAD Resources PTC is proud to join forces with *FIRST* to empower the engineers and innovators of tomorrow! Through PTC Education, teams can gain free software and services, -including Onshape, Creo, Mathcad, Windchill, and Vuforia, easy-to-use training +including Onshape, Creo, Mathcad, Windchill, and :term:`Vuforia`, easy-to-use training curriculum, and financial grants to select teams. PTC’s product development software will enable collaboration, increase efficiency, and enhance accuracy during the robot design process. @@ -14,7 +14,7 @@ Obtaining PTC Software PTC makes software available to all *FIRST* teams via their *FIRST* `PTC Student Download Page `__. -PTC's cloud-based CAD tool, `OnShape `__, merely +PTC's cloud-based :term:`CAD` tool, `OnShape `__, merely requires a `FREE Education account `__ available to all *FIRST* teams (each student/mentor on the team needs their own account, mentors/coaches should sign up as an "Educator"). Once you're signed diff --git a/docs/source/cad_resources/solidworks/solidworks.rst b/docs/source/cad_resources/solidworks/solidworks.rst index 037cb4094..dee830b76 100644 --- a/docs/source/cad_resources/solidworks/solidworks.rst +++ b/docs/source/cad_resources/solidworks/solidworks.rst @@ -4,7 +4,7 @@ SOLIDWORKS® CAD Resources For over 15 years, Dassault Systèmes has been a software supplier to *FIRST®* teams with SOLIDWORKS®. We are also introducing the 3DEXPERIENCE® platform, a technology platform that provides Product Lifecycle Management -(PLM), collaboration, community, and Cloud CAD Apps to all *FIRST* teams. Enhance +(PLM), collaboration, community, and Cloud :term:`CAD` Apps to all *FIRST* teams. Enhance collaborative robot design with your team. Obtaining SOLIDWORKS® Software diff --git a/docs/source/color_processing/color-blob-concepts/color-blob-concepts.rst b/docs/source/color_processing/color-blob-concepts/color-blob-concepts.rst index 1abad05f5..6058b878a 100644 --- a/docs/source/color_processing/color-blob-concepts/color-blob-concepts.rst +++ b/docs/source/color_processing/color-blob-concepts/color-blob-concepts.rst @@ -76,12 +76,12 @@ color), very hard to see. Let's try another image: Teal Outline of Blue Blob Now the teal outline of the blue Blob can be seen. Its shape is irregular, -which can be difficult for your OpMode to evaluate. +which can be difficult for your :term:`OpMode` to evaluate. boxFit Rectangles ----------------- -The orange rectangle is drawn automatically by OpenCV, to give your OpMode a +The orange rectangle is drawn automatically by :term:`OpenCV`, to give your OpMode a simpler geometric shape that represents the Blob. It's not **exactly** like the actual Blob, but hopefully still useful. @@ -140,7 +140,7 @@ Your programming tasks will include: * evaluate its data, and * take robot action accordingly. -Now try the Sample OpMode for the :doc:`Color Locator <../color-locator-discover/color-locator-discover>` processor. +Now try the :term:`Sample OpMode` for the :doc:`Color Locator <../color-locator-discover/color-locator-discover>` processor. ============ diff --git a/docs/source/color_processing/color-locator-challenge/color-locator-challenge.rst b/docs/source/color_processing/color-locator-challenge/color-locator-challenge.rst index 7b76a0ab0..b7e67abb9 100644 --- a/docs/source/color_processing/color-locator-challenge/color-locator-challenge.rst +++ b/docs/source/color_processing/color-locator-challenge/color-locator-challenge.rst @@ -7,8 +7,8 @@ Overview This **Challenge** page introduces Color Locator settings that were **not mentioned in the Sample OpMode**. It assumes you have already followed this tutorial's previous pages: -* :doc:`Discover <../color-locator-discover/color-locator-discover>` page, to open and test the Sample OpMode -* :doc:`Explore <../color-locator-explore/color-locator-explore>` page, to edit settings mentioned in the Sample OpMode +* :doc:`Discover <../color-locator-discover/color-locator-discover>` page, to open and test the :term:`Sample OpMode` +* :doc:`Explore <../color-locator-explore/color-locator-explore>` page, to edit settings mentioned in the Sample :term:`OpMode` Here are the additional ColorLocator settings covered in this page: @@ -55,7 +55,7 @@ To apply a filter setting, use two steps: The "Color Blob Locator" Processor must already be created; adding a filter is **not** part of the Builder pattern here. A pre-filter can be added before or -after the VisionPortal is built. +after the :term:`VisionPortal` is built. In general, a pre-filter setting remains in place and cannot be edited. To "change" a pre-filter, it must be **removed** from the Processor, then @@ -73,7 +73,7 @@ and added again, etc. You might find it more versatile and convenient to create unique filter names, each separately managed (i.e. set criteria, add, remove, add again). -Select and read the Blocks **or** Java section below: +Select and read the :term:`Blocks` **or** Java section below: .. tab-set:: .. tab-item:: Blocks @@ -402,7 +402,7 @@ Select and read the Blocks **or** Java section below: MatOfPoint myContour = getContour() - This method returns a matrix unique to the OpenCV library. The matrix + This method returns a matrix unique to the :term:`OpenCV` library. The matrix object can convert itself to an array, as follows: .. code-block:: java @@ -449,7 +449,7 @@ Select and read the Blocks **or** Java section below: .. tab-item:: Java :sync: java - Here's a modified version of the Sample OpMode's telemetry code, to + Here's a modified version of the Sample OpMode's :term:`telemetry ` code, to display only the size and angle of the instant boxFit being processed. .. code-block:: java @@ -465,7 +465,7 @@ Select and read the Blocks **or** Java section below: } The Java class ``Size`` here is different than another class of the same - simple name. OnBot Java and Android Studio do not allow imports of + simple name. :term:`OnBot Java` and :term:`Android Studio` do not allow imports of identical simple classnames. In fact OnBot Java will not allow the import of this version, even if the diff --git a/docs/source/color_processing/color-locator-discover/color-locator-discover.rst b/docs/source/color_processing/color-locator-discover/color-locator-discover.rst index 2238bc4db..295d39c52 100644 --- a/docs/source/color_processing/color-locator-discover/color-locator-discover.rst +++ b/docs/source/color_processing/color-locator-discover/color-locator-discover.rst @@ -4,7 +4,7 @@ Color Locator (Discover) Overview -------- -Another way to use FTC's new OpenCV vision tools is to operate a "Color +Another way to use FTC's new :term:`OpenCV` vision tools is to operate a "Color Locator". Namely, it can **find a target color that you specify**. As with the Color Sensor tool, you can specify a **Region of Interest** (ROI). @@ -31,10 +31,10 @@ The target color here is BLUE. The white rectangle is the Region of Interest the purple rectangle is the boxFit. The software reports the size, position and orientation of each "boxFit". That -data can be evaluated by your OpMode for **robot navigation** and other +data can be evaluated by your :term:`OpMode` for **robot navigation** and other actions. -The following sections describe how to do this, with a Sample OpMode. +The following sections describe how to do this, with a :term:`Sample OpMode`. Configuration ------------- @@ -44,15 +44,15 @@ Configuration * *the active robot configuration already contains "Webcam 1",* or * *using the built-in camera of an Android phone as Robot Controller.* -Before starting the programming, REV Control Hub users should make a robot -configuration that includes the USB webcam to be used as a color locator. +Before starting the programming, REV :term:`Control Hub` users should make a robot +configuration that includes the USB :term:`webcam ` to be used as a color locator. For now, use the default webcam name, "Webcam 1". If a different name is preferred, edit the Sample OpMode to agree with the exact webcam name in the robot configuration. **Save and activate** that configuration; its name should appear on the paired -Driver Station screen. +:term:`Driver Station` screen. Sample OpMode ------------- @@ -60,7 +60,7 @@ Sample OpMode Opening the Sample OpMode +++++++++++++++++++++++++ -To learn about opening the Sample OpMode, select and read the Blocks **or** +To learn about opening the Sample OpMode, select and read the :term:`Blocks` **or** Java section below: .. tab-set:: @@ -80,7 +80,7 @@ Java section below: 3. Near the beginning of the OpMode code, change `ARTIFACT_PURPLE` to `BLUE`. 4. At the top of the Blocks screen, you can change the type from "TeleOp" - to "Autonomous", since this Sample OpMode does not use gamepads. + to "Autonomous", since this Sample OpMode does not use :term:`gamepads `. 5. If using the built-in camera of an RC phone, drag out the relevant Block from the left-side ``VisionPortal.Builder`` toolbox. @@ -90,7 +90,7 @@ Java section below: .. tab-item:: Java :sync: java - 1. Open your choice of OnBot Java or Android Studio. + 1. Open your choice of :term:`OnBot Java` or :term:`Android Studio`. 2. In the ``teamcode`` folder, add/create a new OpMode with a name such as "ColorLocator_Javier_v01.java", and select the Sample OpMode @@ -109,13 +109,13 @@ Java section below: Running the Sample OpMode +++++++++++++++++++++++++ -1. On the Driver Station, select the Autonomous OpMode that you just saved or +1. On the Driver Station, select the :term:`Autonomous` OpMode that you just saved or built. 2. Turn off the automatic 30-second match timer (green slider). Aim the camera at a **blue object**. -3. Touch INIT only. The OpMode should give Telemetry showing the results of +3. Touch INIT only. The OpMode should give :term:`Telemetry` showing the results of one or more Blobs: .. figure:: images/23-basic-telemetry.png @@ -168,7 +168,7 @@ Telemetry. RC Preview ---------- -The Robot Controller (RC) device also makes a preview, called ``LiveView``. +The :term:`Robot Controller` (RC) device also makes a preview, called ``LiveView``. This is full video, and is shown automatically on the screen of an RC phone. .. figure:: images/32-LiveView.png @@ -321,7 +321,7 @@ the Submersible (from INTO THE DEEP). Could the data from this boxFit (orange rectangle) help you **grab only the Blue Sample**\ ? -Could this help in Autonomous **and** TeleOp? +Could this help in Autonomous **and** :term:`TeleOp `? More Documentation ------------------ diff --git a/docs/source/color_processing/color-locator-explore/color-locator-explore.rst b/docs/source/color_processing/color-locator-explore/color-locator-explore.rst index 8576a27fa..3de1245a4 100644 --- a/docs/source/color_processing/color-locator-explore/color-locator-explore.rst +++ b/docs/source/color_processing/color-locator-explore/color-locator-explore.rst @@ -31,7 +31,7 @@ Building the VisionPortal The Sample OpMode first creates a "Color Blob Locator" **Processor** using the Java **Builder** pattern. This is the same Builder pattern used to create an -AprilTag Processor. +:term:`AprilTag` Processor. The Sample OpMode then creates a **VisionPortal**, again using a Builder pattern. This includes adding the "Color Blob Locator" Processor to the diff --git a/docs/source/color_processing/color-locator-round-blobs/color-locator-round-blobs.rst b/docs/source/color_processing/color-locator-round-blobs/color-locator-round-blobs.rst index 2cd0f75c9..d773a1ae3 100644 --- a/docs/source/color_processing/color-locator-round-blobs/color-locator-round-blobs.rst +++ b/docs/source/color_processing/color-locator-round-blobs/color-locator-round-blobs.rst @@ -13,14 +13,14 @@ FTC's "Color Locator" now offers a best-fit circle called ``circleFit``, an alte circleFit versus boxFit detection -This page describes the new Sample OpMode called ``ConceptVisionColorLocator_Circle``, in FTC Blocks and Java. These notes assume familiarity with the original Sample OpMode, now called ``ConceptVisionColorLocator_Rectangle``. +This page describes the new :term:`Sample OpMode` called ``ConceptVisionColorLocator_Circle``, in FTC :term:`Blocks` and Java. These notes assume familiarity with the original Sample OpMode, now called ``ConceptVisionColorLocator_Rectangle``. The new ``_Circle`` Sample uses these settings for convenient processing of DECODE Artifacts: * increase Erode and Dilate areas from 5 to 15 pixels * change order of Erode and Dilate * draw ``circleFit`` preview -* Telemetry shows only Circularity, Radius and Center +* :term:`Telemetry` shows only Circularity, Radius and Center As an alternate, the ``_Rectangle`` Sample OpMode can still be used and modified to process objects of any shape, including round balls, with access to the same attributes. @@ -30,8 +30,8 @@ Quick Start .. note:: This and other steps here were previously described in detail, starting with the page called :doc:`Color Locator - Discover <../color-locator-discover/color-locator-discover>`. -#. In FTC Blocks or Java, create a new Autonomous OpMode from the Sample ``ConceptVisionColorLocator_Circle``. -#. On the Driver Station, select the OpMode that you just saved or built. +#. In FTC Blocks or Java, create a new :term:`Autonomous` OpMode from the Sample ``ConceptVisionColorLocator_Circle``. +#. On the :term:`Driver Station`, select the OpMode that you just saved or built. #. Turn off the automatic 30-second match timer (green slider). Aim the camera at a DECODE **Purple Artifact**\ , or a picture of one. #. Touch INIT only. The OpMode should give Telemetry showing the results of one or more Blobs: @@ -54,7 +54,7 @@ It's working! Your camera is working as a **color locator**. Think about how t DS and RC Previews ------------------ -Before studying the telemetry data more closely (below), make sure you can see the **previews** of the OpenCV results. Previewing is essential for working with vision code. +Before studying the telemetry data more closely (below), make sure you can see the **previews** of the :term:`OpenCV` results. Previewing is essential for working with vision code. The Driver Station (DS) "snapshot" preview is available at the ``Camera Stream`` menu choice, with the OpMode in INIT. @@ -65,7 +65,7 @@ The Driver Station (DS) "snapshot" preview is available at the ``Camera Stream`` Driver Station Camera Stream Image showing a successful Circle Fit -The Robot Controller (RC) device makes a video preview called ``LiveView``. For a REV Control Hub, this video can be seen on an HDMI monitor **or** with open-source `scrcpy `_ (called "screen copy"): +The :term:`Robot Controller` (RC) device makes a video preview called ``LiveView``. For a REV :term:`Control Hub`, this video can be seen on an HDMI monitor **or** with open-source `scrcpy `_ (called "screen copy"): .. figure:: images/33-circleFit-LiveView.png :width: 75% @@ -124,7 +124,7 @@ With these estimates of distance and position, the robot can be programmed to ap Manage the Previews ------------------- -The FTC SDK handles the two preview shapes differently: +The FTC :term:`SDK` handles the two preview shapes differently: * ``boxFit`` is enabled by default * ``circleFit`` is disabled by default @@ -224,13 +224,13 @@ Telemetry Results can be **sorted** by any of the above attributes. See the Sam Lighting Challenges ------------------- -Robotics vision is highly sensitive to field lighting. The FTC VisionPortal offers software tools called Camera Controls to help address varying or "difficult" lighting conditions. +Robotics vision is highly sensitive to field lighting. The FTC :term:`VisionPortal` offers software tools called Camera Controls to help address varying or "difficult" lighting conditions. If needed, see the separate tutorial called :ref:`FTC VisionPortal Camera Controls `. More detail on these controls is provided in the :ref:`ftc-docs Webcam Controls tutorial `. -These tools can help with Color Processing **and** AprilTag Detection. +These tools can help with Color Processing **and** :term:`AprilTag` Detection. Lastly, some webcams perform **automatic color correction**, under changing lighting conditions. If you observe this in Previews, make adjustments as needed. diff --git a/docs/source/color_processing/color-sensor/color-sensor.rst b/docs/source/color_processing/color-sensor/color-sensor.rst index fb16741fa..ac6842896 100644 --- a/docs/source/color_processing/color-sensor/color-sensor.rst +++ b/docs/source/color_processing/color-sensor/color-sensor.rst @@ -210,7 +210,7 @@ Building the VisionPortal The Sample OpMode first creates a "Predominant Color" **Processor** using the **Builder** pattern. This is the same Builder pattern used to create an -AprilTag Processor. +:term:`AprilTag` Processor. The Sample OpMode then creates a **VisionPortal**, again using a Builder pattern. This includes adding the "Predominant Color" Processor to the diff --git a/docs/source/color_processing/color-spaces/color-spaces.rst b/docs/source/color_processing/color-spaces/color-spaces.rst index 81eb07f5c..3258b4752 100644 --- a/docs/source/color_processing/color-spaces/color-spaces.rst +++ b/docs/source/color_processing/color-spaces/color-spaces.rst @@ -6,7 +6,7 @@ Overview This page of the FTC Color Processing tutorial introduces **Color Spaces**. -OpenCV can process color information using any one of several Color Spaces, +:term:`OpenCV` can process color information using any one of several Color Spaces, which are methods to describe an exact shade and brightness. This page describes 3 choices available in the FTC SDK: diff --git a/docs/source/color_processing/index.rst b/docs/source/color_processing/index.rst index 07e4b24ab..aeab6dd21 100644 --- a/docs/source/color_processing/index.rst +++ b/docs/source/color_processing/index.rst @@ -26,21 +26,21 @@ Here's the outline of this tutorial's main pages: color-locator-round-blobs/color-locator-round-blobs color-spaces/color-spaces -Much credit to developer and Sample OpMode author `@gearsincorg `_, EasyOpenCV developer `@Windwoes `_, FTC Blocks developer `@lizlooney `_, and the open-source team at `OpenCV `_. +Much credit to developer and :term:`Sample OpMode` author `@gearsincorg `_, :term:`EasyOpenCV` developer `@Windwoes `_, FTC :term:`Blocks` developer `@lizlooney `_, and the open-source team at `OpenCV `_. Compatibility ------------- This new software includes two Color Processors, each compatible with the FTC -VisionPortal introduced in 2023. These processors can run alongside an -AprilTag processor, and replace the TensorFlow processor (removed in 2024). +:term:`VisionPortal` introduced in 2023. These processors can run alongside an +:term:`AprilTag` processor, and replace the :term:`TensorFlow` processor (removed in 2024). These new processors can be used on the usual FTC cameras: -* any UVC-compatible webcam -* the built-in camera of an FTC-supported Android phone (as Robot Controller) +* any UVC-compatible :term:`webcam ` +* the built-in camera of an FTC-supported Android phone (as :term:`Robot Controller`) -This does **not** include vision sensors such as HuskyLens and LimeLight 3A, +This does **not** include vision :term:`sensors ` such as HuskyLens and LimeLight 3A, which do not use the FTC VisionPortal. Two Processors @@ -54,7 +54,7 @@ The new software includes these processors: in a specified zone This tutorial has a :doc:`Color Sensor ` page, showing how -to use the Sample OpMode called ``ConceptVisionColorSensor``. +to use the Sample :term:`OpMode` called ``ConceptVisionColorSensor``. For the **Color Locator** processor, the color "clusters" are called **Blobs**. As listed above, this tutorial offers one page on Color Blob Concepts, and @@ -62,7 +62,7 @@ four pages covering the Sample OpModes called ``ConceptVisionColorLocator_Rectan and ``ConceptVisionColorLocator_Circle``. The Sample OpModes are available in **FTC Blocks**\ , and in **Java** for use -in OnBot Java or Android Studio. Each programming section of this tutorial has +in :term:`OnBot Java` or :term:`Android Studio`. Each programming section of this tutorial has a Blocks tab and a Java tab. Next Steps @@ -76,8 +76,8 @@ Sensor `. Then read about **Color Blob Concepts**\ , and try the **Color Locator** Sample OpModes. -Soon you'll be ready to add one or both features to your Autonomous OpModes -- -perhaps even to help automate your TeleOp! +Soon you'll be ready to add one or both features to your :term:`Autonomous` OpModes -- +perhaps even to help automate your :term:`TeleOp `! ============ diff --git a/docs/source/common/mission.rst b/docs/source/common/mission.rst index c4a8b66ff..881d93e72 100644 --- a/docs/source/common/mission.rst +++ b/docs/source/common/mission.rst @@ -1,4 +1,4 @@ -FTC Docs aims to provide a comprehensive documentation base for *FIRST* Tech Challenge teams and mentors. +:term:`FTC Docs` aims to provide a comprehensive documentation base for *FIRST* Tech Challenge teams and mentors. It is a community-driven project, hosted and moderated by FIRST Tech Challenge staff, and we welcome contributions from all teams and mentors. It is our hope that this project will help to make the community more connected and informed while reducing the fragmentation of documentation present diff --git a/docs/source/contrib/guidelines/guidelines.rst b/docs/source/contrib/guidelines/guidelines.rst index 57055dcec..d9e394bc1 100644 --- a/docs/source/contrib/guidelines/guidelines.rst +++ b/docs/source/contrib/guidelines/guidelines.rst @@ -48,7 +48,7 @@ We have specific guidance for making changes, start with the :doc:`Change Overvi Colophon -------- -FTC Docs is built with `Sphinx `__ using a `theme `__ provided by `Read the Docs `__. +:term:`FTC Docs` is built with `Sphinx `__ using a `theme `__ provided by `Read the Docs `__. Sphinx is a documentation generator. Sphinx converts reStructuredText files into HTML web pages. diff --git a/docs/source/contrib/index.rst b/docs/source/contrib/index.rst index f4b753ffb..ba1e16b75 100644 --- a/docs/source/contrib/index.rst +++ b/docs/source/contrib/index.rst @@ -23,7 +23,7 @@ Mission Statement ==== -FTC Docs is brought to you by: +:term:`FTC Docs` is brought to you by: - Daniel Alfredo Diaz, Jr — Maintainer. - Elizabeth Gilibert — Project Manager diff --git a/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst b/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst index 4d288e194..2f8d83ed1 100644 --- a/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst +++ b/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst @@ -10,7 +10,7 @@ Then move to meet the level AA criteria to improve that accessibility. See the `How to Meet WCAG Quick Reference `_ for more information. .. Note:: - This page attempts to document from the WCAG perspective what is important and relate that to FTC Docs. + This page attempts to document from the WCAG perspective what is important and relate that to :term:`FTC Docs`. This page is primarily for content authors. Accessibility issues due to Sphinx or Read the Docs will be dealt with in GitHub issues. .. contents:: Contents diff --git a/docs/source/contrib/style_guide/image-and-figure-details.rst b/docs/source/contrib/style_guide/image-and-figure-details.rst index 7dc3af7b3..212b6124f 100644 --- a/docs/source/contrib/style_guide/image-and-figure-details.rst +++ b/docs/source/contrib/style_guide/image-and-figure-details.rst @@ -1,7 +1,7 @@ Image and Figure Details ======================== -This section has detailed information about images and figures and more advice about how to handle them in FTC Docs. +This section has detailed information about images and figures and more advice about how to handle them in :term:`FTC Docs`. .. contents:: Contents :local: @@ -124,7 +124,7 @@ width, height, scale Sighted persons who want to see the full size image have the option to right click the image and open it in a new tab or window. - The AprilTag test images have both height and width specified as 5 inches which looks OK on the desktop or in a PDF, + The :term:`AprilTag` test images have both height and width specified as 5 inches which looks OK on the desktop or in a PDF, but ends up with a squished aspect ratio if viewed in a mobile browser. We'd be better off not specifying set sizes for the HTML and the PDF version of FTC docs. Then provide a separate PDF download that they can print to get accurately sized AprilTags. @@ -332,7 +332,7 @@ Instead of a paragraph, you can include a table or list if that would better des The following example is how we might describe a complex diagram. We use a ``.. figure`` directive with alt text, caption and long description. -This diagram is located on the Control System Introduction page. +This diagram is located on the :term:`Control System` Introduction page. .. code:: ReST @@ -351,7 +351,7 @@ This diagram is located on the Control System Introduction page. - Two motors are connected to the Expansion hub. Each motor has a power connection and an encoder connection. There are four motor ports on the Expansion Hub. The alt text is a summary of the functional description of the image (which follows the caption). -The caption indicates that this is an example of an Expansion Hub and phone and relates to the prior paragraphs +The caption indicates that this is an example of an :term:`Expansion Hub` and phone and relates to the prior paragraphs on the Control System Introduction page which talk about possible configurations of the Expansion Hub. In this case the long description is basically a listing of the devices connected to the Expansion Hub. @@ -366,17 +366,17 @@ In this case the long description is basically a listing of the devices connecte The Expansion Hub has the following devices connected. - - a Robot Controller phone via a USB connection; - - A 12 volt battery with on/off switch; - - A three wire servo connects to one of six servo ports; - - An analog sensor connects to one of two analog sensor ports; - - An I2C sensor connects to one of four I2C ports; - - Two motors are connected to the Expansion hub. Each motor has a power connection and an encoder connection. There are four motor ports on the Expansion Hub. + - a :term:`Robot Controller` phone via a USB connection; + - A 12 volt :term:`battery ` with on/off switch; + - A three wire :term:`servo ` connects to one of six servo ports; + - An analog :term:`sensor ` connects to one of two analog sensor ports; + - An :term:`I2C` sensor connects to one of four I2C ports; + - Two motors are connected to the Expansion hub. Each motor has a power connection and an :term:`encoder ` connection. There are four motor ports on the Expansion Hub. Using a Figure with Caption and Legend is good for accessibility because Sphinx will generate a HTML Figure tag and Figcaption tag. This clearly associates the text with the image for screen readers. -This HTML is from the square field image of the Field Coordinate System page. +This HTML is from the square field image of the :term:`Field Coordinate System` page. .. code:: HTML diff --git a/docs/source/contrib/style_guide/style-guide.rst b/docs/source/contrib/style_guide/style-guide.rst index 3d0127f07..56eb843fe 100644 --- a/docs/source/contrib/style_guide/style-guide.rst +++ b/docs/source/contrib/style_guide/style-guide.rst @@ -1,7 +1,7 @@ FTC Docs Style Guide ==================== -This guide contains the various reStructuredText (RST) and Sphinx specific guidelines for the FTC Docs project. +This guide contains the various reStructuredText (RST) and Sphinx specific guidelines for the :term:`FTC Docs` project. reStructuredText is the default plain text markup language used by Sphinx. .. contents:: Contents @@ -342,9 +342,61 @@ Which looks like: `Game and Season Materials ` defines the hardware, software, programming and +competition terms used across the site. +Link to it with the ``:term:`` role so a reader who does not recognize a term can check it +without leaving the page — FTC Docs shows glossary definitions as a hover tooltip. + +.. code:: rest + + An :term:`OpMode` runs on the :term:`Robot Controller`. + +When the word in your sentence does not match the glossary entry exactly — a plural, or a +lowercase spelling — give the display text first and the entry in angle brackets: + +.. code:: rest + + Plug both :term:`encoders ` into the :term:`Control Hub`. + +**Link the first mention of every glossary term on the page.** This is a requirement, not a +suggestion: a reader arriving on any page from a search engine should be able to look up any +term it uses. Every page on the site currently satisfies this, so please keep it that way +when you add or edit content. + +Link the *first* mention only — not every mention. A page where all eleven instances of +"Control Hub" are links is harder to read, not easier. + +Some words are glossary terms in one sentence and ordinary English in the next. Link only the +sense the glossary defines: + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Link it + - Leave it alone + * - a wireless problem during a :term:`Match` + - "check for a match with the DS app version" + * - the robot's :term:`Heading` from the :term:`IMU` + - "the items appear under the heading Downloaded" + * - the robot's 12V :term:`Battery` + - "a USB battery pack", "the phone has a low battery" + +A few places cannot take a role at all — code blocks and inline literals, text that is already +a link, image ``:alt:`` text, section titles, and the label of a ``button-ref`` or the header of +a ``grid-item-card`` (a link nested inside a button does not render). Where a term's only +mention on a page falls in one of those, leave it unlinked. + +If a term is missing from the glossary, add it there rather than defining it inline in your +page. Definitions that live in one place stay consistent. When you add an entry, also link its +first mention on the pages that already use the word. + Links to Files ^^^^^^^^^^^^^^ - + You can directly link to files such as a PDF, but that is an accessibility problem. The issue is the context switch from web browsing to suddenly having to deal with a PDF that has probably opened in a new tab/window without any warning. FTC Docs contains quite a few links to PDFs that should be make more accessible. @@ -416,8 +468,8 @@ Here's a gateway page example for the Field Setup Guide PDF. - A list all the game elements and scoring elements with the quantity of each. - Instructions for setup of the field perimeter and field tiles. - Step by step instructions for assembling parts and setting them on the field. - - Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the Alliances, and sometimes for game areas. - - Most games have AprilTags placed around the field that can be used for robot navigation. + - Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the :term:`Alliances `, and sometimes for game areas. + - Most games have :term:`AprilTags ` placed around the field that can be used for robot navigation. - Finally, there are tear down instructions that indicate how to take the field down for storage or transport. Use the following button link to download a PDF of the Field Setup Guide from the *FIRST* Website: @@ -457,7 +509,7 @@ The ``:alt:`` line is indented three spaces. The description should be functional. Describe the image for someone who cannot see it. Here's what the web page for an image looks like (but reduced in size for this example). -The image is a screen shot of the Blocks programming tool on a page that talks about the various programming tools available. +The image is a screen shot of the :term:`Blocks` programming tool on a page that talks about the various programming tools available. .. list-table:: diff --git a/docs/source/contrib/tutorials/index.rst b/docs/source/contrib/tutorials/index.rst index 0b17cb34a..ed0ec9621 100644 --- a/docs/source/contrib/tutorials/index.rst +++ b/docs/source/contrib/tutorials/index.rst @@ -2,7 +2,7 @@ Tutorials ============ These are a couple tutorials that will walk you through the process of creating and editing -in FTC Docs. +in :term:`FTC Docs`. .. toctree:: :maxdepth: 2 diff --git a/docs/source/contrib/tutorials/make_branch/make-branch.rst b/docs/source/contrib/tutorials/make_branch/make-branch.rst index 18aeec875..90b4ce1ca 100644 --- a/docs/source/contrib/tutorials/make_branch/make-branch.rst +++ b/docs/source/contrib/tutorials/make_branch/make-branch.rst @@ -10,7 +10,7 @@ development because it allows you to work on a feature or bug fix in an isolated environment without affecting the main project. Once you've made the changes you want to make, you can merge your branch back into the main branch to publish your changes. -In the case of the FTC Docs, the main branch of your fork should always be a copy +In the case of the :term:`FTC Docs`, the main branch of your fork should always be a copy of the main branch of the main repository which serves as a reference point to create new branches from. After we are satisfied with the changes we've made in our branch, we will create a Pull Request to merge our changes back into the main branch of the diff --git a/docs/source/contrib/tutorials/make_fork/make-fork.rst b/docs/source/contrib/tutorials/make_fork/make-fork.rst index 7a6b086a5..a2a2f89f0 100644 --- a/docs/source/contrib/tutorials/make_fork/make-fork.rst +++ b/docs/source/contrib/tutorials/make_fork/make-fork.rst @@ -11,7 +11,7 @@ You can also submit a pull request to the original repository to propose changes Steps ----- -1. Go to the repository you want to fork. In this case, it is the FTC Docs `repository `_. +1. Go to the repository you want to fork. In this case, it is the :term:`FTC Docs` `repository `_. .. figure:: images/ftcdocs-gh.png :alt: FTC Docs Repository diff --git a/docs/source/contrib/tutorials/make_pr/make-pr.rst b/docs/source/contrib/tutorials/make_pr/make-pr.rst index db0602cf9..0dcd4b5a6 100644 --- a/docs/source/contrib/tutorials/make_pr/make-pr.rst +++ b/docs/source/contrib/tutorials/make_pr/make-pr.rst @@ -5,7 +5,7 @@ Submitting Your Changes for Review Workflows --------- -The following diagram shows the workflow for submitting changes to the FTC Docs repository. +The following diagram shows the workflow for submitting changes to the :term:`FTC Docs` repository. For first time users of Git/GitHub, do not worry if this seems confusing. First focus on understanding the steps and then the workflow will make more sense. diff --git a/docs/source/contrib/tutorials/overview/overview.rst b/docs/source/contrib/tutorials/overview/overview.rst index 243e4cd9d..01a110b2d 100644 --- a/docs/source/contrib/tutorials/overview/overview.rst +++ b/docs/source/contrib/tutorials/overview/overview.rst @@ -1,7 +1,7 @@ Overview ========= -Below is an overview of the process of contributing to FTC Docs. +Below is an overview of the process of contributing to :term:`FTC Docs`. .. warning:: diff --git a/docs/source/contrib/tutorials/setup/setup.rst b/docs/source/contrib/tutorials/setup/setup.rst index 7d33bb523..11ef46c6c 100644 --- a/docs/source/contrib/tutorials/setup/setup.rst +++ b/docs/source/contrib/tutorials/setup/setup.rst @@ -7,7 +7,7 @@ Setting Up Your Development Environment Only complete these steps if you have chosen to develop the site locally. If you are using **GitHub Codespaces** you should skip this section. -FTC Docs uses a `Nix `__ flake (``flake.nix`` at the root of the repository) to provide every +:term:`FTC Docs` uses a `Nix `__ flake (``flake.nix`` at the root of the repository) to provide every dependency needed to build the site -- Python, Sphinx, and the LaTeX toolchain used for PDF booklets -- in one reproducible environment. You no longer need to install Python, Pip, or a LaTeX distribution yourself. diff --git a/docs/source/contrib/tutorials/tasks/tasks.rst b/docs/source/contrib/tutorials/tasks/tasks.rst index ff0223b33..ddc389611 100644 --- a/docs/source/contrib/tutorials/tasks/tasks.rst +++ b/docs/source/contrib/tutorials/tasks/tasks.rst @@ -2,7 +2,7 @@ Intro to VS Code Tasks ======================= :bdg-secondary:`Information` -In order to simplify the process of building and running FTC Docs we have created a set of tasks for Visual Studio Code. +In order to simplify the process of building and running :term:`FTC Docs` we have created a set of tasks for Visual Studio Code. These tasks are defined in the `.vscode/tasks.json` file and can be run via the `Terminal` -> `Run Task...` menu. Tasks diff --git a/docs/source/contrib/workflow/workflow.rst b/docs/source/contrib/workflow/workflow.rst index 304759d68..74bd5a9ad 100644 --- a/docs/source/contrib/workflow/workflow.rst +++ b/docs/source/contrib/workflow/workflow.rst @@ -2,7 +2,7 @@ FTC Docs Workflows =================== .. note:: Please note that this flowchart is meant only for reference for - *maintainers* of the FTC Docs repository. For those looking + *maintainers* of the :term:`FTC Docs` repository. For those looking only to contribute to the FTC Docs documents please refer to the :doc:`Contributing to FTC Docs ` document. diff --git a/docs/source/control_hard_compon/ds_components/components/components.rst b/docs/source/control_hard_compon/ds_components/components/components.rst index e5d55965b..a0f53edfc 100644 --- a/docs/source/control_hard_compon/ds_components/components/components.rst +++ b/docs/source/control_hard_compon/ds_components/components/components.rst @@ -11,7 +11,7 @@ Android Device :class-header: sd-bg-dark font-weight-bold sd-text-white :class-body: sd-text-left body - REV Driver Hub + REV :term:`Driver Hub` ^^^ @@ -41,11 +41,11 @@ Android Device Moto E5 -The heart of the Driver Station is the Android Device that runs the Driver +The heart of the :term:`Driver Station` is the Android Device that runs the Driver Station App. This Android Device requirement can be fulfilled either through the use of a `REV Driver Hub `_ or -one of the approved Android Smartphones listed in the Competition Manual. It is -of vital importance that the Driver Station App be updated to a version that +one of the approved Android Smartphones listed in the :term:`Competition Manual`. It is +of vital importance that the :term:`Driver Station App` be updated to a version that meets or exceeds the minimum Driver Station App version as defined in the Competition Manual. @@ -70,13 +70,13 @@ USB-OTG Adapter / Hubs +++ - USB OTG Adapter Cable + USB :term:`OTG Adapter` Cable .. grid-item-card:: :class-header: sd-bg-dark font-weight-bold sd-text-white :class-body: sd-text-left body - USB Hub + :term:`USB Hub` ^^^ @@ -108,7 +108,7 @@ USB-OTG Adapter / Hubs If the Android Device being used is an Android Smartphone, the smartphone only provides a single USB-Micro-B port on the bottom of the phone. In order to use -USB devices with the Android Smartphone, like a gamepad, a USB-OTG Adapter +USB devices with the Android Smartphone, like a :term:`gamepad `, a USB-OTG Adapter Cable must be used. This cable provides a USB Type A port for the Gamepad or peripherals (like a USB Hub, to allow more than one Gamepad to be used). If available, it is instead recommended to use a USB Hub with OTG cable built in, like the diff --git a/docs/source/control_hard_compon/ds_components/index.rst b/docs/source/control_hard_compon/ds_components/index.rst index 5f7bd1c4f..d719b4b76 100644 --- a/docs/source/control_hard_compon/ds_components/index.rst +++ b/docs/source/control_hard_compon/ds_components/index.rst @@ -7,14 +7,14 @@ Driver Station Overview ======================= These images represent a basic connection diagram for the components that have -typically been used to create a Driver Station. These components have +typically been used to create a :term:`Driver Station`. These components have typically been purchased from the *FIRST* Storefront (in the "Control and Communication" kit). These configurations show sample connections, and in no way represent the only possible way of connecting these components. These images also do not represent using a `Driver Station Carrier `_, which is recommended for teams to use for component management and -transportation. See the Competition Manual for more information +transportation. See the :term:`Competition Manual` for more information on *OPERATOR CONSOLES*. .. tab-set:: diff --git a/docs/source/control_hard_compon/index.rst b/docs/source/control_hard_compon/index.rst index 01cb75c11..a6887f777 100644 --- a/docs/source/control_hard_compon/index.rst +++ b/docs/source/control_hard_compon/index.rst @@ -6,8 +6,8 @@ Hardware Component Overview ============================ -The *FIRST* Tech Challenge Control System is divided into two main components: -the Driver Station (DS) and the Robot Controller (RC). This section will give +The *FIRST* Tech Challenge :term:`Control System` is divided into two main components: +the :term:`Driver Station` (DS) and the :term:`Robot Controller` (RC). This section will give you a brief introduction to the hardware components, their various configurations, and connections. diff --git a/docs/source/control_hard_compon/rc_components/encoders/encoders.rst b/docs/source/control_hard_compon/rc_components/encoders/encoders.rst index 2c3a7feff..966ff6d85 100644 --- a/docs/source/control_hard_compon/rc_components/encoders/encoders.rst +++ b/docs/source/control_hard_compon/rc_components/encoders/encoders.rst @@ -18,7 +18,7 @@ Encoders (Rotation Counters) +++ - Built-in Encoder in the REV HD Hex Motor + Built-in :term:`Encoder` in the REV HD Hex Motor .. grid-item-card:: :class-header: sd-bg-dark font-weight-bold sd-text-white diff --git a/docs/source/control_hard_compon/rc_components/hub/hub.rst b/docs/source/control_hard_compon/rc_components/hub/hub.rst index cab67bb2c..0d1f74e94 100644 --- a/docs/source/control_hard_compon/rc_components/hub/hub.rst +++ b/docs/source/control_hard_compon/rc_components/hub/hub.rst @@ -18,7 +18,7 @@ Control Hub REV Control Hub (REV-31-1595) -A REV Control Hub combines a REV Expansion Hub with an embedded Android +A REV :term:`Control Hub` combines a REV :term:`Expansion Hub` with an embedded Android daughterboard connected to it. This means it is able to control all of the hardware components of your robot and also run your actual robot software. This is in contrast to the REV Expansion Hub which was only able to control hardware @@ -39,7 +39,7 @@ Expansion Hub REV Expansion Hub (REV-31-1153) -A REV Expansion Hub is a hub that is used to control all of the hardware components of your robot. +A REV Expansion Hub is a :term:`hub ` that is used to control all of the hardware components of your robot. It takes the commands your Android Device sends and actually makes it happen. If you want to move a motor, an Expansion Hub is what takes the instruction of moving the motor and actually sends power to the motor in the correct manner. It however does not know when to do this which is where the Android Device comes into play. This device 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 9df6539b6..004d244f2 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 @@ -20,7 +20,7 @@ USB 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. +The control :term:`hub ` has four USB ports described below. USB 2.0 and USB 3.0 refer to the USB specifications that relate to data exchange rate and power delivery. @@ -33,20 +33,20 @@ USB Type-A and USB-C and USB Mini-B refer to the type of connector. 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. +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 :term:`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 + The REV :term:`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). + Using the USB 2.0 Port may cause :term:`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 ^^^^^^^ -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). +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 (:term:`webcams `). USB C ^^^^^ @@ -58,7 +58,7 @@ 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 +the I/O system. In this case, it is only for the purpose of uploading :term:`firmware ` to the device. HDMI diff --git a/docs/source/control_hard_compon/rc_components/hub/ports/exh-ports.rst b/docs/source/control_hard_compon/rc_components/hub/ports/exh-ports.rst index 549a32f00..f635548e5 100644 --- a/docs/source/control_hard_compon/rc_components/hub/ports/exh-ports.rst +++ b/docs/source/control_hard_compon/rc_components/hub/ports/exh-ports.rst @@ -12,5 +12,5 @@ Expansion Hub Ports USB-B Port ---------- -An Android RC phone controls an Expansion Hub through this USB-mini-B -port, connected with USB OTG cable. This port also allows firmware updates. \ No newline at end of file +An Android RC phone controls an :term:`Expansion Hub` through this USB-mini-B +port, connected with USB OTG cable. This port also allows :term:`firmware ` updates. \ No newline at end of file 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 57a4caf95..abbaedaf2 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 @@ -2,8 +2,8 @@ Battery Ports -------------- .. danger:: - **Never** connect a battery charger directly to the battery port. This will - void your warranty and fry your hub. + **Never** connect a :term:`battery ` charger directly to the battery port. This will + void your warranty and fry your :term:`hub `. The yellow `XT30 `_ connectors are used to power your REV Hub as well as all the devices connected to it. @@ -36,7 +36,7 @@ Encoder Ports -------------- These 4-pin `JST-PH `_ -style connectors are used for your quadrature encoders. There are 4 of these +style connectors are used for your quadrature :term:`encoders `. There are 4 of these ports on each hub and they can be used in tandem with the motor they are adjacent to. However, it is also possible to use this port to connect to a standalone incremental encoder. To connect to more than 4 encoders it is @@ -47,7 +47,7 @@ port please see 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. +These 0.1” Header pins are used to power and control your :term:`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. See the Motors & Actuators section of the `Competition Manual `_ for approved servo power devices. @@ -59,7 +59,7 @@ please see `REV Servo Port Documentation `. For more information on this port please see `REV +5V Power Port Documentation `_ and the Power Distribution section of the `Competition Manual `_. @@ -68,8 +68,8 @@ Analog Ports -------------- These 4-pin `JST-PH `_ -style connectors are used for your analog inputs. There are 2 of these ports on each hub. These ports -have 4 channels labeled from 0-4. This port can be used to connect to a standalone analog sensor. A common example of an +style connectors are used for your :term:`analog inputs `. There are 2 of these ports on each hub. These ports +have 4 channels labeled from 0-4. This port can be used to connect to a standalone analog :term:`sensor `. A common example of an analog sensor is a `potentiometer `_. An analog sensor is one that outputs a range of values rather than digital which alternates between one of two states. For more information on this port please see `REV Analog Port Documentation `_. @@ -88,7 +88,7 @@ I2C Ports .. todo:: TODO [uvidyadharan] - Add reference to I2C Driver creation tutorial once migrated + Add reference to :term:`I2C` Driver creation tutorial once migrated 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 diff --git a/docs/source/control_hard_compon/rc_components/index.rst b/docs/source/control_hard_compon/rc_components/index.rst index 5c17b7efb..ef6d26ded 100644 --- a/docs/source/control_hard_compon/rc_components/index.rst +++ b/docs/source/control_hard_compon/rc_components/index.rst @@ -13,7 +13,7 @@ purchased from the *FIRST* Storefront (demonstrating components from the REV and Tetrix starter kits, along with the Electronics kit). These configurations show sample connections, and in no way represent the only possible way of connecting these components. In both diagrams is an extra optional REV -Expansion Hub that has NOT been included with standard starter kits nor +:term:`Expansion Hub` that has NOT been included with standard starter kits nor electronics kits; it is included in these diagrams as a sample of how to connect an additional optional REV Expansion Hub if one is available and desired. diff --git a/docs/source/control_hard_compon/rc_components/motors/motors.rst b/docs/source/control_hard_compon/rc_components/motors/motors.rst index 63fbdc4f8..dc6dc3af8 100644 --- a/docs/source/control_hard_compon/rc_components/motors/motors.rst +++ b/docs/source/control_hard_compon/rc_components/motors/motors.rst @@ -19,7 +19,7 @@ Motors +++ - TETRIX 12V TorqueNADO DC Motor + TETRIX 12V TorqueNADO :term:`DC Motor` .. grid-item-card:: :class-header: sd-bg-dark font-weight-bold sd-text-white @@ -90,8 +90,8 @@ Motors REV Robotics Core Hex 12V DC Motor Motors are the primary drivers of a robot. All motors are 12v brushed DC motors -and are enumerated in the Competition Manual. They may only be controlled via a -REV Expansion Hub, REV Control Hub, or REV SPARKmini Motor Controller. +and are enumerated in the :term:`Competition Manual`. They may only be controlled via a +REV :term:`Expansion Hub`, REV :term:`Control Hub`, or REV SPARKmini Motor Controller. Additional Resources --------------------- diff --git a/docs/source/control_hard_compon/rc_components/power_distr/power-distr.rst b/docs/source/control_hard_compon/rc_components/power_distr/power-distr.rst index be3a87d27..5b30956a9 100644 --- a/docs/source/control_hard_compon/rc_components/power_distr/power-distr.rst +++ b/docs/source/control_hard_compon/rc_components/power_distr/power-distr.rst @@ -58,8 +58,8 @@ Robot Main Battery REV Robotics (REV-31-1302) -The main power of a robot comes from one 12v battery. The batteries above are -samples of these batteries, check the Competition Manual for the full list of +The main power of a robot comes from one 12v :term:`battery `. The batteries above are +samples of these batteries, check the :term:`Competition Manual` for the full list of batteries. Note that it is typically allowed to replace the connector on the batteries, provided the in-line fuse on the battery is preserved, again check the Competition Manual for full details. diff --git a/docs/source/control_hard_compon/rc_components/sensors/sensors.rst b/docs/source/control_hard_compon/rc_components/sensors/sensors.rst index ec58619cc..54ca24344 100644 --- a/docs/source/control_hard_compon/rc_components/sensors/sensors.rst +++ b/docs/source/control_hard_compon/rc_components/sensors/sensors.rst @@ -211,7 +211,7 @@ IMU BNO055 -An Inertial Measurement Unit (IMU) is a sensor that is a combination of a +An Inertial Measurement Unit (:term:`IMU`) is a sensor that is a combination of a Gyroscope, Accelerometer, and Magnetometer. A Gyroscope is a device that reports the `angular orientation `_ of an object in 3 dimensions. An Accelerometer is a device that reports the diff --git a/docs/source/control_hard_compon/rc_components/servos/servos.rst b/docs/source/control_hard_compon/rc_components/servos/servos.rst index 9e066ba0e..5128aa6e2 100644 --- a/docs/source/control_hard_compon/rc_components/servos/servos.rst +++ b/docs/source/control_hard_compon/rc_components/servos/servos.rst @@ -55,15 +55,15 @@ Servos W39197 -A servo is a type of device that takes a Pulse-Width Modulated (PWM) signal as +A :term:`servo ` is a type of device that takes a Pulse-Width Modulated (:term:`PWM`) signal as an input and, with the help of an embedded controller, produces linear or rotational movement based upon the input signal. Servos may take an input signal -generated by a REV Hub (either by a Control Hub or Expansion Hub) which itself +generated by a REV Hub (either by a :term:`Control Hub` or :term:`Expansion Hub`) which itself provides 5V of power and a limited amount of current (see REV Documentation for more information). Servo power injectors such as the REV Servo Power Module (SPM) may be utilized to boost the power provided to servos up to 6V for up to 6 servos per device. Robots in *FIRST* Tech Challenge are subject to limitations on servos, -including quantity and mechanical power. Please see the Competition Manual for details. +including quantity and mechanical power. Please see the :term:`Competition Manual` for details. Additional Resources --------------------- 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 2123608b3..97953a384 100644 --- a/docs/source/control_hard_compon/rc_components/uvc/uvc.rst +++ b/docs/source/control_hard_compon/rc_components/uvc/uvc.rst @@ -1,12 +1,12 @@ UVC Webcam =========== -A webcam is a device that provides visual images of the surrounding environment. +A :term:`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. +the REV :term:`Control Hub` or to the Robot Control system via a :term:`USB hub `. .. grid:: 1 2 2 2 :gutter: 2 @@ -50,14 +50,14 @@ the REV Control Hub or to the Robot Control system via a USB hub. Webcams are intended to be used in computer vision related tasks. Example use cases for a webcam are: -- :doc:`detecting <../../../apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values>` an AprilTag, +- :doc:`detecting <../../../apriltag/understanding_apriltag_detection_values/understanding-apriltag-detection-values>` an :term:`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. +- using :term:`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. +- A :doc:`list of webcams <../../../apriltag/vision_portal/visionportal_webcams/visionportal-webcams>` known to be compatible with :term:`VisionPortal`. - :ref:`Connecting UVC Camera via Powered USB Hub ` - :ref:`Connecting UVC Camera directly to REV Control Hub ` - :ref:`USB Port Overview ` diff --git a/docs/source/control_system_troubleshooting/index.rst b/docs/source/control_system_troubleshooting/index.rst index bba82722a..f810f82e5 100644 --- a/docs/source/control_system_troubleshooting/index.rst +++ b/docs/source/control_system_troubleshooting/index.rst @@ -6,18 +6,18 @@ Control System Troubleshooting Guide ===================================== -*FIRST* Tech Challenge uses an Android-based Control System for its robot +*FIRST* Tech Challenge uses an Android-based :term:`Control System` for its robot competition. Teams are responsible for bringing, maintaining, and troubleshooting their own wireless Control System, but at an event they may need help from a FIRST Technical Advisor (FTA), Control System Advisor (CSA), and/or Wi-Fi Technical Advisor (WTA). This guide provides tips and procedures for avoiding, diagnosing, and resolving common problems with the wireless -Control System, both for teams and for the technical volunteers who support +Control System, both for teams and for the technical :term:`volunteers ` who support them at events. This guide assumes you already have a basic understanding of the Control -System's components. For an introduction to the Driver Station, Robot -Controller, Control Hub, and Driver Hub, see +System's components. For an introduction to the :term:`Driver Station`, Robot +Controller, :term:`Control Hub`, and :term:`Driver Hub`, see :doc:`/programming_resources/shared/control_system_intro/The-FTC-Control-System`. .. toctree:: @@ -34,7 +34,7 @@ Controller, Control Hub, and Driver Hub, see Mitigating Disruptions Due to Electrostatic Shocks --------------------------------------------------- -Electrostatic discharge (ESD) events have the potential to disrupt the +Electrostatic discharge (:term:`ESD`) events have the potential to disrupt the normal operation of a competition robot. The :doc:`/hardware_and_software_configuration/configuring/managing_esd/managing-esd` article provides a comprehensive discussion of this topic. Key takeaways diff --git a/docs/source/control_system_troubleshooting/monitoring_wireless_environment/monitoring-wireless-environment.rst b/docs/source/control_system_troubleshooting/monitoring_wireless_environment/monitoring-wireless-environment.rst index 40d26e4e1..0a92238c8 100644 --- a/docs/source/control_system_troubleshooting/monitoring_wireless_environment/monitoring-wireless-environment.rst +++ b/docs/source/control_system_troubleshooting/monitoring_wireless_environment/monitoring-wireless-environment.rst @@ -1,8 +1,8 @@ Monitoring the Wireless Environment ===================================== -The *FIRST* Tech Challenge Control System uses Wi-Fi Direct and/or wireless -access point technology to connect the Driver Station device to the Robot +The *FIRST* Tech Challenge :term:`Control System` uses :term:`Wi-Fi Direct` and/or wireless +access point technology to connect the :term:`Driver Station` device to the Robot Controller. Wi-Fi Direct networks can be managed like normal Wi-Fi networks, so the techniques and tools used to monitor and troubleshoot a corporate Wi-Fi network can also be applied to the Wi-Fi Direct networks used by the @@ -49,7 +49,7 @@ connectivity for those pairs. 5GHz Portion of the Spectrum ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -FTC-approved smartphones and the REV Robotics Control Hub and Driver Hub +FTC-approved smartphones and the REV Robotics :term:`Control Hub` and :term:`Driver Hub` support both the 2.4GHz and 5GHz bands. 5GHz channels do not overlap each other, and they offer greater bandwidth than 2.4GHz channels. They also have more limited range, which can be useful in a crowded competition venue with diff --git a/docs/source/control_system_troubleshooting/troubleshooting_common_issues/troubleshooting-common-issues.rst b/docs/source/control_system_troubleshooting/troubleshooting_common_issues/troubleshooting-common-issues.rst index ab6418e56..3137fbfe0 100644 --- a/docs/source/control_system_troubleshooting/troubleshooting_common_issues/troubleshooting-common-issues.rst +++ b/docs/source/control_system_troubleshooting/troubleshooting_common_issues/troubleshooting-common-issues.rst @@ -1,7 +1,7 @@ Troubleshooting Common Control System Issues ============================================= -This page collects common Control System problems reported by teams at +This page collects common :term:`Control System` problems reported by teams at events, along with the checks and fixes an FTA, CSA, or WTA can walk a team through. @@ -11,7 +11,7 @@ FIRST Tech Challenge Driver Station Gamepad is Not Recognized ^^^^^^^^^^^^^^^^^^^^^^^^^^ -If a gamepad is recognized by the *FIRST* Tech Challenge Driver Station app, +If a :term:`gamepad ` is recognized by the *FIRST* Tech Challenge :term:`Driver Station` app, then whenever there is activity with that gamepad, the appropriate gamepad icon in the upper right-hand corner of the Driver Station main screen will be highlighted in green. @@ -59,15 +59,15 @@ Gamepad Joysticks Were Not in Neutral Position When Connected to Driver Station Teams can connect up to two gamepads to the Driver Station Android device. Each gamepad has a pair of joysticks that the team's drivers use to control -their robot. The gamepads are usually connected directly to a REV Driver Hub -or through a non-powered USB hub to the USB Micro OTG port on an Android +their robot. The gamepads are usually connected directly to a REV :term:`Driver Hub` +or through a non-powered :term:`USB hub ` to the USB Micro OTG port on an Android smartphone Driver Station. When the gamepads are first connected, the Android device calibrates the zero, or neutral, position of the two analog joysticks on each gamepad. If a user has deflected or moved the joysticks while they are being plugged in, the Driver Station might use that non-zero position as the calibrated -reference point. This can cause unexpected behavior when an OpMode runs — +reference point. This can cause unexpected behavior when an :term:`OpMode` runs — for example, if the user starts the OpMode and the robot starts driving without the user touching the joysticks, an improperly calibrated joystick could be the cause. @@ -83,7 +83,7 @@ The Logitech F310 gamepad has a button labeled "MODE". When this button is pressed, the small green LED next to it turns on. Teams usually do **not** want this button enabled — with MODE enabled, the outputs of the left joystick and the D-pad are swapped, which often confuses teams if the -button gets pressed during a match. +button gets pressed during a :term:`match `. .. figure:: images/f310-mode-button.png :alt: Logitech F310 gamepad with the MODE button, located below the D-pad, circled in red. @@ -125,7 +125,7 @@ is unexpectedly shutting off, check that it has an adequate charge. Unable to Find a Specific OpMode in the Driver Station's List of Available OpModes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If a team used Android Studio and the *FIRST* Tech Challenge SDK to create +If a team used :term:`Android Studio` and the *FIRST* Tech Challenge SDK to create an OpMode but cannot find it in the Driver Station's list of available OpModes, ask the team if they remembered to register their OpMode in the ``FtcOpModeRegister`` class. If they created the OpMode but did not register @@ -150,7 +150,7 @@ User Code Threw an Uncaught Exception: null This error occurs when a method is called on an object that is null at the time of the call. To address it, first look at the robot log file to find where to search for the problem. To access the log files, open the settings -in the Robot Controller app and select **View Logs**, then scroll up until a +in the :term:`Robot Controller` app and select **View Logs**, then scroll up until a block of red text appears and look for a line resembling: .. code-block:: text @@ -166,7 +166,7 @@ before that line. User Code Threw an Uncaught Exception: number XXX is invalid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This exception is typically thrown when a motor or servo is set to a value +This exception is typically thrown when a motor or :term:`servo ` is set to a value less than -1 or greater than 1. To find which line of code threw the exception, check the robot logs the same way as above — open the settings in the Robot Controller app, select **View Logs**, scroll up to the first block @@ -202,7 +202,7 @@ map, and it applies to apps created using Android Studio. If you are at an event and encounter this error, ask the team to verify that the name they use in their OpMode to reference a hardware device matches the name specified for that device in their Robot Controller's -configuration file. The spelling is case sensitive, so the names must match +:term:`configuration file `. The spelling is case sensitive, so the names must match exactly. Common Programming Errors @@ -253,8 +253,8 @@ following OpMode: } In this example, the motors turn on and the OpMode loops indefinitely until -the touch sensor is pressed. This OpMode is uninterruptible: if the user -presses the STOP button on the Driver Station before the touch sensor is +the :term:`touch sensor ` is pressed. This OpMode is uninterruptible: if the user +presses the STOP button on the Driver Station before the touch :term:`sensor ` is pressed, the ``while`` loop keeps running and the OpMode is not properly stopped. This can cause the robot to behave erratically and become unresponsive — the robot continues to run, and the Driver Station continues @@ -298,9 +298,9 @@ the touch sensor is pressed: REV Robotics Control and Expansion Hubs ------------------------------------------ -The REV Expansion Hub is a compact hardware controller with 4 DC motor -ports, 6 servo ports, and multiple digital, I2C, and analog ports. The REV -Control Hub is a REV Expansion Hub with an integrated Android device. +The REV :term:`Expansion Hub` is a compact hardware controller with 4 :term:`DC motor ` +ports, 6 servo ports, and multiple digital, :term:`I2C`, and analog ports. The REV +:term:`Control Hub` is a REV Expansion Hub with an integrated Android device. Detailed information and specifications on the Control and Expansion Hubs are available in the REV Robotics Control Hub and Expansion Hub Getting @@ -314,7 +314,7 @@ Resetting a REV Control Hub Wi-Fi Password ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A common issue for teams is resetting the REV Control Hub's Wi-Fi password -to a new value, which is required as part of field inspection. +to a new value, which is required as part of field :term:`inspection `. On the Driver Station app, tap the three dots (⋮) and select **Program and Manage**. This may take up to about 30 seconds to load. Then follow these @@ -341,7 +341,7 @@ Logic Level Converters ^^^^^^^^^^^^^^^^^^^^^^^ The REV Robotics Control and Expansion Hubs operate using 3.3V digital -logic levels. Older Modern Robotics-compatible sensors and encoders operate +logic levels. Older Modern Robotics-compatible sensors and :term:`encoders ` operate using 5V digital logic levels. If a team would like to use a 5V device that was compatible with Modern Robotics hardware controllers, the team will need a Logic Level Converter (available from REV Robotics) to connect the @@ -389,7 +389,7 @@ If a team is having a problem with a dual Expansion Hub configuration, it is important that the FTA or CSA verify that each of the daisy-chained Expansion Hubs has a non-conflicting serial address. By default, all Expansion Hubs are assigned an address of 2 at the factory, so a team that -wants to connect two Hubs together must first change the serial address of +wants to connect two :term:`Hubs ` together must first change the serial address of one of them to prevent it from conflicting with the other Hub's address. An FTA or CSA can connect each Expansion Hub individually (not diff --git a/docs/source/control_system_troubleshooting/troubleshooting_wireless_at_events/troubleshooting-wireless-at-events.rst b/docs/source/control_system_troubleshooting/troubleshooting_wireless_at_events/troubleshooting-wireless-at-events.rst index d881e2b8e..ea10c63cb 100644 --- a/docs/source/control_system_troubleshooting/troubleshooting_wireless_at_events/troubleshooting-wireless-at-events.rst +++ b/docs/source/control_system_troubleshooting/troubleshooting_wireless_at_events/troubleshooting-wireless-at-events.rst @@ -14,8 +14,8 @@ Ping Times ---------- If you are at a *FIRST* Tech Challenge event, you can use the ping time -feature of the FTC Driver Station app as an indicator of network quality. -When a Driver Station is connected to a Robot Controller, it periodically +feature of the FTC :term:`Driver Station` app as an indicator of network quality. +When a Driver Station is connected to a :term:`Robot Controller`, it periodically sends a heartbeat packet to the Robot Controller. The Robot Controller is supposed to respond to each ping and send an acknowledgement packet (an "ACK") back to the Driver Station. @@ -73,7 +73,7 @@ channel is most likely free of other Wi-Fi and non-Wi-Fi traffic. .. important:: The observed ping time is also affected by whether the Robot Controller is available to respond to heartbeat messages from the Driver Station. If the Robot Controller is busy — for example, because it is - blocked in a portion of an improperly written OpMode — and it can't + blocked in a portion of an improperly written :term:`OpMode` — and it can't respond to the Driver Station in a timely manner, the observed ping times will be higher even if the wireless connection itself is strong. @@ -230,7 +230,7 @@ by FTC Driver Station-Robot Controller pairs. There is an amendment to the 802.11 standard (802.11w) that makes it more difficult to conduct some of these attacks. The 802.11w standard is the -default setting for the REV Driver Hub and the REV Control Hub, but +default setting for the REV :term:`Driver Hub` and the REV :term:`Control Hub`, but unfortunately it is not yet available on Android smartphones — the Android devices used at *FIRST* Tech Challenge events remain vulnerable to certain wireless attacks. @@ -255,11 +255,11 @@ Determining if Wi-Fi Interference Warrants a Match Replay The most critical responsibility of a FIRST Technical Advisor (FTA), Control System Advisor (CSA), or Wireless Technical Advisor (WTA) is deciding -whether wireless interference during a match was significant enough to +whether wireless interference during a :term:`match ` was significant enough to warrant a replay. This is a difficult and subjective decision. The -Competition Manual states that matches are replayed at the discretion of the -Head Referee only for a failure of an Arena Element or verified Wi-Fi -interference that was likely to have impacted which Alliance won the match. +:term:`Competition Manual` states that matches are replayed at the discretion of the +Head :term:`Referee` only for a failure of an Arena Element or verified Wi-Fi +interference that was likely to have impacted which :term:`Alliance` won the match. To recommend a match replay to the Head Referee, the FTA (or CSA or WTA) must have sufficient proof of such Wi-Fi interference. @@ -323,7 +323,7 @@ following: - Disruption due to an :doc:`electrostatic discharge (ESD) ` event or a physical impact to the robot. -- High current draw from motors or servos causing a "brown-out" that +- High current draw from motors or :term:`servos ` causing a "brown-out" that temporarily affects the Robot Controller's Wi-Fi antenna. - A loose or disconnected wire supplying power to the REV Control Hub. - A wire with damaged insulation contacting the robot's structure. @@ -349,7 +349,7 @@ during the event to help monitor the wireless environment. If resources are limited, using a spare set of Robot Controller and Driver Station devices to keep track of ping times is a relatively easy way to monitor the wireless environment. For larger and higher profile events, the -event host and technical volunteers should consider using some of the more +event host and technical :term:`volunteers ` should consider using some of the more sophisticated tools described in :doc:`/control_system_troubleshooting/monitoring_wireless_environment/monitoring-wireless-environment` to monitor the wireless spectrum at their event. These more sophisticated diff --git a/docs/source/control_system_troubleshooting/using_log_files/using-log-files.rst b/docs/source/control_system_troubleshooting/using_log_files/using-log-files.rst index 2de70f1b6..71c7a6486 100644 --- a/docs/source/control_system_troubleshooting/using_log_files/using-log-files.rst +++ b/docs/source/control_system_troubleshooting/using_log_files/using-log-files.rst @@ -5,7 +5,7 @@ Introduction ------------ One of the most useful features in the troubleshooting process is the ability to retrieve and -review the log files on the Driver Station and Robot Controller devices. The system logs all +review the log files on the :term:`Driver Station` and :term:`Robot Controller` devices. The system logs all sorts of information in these files, and when an incident occurs it is often helpful to review them to look for a pattern or clue that can help diagnose the problem. This page is the full walkthrough referenced from :doc:`/control_system_troubleshooting/troubleshooting_common_issues/troubleshooting-common-issues`, @@ -202,19 +202,19 @@ Using the REV Hardware Client Windows App to View Log Files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A convenient and easy way to troubleshoot problems with the REV Control system is to view log -files using the REV Hardware Client for Windows computers. The REV Hardware Client log viewer has +files using the :term:`REV Hardware Client` for Windows computers. The REV Hardware Client log viewer has filters, tags, and a search function that makes it easy to see what is happening on the Control -Hub or Driver Hub during an OpMode run. Instructions for using the REV Hardware Client are +Hub or :term:`Driver Hub` during an :term:`OpMode` run. Instructions for using the REV Hardware Client are available on the REV Robotics website: `Using the Log Viewer `__. Using the Android Debug Bridge for Troubleshooting ----------------------------------------------------- -The Android Debug Bridge (ADB) is a utility program included with the Android Software +The Android Debug Bridge (:term:`ADB`) is a utility program included with the Android Software Development Kit (SDK) platform-tools. ADB is invoked from a command line and is a very helpful utility. To use ADB you will need the Android SDK platform-tools installed (preferably a recent -version of the Android SDK). Normally, when you install Android Studio, you also install the +version of the Android SDK). Normally, when you install :term:`Android Studio`, you also install the Android SDK, including the platform-tools package. The examples in this section were made with a Windows PC, but the process is similar for Mac and @@ -427,7 +427,7 @@ of the Robot Controller: } This linear OpMode example shows how to use the ``RobotLog.d`` method to log information to the -log file. You can use the Android Monitor window of the Android Studio IDE to view these log +log file. You can use the Android Monitor window of the Android Studio :term:`IDE` to view these log messages in real time. You can also create a filter so you only see a subset of log messages in the window. diff --git a/docs/source/control_system_troubleshooting/wifi_channel_planning/wifi-channel-planning.rst b/docs/source/control_system_troubleshooting/wifi_channel_planning/wifi-channel-planning.rst index 2280ce517..971f37dfc 100644 --- a/docs/source/control_system_troubleshooting/wifi_channel_planning/wifi-channel-planning.rst +++ b/docs/source/control_system_troubleshooting/wifi_channel_planning/wifi-channel-planning.rst @@ -8,7 +8,7 @@ Planning Wi-Fi Channels for Large Events Accommodating a Large Number of Robots at an Event ---------------------------------------------------- -The wireless Control System is a point-to-point system. This means that each +The wireless :term:`Control System` is a point-to-point system. This means that each Driver Station-robot pair establishes its own Wi-Fi network at an event. If there are a large number of robots in a venue, then there will be a large number of wireless networks operating in the venue. If there are a large @@ -30,7 +30,7 @@ Wi-Fi Event Planning Guide ^^^^^^^^^^^^^^^^^^^^^^^^^^^ *FIRST* Tech Challenge has published a Wi-Fi Event Planning Guide that -contains detailed steps a technical volunteer can take to help keep the +contains detailed steps a technical :term:`volunteer ` can take to help keep the wireless environment operating smoothly at larger events. Check the *FIRST* Tech Challenge community and resource library for the current version of this guide. @@ -98,11 +98,11 @@ channel, here are some factors to consider when doing your planning. channel. - *Use a pair of Android devices to monitor ping times.* If a target channel looks relatively clean, you should use a pair of Android - devices running the FTC Driver Station and FTC Robot Controller apps to + devices running the FTC :term:`Driver Station` and FTC :term:`Robot Controller` apps to monitor the ping times on the target channel. You will need a pair of Android devices that support channel changing (such as approved FTC phones). Switch to the target channel and test to make sure you can - select and run an OpMode (like the NullOp sample OpMode). If the average + select and run an :term:`OpMode` (like the NullOp sample OpMode). If the average ping times for the test Android devices are low (less than 5 msec) then the channel is clear. If the average ping times are high (more than 50 msec) then there might be some type of interference on the channel. @@ -128,7 +128,7 @@ channel, here are some factors to consider when doing your planning. .. important:: Approved hardware changes over time. For the current list of allowed phones and other hardware and software, teams should always refer - to the current season's *FIRST* Tech Challenge Competition Manual and its + to the current season's *FIRST* Tech Challenge :term:`Competition Manual` and its updates, rather than relying on the list above. UnPairing Then Re-Pairing the Driver Station to the Robot Controller @@ -195,7 +195,7 @@ Changing the Channel Using an Approved Motorola Smartphone If you are using an approved Motorola smartphone as your Robot Controller, you can use the channel change function that is built into the FTC Robot -Controller app to change the Wi-Fi Direct operating channel. From the Robot +Controller app to change the :term:`Wi-Fi Direct` operating channel. From the Robot Controller app, launch the Settings menu and select the Change Wi-Fi Channel option. diff --git a/docs/source/control_system_troubleshooting/wifi_technology/wifi-technology.rst b/docs/source/control_system_troubleshooting/wifi_technology/wifi-technology.rst index 2621f12ad..4289bad21 100644 --- a/docs/source/control_system_troubleshooting/wifi_technology/wifi-technology.rst +++ b/docs/source/control_system_troubleshooting/wifi_technology/wifi-technology.rst @@ -1,11 +1,11 @@ Wi-Fi Technology and Direct Connections ======================================== -The Driver Station and Robot Controller are Android devices that run special +The :term:`Driver Station` and :term:`Robot Controller` are Android devices that run special *FIRST* Tech Challenge apps to create a unique and secure wireless connection -between the two devices. For this connection, the REV Control Hub uses +between the two devices. For this connection, the REV :term:`Control Hub` uses Wireless Access Point (WAP) technology, while a standalone phone-based Robot -Controller uses Wi-Fi Direct (P2P) technology. There are some minor, subtle +Controller uses :term:`Wi-Fi Direct` (P2P) technology. There are some minor, subtle differences between how these two technologies connect the devices together wirelessly. Note that the FTC Driver Station app is able to connect to both types of Robot Controllers. @@ -42,12 +42,12 @@ is required. Programming Laptop -------------------- -During a typical *FIRST* Tech Challenge match, only a team's Driver Station +During a typical *FIRST* Tech Challenge :term:`match `, only a team's Driver Station is connected to the Wi-Fi Direct group or the wireless access point (WAP) that is established by the team's Robot Controller. Away from the competition field, however, a team might have additional devices connected -to this Wi-Fi Direct group. For example, when a team edits an OpMode using -the FTC Blocks Development Tool or the FTC OnBot Java Development Tool, their +to this Wi-Fi Direct group. For example, when a team edits an :term:`OpMode` using +the FTC :term:`Blocks` Development Tool or the FTC :term:`OnBot Java` Development Tool, their developer's laptop will also be connected to the Robot Controller's wireless network. @@ -58,7 +58,7 @@ network. from the competition field. Note that the wireless connection between the developer's laptop and the -Robot Controller does not violate the prohibition in the Competition Manual +Robot Controller does not violate the prohibition in the :term:`Competition Manual` on teams setting up their own wireless network. For this case, the developer's laptop is connected to the existing Wi-Fi Direct group or wireless access point that is also used by the Driver Station to communicate @@ -239,7 +239,7 @@ successfully, it will display useful status information (see the figure above) on its screen, including the name of the device that it is connected to, the average ping time between the Driver Station and Robot Controller, and voltage info for the Robot Controller smartphone (if used) and the main -robot battery. +robot :term:`battery `. Is the Robot Controller On? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -312,7 +312,7 @@ Station and Robot Controller devices are not connected to any other networks other than each other. It is possible, and sometimes desirable, to connect your Android device to an alternate wireless network: -- Teams like to use the wireless ADB mechanism to debug their apps. +- Teams like to use the wireless :term:`ADB` mechanism to debug their apps. - Teams might need to connect to a wireless network to download something to their phone from the internet. - Teams might have used the Android device to check their e-mail or look up diff --git a/docs/source/control_system_troubleshooting/wireshark_packet_capture/wireshark-packet-capture.rst b/docs/source/control_system_troubleshooting/wireshark_packet_capture/wireshark-packet-capture.rst index a0d77d698..4a6ea0043 100644 --- a/docs/source/control_system_troubleshooting/wireshark_packet_capture/wireshark-packet-capture.rst +++ b/docs/source/control_system_troubleshooting/wireshark_packet_capture/wireshark-packet-capture.rst @@ -103,8 +103,8 @@ attack. DEAUTH packets around that time, and cross-reference the source address of those packets against the addresses of the robots that lost wireless connectivity. During a DEAUTH attack, an attacker spoofs the MAC address - of the target Robot Controller, pretends to be that Robot Controller, and - sends DEAUTH packets to devices (such as the Driver Station) connected to + of the target :term:`Robot Controller`, pretends to be that Robot Controller, and + sends DEAUTH packets to devices (such as the :term:`Driver Station`) connected to its wireless network. To stop the capture, click the red square icon. Use **File -> Save** to save diff --git a/docs/source/devices/huskylens/huskylens.rst b/docs/source/devices/huskylens/huskylens.rst index 31e9b703d..350b9282d 100644 --- a/docs/source/devices/huskylens/huskylens.rst +++ b/docs/source/devices/huskylens/huskylens.rst @@ -21,7 +21,7 @@ version 9.0 in September 2023 with the CENTERSTAGE robot game kickoff. HuskyLens uses **on-board programming** to perform AI-assisted learning, vision processing and recognition. It plugs into an **I2C sensor port** -of a REV Control Hub or REV Expansion Hub. +of a REV :term:`Control Hub` or REV :term:`Expansion Hub`. HuskyLens is **not a USB webcam**, and **does not use** the FTC :ref:`VisionPortal ` @@ -31,11 +31,11 @@ Electrical Connection --------------------- You will need a **custom adapter cable** to connect the HuskyLens to an -I2C port on a REV Control Hub or Expansion Hub. The 4 wires/pins of the +:term:`I2C` port on a REV Control Hub or Expansion Hub. The 4 wires/pins of the HuskyLens connector are not in the same order/position as the 4 pins on the REV Hub. -Three of the wires have **the same color** as wires in the REV sensor +Three of the wires have **the same color** as wires in the REV :term:`sensor ` cable. Your custom cable should connect **red to red**, **black to black**, and **blue to blue**. This leaves only the HuskyLens **green wire**; connect it to the REV **white wire**. Simple! @@ -49,7 +49,7 @@ This tutorial does **not** cover the (many) ways to: - crimped connectors - lever nuts (example below) -FTC Competition Manual allows this work, but teams must ensure high quality for +FTC :term:`Competition Manual` allows this work, but teams must ensure high quality for robot competition all season. .. figure:: images/060-adapter.png @@ -92,7 +92,7 @@ avoid (unlikely) overload of data traffic. The label 0 (zero) is I2C Bus 0, which likely has a **built-in IMU** on its Port 0. An I2C Bus can contain multiple I2C Ports, sharing traffic. -On the Driver Station, touch the three-dots menu, and +On the :term:`Driver Station`, touch the three-dots menu, and ``Configure Robot``. Edit an existing (correct) configuration, or touch ``New``. Touch @@ -111,7 +111,7 @@ in. Touch ``Add``, and select device “HuskyLens” from the drop-down list for Port 0 (or first available port). Type the device name “huskylens”, as -expected by the Sample OpMode. +expected by the :term:`Sample OpMode`. Touch ``Done`` several times, then ``Save``, to save and name/rename this updated robot configuration. Touch the DS “Back” arrow, returning @@ -123,15 +123,15 @@ configuration. Sample OpMode ------------- -Connect your programming computer to the Robot Controller, and open the +Connect your programming computer to the :term:`Robot Controller`, and open the programming software. This tutorial uses **FTC Blocks**. .. note:: **OnBot Java** and **Android Studio** users can easily follow along, since - the Java Sample OpMode uses the same programming logic and is well + the Java Sample :term:`OpMode` uses the same programming logic and is well commented. -In FTC Blocks, create a new OpMode using the sample called +In FTC :term:`Blocks`, create a new OpMode using the sample called “SensorHuskyLens”: .. figure:: images/140-Sample-Blocks.png @@ -142,7 +142,7 @@ In FTC Blocks, create a new OpMode using the sample called HuskyLens Blocks Sample Change the OpMode type from ``TeleOp`` to ``Autonomous``, since this -sample does not use the gamepads. +sample does not use the :term:`gamepads `. .. figure:: images/160-Algorithm-Blocks.png :align: center @@ -152,14 +152,14 @@ sample does not use the gamepads. HuskyLens Blocks Algorithm Notice the default algorithm here is ``TAG_RECOGNITION``, which simply -detects any (common) AprilTags in the sensor’s field of view. This +detects any (common) :term:`AprilTags ` in the sensor’s field of view. This recognition is unrelated to the FTC game CENTERSTAGE and its 10 AprilTags with metadata. Instead, this is a simple built-in, generic function of HuskyLens, used here only to validate the sensor’s operation. For AprilTag recognition and navigation, FTC teams may find much more -value from a UVC webcam and the FTC +value from a UVC :term:`webcam ` and the FTC :ref:`VisionPortal ` software. An FTC robot may use HuskyLens **and** USB webcams. @@ -177,7 +177,7 @@ AprilTag from the common 36h11 family: The HuskyLens’ small screen will show the recognized AprilTag, surrounded by a thin white Bounding Box. -Here’s the corresponding DS Telemetry: +Here’s the corresponding DS :term:`Telemetry`: .. figure:: images/220-DS-1-big-AprilTag.png :align: center @@ -229,7 +229,7 @@ All three AprilTags were recognized: Telemetry Showing 3 Blocks This validates the possibility that HuskyLens could recognize a trained -object in one of various known positions – useful for the Autonomous +object in one of various known positions – useful for the :term:`Autonomous` phase of the CENTERSTAGE game. Single Color Training @@ -432,7 +432,7 @@ its planned match start position, “on-robot”. Also, the trained ambient lighting must be similar to expected match conditions. This may suggest performing the final color-training as part -of tournament or match set-up. With practice, it could be done in a few +of :term:`tournament ` or match set-up. With practice, it could be done in a few seconds. 4. Programming @@ -471,7 +471,7 @@ wish to train **two colors** (e.g. a Red shade and a Blue shade). This would avoid the need for multiple color-training sessions during an FTC tournament. With single-color, you would train for Red before -playing an FTC match as Red Alliance, and train for Blue before playing +playing an FTC :term:`match ` as Red :term:`Alliance`, and train for Blue before playing as Blue Alliance. With multi-color, your Red-Alliance Autonomous OpMode could seek Red as diff --git a/docs/source/faq/faqs.rst b/docs/source/faq/faqs.rst index 8e9bb6e6e..e2cbf15f5 100644 --- a/docs/source/faq/faqs.rst +++ b/docs/source/faq/faqs.rst @@ -7,7 +7,7 @@ Common Team FAQs ================= If you're looking for quick answers regarding the many facets of being a team from registration to -competition to judging. Please refer to these official questions and answers to guide you through the season. +competition to :term:`judging `. Please refer to these official questions and answers to guide you through the season. If you need further clarification navigate to https://www.firstinspires.org/ to Live Chat or ask game specific questions on the `Game Q&A `_ . @@ -70,22 +70,22 @@ Competition FAQs .. grid-item-card:: Who on my team needs to be with the robot for inspection? - At least one student must be present during inspection per the Competition Manual. + At least one student must be present during :term:`inspection ` per the :term:`Competition Manual`. However, inspectors will ask questions about the mechanical and electrical components of your robot. Ideally, you have one or more team members who can answer such questions. In addition, you may need to turn your robot and driver station on and demonstrate your robot complies with a particular rule like sizing. - That may involve someone from the drive team if you need to use a gamepad to operate a mechanism or place the robot in its starting configuration. + That may involve someone from the drive team if you need to use a :term:`gamepad ` to operate a mechanism or place the robot in its starting configuration. Look at the self inspection checklist, you can generally determine what you're doing based on the checklist. .. grid-item-card:: Why aren’t you going to replay that match? - There are only certain situations that warrant replaying a match. Consult the Competition Manual to understand what conditions and processes can result in a replay. + There are only certain situations that warrant replaying a :term:`match `. Consult the Competition Manual to understand what conditions and processes can result in a replay. Typically unless something went wrong with the field or field staff there will not be grounds for a replay. A malfunctioning robot typically does not provide grounds for a replay. .. grid-item-card:: Why did you replay a match for someone else, but not us? - The situation was different. If necessary, teams can talk with the head referee in the competition area Question Box. + The situation was different. If necessary, teams can talk with the head :term:`referee ` in the competition area Question Box. .. grid-item-card:: Why won’t you fix that score? We have video (or photographs) to prove the score is wrong! @@ -99,7 +99,7 @@ Competition FAQs If a team has questions about a match outcome, they should send one student representative to the Question Box to talk to the Head Referee (do not interrupt matches for this conversation). If the referees agree that they made a mistake, they can correct it. If the referees are confident in their score, the team should accept that - decision. Check the Competition Manual for more information about key volunteer roles, tournament operations, and how to use the Question Box. + decision. Check the Competition Manual for more information about key :term:`volunteer ` roles, :term:`tournament ` operations, and how to use the Question Box. Technology FAQs -------------------- diff --git a/docs/source/ftc_sdk/overview/index.rst b/docs/source/ftc_sdk/overview/index.rst index 7869ad428..949206149 100644 --- a/docs/source/ftc_sdk/overview/index.rst +++ b/docs/source/ftc_sdk/overview/index.rst @@ -6,15 +6,15 @@ *FIRST* Tech Challenge Software Development Kit =============================================== -The Software Development Kit (SDK) is the collection of tools for developing +The :term:`Software Development Kit` (SDK) is the collection of tools for developing software and executing it on a *FIRST* Tech Challenge robot. SDK Software includes: -- *FIRST* Tech Challenge Driver Station App +- *FIRST* Tech Challenge :term:`Driver Station App` - * Includes Self-Inspect, :doc:`Robot Configuration `, and others + * Includes :term:`Self-Inspect`, :doc:`Robot Configuration `, and others -- *FIRST* Tech Challenge Robot Controller App +- *FIRST* Tech Challenge :term:`Robot Controller App` * Includes :doc:`Blocks Programming Environment ` * Includes :doc:`OnBot Java Programming Environment ` @@ -23,7 +23,7 @@ includes: for building the Robot Controller App with :doc:`Android Studio ` - `Javadoc Reference Documentation `__ -- Season-Specific Assets (AprilTag libraries, game element assets, etc...) +- Season-Specific Assets (:term:`AprilTag` libraries, game element assets, etc...) All released apps/source can be found in the `SDK GitHub Repository `__. @@ -44,7 +44,7 @@ This build consists of: - Built Driver Station App (``FtcDriverStation-release.apk``) - Built Robot Controller App (``FtcRobotController-release.apk``) -- Android Studio Project source code (``vX.X.zip``, ``vX.X.tar.gz``) +- :term:`Android Studio Project` source code (``vX.X.zip``, ``vX.X.tar.gz``) - `Javadoc Reference Documentation `__ - Season-Specific Assets (AprilTag libraries, game element assets, etc... hosted separately) @@ -139,7 +139,7 @@ Updating SDK Software It is important for teams to update the SDK software. Updates mid-season may not be required. Teams can check the minimum software version required for a -game in the Competition Manual. It is recommended to use the REV Hardware +game in the :term:`Competition Manual`. It is recommended to use the REV Hardware Client to update hardware, if a 64-bit Windows computer is available. If not, then alternate methods provided can be used to update the software. diff --git a/docs/source/ftc_sdk/updating/controlhub_os/Updating-the-Control-Hub-OS.rst b/docs/source/ftc_sdk/updating/controlhub_os/Updating-the-Control-Hub-OS.rst index 94776b710..bf9775e70 100644 --- a/docs/source/ftc_sdk/updating/controlhub_os/Updating-the-Control-Hub-OS.rst +++ b/docs/source/ftc_sdk/updating/controlhub_os/Updating-the-Control-Hub-OS.rst @@ -6,11 +6,11 @@ functions, such as scheduling tasks, executing applications, and controlling peripherals. This must sometimes be updated on the **REV Control Hub**. While this OS update is not specifically part of the :doc:`Software Development Kit (SDK) `, the SDK requires -these updates for the Control Hub in order to perform correctly. +these updates for the :term:`Control Hub` in order to perform correctly. Here are two methods for updating the Control Hub OS: -1. REV Hardware Client (RHC) +1. :term:`REV Hardware Client` (RHC) 2. Manage page on computer More info about updating the Control Hub OS is @@ -23,7 +23,7 @@ More info about updating the Control Hub OS is 2. Plug the Control Hub directly into a computer running the REV Hardware Client, with a USB-C data cable. - 3. Click the hub’s large icon/rectangle. Under “Control Hub Operating + 3. Click the :term:`hub `’s large icon/rectangle. Under “Control Hub Operating System”, see the current/latest mismatch, if any (yellow oval, below). diff --git a/docs/source/ftc_sdk/updating/driverhub_os/Updating-the-Driver-Hub-OS.rst b/docs/source/ftc_sdk/updating/driverhub_os/Updating-the-Driver-Hub-OS.rst index 614a374c2..bdb04caab 100644 --- a/docs/source/ftc_sdk/updating/driverhub_os/Updating-the-Driver-Hub-OS.rst +++ b/docs/source/ftc_sdk/updating/driverhub_os/Updating-the-Driver-Hub-OS.rst @@ -6,11 +6,11 @@ functions, such as scheduling tasks, executing applications, and controlling peripherals. This must sometimes be updated on the **REV Driver Hub**. While this OS update is not specifically part of the :doc:`Software Development Kit (SDK) `, the SDK requires -these updates for the Driver Hub in order to perform correctly. +these updates for the :term:`Driver Hub` in order to perform correctly. Here are two methods for updating the Driver Hub OS: -1. REV Hardware Client (RHC) +1. :term:`REV Hardware Client` (RHC) 2. Software Manager on Driver Hub More info about updating the Driver Hub OS is diff --git a/docs/source/ftc_sdk/updating/ds_app/Updating-the-DS-App.rst b/docs/source/ftc_sdk/updating/ds_app/Updating-the-DS-App.rst index 6569316db..99cced639 100644 --- a/docs/source/ftc_sdk/updating/ds_app/Updating-the-DS-App.rst +++ b/docs/source/ftc_sdk/updating/ds_app/Updating-the-DS-App.rst @@ -1,13 +1,13 @@ Updating the Driver Station App =============================== -The Driver Station App is one of the Apps provided with the *FIRST* Tech +The :term:`Driver Station App` is one of the Apps provided with the *FIRST* Tech Challenge :doc:`Software Development Kit (SDK) `. The Driver -Station App is the major interface for robot configuration, gamepad support, +Station App is the major interface for robot configuration, :term:`gamepad ` support, self-inspect, Team code selection and execution, and others. This app runs -on the REV Driver Hub or an approved Android smartphone. +on the REV :term:`Driver Hub` or an approved Android smartphone. -This page shows how to update the Driver Station (DS) app on these +This page shows how to update the :term:`Driver Station` (DS) app on these devices: - REV Driver Hub @@ -20,7 +20,7 @@ of the programming language/environment used to program robot Team Code. Here are 3 methods to update the DS app on a REV Driver Hub: - #. REV Hardware Client (RHC) + #. :term:`REV Hardware Client` (RHC) #. "Side loading” with APK #. Software Manager on REV Driver Hub diff --git a/docs/source/ftc_sdk/updating/hardware_client/Updating-REV-Hardware-Client.rst b/docs/source/ftc_sdk/updating/hardware_client/Updating-REV-Hardware-Client.rst index 721af2237..d22f55da0 100644 --- a/docs/source/ftc_sdk/updating/hardware_client/Updating-REV-Hardware-Client.rst +++ b/docs/source/ftc_sdk/updating/hardware_client/Updating-REV-Hardware-Client.rst @@ -1,7 +1,7 @@ Installing and Updating the REV Hardware Client =============================================== -The REV Hardware Client is a desktop app, or software tool, that simplifies +The :term:`REV Hardware Client` is a desktop app, or software tool, that simplifies updating software on devices used in *FIRST* Tech Challenge. Unfortunately the REV Hardware Client is currently Windows-only, Apple/Mac users must use alternate methods of updating software. In this tutorial, some steps ask to @@ -49,7 +49,7 @@ Open the RHC app. This is a good time to **pre-download** various pieces of software you might need soon. Why download now? Later, this computer might be connected via Wi-Fi to a -Robot Controller, not to the internet. Or a good internet connection +:term:`Robot Controller`, not to the internet. Or a good internet connection might not be available when urgently needed (Murphy’s Law). Click on the Downloads tab (top left). Under “Available Files” is a list diff --git a/docs/source/ftc_sdk/updating/hub_firmware/Updating-Hub-Firmware.rst b/docs/source/ftc_sdk/updating/hub_firmware/Updating-Hub-Firmware.rst index 2f51b9b5a..eca0950d8 100644 --- a/docs/source/ftc_sdk/updating/hub_firmware/Updating-Hub-Firmware.rst +++ b/docs/source/ftc_sdk/updating/hub_firmware/Updating-Hub-Firmware.rst @@ -1,22 +1,22 @@ Updating Hub Firmware ===================== -Firmware is low-level software that controls a device’s circuit boards, or +:term:`Firmware` is low-level software that controls a device’s circuit boards, or electronic **hardware**. This must sometimes be updated on the REV Expansion -Hub and the REV Control Hub in order for the :doc:`Software Development Kit +Hub and the REV :term:`Control Hub` in order for the :doc:`Software Development Kit (SDK) ` to perform correctly. Here are 5 methods: -1. REV Hardware Client (RHC) -2. Driver Station app -3. Robot Controller (RC) app - on RC phone +1. :term:`REV Hardware Client` (RHC) +2. :term:`Driver Station` app +3. :term:`Robot Controller` (RC) app - on RC phone 4. Manage page on computer -5. Manage page on Driver Station device (DS phone or Driver Hub) +5. Manage page on Driver Station device (DS phone or :term:`Driver Hub`) .. dropdown:: Method 1 - REV Hardware Client (RHC) - Windows computers only - 1. For REV Control Hub, apply 12V robot power. For REV Expansion Hub, + 1. For REV Control Hub, apply 12V robot power. For REV :term:`Expansion Hub`, 12V power is optional. 2. Plug the REV Hub directly into a computer running the REV Hardware @@ -24,7 +24,7 @@ Here are 5 methods: port is Mini USB (not micro). On the Control Hub, use only the USB-C port, not its Mini USB port. - 3. Click the hub’s large icon/rectangle. Under “Expansion/Control Hub + 3. Click the :term:`hub `’s large icon/rectangle. Under “Expansion/Control Hub Firmware”, see the current/latest mismatch, if any (yellow oval, below). diff --git a/docs/source/ftc_sdk/updating/index.rst b/docs/source/ftc_sdk/updating/index.rst index bbf57ef79..50b79bb37 100644 --- a/docs/source/ftc_sdk/updating/index.rst +++ b/docs/source/ftc_sdk/updating/index.rst @@ -6,7 +6,7 @@ Updating Components of the Control System ========================================= -Certain components of the *FIRST* Tech Challenge Control System will +Certain components of the *FIRST* Tech Challenge :term:`Control System` will periodically receive updates. Teams should make sure to update each component of the Control System to the latest released version. diff --git a/docs/source/ftc_sdk/updating/rc_app/Updating-the-RC-App.rst b/docs/source/ftc_sdk/updating/rc_app/Updating-the-RC-App.rst index 7882ef49b..8f9681c37 100644 --- a/docs/source/ftc_sdk/updating/rc_app/Updating-the-RC-App.rst +++ b/docs/source/ftc_sdk/updating/rc_app/Updating-the-RC-App.rst @@ -1,13 +1,13 @@ Updating the Robot Controller (RC) App ====================================== -The Robot Controller App is one of the Apps provided with the *FIRST* Tech +The :term:`Robot Controller App` is one of the Apps provided with the *FIRST* Tech Challenge :doc:`Software Development Kit (SDK) `. The Robot Controller App is the application that runs on the Robot Controller Android -Device (REV Control Hub or an approved Android RC phone). This app -communicates with the Driver Station App to control the robot. +Device (REV :term:`Control Hub` or an approved Android RC phone). This app +communicates with the :term:`Driver Station App` to control the robot. -This page shows how to update the Robot Controller (RC) app on these +This page shows how to update the :term:`Robot Controller` (RC) app on these devices: - REV Control Hub @@ -19,8 +19,8 @@ Blocks / OnBot Java vs Android Studio Blocks / OnBot Java ^^^^^^^^^^^^^^^^^^^ -The Robot Controller (RC) App contains the programming environments for Blocks -and OnBot Java, and the User Programs (Team Code) developed using those +The Robot Controller (RC) App contains the programming environments for :term:`Blocks` +and :term:`OnBot Java`, and the User Programs (Team Code) developed using those environments are stored independently ALONGSIDE the RC App. This makes it possible to update the RC App independently without affecting Team Code. This incredibly simplifies updating the RC App software, since no *code* needs to be @@ -33,14 +33,14 @@ flexibility is still possible in this regard for advanced users. Android Studio ^^^^^^^^^^^^^^ -Android Studio, in general, works exactly the opposite. The FtcRobotController -repository (the Android Studio Project) contains the full source code needed to +:term:`Android Studio`, in general, works exactly the opposite. The FtcRobotController +repository (the :term:`Android Studio Project`) contains the full source code needed to build a complete RC App; when the Android Studio Project is compiled and deployed, it's actually building a complete Robot Controller App and installing it onto the RC Android device. Team Code **and** the Robot Controller code are compiled *together*, meaning the Team Code is embedded WITHIN the RC App and cannot be updated/edited independently of the RC App. If the Android -Studio-deployed RC App is replaced using the REV Hardware Client or similar +Studio-deployed RC App is replaced using the :term:`REV Hardware Client` or similar process, the RC App with the Team Code embedded is removed and replaced with the default RC App - so Android Studio users should NEVER update the RC App using anything but Android Studio! However, this can complicate upgrading and @@ -77,7 +77,7 @@ Expand the following instructions that apply to your Robot Controller hardware: #. REV Hardware Client (RHC) #. Manage page on computer - #. Manage page on DS phone or Driver Hub + #. Manage page on DS phone or :term:`Driver Hub` .. note:: “Side loading”, while possible, is not described here for the Control Hub @@ -212,7 +212,7 @@ Expand the following instructions that apply to your Robot Controller hardware: Now touch the “Update” button (green arrow, above). The software will replace the existing RC app with your new updated RC - app. The connection between Driver Station and Control Hub will + app. The connection between :term:`Driver Station` and Control Hub will temporarily be lost, then automatically restored. When the completion message appears, the updated RC app is ready to use. diff --git a/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst b/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst index 62bab12b2..b0accd314 100644 --- a/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst +++ b/docs/source/game_specific_resources/field_coordinate_system/field-coordinate-system.rst @@ -6,14 +6,14 @@ .. meta:: :description: This document defines the FIRST Tech Challenge Field Coordinate System which can be used to specify position on the playing field. -Summary: The *FIRST* Tech Challenge Field Coordinate System is a Cartesian Coordinate System of three dimensions. +Summary: The *FIRST* Tech Challenge :term:`Field Coordinate System` is a Cartesian Coordinate System of three dimensions. The X and Y axes will refer to a position on the field and the Z axis a height above the field. Scope ----- This document defines the Field Coordinate System -for a *FIRST* Tech Challenge playing field. This definition can be +for a *FIRST* Tech Challenge :term:`playing field `. This definition can be used for consistent field-centric navigation, target localization and path planning. @@ -21,7 +21,7 @@ Reference Frame --------------- The reference frame for this definition is the field perimeter wall, adjacent -to the red Alliance Area, known here after as the Red Wall. The definition is +to the red :term:`Alliance` Area, known here after as the Red Wall. The definition is from the perspective of a person, standing outside the field, in the center of Red Wall, looking towards the center of the field. @@ -156,7 +156,7 @@ Given the order of coordinates then X = -58.3727, Y = 55.6425, and Z = 29.5. * The Y axis value of 55.6425 would be located closer to the Blue Wall, about a 3/4 tile length from the Blue wall. * The Z axis value of 29.5 is 29.5 inches above the field tiles. -This set of coordinates is the center of the Red Goal AprilTag on the Red Goal. +This set of coordinates is the center of the Red Goal :term:`AprilTag` on the Red Goal. Measured Values --------------- @@ -185,7 +185,7 @@ The Field Coordinate System rotation convention comes from the `right hand rule `__ of classic geometry. -Robots with a webcam can use :ref:`AprilTags ` +Robots with a :term:`webcam ` can use :ref:`AprilTags ` to determine where an :ref:`AprilTag is located ` with respect to the robot. @@ -193,9 +193,9 @@ Since AprilTags are in known locations on the field, you can also determine the :ref:`location of the robot ` on the field. -Robots can use an inertial measurement unit (IMU) to measure rotations about axes +Robots can use an inertial measurement unit (:term:`IMU`) to measure rotations about axes with respect to the robot. See :ref:`IMU axes definition. ` -The yaw value from the IMU, also known the heading, measures rotation about the Z axis +The yaw value from the IMU, also known the :term:`heading `, measures rotation about the Z axis which points up from the robot. You can use the IMU to determine which direction a robot is facing. diff --git a/docs/source/game_specific_resources/ftcqa/ftcqa.rst b/docs/source/game_specific_resources/ftcqa/ftcqa.rst index e74795363..83621161b 100644 --- a/docs/source/game_specific_resources/ftcqa/ftcqa.rst +++ b/docs/source/game_specific_resources/ftcqa/ftcqa.rst @@ -8,7 +8,7 @@ FIRST Tech Challenge Game Q&A The `Game Q&A `_ is a forum/tool that provides teams an opportunity to receive clarifications from the Game Design Committee about the current season's challenge. Rulings on the Q&A are final -and binding, and will be reflected in the Competition Manual. +and binding, and will be reflected in the :term:`Competition Manual`. How to Ask Questions ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst b/docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst index 841cbca4a..a88b29394 100644 --- a/docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst +++ b/docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst @@ -9,8 +9,8 @@ Playing Field Resources About the Playing Field ----------------------- -There are multiple configurations of the playing field that can be used. For traditional games, the playing field is a part of the Arena that includes the 12 ft. x 12 ft. (3.66 m x 3.66 m) field and all -the elements described in the official field drawings. The base field stays the same for all games but the game elements are subject to change as per the Competition Manual. +There are multiple configurations of the :term:`playing field ` that can be used. For traditional games, the playing field is a part of the Arena that includes the 12 ft. x 12 ft. (3.66 m x 3.66 m) field and all +the elements described in the official field drawings. The base field stays the same for all games but the game elements are subject to change as per the :term:`Competition Manual`. The Competition Manual contains an Arena section that details the playing field for that years game. It includes measurements for key aspects of the field and game elements and scoring elements. @@ -31,8 +31,8 @@ The guide typically has the following sections: - Lists all the game elements and scoring elements with the quantity of each. - Instructions for setup of the field perimeter and field tiles. - Step by step instructions for assembling parts and setting them on the field. -- Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the Alliances, and sometimes for game areas. -- Most games have AprilTags placed around the field that can be used for robot navigation. +- Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the :term:`Alliances `, and sometimes for game areas. +- Most games have :term:`AprilTags ` placed around the field that can be used for robot navigation. - Finally, there are teardown instructions that indicate how to take the field down for storage or transport. Use the following button link to download a PDF of the current Field Setup Guide from the *FIRST* Website: @@ -48,4 +48,4 @@ Use the following button link to download a PDF of the current Field Setup Guide want official game elements but don't have room to setup a full field. The `Game and Season Materials page `_ also contains a downloadable PDF for the AprilTag images that can be printed and placed on the field. -There is a Do It Yourself (DIY) Resources section that includes CAD models of scoring elements and DIY field and perimeter build guides. +There is a Do It Yourself (DIY) Resources section that includes :term:`CAD` models of scoring elements and DIY field and perimeter build guides. diff --git a/docs/source/glossary/glossary.rst b/docs/source/glossary/glossary.rst new file mode 100644 index 000000000..987ca8704 --- /dev/null +++ b/docs/source/glossary/glossary.rst @@ -0,0 +1,523 @@ +.. meta:: + :title: FIRST Tech Challenge Glossary + :description: Definitions of the hardware, software, programming and competition terms used throughout FIRST Tech Challenge documentation. + :keywords: FTC Docs, FIRST Tech Challenge, FTC, Glossary, Terminology, Definitions + +.. _glossary: + +Glossary +======== + +This page collects the terms used throughout *FIRST* Tech Challenge documentation. +Terms are listed alphabetically. Throughout the rest of this site, the first +mention of any of these terms on a page links back here, so you can check a +definition without losing your place. Hover a term link to read its definition +in place. + +.. note:: + + Game-specific vocabulary (scoring elements, field features, award names and + the like) changes every season and is defined in the + :doc:`Competition Manual ` rather than + here. Where a rule and this glossary disagree, the Competition Manual wins. + +.. glossary:: + :sorted: + + ADB + Android Debug Bridge + A command-line tool, included with the Android platform tools, that lets a + computer communicate with an Android device. Teams most often meet it + indirectly: :term:`Android Studio` uses it to install the + :term:`Robot Controller App` onto a :term:`Control Hub` or phone, either + over USB or over the wireless network. + + Alliance + The pair of teams that play a :term:`Match` together, either as the red + Alliance or the blue Alliance. Alliance partners share a score. + + Analog Input + A :term:`Hub` port that measures a continuous voltage rather than a simple + on/off state. Used by sensors such as a :term:`Potentiometer` that report + their reading as a voltage level. + + Android Studio + Google's integrated development environment (:term:`IDE`) for Android + apps. It is the most powerful of the three *FIRST* Tech Challenge + programming tools: teams work from the ``FtcRobotController`` + :term:`Android Studio Project` on a laptop and build a customized + :term:`Robot Controller App`, which gives access to version control, + :term:`External Libraries` and a full debugger. + See :doc:`/programming_resources/android_studio_java/Android-Studio-Tutorial`. + + Android Studio Project + The ``FtcRobotController`` project published with each :term:`SDK` + release. It contains the source of the :term:`Robot Controller App` plus a + ``TeamCode`` module that teams add their own :term:`OpMode` classes to. + + AprilTag + A fiducial marker — a square, high-contrast pattern, similar in spirit to a + QR code but far simpler — developed at the University of Michigan. Because + the physical size of a tag is known, detecting one in a camera image yields + both its identity and its position and orientation relative to the camera. + *FIRST* Tech Challenge places AprilTags on the :term:`Playing Field` so + robots can locate themselves. See + :doc:`/apriltag/vision_portal/apriltag_intro/apriltag-intro`. + + AUTO + Autonomous + The first phase of a :term:`Match`, during which the robot runs a + pre-written :term:`OpMode` with no human input. Contrast with + :term:`TELEOP`. + + Battery + The 12V rechargeable battery that powers the :term:`Control Hub`, + :term:`Expansion Hub`, motors, servos and sensors. The *FIRST* Tech + Challenge battery has a 20A :term:`Fuse` built into its lead. + See :doc:`/control_hard_compon/rc_components/power_distr/power-distr`. + + Blocks + Blocks Programming Tool + The visual, drag-and-drop programming tool built into the + :term:`Robot Controller App`. Teams connect colored blocks in a web + browser to build an :term:`OpMode`, with no typing of Java required. It is + the recommended starting point for new teams. + See :doc:`/programming_resources/blocks/Blocks-Tutorial`. + + CAD + Computer Aided Design + Software used to design parts and assemblies in three dimensions before + they are built. CAD models feed :term:`3D Printing`, :term:`CNC` machining + and laser cutting, and let a team check that a mechanism fits before + cutting metal. See :doc:`/cad_resources/index`. + + CNC + Computer Numerical Control + Machining in which a computer drives the cutting tool from a digital + model, rather than a human turning handwheels. Mills, routers and lathes + are all available in CNC form. + See :doc:`/manufacturing/index`. + + Competition Manual + The official rule book for the season, published by *FIRST*. It defines + the game, the :term:`Playing Field`, robot construction rules, + :term:`Inspection` requirements and tournament procedure, and it supersedes + anything written on this site. + See :doc:`/manuals/game_manuals/game_manuals`. + + Configuration File + Robot Configuration + A file stored on the :term:`Robot Controller` that lists every motor, + servo and sensor attached to the robot, which port each one is plugged + into, and the name a program should use to refer to it. An :term:`OpMode` + looks up devices from this file through :term:`hardwareMap`, so a name + typed in code must match the configuration exactly. + See :doc:`/hardware_and_software_configuration/configuring/index`. + + Continuous Rotation Servo + A :term:`Servo` modified to spin continuously in either direction instead + of holding a commanded angle. Its power setting controls speed and + direction, much like a small :term:`DC Motor`, but it has no position + feedback. + + Control Hub + The REV Robotics Control Hub: an Android-based device that combines a + :term:`Robot Controller` and a :term:`Hub` in one package. It runs the + :term:`Robot Controller App`, provides the motor, servo and sensor ports, + and creates the wireless network the :term:`Driver Station` connects to. + See :doc:`/control_hard_compon/rc_components/index`. + + Control System + The collective name for the electronics and software that make a robot + run: the :term:`Driver Station`, the :term:`Robot Controller`, the + :term:`Hub` hardware, and the :term:`SDK` software on both ends. + See :doc:`/programming_resources/shared/control_system_intro/The-FTC-Control-System`. + + DC Motor + A motor that turns continuously when voltage is applied to it, used for + drivetrains, lifts and intakes. Competition motors are supplied as a motor + plus a gearbox and usually an :term:`Encoder`, and connect to a + :term:`Hub` motor port. + See :doc:`/control_hard_compon/rc_components/motors/motors`. + + Dead Wheel + An unpowered wheel, fitted with an :term:`Encoder`, that rolls along the + floor purely to measure how far the robot has traveled. Because it is not + driven, it does not slip under load the way a drive wheel does, which makes + it a more trustworthy source for :term:`Odometry`. + + Digital I/O + A :term:`Hub` port that reads or writes a simple on/off signal. Used by + devices such as a :term:`Touch Sensor` or an indicator LED. + + Driver Hub + The REV Robotics Driver Hub: a purpose-built Android device with a screen + and USB ports that runs the :term:`Driver Station App`. It is the most + common :term:`Driver Station` hardware. + See :doc:`/control_hard_compon/ds_components/index`. + + Driver Station + DS + The Android device that sits with the drivers and acts as the robot's + remote control. It runs the :term:`Driver Station App`, has one or two + :term:`Gamepad` controllers attached, and communicates with the + :term:`Robot Controller` over a wireless link. The :term:`Driver Hub` is + the officially supported Driver Station. An Android phone also works and + is legal to use in competition, but is not officially supported. + + Driver Station App + The *FIRST* Tech Challenge app that runs on the :term:`Driver Station`. + It selects and starts :term:`OpMode` programs, displays + :term:`Telemetry`, forwards :term:`Gamepad` input to the robot, and hosts + :term:`Self-Inspect` and the :term:`Configuration File` editor. + + EasyOpenCV + A community-maintained library that made it straightforward to run + :term:`OpenCV` vision pipelines on a camera stream in older versions of + the :term:`SDK`. Newer code should generally use :term:`VisionPortal` + instead, which provides equivalent camera handling in the SDK itself. + + Encoder + A sensor built into or attached to a motor that counts shaft rotation, + reporting position in "ticks" and allowing speed to be measured. Encoders + are what make it possible to drive a known distance or hold an arm at a + known angle. See + :doc:`/control_hard_compon/rc_components/encoders/encoders`. + + End Game + The final portion of :term:`TELEOP` in which additional scoring + opportunities open up. What counts as End Game scoring is defined each + season in the :term:`Competition Manual`. + + ESD + Electrostatic Discharge + The sudden flow of static electricity between two objects at different + potentials — the spark you feel after walking across a carpet. On a robot + it can reset or damage the :term:`Control Hub` and is a common cause of + unexplained disconnections. + See :doc:`/hardware_and_software_configuration/configuring/managing_esd/managing-esd`. + + Expansion Hub + The REV Robotics Expansion Hub: a :term:`Hub` that adds a second set of + motor, servo and sensor ports to a robot. It has no Android device inside, + so it must be paired with a :term:`Control Hub` or a phone acting as the + :term:`Robot Controller`. + + External Libraries + Third-party code added to a team's project to provide functionality the + :term:`SDK` does not. Libraries can be added as ``.aar``/``.jar`` files in + :term:`OnBot Java`, or as Gradle dependencies in + :term:`Android Studio`. + + Field Coordinate System + The convention *FIRST* Tech Challenge uses to describe positions and + headings on the :term:`Playing Field`, so that a robot's location can be + expressed as X, Y and heading values that everyone interprets the same way. + See :doc:`/game_specific_resources/field_coordinate_system/field-coordinate-system`. + + FIRST + *For Inspiration and Recognition of Science and Technology*: the + non-profit organization that runs *FIRST* Tech Challenge along with its + other robotics programs. + See :doc:`/overview/ftcoverview`. + + Firmware + The low-level software running on a :term:`Hub`'s own microcontroller, as + distinct from the Android operating system or the + :term:`Robot Controller App`. Hub firmware occasionally needs updating to + stay compatible with a new :term:`SDK`. + See :doc:`/ftc_sdk/updating/hub_firmware/Updating-Hub-Firmware`. + + FTC Docs + This documentation site, at + `ftc-docs.firstinspires.org `__. It + is written and maintained by the *FIRST* Tech Challenge community; see + :doc:`/contrib/index` if you would like to contribute. + + Fuse + A deliberately weak link in a circuit that melts and breaks the connection + if too much current flows, protecting everything downstream. The *FIRST* + Tech Challenge :term:`Battery` carries a 20A automotive-style fuse in its + lead. + + Gamepad + A game controller, connected to the :term:`Driver Station` by USB, that a + driver uses to command the robot during :term:`TELEOP`. An :term:`OpMode` + reads its buttons and joysticks through the ``gamepad1`` and ``gamepad2`` + objects. + + Gear Ratio + The ratio between the rotation of an input shaft and an output shaft in a + gearbox or belt drive. Gearing down trades speed for torque; gearing up + does the reverse. A motor's stated gear ratio must be accounted for when + converting :term:`Encoder` ticks into real-world distance. + + Gracious Professionalism + A core *FIRST* value: competing hard, while treating opponents, + volunteers and teammates with respect, and helping others succeed even at + a cost to yourself. + See :doc:`/gracious_professionalism/gp`. + + hardwareMap + The object available inside every :term:`OpMode` that looks up a physical + device by the name given to it in the :term:`Configuration File`, for + example ``hardwareMap.get(DcMotor.class, "left_drive")``. It is the bridge + between a program and the robot's wiring. + + Heading + The direction the robot is facing, measured as an angle within the + :term:`Field Coordinate System`. Usually obtained from the :term:`IMU` or + from :term:`Odometry`. + + Hub + Shorthand for a :term:`Control Hub` or an :term:`Expansion Hub` — the + electronic input/output module that lets the + :term:`Robot Controller` talk to motors, servos and sensors. + See :doc:`/control_hard_compon/rc_components/hub/hub`. + + I2C + A two-wire communication bus used by many sensors, including the + :term:`IMU` and most color and distance sensors. Several devices can share + one bus, but each needs a distinct address, so identical sensors normally + go on separate :term:`Hub` I2C buses. + + IDE + Integrated Development Environment + An application that combines a code editor, a compiler and a debugger in + one place. :term:`Android Studio` is the IDE used for *FIRST* Tech + Challenge Java development. + + IMU + Inertial Measurement Unit + A sensor that measures rotation and acceleration, and so can report the + robot's :term:`Heading`. An IMU is built into every :term:`Control Hub` + and :term:`Expansion Hub`, and external IMUs are also available. + See :doc:`/programming_resources/imu/imu`. + + Inspection + The pre-competition check that a robot and its software meet the rules in + the :term:`Competition Manual`. :term:`Self-Inspect` in the + :term:`Driver Station App` covers the software half in advance. + See :doc:`/hardware_and_software_configuration/self_inspect/self-inspect`. + + Iterative OpMode + An :term:`OpMode` written by overriding the ``init``, ``loop`` and ``stop`` + methods of the ``OpMode`` class. The :term:`SDK` calls ``loop`` repeatedly + for you. Contrast with :term:`LinearOpMode`. + + Javadoc + Reference documentation generated from comments in the :term:`SDK` source + code, describing every class and method available to an :term:`OpMode`. + Published at `javadoc.io `__. + + Judging + The interview and evaluation process at a tournament through which teams + are considered for awards, separate from :term:`Match` play. + + LinearOpMode + An :term:`OpMode` written as a single ``runOpMode`` method that executes + top to bottom, pausing at ``waitForStart()``. This style suits + :term:`AUTO` programs, where steps happen in sequence. Contrast with + :term:`Iterative OpMode`. + + Match + One playing of the game between two :term:`Alliance` pairs, consisting of + an :term:`AUTO` phase followed by a :term:`TELEOP` phase. + + Mecanum + Mecanum Drive + A drivetrain using wheels with rollers set at 45° around the rim. By + driving the four wheels at different speeds the robot can move sideways + and rotate without turning first — often called holonomic or + omnidirectional movement. + + Odometry + Estimating how far the robot has moved, and where it now is, by + accumulating :term:`Encoder` readings over time. Accuracy depends on wheels + not slipping, which is why :term:`Dead Wheel` pods are popular. + + OnBot Java + OnBot Java Programming Tool + A text-based Java editor built into the :term:`Robot Controller App` and + used from a web browser. Code is compiled on the robot itself, so no + laptop toolchain is needed — a middle step between :term:`Blocks` and + :term:`Android Studio`. + See :doc:`/programming_resources/onbot_java/OnBot-Java-Tutorial`. + + OpMode + Op Mode + Operational Mode + A program that defines part of a robot's behavior, written by the team and + run on the :term:`Robot Controller`. OpModes are selected and started from + the :term:`Driver Station`, and are declared as either :term:`AUTO` or + :term:`TELEOP`. Each one is written as a :term:`LinearOpMode` or an + :term:`Iterative OpMode`. + See :doc:`/programming_resources/index`. + + OpenCV + An open-source computer vision library, bundled with the :term:`SDK`, that + provides the image-processing building blocks — color conversion, + thresholding, contour finding — used to detect objects in a camera frame. + See :doc:`/color_processing/index`. + + OTG Adapter + A small "USB On-The-Go" adapter that lets an Android phone act as a USB + host, so that a :term:`Gamepad`, :term:`USB Hub` or + :term:`Expansion Hub` can be plugged into it. + + PIDF + A control algorithm — Proportional, Integral, Derivative, Feedforward — + that adjusts motor power based on the difference between a target and the + measured :term:`Encoder` value. The :term:`SDK` uses PIDF internally for + motor velocity control, and its coefficients can be tuned. + + Playing Field + The 12ft × 12ft tiled area, enclosed by field walls, on which a + :term:`Match` is played. Its layout, including + :term:`AprilTag` placement, changes each season. + See :doc:`/game_specific_resources/playing_field_resources/playing_field_resources`. + + Potentiometer + A sensor whose resistance varies with the position of a knob or shaft, + read through an :term:`Analog Input`. Useful for measuring the angle of an + arm across a limited range. + + PWM + Pulse Width Modulation + A technique for controlling how much power reaches a device by switching + it on and off very rapidly and varying the fraction of time it spends on. + :term:`Servo` position commands are sent as PWM signals. + + Referee + The volunteer who enforces the rules of the :term:`Competition Manual` + during a :term:`Match` and determines the final score. + + REV Hardware Client + A Windows application from REV Robotics that updates the + :term:`Firmware`, operating system and apps on a :term:`Control Hub`, + :term:`Expansion Hub` or :term:`Driver Hub` over USB. It is the + recommended way to keep hardware current. + See :doc:`/ftc_sdk/updating/hardware_client/Updating-REV-Hardware-Client`. + + Robot Controller + RC + The Android device mounted on the robot that runs the team's + :term:`OpMode` programs — the "brains" of the robot. The + :term:`Control Hub` is the officially supported Robot Controller. An + Android phone paired with an :term:`Expansion Hub` also works and is + legal to use in competition, but is not officially supported. + + Robot Controller App + The *FIRST* Tech Challenge app that runs on the + :term:`Robot Controller`. It executes :term:`OpMode` programs, manages the + :term:`Configuration File`, and serves the :term:`Blocks` and + :term:`OnBot Java` programming tools to a web browser. + + Sample OpMode + One of the ready-made example :term:`OpMode` programs shipped with the + :term:`SDK`, found in the ``samples`` folder in + :term:`Android Studio` or offered as a template in :term:`OnBot Java` and + :term:`Blocks`. Samples are the fastest way to see a working example of a + given sensor or technique. + + Scrimmage + An informal practice competition, not part of the official tournament + structure, where teams play :term:`Match` games to test robots and gain + experience. + + SDK + Software Development Kit + The collection of *FIRST* Tech Challenge software tools: the + :term:`Robot Controller App`, the :term:`Driver Station App`, the + :term:`Android Studio Project`, the :term:`Javadoc` reference, and the + season-specific assets. A new SDK is released each season. + See :doc:`/ftc_sdk/overview/index`. + + Self-Inspect + A screen in the :term:`Driver Station App` that checks the app versions, + operating system versions and :term:`Firmware` on both the + :term:`Driver Station` and the :term:`Robot Controller`, and reports + whether they satisfy the requirements for competition. + See :doc:`/hardware_and_software_configuration/self_inspect/new-self-inspect`. + + Sensor + Any device that reports information about the robot or its surroundings — + touch, distance, color, rotation — to the :term:`Robot Controller`. + Sensors attach to :term:`Digital I/O`, :term:`Analog Input` or + :term:`I2C` ports on a :term:`Hub`. + See :doc:`/control_hard_compon/rc_components/sensors/sensors`. + + Servo + A motor that rotates to and holds a commanded position, typically over a + limited range. Servos plug into dedicated :term:`Servo` ports on a + :term:`Hub` and are commanded by position rather than power. See also + :term:`Continuous Rotation Servo` and + :doc:`/control_hard_compon/rc_components/servos/servos`. + + TELEOP + Driver-Controlled Period + The phase of a :term:`Match` after :term:`AUTO`, in which up to two human + drivers control the robot using :term:`Gamepad` controllers connected to + the :term:`Driver Station`. + + Telemetry + Data sent from an :term:`OpMode` on the :term:`Robot Controller` to the + :term:`Driver Station` screen, where it appears as lines of text. + Telemetry is the primary way to see what a program is doing, and is + therefore the primary debugging tool. + + TensorFlow + TFOD + TensorFlow Object Detection + A machine-learning framework used to recognize objects in a camera image + from a trained model. The :term:`SDK` ships a TFOD processor that can be + run through :term:`VisionPortal`, along with season-specific models. + + Touch Sensor + A simple switch that reports whether it is pressed, read through a + :term:`Digital I/O` port. Commonly used as a limit switch to tell a + mechanism it has reached the end of its travel. + + Tournament + An official *FIRST* Tech Challenge event at which teams compete in + :term:`Match` play and take part in :term:`Judging`. + + USB Hub + A powered or unpowered splitter that provides extra USB ports. Needed when + a :term:`Driver Station` phone must host two :term:`Gamepad` controllers + at once, in which case it connects through an :term:`OTG Adapter`. + + VisionPortal + The :term:`SDK` camera API. A VisionPortal opens a camera — a webcam or a + phone's built-in camera — and feeds each frame to one or more vision + processors, such as the :term:`AprilTag` or :term:`TFOD` processors, or a + team's own :term:`OpenCV` pipeline. + See :doc:`/apriltag/vision_portal/visionportal_overview/visionportal-overview`. + + Volunteer + Anyone who gives their time to run a *FIRST* Tech Challenge event — + :term:`Referee`, judge, inspector, queuer, scorekeeper and many more roles. + Events cannot happen without them. + + Vuforia + An image-target tracking library used in earlier seasons to locate the + robot from printed picture targets on the field. It has been superseded by + :term:`AprilTag` detection through :term:`VisionPortal`. + + Webcam + A USB camera plugged into a :term:`Control Hub` or + :term:`Robot Controller` phone and used for vision. Only cameras + supporting the USB Video Class (UVC) standard work. + See :doc:`/apriltag/vision_portal/visionportal_webcams/visionportal-webcams`. + + Wi-Fi Direct + A peer-to-peer wireless standard that lets two devices connect without a + router. It is how a :term:`Driver Station` phone pairs with a + :term:`Robot Controller` phone. A :term:`Control Hub` instead creates its + own wireless network for the Driver Station to join. + + 3D Printing + Building a part by depositing or curing material layer by layer from a + :term:`CAD` model. The most common form in *FIRST* Tech Challenge is + Fused Deposition Modeling (FDM), which extrudes melted plastic filament. + See :doc:`/manufacturing/3d_printing/index`. diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_color_sensor/configuring-color-sensor.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_color_sensor/configuring-color-sensor.rst index 0823fd68b..a723a3660 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_color_sensor/configuring-color-sensor.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_color_sensor/configuring-color-sensor.rst @@ -1,7 +1,7 @@ Configuring a Color Distance Sensor ===================================== -The REV Robotics Color Distance Sensor is an I2C sensor. It actually +The REV Robotics Color Distance :term:`Sensor` is an :term:`I2C` sensor. It actually combines two sensor functions into a single device. It is a color sensor, that can determine the color of an object. It is also a distance or range sensor, that can be used to measure short range distances. Note @@ -19,11 +19,11 @@ configuration screen for this I2C bus. | -The Control Hub or Expansion Hub has four independent I2C buses, labeled "0" through "3". In this example, since you connected the Color Sensor to the port labeled "0", it resides on I2C Bus 0. +The :term:`Control Hub` or :term:`Expansion Hub` has four independent I2C buses, labeled "0" through "3". In this example, since you connected the Color Sensor to the port labeled "0", it resides on I2C Bus 0. 2. Look at the **I2C Bus 0** screen. There should already be a sensor configured for this bus. The Control Hub or Expansion Hub has its own built-in -inertial measurement unit (IMU) sensor. This sensor can be used to +inertial measurement unit (:term:`IMU`) sensor. This sensor can be used to determine the orientation of a robot, as well as measure the accelerations on a robot. @@ -32,7 +32,7 @@ accelerations on a robot. | -The built-in IMU is internally connected to I2C Bus 0 on each Control Hub or Expansion Hub. Whenever you configure a Control Hub or Expansion Hub using the Robot Controller, the app automatically configures the IMU for I2C Bus 0. You will need to add another I2C device for this bus to be able to configure the color sensor. +The built-in IMU is internally connected to I2C Bus 0 on each Control Hub or Expansion Hub. Whenever you configure a Control Hub or Expansion Hub using the :term:`Robot Controller`, the app automatically configures the IMU for I2C Bus 0. You will need to add another I2C device for this bus to be able to configure the color sensor. 3. Press the **Add** button to add another I2C device to this bus. diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_dc_motor/configuring-dc-motor.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_dc_motor/configuring-dc-motor.rst index f04fed9e6..e65c3e795 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_dc_motor/configuring-dc-motor.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_dc_motor/configuring-dc-motor.rst @@ -1,8 +1,8 @@ Configuring a DC Motor ======================= -Now that you've created a file, you will need to add a DC Motor to the -configuration file. +Now that you've created a file, you will need to add a :term:`DC Motor` to the +:term:`configuration file `. .. important:: At this point, although you have created your configuration file, you have not yet saved its contents to the Robot Controller. You will save the configuration file later in the :ref:`Saving the Configuration Information ` step. @@ -17,7 +17,7 @@ Configuration screen. | -2. Since we installed our motor onto port #0 of the Expansion Hub, +2. Since we installed our motor onto port #0 of the :term:`Expansion Hub`, use the dropdown control for port 0 to select the motor type (Tetrix Motor for this example). diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_digital_touch_sensor/configuring-digital-touch-sensor.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_digital_touch_sensor/configuring-digital-touch-sensor.rst index 0d63fcdeb..1451cc821 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_digital_touch_sensor/configuring-digital-touch-sensor.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_digital_touch_sensor/configuring-digital-touch-sensor.rst @@ -1,14 +1,14 @@ Configuring a Digital Touch Sensor ================================== -The REV Robotics Touch Sensor is a digital sensor. An Op Mode can query +The REV Robotics :term:`Touch Sensor` is a digital :term:`sensor `. An :term:`Op Mode ` can query the Touch Sensor to see if its button is being pressed or not. Configuring a Digital Touch Sensor Instructions ----------------------------------------------- 1. Touch the words **Digital Devices** on the screen to launch the -Digital I/O configuration screen. +:term:`Digital I/O` configuration screen. .. image:: images/ConfiguringHardwareTouchStep1.jpg :align: center diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_dual_hubs/configuring-dual-hubs.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_dual_hubs/configuring-dual-hubs.rst index 8b9016eaa..5ea94ed50 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_dual_hubs/configuring-dual-hubs.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_dual_hubs/configuring-dual-hubs.rst @@ -4,15 +4,15 @@ Adding an Expansion Hub Introduction ~~~~~~~~~~~~ -A single REV Robotics Control or Expansion Hub has a limited amount of input/output +A single REV Robotics Control or :term:`Expansion Hub` has a limited amount of input/output (I/O) ports available. In some instances, you might want to use more devices than there are ports available. For these instances you might -need to connect an Expansion Hub to your first Hub to add more I/O +need to connect an Expansion Hub to your first :term:`Hub` to add more I/O ports. This document describes how to connect and configure an additional Expansion Hub for use in the FIRST Tech Challenge. Note that the FIRST Tech Challenge -Competition Manual limits the maximum number of Control or Expansion Hubs on +:term:`Competition Manual` limits the maximum number of Control or Expansion Hubs on a single robot to two. Equipment Needed @@ -29,7 +29,7 @@ need the following items: * - Required Item(s) - Image - * - REV Robotics Driver Hub (REV-31-1596) + * - REV Robotics :term:`Driver Hub` (REV-31-1596) - .. figure:: images/driverHub.jpg * - REV Robotics Switch, Cable, & Bracket (REV-31-1387). @@ -38,11 +38,11 @@ need the following items: * - REV Robotics Tamiya to XT30 Adapter Cable (REV-31-1382). - .. figure:: images/TamiyaAdapter.jpg - * - FIRST-approved 12V Battery (such as Tetrix W39057). For a list of + * - FIRST-approved 12V :term:`Battery` (such as Tetrix W39057). For a list of FIRST-approved 12V batteries, refer to the current Competition Manual. - .. figure:: images/Battery.jpg - * - REV Robotics Control Hub (REV-31-1595). + * - REV Robotics :term:`Control Hub` (REV-31-1595). - .. figure:: images/controlHub.jpg * - REV Robotics Expansion Hub (REV-31-1153). @@ -89,7 +89,7 @@ Configuring Both devices ~~~~~~~~~~~~~~~~~~~~~~~~ If you successfully daisy chained your Expansion Hub and Control Hub, -then you should be able to create a new configuration file that includes +then you should be able to create a new :term:`configuration file ` that includes both devices. **Note:** If you already have a configuration that contains just the @@ -97,9 +97,9 @@ Control Hub, you can add the Expansion Hub by editing the configuration and pressing the "Scan" button. Connect your Driver Hub to the Control Hub's WiFi network and select the -Configure Robot option from the Driver Station app. Press the New button +Configure Robot option from the :term:`Driver Station` app. Press the New button to create a new configuration file. When you first scan for hardware, your -Robot Controller should detect the embedded Control Hub. The Robot Controller +:term:`Robot Controller` should detect the embedded Control Hub. The Robot Controller will automatically label this device as an Control Hub “Portal”. The Robot Controller will communicate through this portal to the individual Hubs. @@ -147,7 +147,7 @@ using a Control Hub on their robot. * - USB Type A male to type mini-B male cable. - .. figure:: images/USBTypeACable.jpg - * - Micro USB OTG adapter. + * - Micro USB :term:`OTG adapter `. - .. figure:: images/OTGAdapter.jpg * - An additional REV Robotics Expansion Hub (REV-31-1153). @@ -156,7 +156,7 @@ using a Control Hub on their robot. Changing the Address of an Expansion Hub ---------------------------------------- -You can use the Advanced Settings menu of the Robot Controller App +You can use the Advanced Settings menu of the :term:`Robot Controller App` to change the address of any connected Expansion Hubs. **Important Note:** If both of your Expansion Hubs have the same address 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 8c09a3545..f840b0b92 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 @@ -4,10 +4,10 @@ Configuring an External Webcam with a Control Hub Introduction ------------ -The Competition Manual allows the use of USB Video Class (UVC) compatible +The :term:`Competition Manual` allows the use of USB Video Class (UVC) compatible 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 +If you are using a REV Robotics :term:`Control Hub`, then +you will need to use an external :term:`webcam `, since the Control Hub does not include a built-in camera. This document describes how to connect, configure and use an external webcam with a Control Hub. @@ -37,8 +37,8 @@ Connecting the Camera --------------------- 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. +Hub. Unlike the REV :term:`Expansion Hub`, there is no need for an external +powered :term:`USB hub `. .. image:: images/USB-camera-Control-Hub.jpg :alt: Control Hub with UVC camera connected. @@ -48,7 +48,7 @@ powered USB hub. 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). + Using the USB 2.0 Port may cause :term:`ESD` to affect your Control Hub's Wi-Fi Chip (causing Wi-Fi disconnects with the driver :term:`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`_. @@ -57,7 +57,7 @@ Camera Configuration -------------------- Before using the external camera, it must be added to the active -configuration file as a USB-connected device. +:term:`configuration file ` as a USB-connected device. Use the Configure Robot menu item on the paired DRIVER STATION device to add the webcam as a USB-connected device to an existing or newly created @@ -68,7 +68,7 @@ activity should detect the webcam and give it a default name of “Webcam .. 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) +You can keep this default name (the sample :term:`Op Modes ` reference this name) or change it. If you change the webcam name, make sure your Op Modes refer to this new name. @@ -78,8 +78,8 @@ Sample Op Modes When the configuration has been saved and activated, the external UVC camera can be programmed for robot vision tasks. -The SDK software offers “webcam” versions of its sample Blocks and Java -Op Modes, showing how to use the external UVC camera for VisionPortal operations. +The SDK software offers “webcam” versions of its sample :term:`Blocks` and Java +Op Modes, showing how to use the external UVC camera for :term:`VisionPortal` operations. .. image:: images/blockswebcam.png :alt: Blocks code for initializing a webcam. @@ -140,7 +140,7 @@ 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. +you will first need to obtain an :term:`ADB` connection with your Control Hub. 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 `__. @@ -153,7 +153,7 @@ to install and run scrcpy on your computer. .. warning:: While scrcpy is a great way to view the camera output, the Competition Manual does not allow teams to have any devices other than the DRIVER STATION connected to your Control - Hub during a match. + Hub during a :term:`match `. External HDMI Monitor --------------------- @@ -172,7 +172,7 @@ device plugged into the HDMI port on the REV Control Hub. Advanced Users -------------- -For custom streams, advanced users of Android Studio may consult the +For custom streams, advanced users of :term:`Android Studio` may consult the `API documentation `__ for `CameraStreamClient `__, `CameraStreamServer `__ @@ -196,7 +196,7 @@ This avoid the ESD issue with devices on the USB 2.0 port. 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. +By adding a powered USB hub the Limelight will not drain your robot's :term:`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. @@ -217,7 +217,7 @@ It has a USB C port that can supply power to all connected devices. A powerbank is connected to the USB C port on the USB hub to supply power to the connected devices. Two Logitech C920 webcams are connected to the USB hub. -See the `AprilTag Switchable Cameras `_ sample program that demonstrates swapping between the two cameras to detect AprilTags. +See the `AprilTag Switchable Cameras `_ sample program that demonstrates swapping between the two cameras to detect :term:`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. diff --git a/docs/source/hardware_and_software_configuration/configuring/configuring_servo/configuring-servo.rst b/docs/source/hardware_and_software_configuration/configuring/configuring_servo/configuring-servo.rst index cecf8e92f..345015948 100644 --- a/docs/source/hardware_and_software_configuration/configuring/configuring_servo/configuring-servo.rst +++ b/docs/source/hardware_and_software_configuration/configuring/configuring_servo/configuring-servo.rst @@ -1,7 +1,7 @@ Configuring a Servo ==================== -You will also want to add a servo to the configuration file. In this +You will also want to add a :term:`servo ` to the :term:`configuration file `. In this example, you are using a standard 180-degree servo. 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 212fdbe18..07b6f1f07 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 @@ -4,7 +4,7 @@ Configuring an External UVC Camera and a Powered USB Hub Introduction ------------ -The Competition Manual allows the use of USB Video Class (UVC) compatible +The :term:`Competition Manual` allows the use of USB Video Class (UVC) compatible 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 @@ -12,7 +12,7 @@ for computer vision tasks. The advantage of using an external camera is that the camera can be mounted in a location that is convenient for vision-related tasks while -the Android Robot Controller can be mounted where it is convenient for +the Android :term:`Robot Controller` can be mounted where it is convenient for Robot Controller-related tasks. The disadvantage of using an external camera is there is additional @@ -29,7 +29,7 @@ the system. However, there are a couple of recommended web cameras that 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 :term:`Webcam` C310 - Logitech HD Pro Webcam C920 There are notes on :doc:`other UVC webcams <../../../apriltag/vision_portal/visionportal_webcams/visionportal-webcams>` @@ -45,7 +45,7 @@ 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. +For teams using an Android phone and an :term:`Expansion Hub` you are required to add a :term:`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. @@ -58,7 +58,7 @@ 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. Note: a USB 3.0 hub will still work, just not at the faster speed. +1. Compatible with USB 2.0. Note: a USB 3.0 :term:`hub ` will still work, just not at the faster speed. 2. Supports a data transfer rate of 480Mbps. Note that the Competition Manual permits the use of a powered USB @@ -113,7 +113,7 @@ and on the other end can be plugged into the power port of the USB hub. The USB hub is connected to the 5V Auxiliary port. -Note that teams can create this special cable using one end of a servo +Note that teams can create this special cable using one end of a :term:`servo ` extension cable (to plug into the 5V aux port) and one end of a Micro USB cable (to plug into the Anker hub’s power port). **Creating this cable is an advanced task and should only be attempted by teams who have @@ -125,9 +125,9 @@ electronic equipment.** Sample Op Modes ^^^^^^^^^^^^^^^ -There are sample Blocks and Java Op Modes that demonstrate how to use -the external UVC web camera for VisionPortal operations. Before -a team can use the external UVC camera, a configuration file must be +There are sample :term:`Blocks` and Java :term:`Op Modes ` that demonstrate how to use +the external UVC web camera for :term:`VisionPortal` operations. Before +a team can use the external UVC camera, a :term:`configuration file ` must be configured with the external camera defined as one of the USB-connected devices. diff --git a/docs/source/hardware_and_software_configuration/configuring/getting_started/getting-started.rst b/docs/source/hardware_and_software_configuration/configuring/getting_started/getting-started.rst index cc7704d5c..e6cce1b1c 100644 --- a/docs/source/hardware_and_software_configuration/configuring/getting_started/getting-started.rst +++ b/docs/source/hardware_and_software_configuration/configuring/getting_started/getting-started.rst @@ -4,9 +4,9 @@ Getting Started Creating a Configuration ~~~~~~~~~~~~~~~~~~~~~~~~ -Before you can communicate with the motor, servo and sensors that are -connected to the Control Hub or Expansion Hub, you first must create a -configuration file on your Robot Controller, so that the Robot +Before you can communicate with the motor, :term:`servo ` and :term:`sensors ` that are +connected to the :term:`Control Hub` or :term:`Expansion Hub`, you first must create a +:term:`configuration file ` on your :term:`Robot Controller`, so that the Robot Controller will know what hardware is available on the Control Hub's or Expansion Hub's external ports. @@ -44,7 +44,7 @@ on the Expansion Hub. | -3. Plug the Type A end of the USB cable into the OTG adapter. +3. Plug the Type A end of the USB cable into the :term:`OTG adapter `. .. image:: images/ConfiguringHardwareStep3.jpg :align: center @@ -96,7 +96,7 @@ Creating a Configuration File on the Robot Controller using the DRIVER STATION I ------------------------------------------------------------------------------------------- 1. Touch the three vertical dots in the upper right hand corner of -the Driver Station app. This will launch a pop-up menu. +the :term:`Driver Station` app. This will launch a pop-up menu. .. image:: images/ConfiguringHardwareNewStep1.jpg :align: center 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 24628a0e3..85ec7ee2c 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 @@ -4,7 +4,7 @@ Managing Electrostatic Discharge Effects Introduction ~~~~~~~~~~~~ -Electrostatic discharge (ESD) events have the potential to disrupt the +Electrostatic discharge (:term:`ESD`) events have the potential to disrupt the normal operation of a competition robot. This section examines causes of ESD events and discusses ways to mitigate the risk that an ESD event will disable or damage a robot’s control system. @@ -20,7 +20,7 @@ quantifies the efficacy of various ESD mitigation techniques: 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 mitigate the risk caused by this phenomenon. Also special thanks to *FIRST* -Tech Challenge Teams 2844, 8081, 10523, 10523a, and 10984, and the volunteer +Tech Challenge Teams 2844, 8081, 10523, 10523a, and 10984, and the :term:`volunteer ` team from Arizona (including Robert Garduno, Susan Garduno, Richard Gomez, Matthew Rainey, Christine Sapio, Patricia Strones, and David Thompson) for assisting in testing some of these mitigation techniques under the hot desert @@ -132,7 +132,7 @@ Step 2: Add Ferrite Chokes to Signal Wires Ferrite chokes block large changes in current like those seen during an ESD event. This can reduce the risk of damage to or disruption of -electrical components when a sensor or other peripheral device receives +electrical components when a :term:`sensor ` or other peripheral device receives a shock. .. image:: images/ferritechoke.jpg @@ -146,16 +146,16 @@ effects of ESD: 2. Install snap-on ferrite chokes onto your signal cables: - Sensor cables - - Encoder cables - - Servo cables + - :term:`Encoder` cables + - :term:`Servo` cables 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* -Tech Challenge match, charge can accumulate on the metallic frame of the +Tech Challenge :term:`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 +frame of the robot, but the electronics that make up the :term:`Control System` are at a different voltage, then a shock can occur if an exposed or poorly insulated portion of the Control System gets close (less than 3/8” or 10mm) to the metal frame. @@ -193,10 +193,10 @@ frame, a shock can occur if a charge accumulates on the frame. of the electronics. For example, the 4-wire sensor cables that are used by the REV Robotics -Expansion Hub have plastic connectors that are poorly insulated. If a +:term:`Expansion Hub` have plastic connectors that are poorly insulated. If a 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. +shock can disrupt or even damage the :term:`I2C` port of an Expansion Hub. Similarly, some servo extension cables have exposed portions of metal that could be vulnerable to ESD unless properly @@ -223,10 +223,10 @@ Using electrical tape to insulate these areas can be equally effective and may b .. 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 + The REV :term:`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). + 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 :term:`hub `). Ensure that you plug USB devices, such as a Camera, into the USB 3.0 Port on your Control Hub. diff --git a/docs/source/hardware_and_software_configuration/configuring/saving_config/saving-config.rst b/docs/source/hardware_and_software_configuration/configuring/saving_config/saving-config.rst index 9b805914e..b42c68d1a 100644 --- a/docs/source/hardware_and_software_configuration/configuring/saving_config/saving-config.rst +++ b/docs/source/hardware_and_software_configuration/configuring/saving_config/saving-config.rst @@ -1,7 +1,7 @@ Saving the Configuration Information ==================================== Once you have configured your hardware, you must save the information to -the configuration file. If you do not save this information, it will be +the :term:`configuration file `. If you do not save this information, it will be lost and the robot controller will be unable to communicate with your hardware. diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_color/connecting-color.rst b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_color/connecting-color.rst index 3f11fd357..f27988d94 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_color/connecting-color.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_color/connecting-color.rst @@ -1,8 +1,8 @@ Connecting a Color-Distance Sensor to the Hub ============================================= -The Hub has 4 independent I2C buses. Each bus has its own port on the -Hub. We will connect a REV Robotics Color-Distance sensor to the I2C bus +The :term:`Hub` has 4 independent :term:`I2C` buses. Each bus has its own port on the +Hub. We will connect a REV Robotics Color-Distance :term:`sensor ` to the I2C bus #0 on the Hub. Note that it will take an estimated 2.5 minutes to complete this task. diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_motor/connecting-motor.rst b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_motor/connecting-motor.rst index d3d110ca0..592682f2b 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_motor/connecting-motor.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_motor/connecting-motor.rst @@ -1,7 +1,7 @@ Connecting a Motor to the Hub ============================== -The Hub can drive up to four (4) 12V DC motors per Hub. The Hub uses a +The :term:`Hub` can drive up to four (4) 12V :term:`DC motors ` per Hub. The Hub uses a type of electrical connector known as a 2-pin JST VH connector. Many of the *FIRST* approved 12V DC motors are equipped with Anderson Powerpole connectors. An adapter cable can be used to connect the Anderson diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_power/connecting-power.rst b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_power/connecting-power.rst index b2cf80b76..2b113fe39 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_power/connecting-power.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_power/connecting-power.rst @@ -1,8 +1,8 @@ Connecting 12V Power to the Hub ================================ -The Hub draws power from a 12V rechargeable battery. For safety reasons, -the battery has a 20A fuse built in. A mechanical switch is used to turn +The :term:`Hub` draws power from a 12V rechargeable :term:`battery `. For safety reasons, +the battery has a 20A :term:`fuse ` built in. A mechanical switch is used to turn on/turn off the power. Note that it will take an estimated 5 minutes to complete this task. diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_servo/connecting-servo.rst b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_servo/connecting-servo.rst index e90a80265..6708233cf 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_servo/connecting-servo.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_servo/connecting-servo.rst @@ -1,7 +1,7 @@ Connecting a Servo to the Hub ============================== -The Hub has 6 built-in servo ports. The servo ports accept the standard +The :term:`Hub` has 6 built-in :term:`servo ` ports. The servo ports accept the standard 3-wire header style connectors commonly found on servos. Note that ground pin is on the left side of the servo port. diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_touch/connecting-touch.rst b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_touch/connecting-touch.rst index 74be718a6..a2f76daed 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/connecting_touch/connecting-touch.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/connecting_touch/connecting-touch.rst @@ -1,12 +1,12 @@ Connecting a Touch Sensor to the Hub ===================================== -The Hub has 4 independent digital input/output (I/O) ports. Each port -has two digital I/O pins for a total of 8 digital I/O pins on a Hub. You -will connect a REV Robotics Touch sensor to one of the digital I/O +The :term:`Hub` has 4 independent digital input/output (I/O) ports. Each port +has two :term:`digital I/O ` pins for a total of 8 digital I/O pins on a Hub. You +will connect a REV Robotics :term:`Touch sensor ` to one of the digital I/O ports. -Note that in the case of the REV Robotics Touch Sensor, the device has a +Note that in the case of the REV Robotics Touch :term:`Sensor`, the device has a connector port for a 4-pin sensor cable. However, the device only needs to connect to one of the two available digital I/O pins. For the REV Robotics Touch Sensor, the second digital I/O pin in the port is the one diff --git a/docs/source/hardware_and_software_configuration/connecting_devices/index.rst b/docs/source/hardware_and_software_configuration/connecting_devices/index.rst index 2c08c586d..e286e9fa8 100644 --- a/docs/source/hardware_and_software_configuration/connecting_devices/index.rst +++ b/docs/source/hardware_and_software_configuration/connecting_devices/index.rst @@ -1,8 +1,8 @@ Connecting Devices To a Control or Expansion Hub ================================================ -This section explains how to connect a motor, a servo, and some sensors -to your REV Robotics Control Hub or REV Robotics Expansion Hub. While +This section explains how to connect a motor, a :term:`servo `, and some :term:`sensors ` +to your REV Robotics :term:`Control Hub` or REV Robotics :term:`Expansion Hub`. While the Control Hub differs from the Expansion Hub because of its built in Android device, the layout of the external motor, servo, and sensor ports are identical for the Control Hub and Expansion Hub. diff --git a/docs/source/hardware_and_software_configuration/index.rst b/docs/source/hardware_and_software_configuration/index.rst index 151f1a337..e24f132e4 100644 --- a/docs/source/hardware_and_software_configuration/index.rst +++ b/docs/source/hardware_and_software_configuration/index.rst @@ -6,7 +6,7 @@ Hardware and Software Configuration ===================================== -Hardware and Software Configuration for the Control System +Hardware and Software Configuration for the :term:`Control System` .. toctree:: :maxdepth: 2 diff --git a/docs/source/hardware_and_software_configuration/self_inspect/new-self-inspect.rst b/docs/source/hardware_and_software_configuration/self_inspect/new-self-inspect.rst index 3afdb4dec..1860cc03f 100644 --- a/docs/source/hardware_and_software_configuration/self_inspect/new-self-inspect.rst +++ b/docs/source/hardware_and_software_configuration/self_inspect/new-self-inspect.rst @@ -4,12 +4,12 @@ Introduction ------------ -This page describes the Self Inspect screens in the FTC Driver Station -(DS) app and the FTC Robot Controller (RC) app. +This page describes the Self Inspect screens in the FTC :term:`Driver Station` +(DS) app and the FTC :term:`Robot Controller` (RC) app. A Self Inspect screen provides a snapshot of device status, as it relates to FTC rules for the control system. -These rules are described in the Competition Manual which can be found on the +These rules are described in the :term:`Competition Manual` which can be found on the `Current Game and Season Materials page `_ on the *FIRST* Website. .. tip:: An `Inspection Checklist (PDF) `_ @@ -22,7 +22,7 @@ The Self Inspect screen is provided only as a quick, handy reference to help teams confirm that certain control system elements are up-to-date and properly configured. -Each inspection screen updates automatically, with or without a Restart +Each :term:`inspection ` screen updates automatically, with or without a Restart Robot. This allows quick verification that issues have been resolved. The challenge is to maximize useful information in a small screen. The @@ -32,7 +32,7 @@ clarifies some of the brief but meaningful captions. Robot Inspection ---------------- -The Self Inspection reports may be reviewed in Robot Inspection at an FTC tournament, but is **not** a comprehensive or official standard of compliance with FTC rules. +The Self Inspection reports may be reviewed in Robot Inspection at an FTC :term:`tournament `, but is **not** a comprehensive or official standard of compliance with FTC rules. With the robot and driver station turned on and connected the inspector may go through the **Inspection Checklist** form (on paper or a tablet). They will check both the **Driver Station Inspection Report** and the **Robot Controller Inspection Report**, both of which can be displayed from the DS. Many FTC events will scan the QR Code that is displayed on the RC Inspection Report. @@ -40,20 +40,20 @@ Many FTC events will scan the QR Code that is displayed on the RC Inspection Rep Version Information ------------------- -The Competition Manual lists the minimum recommended versions of device firmware, Android operating system, and FTC Apps. +The Competition Manual lists the minimum recommended versions of device :term:`firmware `, Android operating system, and FTC Apps. Teams may choose to run older versions without affecting their ROBOT inspection status. This avoids the situation of trying to upgrade a device at a competition at the last minute where a mistake might leave the robot inoperable. .. note:: The images in this page show Version 10.3 or newer of the FTC apps. - This page only shows a Driver Hub paired with a Control Hub, there may be slight differences if a phone is used as a driver station or robot controller. + This page only shows a :term:`Driver Hub` paired with a :term:`Control Hub`, there may be slight differences if a phone is used as a driver station or robot controller. See the :doc:`old self-inspect` page for screen images for app versions 10.2 or earlier. *FIRST* recommends but does not require that teams use the most recent versions of firmware, Android Operating System, and FTC Apps. Current versions have the latest bug fixes and enhancements. For example, version 1.1.6 of the **Control Hub Android OS** has a fix related to Wi-Fi. Each FTC season new major versions the FTC Apps are released. The INTO THE DEEP major version is 10, and the DECODE major version is 11. -If the game has AprilTags, the SDK will include :doc:`localization<../../apriltag/vision_portal/apriltag_localization/apriltag-localization>` information for those tags that lets you determine the robot's position on the field. +If the game has :term:`AprilTags `, the SDK will include :doc:`localization<../../apriltag/vision_portal/apriltag_localization/apriltag-localization>` information for those tags that lets you determine the robot's position on the field. As the season progresses, minor releases will include bug fixes and some enhancements. e.g. 11.1, 11.2, etc. Regardless of the versions selected, it is highly recommended that the installed ROBOT CONTROLLER @@ -102,7 +102,7 @@ The following is a screen shot of a DS Self Inspection Report with the Driver Hu It does not check whether the RC name matches FTC format requirements. See the Robot Controller Self Inspection Report. - Item 13 Apps Installed ``Robot Controller`` should be **Not installed**. This verifies that the Driver Station device does **not** also have a Robot Controller app installed. Only one FTC app should be installed on each device. It's possible to accidentally install both apps, but this usually causes the apps to not work properly. -- Item 14 Apps Installed ``Driver Station`` should indicate the version number of the Driver Station App. *FIRST* recommends but does not require that teams use the currently available version. +- Item 14 Apps Installed ``Driver Station`` should indicate the version number of the :term:`Driver Station App`. *FIRST* recommends but does not require that teams use the currently available version. An invalid or future device system date can result in an invalid inspection item here with a message that "The Driver Station app is obsolete". Correcting the date on the device should fix the invalid inspection item. @@ -111,9 +111,9 @@ The following is a screen shot of a DS Self Inspection Report with the Driver Hu Here’s a report from a Driver Station with some items **rejected** by Self Inspect. Problems are indicated by a red circle exclamation mark icon, or an orange triangle exclamation mark icon. -This was a driver hub that was firmware reset. This reset the DS version to 7 and restored all system and DS app settings to defaults. +This was a driver :term:`hub ` that was firmware reset. This reset the DS version to 7 and restored all system and DS app settings to defaults. Then the `REV Hardware Client `_ was used to update the DS version 10.3. -Then the FTCRobotController app was also deployed to the DS device from Android Studio. +Then the FTCRobotController app was also deployed to the DS device from :term:`Android Studio`. .. figure:: images/newDSerrors.png :align: center @@ -156,7 +156,7 @@ FYI - if you connect an external monitor to the Control Hub's HDMI port and a mo - Item 4 ``Control Hub OS Version`` should be at least 1.1.6. *FIRST* recommends but does not require that teams use the currently available version. - Item 5 ``Android Version`` is probably 7.1.2 for a Control Hub. - Item 6 ``Hub Firmware`` lists the hub addresses and firmware levels. This - example shows one Control Hub, but an Expansion Hub can also be listed here. A + example shows one Control Hub, but an :term:`Expansion Hub` can also be listed here. A check mark indicates all firmware is up-to-date based on the current version of the RC app. *FIRST* recommends but does not require that teams use the currently available version. - Item 7 shows the ``Battery Level`` of the device being reported. diff --git a/docs/source/hardware_and_software_configuration/self_inspect/self-inspect.rst b/docs/source/hardware_and_software_configuration/self_inspect/self-inspect.rst index 9ac98a7ba..edfad8316 100644 --- a/docs/source/hardware_and_software_configuration/self_inspect/self-inspect.rst +++ b/docs/source/hardware_and_software_configuration/self_inspect/self-inspect.rst @@ -4,13 +4,13 @@ Old Self-Inspect Introduction ------------ -This page describes the older Self Inspect screens in the FTC Driver Station -(DS) app and the FTC Robot Controller (RC) app. +This page describes the older Self Inspect screens in the FTC :term:`Driver Station` +(DS) app and the FTC :term:`Robot Controller` (RC) app. See the :doc:`new self-inspect` page for screen images for version 10.3 or better. A Self Inspect screen provides a snapshot of device status, as it relates to FTC rules for the control system. -These rules are described in the Competition Manual which can be found on the +These rules are described in the :term:`Competition Manual` which can be found on the `Current Game and Season Materials page `_ on the *FIRST* Website. .. tip:: An `Inspection Checklist PDF `_ @@ -19,7 +19,7 @@ These rules are described in the Competition Manual which can be found on the The Self Inspect screen is provided only as a quick, handy reference to help teams confirm that certain control system elements are up-to-date and properly configured. Self Inspect may be reviewed in Robot -Inspection at an FTC tournament, but is **not** a comprehensive or +:term:`Inspection` at an FTC :term:`tournament `, but is **not** a comprehensive or official standard of compliance with FTC rules. Each inspection screen updates automatically, with or without a Restart @@ -38,10 +38,10 @@ Device Pairing -------------- Pairing technology is a key aspect of Self Inspect reporting. Remember -that RC phones host via **Wi-Fi Direct**, while Control Hubs host via +that RC phones host via **Wi-Fi Direct**, while :term:`Control Hubs ` host via **Standard, or ‘infrastructure’, Wi-Fi**. -In the DS app’s Settings, the selected Pairing Method (Wi-Fi Direct or +In the DS app’s Settings, the selected Pairing Method (:term:`Wi-Fi Direct` or Control Hub) will influence acceptance/rejection in the DS Self Inspect report, as described in examples below. @@ -54,7 +54,7 @@ FTC control devices may use these combinations: - DS phone, RC phone - DS phone, Control Hub -- Driver Hub, RC phone +- :term:`Driver Hub`, RC phone - Driver Hub, Control Hub A DS device (phone or Driver Hub) can display its own DS Self Inspect @@ -114,7 +114,7 @@ DS Self Inspect 1, on DS phone paired to RC phone - Item 1 is a menu with one choice: Disconnect from Wi-Fi Direct. It does work, but sometimes the apps re-pair automatically. -- Item 5 shows the battery level of the device being reported. Fun +- Item 5 shows the :term:`battery ` level of the device being reported. Fun fact: the green color of the percentage value changes towards **orange** as the charge level goes down. - Item 8 ``Location services`` appears only on devices running @@ -313,10 +313,10 @@ slight differences. RC Self Inspect 1, appearing on RC phone paired with DS phone -- Item 5 lists the Expansion Hub addresses and firmware levels. This +- Item 5 lists the :term:`Expansion Hub` addresses and :term:`firmware ` levels. This example shows one Expansion Hub, but two can be listed here. A check-mark indicates all firmware is up-to-date based on the current - version of the RC app. This item shows “N/A” if no Hubs are + version of the RC app. This item shows “N/A” if no :term:`Hubs ` are connected. - Item 10 ``RC Password`` appears only in RC Self Inspect, not in DS Self Inspect. It checks the FTC requirement for a Control Hub diff --git a/docs/source/index.rst b/docs/source/index.rst index 42f2cd16a..0405bc6fe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,7 @@ and :doc:`gracious_professionalism/gp` to see why. /overview/ftcoverview gracious_professionalism/gp + Glossary .. toctree:: :caption: Getting Started @@ -212,7 +213,7 @@ The main menu contains links to the top level content. The following are quick l ^^^ - Let's get to know the *FIRST* Tech Challenge Control System! + Let's get to know the *FIRST* Tech Challenge :term:`Control System`! +++ @@ -266,7 +267,7 @@ The main menu contains links to the top level content. The following are quick l ^^^ - The Software Development Kit (SDK) is the collection of tools for + The :term:`Software Development Kit` (SDK) is the collection of tools for developing software and executing it on the robot. +++ @@ -320,7 +321,7 @@ The main menu contains links to the top level content. The following are quick l ^^^ Be sure you're following all of the rules of the competition! - The Competition Manual is an essential document. + The :term:`Competition Manual` is an essential document. +++ diff --git a/docs/source/manuals/game_manuals/game_manuals.rst b/docs/source/manuals/game_manuals/game_manuals.rst index 8824cbf4e..c98edf316 100644 --- a/docs/source/manuals/game_manuals/game_manuals.rst +++ b/docs/source/manuals/game_manuals/game_manuals.rst @@ -1,5 +1,5 @@ Competition Manual ================== -The Competition Manual can be found on the `Game and Season Materials page `__ on the *FIRST* Website. +The :term:`Competition Manual` can be found on the `Game and Season Materials page `__ on the *FIRST* Website. diff --git a/docs/source/manufacturing/3d_printing/3d_printed_parts/3d_printed_parts.rst b/docs/source/manufacturing/3d_printing/3d_printed_parts/3d_printed_parts.rst index dc58ef6b7..c5a914c64 100644 --- a/docs/source/manufacturing/3d_printing/3d_printed_parts/3d_printed_parts.rst +++ b/docs/source/manufacturing/3d_printing/3d_printed_parts/3d_printed_parts.rst @@ -6,7 +6,7 @@ Here are some example parts that your team could make with a 3D printer to eithe Mounting Brackets ----------------- -One of the most common uses, 3D Prints can be used to make mounting brackets for motors, servos, +One of the most common uses, 3D Prints can be used to make mounting brackets for motors, :term:`servos `, electrical parts, bearings, and various other objects. This provides teams with a great control of precision over how they mount things, and a decreased part count over commercial parts. diff --git a/docs/source/manufacturing/3d_printing/3d_printing_intro/3d_printing_intro.rst b/docs/source/manufacturing/3d_printing/3d_printing_intro/3d_printing_intro.rst index 04240e58e..9b88a81e5 100644 --- a/docs/source/manufacturing/3d_printing/3d_printing_intro/3d_printing_intro.rst +++ b/docs/source/manufacturing/3d_printing/3d_printing_intro/3d_printing_intro.rst @@ -15,7 +15,7 @@ 3D Printing Methods ------------------- -There are numerous kinds of 3D printing, but for FTC there are only a few that are practical. The most common is +There are numerous kinds of :term:`3D printing <3D Printing>`, but for FTC there are only a few that are practical. The most common is **Fused Deposition Modeling (FDM)**. FDM printers melt a plastic filament and extrude it through a nozzle, which moves around to create the part. FDM printers are the most common type of printer used, and the most practical for robotics teams, so this guide will focus on them. diff --git a/docs/source/manufacturing/3d_printing/designing_and_slicing/designing_and_slicing.rst b/docs/source/manufacturing/3d_printing/designing_and_slicing/designing_and_slicing.rst index 990fd94cc..dfce2b9ee 100644 --- a/docs/source/manufacturing/3d_printing/designing_and_slicing/designing_and_slicing.rst +++ b/docs/source/manufacturing/3d_printing/designing_and_slicing/designing_and_slicing.rst @@ -1,7 +1,7 @@ Designing and Slicing ===================== -This section goes over the essentials of how to design CAD files that are easily 3D printable, and slicing softwares that can take cad files into instructions +This section goes over the essentials of how to design :term:`CAD` files that are easily 3D printable, and slicing softwares that can take cad files into instructions for a 3D printer. .. toctree:: diff --git a/docs/source/manufacturing/3d_printing/designing_and_slicing/tolerancing/tolerancing.rst b/docs/source/manufacturing/3d_printing/designing_and_slicing/tolerancing/tolerancing.rst index d523ef16c..511ef3b7a 100644 --- a/docs/source/manufacturing/3d_printing/designing_and_slicing/tolerancing/tolerancing.rst +++ b/docs/source/manufacturing/3d_printing/designing_and_slicing/tolerancing/tolerancing.rst @@ -3,12 +3,12 @@ Tolerancing Prints Tolerances are everything when it comes to 3D printing- we're not precision machining parts here, we're laying down plastic and hoping it forms a shape. Differences in temperature, nozzle quality, and airflow can vastly change the size a hole actually is despite what the printers instructions tell it to -do. A 4mm hole when printed could end up as actually being 3.6mm. Below are detailed two ways to deal with these tolerance issues for 3D printing. +do. A 4mm hole when printed could end up as actually being 3.6mm. Below are detailed two ways to deal with these tolerance issues for :term:`3D printing <3D Printing>`. Designing Tolerances -------------------- A common way for teams to deal with prints interacting with each other and hardware is to form a table with a list of commonly used hole sizes for your various -applications and then use these hole sizes in their CAD. Numbers depend on your printer and nozzle size, so we would recommend making test prints to see +applications and then use these hole sizes in their :term:`CAD`. Numbers depend on your printer and nozzle size, so we would recommend making test prints to see how hardware can fit best in order to form this table. An example test print would be a print with a 2.8mm, 2.9mm, 3.0mm, 3.1mm, and 3.2mm hole to see which best creates an M3 through hole. diff --git a/docs/source/manufacturing/3d_printing/designing_and_slicing/what_is_slicing/what_is_slicing.rst b/docs/source/manufacturing/3d_printing/designing_and_slicing/what_is_slicing/what_is_slicing.rst index c6b0170ab..f79cf5b03 100644 --- a/docs/source/manufacturing/3d_printing/designing_and_slicing/what_is_slicing/what_is_slicing.rst +++ b/docs/source/manufacturing/3d_printing/designing_and_slicing/what_is_slicing/what_is_slicing.rst @@ -1,7 +1,7 @@ What is Slicing? ================ -One of the most important steps of 3D printing is turning your CAD files into instructions for the printer can carry out and read. +One of the most important steps of :term:`3D printing <3D Printing>` is turning your :term:`CAD` files into instructions for the printer can carry out and read. This is done in a software called a slicer, which turns CAD files, into machine-readable, G-Code Files. .. image:: images/slicinggraphic.jpg diff --git a/docs/source/manufacturing/3d_printing/filament_choice/advanced_filaments/advanced_filaments.rst b/docs/source/manufacturing/3d_printing/filament_choice/advanced_filaments/advanced_filaments.rst index 6471216e6..2a736dd7f 100644 --- a/docs/source/manufacturing/3d_printing/filament_choice/advanced_filaments/advanced_filaments.rst +++ b/docs/source/manufacturing/3d_printing/filament_choice/advanced_filaments/advanced_filaments.rst @@ -19,7 +19,7 @@ ABS (Acrylonitrile Butadiene Styrene) / ASA (Acrylonitrile Styrene Acrylate) | -Before PLA became readily available, ABS was the most common filament used for 3D printing. Nowadays, it's regarded as a +Before PLA became readily available, ABS was the most common filament used for :term:`3D printing <3D Printing>`. Nowadays, it's regarded as a more advanced filament with a specialized setup needed. ABS is very strong, having a high ductility and able to withstand shock loads well. These strengths come with major difficulties, however, as an enclosure is often needed to increase the ambient temperature in order to prevent severe part warping. This enclosure is also a good idea due to ABS's production of diff --git a/docs/source/manufacturing/3d_printing/filament_choice/common_filaments/common_filaments.rst b/docs/source/manufacturing/3d_printing/filament_choice/common_filaments/common_filaments.rst index 994e2c4aa..017a7b12d 100644 --- a/docs/source/manufacturing/3d_printing/filament_choice/common_filaments/common_filaments.rst +++ b/docs/source/manufacturing/3d_printing/filament_choice/common_filaments/common_filaments.rst @@ -26,7 +26,7 @@ PLA (Polylactic Acid) | -Polylactic Acid, or PLA, is the most common 3D printing filament used today. It is made from biological sources such as +Polylactic Acid, or PLA, is the most common :term:`3D printing <3D Printing>` filament used today. It is made from biological sources such as corn starch or sugar cane. PLA is easy to print with, and is usually the best choice for most robot parts. It prints at a low temperature, and tends to warp very little. PLA is very stiff, but can be brittle, especially under shock loads (impacts), and parts should be designed with this in mind. diff --git a/docs/source/manufacturing/3d_printing/filament_choice/filament_choice.rst b/docs/source/manufacturing/3d_printing/filament_choice/filament_choice.rst index 1f1eb44d2..ed8929ccb 100644 --- a/docs/source/manufacturing/3d_printing/filament_choice/filament_choice.rst +++ b/docs/source/manufacturing/3d_printing/filament_choice/filament_choice.rst @@ -1,6 +1,6 @@ Filament Choice =============== -There are many different materials and colors of plastics called "filaments" that can be used for 3D printing, but for FTC there are only +There are many different materials and colors of plastics called "filaments" that can be used for :term:`3D printing <3D Printing>`, but for FTC there are only a few that are of practical use for most teams. Since this guide is currently only addressing FDM (Fused Deposition Modeling) printing, materials like resin (used in SLA printing) will not be discussed. | diff --git a/docs/source/manufacturing/3d_printing/general_knowledge/common_tools/common_tools.rst b/docs/source/manufacturing/3d_printing/general_knowledge/common_tools/common_tools.rst index d1a010b0a..3498a4027 100644 --- a/docs/source/manufacturing/3d_printing/general_knowledge/common_tools/common_tools.rst +++ b/docs/source/manufacturing/3d_printing/general_knowledge/common_tools/common_tools.rst @@ -37,7 +37,7 @@ Flush Cutter Flush cutters, otherwise known as diagonal cutters, snips, or snippers by teams, are an extremely versatile tool that can be used for cutting and trimming things on your printer or your prints. A cheap pair like -pictured below is still great for 3D Printing and general use, just make sure that they stay sharp! +pictured below is still great for :term:`3D Printing` and general use, just make sure that they stay sharp! .. figure:: images/flushcutters.png :align: center diff --git a/docs/source/manufacturing/3d_printing/general_knowledge/common_upgrades/common_upgrades.rst b/docs/source/manufacturing/3d_printing/general_knowledge/common_upgrades/common_upgrades.rst index 83914b3cc..c1c698122 100644 --- a/docs/source/manufacturing/3d_printing/general_knowledge/common_upgrades/common_upgrades.rst +++ b/docs/source/manufacturing/3d_printing/general_knowledge/common_upgrades/common_upgrades.rst @@ -101,7 +101,7 @@ include this option stock, so it's not a concern for many. ABL or Auto-Bed Leveling uses either a mechanical or inductive sensor on your toolhead to probe your bed in different locations and uses software to improve your first layer quality and adhesion. While it requires learning -a bit about firmware, auto bed leveling is extremely worth it. More and more printers are coming with auto bed +a bit about :term:`firmware `, auto bed leveling is extremely worth it. More and more printers are coming with auto bed leveling stock, but if yours didn't and you'd like to upgrade, these options are common: * Mechanical Sensors: BLTouch, CRTouch diff --git a/docs/source/manufacturing/3d_printing/general_knowledge/general_knowledge.rst b/docs/source/manufacturing/3d_printing/general_knowledge/general_knowledge.rst index c3d25d8f6..5c430b5ea 100644 --- a/docs/source/manufacturing/3d_printing/general_knowledge/general_knowledge.rst +++ b/docs/source/manufacturing/3d_printing/general_knowledge/general_knowledge.rst @@ -2,7 +2,7 @@ General Knowledge ================= The following section is general knowledge regarding the operation, maintenance, and terminology -regarding 3D Printing. We'd highly suggest reading through at least the terminology section +regarding :term:`3D Printing`. We'd highly suggest reading through at least the terminology section before getting into the more advanced knowledge documented here! .. toctree:: diff --git a/docs/source/manufacturing/3d_printing/general_knowledge/hardware_tradeoffs/hardware_tradeoffs.rst b/docs/source/manufacturing/3d_printing/general_knowledge/hardware_tradeoffs/hardware_tradeoffs.rst index 9a270c276..85311df82 100644 --- a/docs/source/manufacturing/3d_printing/general_knowledge/hardware_tradeoffs/hardware_tradeoffs.rst +++ b/docs/source/manufacturing/3d_printing/general_knowledge/hardware_tradeoffs/hardware_tradeoffs.rst @@ -40,7 +40,7 @@ relatively easy to damage or scrape. PTFE Lined vs All-Metal Hotends -------------------------------- -PTFE tubing is a common low friction tubing used in 3D printing. PTFE lined hotends have a section of this tubing +PTFE tubing is a common low friction tubing used in :term:`3D printing <3D Printing>`. PTFE lined hotends have a section of this tubing that goes right up to the heated area. These are typically the cheaper option, but it is not recommend to use them whatsoever if you plan on 3D printing anything beyond PLA/PETG. PTFE at temperatures over standard printing temps (normally ~250C is the limit) can "off-gas", putting off dangerous VOCs (Volatile Organic Compounds). All-Metal diff --git a/docs/source/manufacturing/3d_printing/general_knowledge/terminology/terminology.rst b/docs/source/manufacturing/3d_printing/general_knowledge/terminology/terminology.rst index 9e44029b0..17ce37a92 100644 --- a/docs/source/manufacturing/3d_printing/general_knowledge/terminology/terminology.rst +++ b/docs/source/manufacturing/3d_printing/general_knowledge/terminology/terminology.rst @@ -1,12 +1,12 @@ 3D Printing Terminology ======================= -3D Printing terminology can often feel overwhelming and complex, to simplify here's a list of some terms to know! +:term:`3D Printing` terminology can often feel overwhelming and complex, to simplify here's a list of some terms to know! General 3D Printing Terms ------------------------- -* **Additive Manufacturing**: The method of creating a part by building material layer by layer from a CAD model (more commonly known as 3D Printing) +* **Additive Manufacturing**: The method of creating a part by building material layer by layer from a :term:`CAD` model (more commonly known as 3D Printing) * **Fused Deposition Modeling (FDM)**: The most common type of 3D Printing where objects are produced by laying plastics layer by layer on a bed utilizing a heated nozzle. diff --git a/docs/source/manufacturing/3d_printing/index.rst b/docs/source/manufacturing/3d_printing/index.rst index 905fd85e1..96d268fe5 100644 --- a/docs/source/manufacturing/3d_printing/index.rst +++ b/docs/source/manufacturing/3d_printing/index.rst @@ -10,7 +10,7 @@ Many parts in FTC need to be a special/unique shape and size, one that isn't sold or available from a vendor. Sometimes, teams need a part that is impossible to machine or cut out, or needs to be lightweight. Other times, -teams may want to test and iterate the design of a part rapidly and cheaply. 3D printing is a great solution to +teams may want to test and iterate the design of a part rapidly and cheaply. :term:`3D printing <3D Printing>` is a great solution to all of these problems. 3D Printing is the process of creating a three dimensional object by laying down successive layers of material @@ -37,7 +37,7 @@ Volunteer Special Thanks ------------------------- The *FIRST* Tech Challenge staff would like to extend a special thanks -to the following volunteers for their hard work and dedication toward +to the following :term:`volunteers ` for their hard work and dedication toward this project: - Lucas Y., Team 16461 diff --git a/docs/source/manufacturing/3d_printing/printer_choice/high_end_printers/high_end_printers.rst b/docs/source/manufacturing/3d_printing/printer_choice/high_end_printers/high_end_printers.rst index f4e5c1e54..e7ad603e6 100644 --- a/docs/source/manufacturing/3d_printing/printer_choice/high_end_printers/high_end_printers.rst +++ b/docs/source/manufacturing/3d_printing/printer_choice/high_end_printers/high_end_printers.rst @@ -82,7 +82,7 @@ DIY Printers (Voron, HevOrt, VZBot) printers we would highly advise against a DIY printer. These printers are **projects** and take significant effort and upkeep, which make them a poor choice for a first or second printer. -If you want to take a deeper dive into 3D Printing and achieve both extreme speeds and quality, a DIY printer +If you want to take a deeper dive into :term:`3D Printing` and achieve both extreme speeds and quality, a DIY printer may be a good choice. DIY printers can be tailored to your specific needs and perform extremely well but are typically a huge time and financial commitment. diff --git a/docs/source/manufacturing/3d_printing/printer_choice/printer_choice.rst b/docs/source/manufacturing/3d_printing/printer_choice/printer_choice.rst index ba4d13537..5ef2e13bd 100644 --- a/docs/source/manufacturing/3d_printing/printer_choice/printer_choice.rst +++ b/docs/source/manufacturing/3d_printing/printer_choice/printer_choice.rst @@ -18,7 +18,7 @@ Bambu Lab has fixed the issue in Q3 2025, but if you have an older model, it is and temperature trends don't make sense, the 3D printer will shut itself down. This is essential to prevent possible fires and teams should not buy 3D printers without this feature. -Most 3D printers you buy today will have this due to firmware updates, despite the age of the printer, but **it should still be checked (especially pre-2020 Ender 3 models)**. +Most 3D printers you buy today will have this due to :term:`firmware ` updates, despite the age of the printer, but **it should still be checked (especially pre-2020 Ender 3 models)**. Please search up whether the printer model you intend on buying has this feature. If you search up Ender 3s, you will find some results that say it does not, but this is dated information and not true, as newer (after 2020) Ender 3s are diff --git a/docs/source/manufacturing/3d_printing/specific_skill_guides/print_adhesion/print_adhesion.rst b/docs/source/manufacturing/3d_printing/specific_skill_guides/print_adhesion/print_adhesion.rst index 5d25e60f6..bb78408aa 100644 --- a/docs/source/manufacturing/3d_printing/specific_skill_guides/print_adhesion/print_adhesion.rst +++ b/docs/source/manufacturing/3d_printing/specific_skill_guides/print_adhesion/print_adhesion.rst @@ -1,7 +1,7 @@ Print Adhesion ============== -There's a lot of ways that print adhesion can go wrong, and it's one of the biggest things that people new to 3D printing struggle with. Bed Leveling is +There's a lot of ways that print adhesion can go wrong, and it's one of the biggest things that people new to :term:`3D printing <3D Printing>` struggle with. Bed Leveling is often the biggest, but if you just can't get that one part to stick even after a perfect bed level, try some of the things below depending on your build surface! diff --git a/docs/source/manufacturing/index.rst b/docs/source/manufacturing/index.rst index d1b52c3ae..ad1736217 100644 --- a/docs/source/manufacturing/index.rst +++ b/docs/source/manufacturing/index.rst @@ -12,7 +12,7 @@ there are many times when a custom part is needed. This section will cover some manufacturing methods used in FTC for creating these parts. It is important to note that there are many different ways to manufacture parts, and this section will only contain those that are most commonly used. -While a CAD model is not always needed to build a robot or part, it is often required when +While a :term:`CAD` model is not always needed to build a robot or part, it is often required when manufacturing custom parts. For this reason, it is recommended that a team design their robot (or at least the part that needs to be made) in a CAD software. For more information on CAD, see the :doc:`CAD Resources <../cad_resources/index>` section. diff --git a/docs/source/overview/ftcoverview.rst b/docs/source/overview/ftcoverview.rst index 0a748dccc..c2ad7f82f 100644 --- a/docs/source/overview/ftcoverview.rst +++ b/docs/source/overview/ftcoverview.rst @@ -3,7 +3,7 @@ About the *FIRST* Tech Challenge It’s way more than building robots. *FIRST* Tech Challenge teams (up to 15 team members, grades 7-12) are challenged to design, build, program, and operate -robots to compete in a head-to-head challenge in an alliance format. +robots to compete in a head-to-head challenge in an :term:`alliance ` format. Guided by adult coaches and mentors, students develop STEM skills and practice engineering principles, while realizing the value of hard work, innovation, and diff --git a/docs/source/persona_pages/coach_admin/coach_admin.rst b/docs/source/persona_pages/coach_admin/coach_admin.rst index 8279821d3..bdaf69bc0 100644 --- a/docs/source/persona_pages/coach_admin/coach_admin.rst +++ b/docs/source/persona_pages/coach_admin/coach_admin.rst @@ -17,7 +17,7 @@ team while promoting *FIRST*'s ethos. Just click on the button for the resource ^^^ - We express the *FIRST* philosophies of Gracious Professionalism + We express the *FIRST* philosophies of :term:`Gracious Professionalism` and Coopertition through our Core Values. +++ diff --git a/docs/source/persona_pages/mentor_tech/mentor_tech.rst b/docs/source/persona_pages/mentor_tech/mentor_tech.rst index d82cf92cf..0b1ee1463 100644 --- a/docs/source/persona_pages/mentor_tech/mentor_tech.rst +++ b/docs/source/persona_pages/mentor_tech/mentor_tech.rst @@ -19,7 +19,7 @@ Just click on the button for the resource you want to explore! ^^^ - Look for Control System resources here. + Look for :term:`Control System` resources here. +++ @@ -89,7 +89,7 @@ Just click on the button for the resource you want to explore! ^^^ - Look for resources for Computer-Aided Design (CAD) software. + Look for resources for :term:`Computer-Aided Design ` (CAD) software. +++ diff --git a/docs/source/persona_pages/rookie_teams/rookie_teams.rst b/docs/source/persona_pages/rookie_teams/rookie_teams.rst index ddf6c2809..dcdb93268 100644 --- a/docs/source/persona_pages/rookie_teams/rookie_teams.rst +++ b/docs/source/persona_pages/rookie_teams/rookie_teams.rst @@ -19,7 +19,7 @@ resource you want to explore! ^^^ - We express the *FIRST* philosophies of Gracious Professionalism + We express the *FIRST* philosophies of :term:`Gracious Professionalism` and Coopertition through our Core Values. +++ @@ -176,7 +176,7 @@ resource you want to explore! ^^^ Be sure you're following all of the rules of the competition! - The Competition Manual is an essential document. + The :term:`Competition Manual` is an essential document. +++ @@ -243,7 +243,7 @@ resource you want to explore! ^^^ - Look for resources for Computer-Aided Design (CAD) software. + Look for resources for :term:`Computer-Aided Design ` (CAD) software. +++ diff --git a/docs/source/persona_pages/veteran_teams/veteran_teams.rst b/docs/source/persona_pages/veteran_teams/veteran_teams.rst index f5bd94c60..f0a057c30 100644 --- a/docs/source/persona_pages/veteran_teams/veteran_teams.rst +++ b/docs/source/persona_pages/veteran_teams/veteran_teams.rst @@ -73,7 +73,7 @@ resource you want to explore! ^^^ - Look for resources for Computer-Aided Design (CAD) software. + Look for resources for :term:`Computer-Aided Design ` (CAD) software. +++ diff --git a/docs/source/programming_resources/android_studio_java/Android-Studio-Tutorial.rst b/docs/source/programming_resources/android_studio_java/Android-Studio-Tutorial.rst index 4cdf6e903..0cf827c44 100644 --- a/docs/source/programming_resources/android_studio_java/Android-Studio-Tutorial.rst +++ b/docs/source/programming_resources/android_studio_java/Android-Studio-Tutorial.rst @@ -7,8 +7,8 @@ Android Studio Programming Tutorial This tutorial will take you step-by-step through the process of -configuring, programming, and operating your Control System. This -tutorial uses Android Studio to help you get started programming your +configuring, programming, and operating your :term:`Control System`. This +tutorial uses :term:`Android Studio` to help you get started programming your robot. Android Studio is an advanced integrated development environment for diff --git a/docs/source/programming_resources/blocks/Blocks-Tutorial.rst b/docs/source/programming_resources/blocks/Blocks-Tutorial.rst index bdbb04102..a67a09a24 100644 --- a/docs/source/programming_resources/blocks/Blocks-Tutorial.rst +++ b/docs/source/programming_resources/blocks/Blocks-Tutorial.rst @@ -8,11 +8,11 @@ Blocks Programming Tutorial

Introduction

This tutorial will take you step-by-step through the process of -configuring, programming, and operating your Control System. This +configuring, programming, and operating your :term:`Control System`. This tutorial uses the *Blocks Programming Tool* to help you get started quickly. -The Blocks Programming Tool is a visual design tool that lets +The :term:`Blocks Programming Tool` is a visual design tool that lets programmers use a web browser to create, edit and save their *op modes*. *FIRST* recommends getting starting with Blocks, even if you are an diff --git a/docs/source/programming_resources/imu/imu.rst b/docs/source/programming_resources/imu/imu.rst index 86ee08a08..e1536cbb2 100644 --- a/docs/source/programming_resources/imu/imu.rst +++ b/docs/source/programming_resources/imu/imu.rst @@ -6,9 +6,9 @@ Introduction In September 2022, REV Robotics began shipping `Control Hubs `__ with a different internal -Inertial Measurement Unit (IMU). The new IMU chip is designated `BHI260AP +:term:`Inertial Measurement Unit` (IMU). The new IMU chip is designated `BHI260AP `__, -replacing the existing Hub’s IMU chip `BNO055 +replacing the existing :term:`Hub`’s IMU chip `BNO055 `__. Both are from Bosch Sensortec. An IMU can measure many aspects of device motion; this explanatory document focuses primarily on **rotation**. @@ -25,19 +25,19 @@ BHI260AP and BNO055 IMU. This basic tutorial introduces some new features: Teams wanting to use the newer IMU are required to: - use SDK 8.1 or newer -- update the Control Hub OS to 1.1.3 or newer. +- update the :term:`Control Hub` OS to 1.1.3 or newer. However **all teams** are encouraged to begin using the universal IMU classes -and methods for **new** Blocks and Java code. And, migrating **existing code** +and methods for **new** :term:`Blocks` and Java code. And, migrating **existing code** would allow you to switch easily (and perhaps urgently) to a new Control Hub during the season. Don’t know which IMU you have? Check the **Manage** page under ``Program & Manage`` in any of these places: -- connected Driver Station (DS) app +- connected :term:`Driver Station` (DS) app - connected computer’s Chrome browser, at ``http://192.168.43.1:8080`` (Control Hub) or ``http://192.168.49.1:8080`` (RC phone) -- REV Hardware Client (when Hub LED is green) +- :term:`REV Hardware Client` (when Hub LED is green) Each Hub’s IMU type is listed there, as of SDK 8.0. @@ -52,7 +52,7 @@ Each Hub’s IMU type is listed there, as of SDK 8.0. *Reminder: REV Expansion Hubs purchased after December 2021 have no internal IMU.* -Do you have existing OpModes using the original IMU? Your code can run +Do you have existing :term:`OpModes ` using the original IMU? Your code can run unchanged, using Hubs with the BNO055. The new SDK 8.1 fully supports legacy Blocks and Java code using classes and methods for the BNO055 IMU. @@ -79,11 +79,11 @@ The SDK 8.1 README provides more technical background: Potential Usage --------------- -*FIRST* Tech Challenge robots drive mostly on a flat playing field, typically +*FIRST* Tech Challenge robots drive mostly on a flat :term:`playing field `, typically using the IMU to monitor or control **Heading** (Yaw or Z-angle). -Heading is preserved between OpMode runs, unless the robot or Robot Controller -(RC) app are restarted. This can be useful between Autonomous and TeleOp. +:term:`Heading` is preserved between OpMode runs, unless the robot or :term:`Robot Controller` +(RC) app are restarted. This can be useful between :term:`Autonomous` and :term:`TeleOp `. Heading can be reset during an OpMode, as discussed below. *Heading can drift slowly over time. An absolute reference is not available @@ -115,7 +115,7 @@ Examples might include: - robot’s left wheels are raised, on an obstacle - robot is tilted forward on its front 4 wheels (of 6-wheel West Coast Drive) - robot has tipped over (!) -- robot’s secondary Expansion Hub (with IMU) is mounted on a tilting mechanism +- robot’s secondary :term:`Expansion Hub` (with IMU) is mounted on a tilting mechanism The Software SDK can also provide values for **angular velocity**, which is the rate of change (degrees per second) for Roll, Pitch or Yaw. @@ -140,7 +140,7 @@ be the Control Hub, whether old or new. REV IMU Robot Configuration Validation -- **Yellow**: The internal IMU is (always) connected at I2C Bus 0, Port 0. If +- **Yellow**: The internal IMU is (always) connected at :term:`I2C` Bus 0, Port 0. If you want another I2C device also on Bus 0, plug it into the Hub and use the ``Add`` button. @@ -148,7 +148,7 @@ be the Control Hub, whether old or new. fix this only if it was incorrectly modified. Your IMU OpModes **require a correct choice here**. -- **Purple**: The default device name is “imu”, used by all Sample OpModes for +- **Purple**: The default device name is “imu”, used by all :term:`Sample OpModes ` for Blocks and Java. You may enter a custom name here, but you must then **update** all your OpModes that reference the IMU. @@ -518,7 +518,7 @@ Robot Coordinate System: - Heading, or Yaw, is the measure of rotation about the Z axis, which points upwards through the Hub’s front plate or logo. - Pitch is the measure of rotation about the X axis, which points - toward the right-side I2C sensor ports. + toward the right-side I2C :term:`sensor ` ports. - Roll is the measure about the Y axis, which points toward the top-edge USB port(s). diff --git a/docs/source/programming_resources/index.rst b/docs/source/programming_resources/index.rst index 0a817cd4f..1bf5bc50e 100644 --- a/docs/source/programming_resources/index.rst +++ b/docs/source/programming_resources/index.rst @@ -6,7 +6,7 @@ Programming Resources ===================== -This page contains programming tutorials and related Control System +This page contains programming tutorials and related :term:`Control System` documentation useful for configuring and programming Control System components. @@ -69,8 +69,8 @@ Control System Supporting Documentation Vision Programming ~~~~~~~~~~~~~~~~~~ -Programming a camera to recognize AprilTags, colors and shapes is covered in -the **Vision Resources** section of the main menu. Start here: +Programming a camera to recognize :term:`AprilTags `, colors and shapes is +covered in the **Vision Resources** section of the main menu. Start here: - :doc:`Computer Vision Overview ` -- which vision technology to use, and when diff --git a/docs/source/programming_resources/laptops/laptops.rst b/docs/source/programming_resources/laptops/laptops.rst index e9bac913e..157fac834 100644 --- a/docs/source/programming_resources/laptops/laptops.rst +++ b/docs/source/programming_resources/laptops/laptops.rst @@ -19,7 +19,7 @@ heavily: - Any role-specific tasks that the computer may perform in the program -- Type of Computer-Aided Design (CAD) software that may be used on the +- Type of :term:`Computer-Aided Design ` (CAD) software that may be used on the computer - Software development and hardware update requirements @@ -60,7 +60,7 @@ Also Supported: - `iOS Standard Tablet`_ - - LEGO\ :sup:`®` Education SPIKE™ Essential hub cannot be updated + - LEGO\ :sup:`®` Education SPIKE™ Essential :term:`hub ` cannot be updated with iPad - `Android Standard Tablet`_ @@ -123,12 +123,12 @@ Also Supported: - `Android Studio `__ not supported - - Only Blocks and OnBotJava supported + - Only :term:`Blocks` and OnBotJava supported It is also recommended to have an active internet connection during software development. Access to https://github.com is required by the -REV Hardware Client to download and install required season software -updates and is required for Android Studio users to download software +:term:`REV Hardware Client` to download and install required season software +updates and is required for :term:`Android Studio` users to download software templates. Recommended Computer Hardware for *FIRST*\ :sup:`®` Robotics Competition @@ -145,7 +145,7 @@ development computers for two basic purposes – software development and CAD – and team preferences in these two uses shape the required hardware. However, in *FIRST* Robotics Competition there are two roles that computers can serve, such as Software and Design Development -platforms and/or Driver Station platforms, and those roles also shape +platforms and/or :term:`Driver Station` platforms, and those roles also shape the requirements of the computer hardware. It is recommended to have two separate computers, one to use for the @@ -213,7 +213,7 @@ Also Supported: It is also recommended to have an active internet connection during software development. Access to https://github.com is required by the REV Hardware Client to download and install required season software and -firmware updates. Additional software may have similar requirements. +:term:`firmware ` updates. Additional software may have similar requirements. Recommended Hardware Sets ------------------------- @@ -236,7 +236,7 @@ recommendations for all hardware platforms, such as: - Laptops should have at least 2 available physical USB-A ports. - For *FIRST* Tech Challenge, USB-C ports on laptops are not able to - work properly with the REV Control Hub nor REV Driver Hub, so it is + work properly with the REV :term:`Control Hub` nor REV :term:`Driver Hub`, so it is important to have USB-A ports also available. diff --git a/docs/source/programming_resources/onbot_java/OnBot-Java-Tutorial.rst b/docs/source/programming_resources/onbot_java/OnBot-Java-Tutorial.rst index ff46775ac..d616e19ab 100644 --- a/docs/source/programming_resources/onbot_java/OnBot-Java-Tutorial.rst +++ b/docs/source/programming_resources/onbot_java/OnBot-Java-Tutorial.rst @@ -7,8 +7,8 @@ OnBot Java Programming Tutorial This tutorial will take you step-by-step through the process of -configuring, programming, and operating your Control System. This -tutorial uses the OnBot Java Programming Tool to help you get started +configuring, programming, and operating your :term:`Control System`. This +tutorial uses the :term:`OnBot Java Programming Tool` to help you get started programming your robot. The OnBot Java Programming Tool is a text-based programming tool diff --git a/docs/source/programming_resources/shared/auto_load_opmode/auto-load-opmode.rst b/docs/source/programming_resources/shared/auto_load_opmode/auto-load-opmode.rst index 871e51924..81b0007c9 100644 --- a/docs/source/programming_resources/shared/auto_load_opmode/auto-load-opmode.rst +++ b/docs/source/programming_resources/shared/auto_load_opmode/auto-load-opmode.rst @@ -1,7 +1,7 @@ Automatically Loading a Driver Controlled Op Mode ================================================== -A FIRST Tech Challenge match consists of a 30 second autonomous period +A FIRST Tech Challenge :term:`match ` consists of a 30 second autonomous period followed by a 2 minute driver controlled (i.e., tele-operated or teleop) period. Previously, teams had to manually select their teleop op mode after the autonomous portion their match was over. @@ -12,7 +12,7 @@ has completed. This feature can help a team avoid selecting the wrong op mode during a match. To use this feature, verify that you are using version 6.1 or greater of -the SDK software (Robot Controller and Driver Station). +the SDK software (:term:`Robot Controller` and :term:`Driver Station`). Select an autonomous program to use during your match. The preselect button will appear in the lower left corner of the screen. It will be @@ -33,8 +33,8 @@ inactive. Note that in order for the preselect button to be visible, the selected op mode must be designated as an autonomous op mode either by using the -\_@Autonomous\_ annotation if it is written using Java or by selecting -the *Autonomous* option in the Blocks editor. If you do not see the +\_@:term:`Autonomous`\_ annotation if it is written using Java or by selecting +the *Autonomous* option in the :term:`Blocks` editor. If you do not see the preselect button, verify that your currently selected op mode has been designated as autonomous. @@ -63,7 +63,7 @@ button. It will become translucent again and the text adjacent to it will disappear. After the Autonomous program ends, the Driver Station changes the queued -OpMode to the TeleOp program which was preselected before the start of +:term:`OpMode` to the :term:`TeleOp ` program which was preselected before the start of Autonomous. The auto-preselection will be aborted if the user presses stop (either the main stop or init stop buttons). It will only transition if the OpMode either self-exits, or is terminated by the 30s diff --git a/docs/source/programming_resources/shared/choosing_program_lang/choosing-program-lang.rst b/docs/source/programming_resources/shared/choosing_program_lang/choosing-program-lang.rst index ec7bd4f6a..341ffdd06 100644 --- a/docs/source/programming_resources/shared/choosing_program_lang/choosing-program-lang.rst +++ b/docs/source/programming_resources/shared/choosing_program_lang/choosing-program-lang.rst @@ -3,7 +3,7 @@ Choosing a Programming Tool You need to select a programming tool to be able to create op modes for your competition robot. -An Op Mode or Operational Mode is program that tells the robot what to do. +An :term:`Op Mode ` or Operational Mode is program that tells the robot what to do. There are three programming tools that are available for you to use. *FIRST* strongly recommends that **all users** @@ -37,7 +37,7 @@ Android Studio -------------- An advanced integrated development environment for creating Android apps. This tool is the same tool that -professional Android app developers use. Android Studio is only +professional Android app developers use. :term:`Android Studio` is only recommended for advanced users who have extensive Java programming experience. @@ -53,14 +53,14 @@ the best overall tool to use**. The Blocks Programming Tool is intuitive and easy-to-learn. **It is the fastest way to get started programming your robot.** -The OnBot Java Programming Tool is similar to the Blocks Programming -Tool. However, OnBot Java is a text-based tool and it requires that the +The :term:`OnBot Java Programming Tool` is similar to the Blocks Programming +Tool. However, :term:`OnBot Java` is a text-based tool and it requires that the user have a sound understanding of the Java programming language. .. image:: images/ipadPhoneChromebook.jpg :alt: A tablet, a phone, and a laptop each showing the programming tools in use. -It is important to note that with the Blocks Programming Tool and the +It is important to note that with the :term:`Blocks Programming Tool` and the OnBot Java Programming Tool, a user only needs a web browser to create, edit and build op modes for their robot. A user can even create, edit and build op modes using an iPad, an Android phone, or a Chromebook. diff --git a/docs/source/programming_resources/shared/configuring_android/Configuring-Your-Android-Devices.rst b/docs/source/programming_resources/shared/configuring_android/Configuring-Your-Android-Devices.rst index ba9b64329..b8925aee0 100644 --- a/docs/source/programming_resources/shared/configuring_android/Configuring-Your-Android-Devices.rst +++ b/docs/source/programming_resources/shared/configuring_android/Configuring-Your-Android-Devices.rst @@ -7,7 +7,7 @@ What Needs to Be Configured for My Control System? Driver Hub Configuration ^^^^^^^^^^^^^^^^^^^^^^^^ -Teams who are using the REV Robotics Driver Hub as their DRIVER STATION +Teams who are using the REV Robotics :term:`Driver Hub` as their DRIVER STATION should refer to the `official documentation from REV Robotics `_ for instructions on how to set up and use the REV Robotics Driver Hub. @@ -17,9 +17,9 @@ Control Hub Configuration .. note:: References to the DRIVER STATION smartphone may instead apply to the `REV Robotics Driver Hub `__, - which is preloaded with the Driver Station (DS) app. + which is preloaded with the :term:`Driver Station` (DS) app. -Teams who are using a Control Hub (which has an integrated Android Device) +Teams who are using a :term:`Control Hub` (which has an integrated Android Device) will only need to configure a single smartphone for use as a DRIVER STATION. The process is as follows: * Rename the smartphone to "-DS" (where is replaced by your team number). @@ -33,7 +33,7 @@ will only need to configure a single smartphone for use as a DRIVER STATION. The | .. important:: Eventually the Control Hub will need to be renamed so - that its name complies with the Competition Manual, but for now we will + that its name complies with the :term:`Competition Manual`, but for now we will use the Control Hub with its default name. You can learn how to manage a Control Hub (and modify its name, password, etc.) in :doc:`this tutorial <../managing_control_hub/Managing-a-Control-Hub>`. @@ -42,7 +42,7 @@ Two Android Smartphone Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Teams who have two smartphones and are not using a Control Hub will need -to configure one smartphone for use as a Robot Controller and a second +to configure one smartphone for use as a :term:`Robot Controller` and a second smartphone for use as an DRIVER STATION. The process is as follows, * Rename one smartphone to "-RC" (replace with your team number). @@ -127,7 +127,7 @@ level, as described below. * - 7. Select **Configure Device** from the pop-up menu. - |rename7| - * - 8. Use touch pad to enter new name of device. If the device will be a Robot Controller, specify your team number and -RC. If the device will be a DRIVER STATION, specify your team number and -DS. You can also set the Wi-Fi Direct inactivity timeout to *Never disconnect* and then hit the\ **SAVE** button to save your changes. Note that in the screenshot shown to the right, the team number is 9999. The "-C" indicates that this is from the third pair of smartphones for this team. The -RC indicates that this phone will be a Robot Controller. + * - 8. Use touch pad to enter new name of device. If the device will be a Robot Controller, specify your team number and -RC. If the device will be a DRIVER STATION, specify your team number and -DS. You can also set the :term:`Wi-Fi Direct` inactivity timeout to *Never disconnect* and then hit the\ **SAVE** button to save your changes. Note that in the screenshot shown to the right, the team number is 9999. The "-C" indicates that this is from the third pair of smartphones for this team. The -RC indicates that this phone will be a Robot Controller. - |rename8| * - 9. After renaming your phone, power cycle the device. @@ -150,7 +150,7 @@ Google Play.** The `REV Hardware Client `__ software will allow you to download the apps to devices: REV Robotics Control -Hub, REV Robotics Expansion Hub, REV Robotics Driver Hub, and other approved Android +Hub, REV Robotics :term:`Expansion Hub`, REV Robotics Driver Hub, and other approved Android devices (*see section below, called Updating Apps on Android Phones*). Here are some of the benefits: @@ -174,9 +174,9 @@ Updating Apps and Firmware on REV Robotics Devices (REV Robotics Expansion Hub, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The `REV Hardware Client `__ -software is used to install and update apps, firmware and/or +software is used to install and update apps, :term:`firmware ` and/or operating systems on devices from REV Robotics. Simply connect the -device via USB to your PC with the REV Hardware Client installed and +device via USB to your PC with the :term:`REV Hardware Client` installed and running, and the software will detect connected hardware. After detection, the REV Hardware Client can then `update the Robot Controller (RC) app on a REV Robotics Control Hub `__, @@ -232,7 +232,7 @@ For the *FIRST* Tech Challenge competitions, it is important that you place your Robot Controller and DRIVER STATION devices into Airplane mode but keep their Wi-Fi radios turned on. This is important because you do not want any of the cellular telephone functions to be enabled during a -match. The cellular telephone functions could disrupt the function of +:term:`match `. The cellular telephone functions could disrupt the function of the robot during a match. .. note:: It will take an estimated 2.5 minutes per phone to complete this @@ -270,15 +270,15 @@ pre-installed. Once you have successfully installed the Driver Station on an Android phone, you will want to establish a secure wireless connection between the Control Hub and the DRIVER STATION. This connection will allow your DRIVER STATION device to select op modes on -your Robot Controller and send gamepad input to these programs. +your Robot Controller and send :term:`gamepad ` input to these programs. Likewise, it will allow your op modes running on your Robot Controller -to send telemetry data to your DRIVER STATION phone where it can be +to send :term:`telemetry ` data to your DRIVER STATION phone where it can be displayed for your drivers. The process to connect the two devices is known as "pairing." .. note:: the Control Hub does not have its own internal battery. Before you can connect a Driver Station to the Control Hub, you must connect the - Control Hub to a 12V battery. + Control Hub to a 12V :term:`battery `. Also note that it will take an estimated 10 minutes to complete this task. @@ -337,7 +337,7 @@ task. * - 10. Find the name of your Control Hub's wireless network from the list of available WiFi networks. Click on the network name to select the network. If this is the first time you are connecting to the Control Hub, then the default network name should begin with the prefix FTC- (FTC-1Ybr in this example). The default network name should be listed on a sticker attached to the bottom side of the Control Hub. - |pairing10| - * - 11. When prompted, specify the password for the Control Hub's WiFi network and press \ **Connect** to connect to the Hub. Note that the default password for the Control Hub network is ``password``. Also note that when you connect to the Control Hub's WiFi network successfully, the DRIVER STATION will not have access to the Internet. + * - 11. When prompted, specify the password for the Control Hub's WiFi network and press \ **Connect** to connect to the :term:`Hub`. Note that the default password for the Control Hub network is ``password``. Also note that when you connect to the Control Hub's WiFi network successfully, the DRIVER STATION will not have access to the Internet. - |pairing11| * - 12. After you successfully connected to the Hub, use the back arrow to navigate to the previous screen. You should see the name of the WiFi network listed under "Current Robot Controller:". Use the back-arrow key to return to the Settings screen. Then press the back-arrow key one more time to return to the main DRIVER STATION screen. diff --git a/docs/source/programming_resources/shared/control_system_intro/The-FTC-Control-System.rst b/docs/source/programming_resources/shared/control_system_intro/The-FTC-Control-System.rst index f7a3a68ab..55b6cce6c 100644 --- a/docs/source/programming_resources/shared/control_system_intro/The-FTC-Control-System.rst +++ b/docs/source/programming_resources/shared/control_system_intro/The-FTC-Control-System.rst @@ -22,8 +22,8 @@ robot can complete, the more points a team will earn. AUTO vs. TELEOP ~~~~~~~~~~~~~~~ -A *FIRST* Tech Challenge match has an AUTO phase and a -TELEOP phase. In the AUTO phase +A *FIRST* Tech Challenge :term:`match ` has an :term:`AUTO` phase and a +:term:`TELEOP` phase. In the AUTO phase of a match the robot operates without any human input or control. In the TELEOP phase, the robot can receive input from up to two human drivers. @@ -41,20 +41,20 @@ During a competition, each team has two Android devices. One Android device is mounted onto the robot and is called the *Robot Controller*. In most cases, the ROBOT CONTROLLER is integrated into the -REV Robotics Control Hub. The Robot Controller acts as the “brains” of the +REV Robotics :term:`Control Hub`. The :term:`Robot Controller` acts as the “brains” of the robot. It does all of the thinking for the robot and tells the robot what to do. It consists of an Android device running a Robot Controller app. Many -Teams will also connect a REV Robotics Expansion Hub for additional ports to -connect motors, servos and sensors to the ROBOT. +Teams will also connect a REV Robotics :term:`Expansion Hub` for additional ports to +connect motors, :term:`servos ` and :term:`sensors ` to the ROBOT. A second Android device sits with the team drivers and has one or two -gamepads connected. This second device is known as the DRIVER STATION. +:term:`gamepads ` connected. This second device is known as the DRIVER STATION. The DRIVER STATION is like a remote control that you might use to control your television. The DRIVER STATION allows a team to communicate remotely (using a secure, wireless connection) to the Robot Controller and to issue commands to the Robot Controller. The DRIVER STATION -consists of an Android device running an Driver Station app. Most teams use -a REV Robotics Driver Hub, but select Android smartphones are also supported. +consists of an Android device running an :term:`Driver Station` app. Most teams use +a REV Robotics :term:`Driver Hub`, but select Android smartphones are also supported. REV Robotics Control Hub and Expansion Hub ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -66,7 +66,7 @@ Expansion Hub through a serial connection. For the situation where an Android smartphone is used as the Robot Controller, a USB cable is used to establish the serial connection. -The Control Hub and Expansion Hub are also connected to a 12V battery which is used to +The Control Hub and Expansion Hub are also connected to a 12V :term:`battery ` which is used to power the Control Hub, the Expansion Hub, the motors, the servos and sensors. If an Android smartphone is used as the Robot Controller, then the smartphone will have its own independent battery. @@ -81,7 +81,7 @@ Android Smartphones Teams may opt to use an Android smartphone as their DRIVER STATION, ROBOT CONTROLLER or both. DRIVER STATION phones should have the FTC Driver -Station app installed, and will need an OTG adaptor USB hub to connect gamepads. +Station app installed, and will need an :term:`OTG adaptor ` :term:`USB hub ` to connect gamepads. .. image:: images/ControlHubEquals.jpg :align: center @@ -108,7 +108,7 @@ autonomously during a match. Teams write “OpModes” (which stand for “operational modes”) to specify the behavior for their robot. An *OpMode* is a computer program that is used to customize the behavior -of a competition robot. The Robot Controller can *execute* a selected OpMode +of a competition robot. The Robot Controller can *execute* a selected :term:`OpMode` to perform certain tasks during a match. Teams who are participating in *FIRST* Tech Challenge have a variety diff --git a/docs/source/programming_resources/shared/external_libraries_blocks/external-libraries-blocks.rst b/docs/source/programming_resources/shared/external_libraries_blocks/external-libraries-blocks.rst index 8c661d38b..87e2c6780 100644 --- a/docs/source/programming_resources/shared/external_libraries_blocks/external-libraries-blocks.rst +++ b/docs/source/programming_resources/shared/external_libraries_blocks/external-libraries-blocks.rst @@ -4,9 +4,9 @@ External Libraries in OnBot Java and Blocks Introduction ------------ -Blocks and OnBot Java programmers can use external libraries, +:term:`Blocks` and :term:`OnBot Java` programmers can use external libraries, starting with SDK 7.0 released for the Freight Frenzy season. This -capability previously existed for programmers using Android Studio. +capability previously existed for programmers using :term:`Android Studio`. An external library is a collection of specialized software ready for public use, and typically available from a website or repository, called @@ -14,7 +14,7 @@ a ‘repo’. You don’t need to know its inner workings, just what it does and how to use it. This beginner-level tutorial shows how to incorporate a library’s -features into your Op Modes, and provides simple examples. It does +features into your :term:`Op Modes `, and provides simple examples. It does not teach Java. Many thanks to `Liz Looney `__ who @@ -87,9 +87,9 @@ Step 2 - Upload archive file Copy the .jar or .aar file to your programming laptop, if the file is not stored there already. -Connect your laptop via Wi-Fi to a Robot Controller device that’s +Connect your laptop via Wi-Fi to a :term:`Robot Controller` device that’s running the RC app, version 7.0 or higher (see instructions at -``Program and Manage``, on the RC phone or its paired Driver Station +``Program and Manage``, on the RC phone or its paired :term:`Driver Station` device). In the Chrome browser, open OnBot Java. In OnBot Java (OBJ) click the **upload icon**, normally used to upload a @@ -217,7 +217,7 @@ Congratulations, you are now a Java developer! Benefits -------- -Obviously this External Libraries feature provides advanced functions +Obviously this :term:`External Libraries` feature provides advanced functions previously available only to Android Studio teams. Secondly, more of your team members can continue programming the robot @@ -322,7 +322,7 @@ Here is the myBlock that will appear in the Blocks toolbox (menu): On your own, you can try this with the two remaining methods. Use -myBlocks to show telemetry output of various input values. +myBlocks to show :term:`telemetry ` output of various input values. .. figure:: images/470-myBlocks-telemetry.png @@ -377,9 +377,9 @@ to experiment with these. which is a hardware device class for the `REV Potentiometer `__. It uses ``AnalogSensorType`` and ``DeviceProperties`` annotations to make - this sensor appear in the “Configure Robot” menu of the RC app or + this :term:`sensor ` appear in the “Configure Robot” menu of the RC app or paired DS app. After the .aar file has been uploaded (and - ``Build Everything``), configure your robot’s Analog Input Devices + ``Build Everything``), configure your robot’s :term:`Analog Input` Devices and choose ``REV Potentiometer``. It has a public method ``getRotation`` with parameter of type AngleUnit. diff --git a/docs/source/programming_resources/shared/installing_javascript_browser/Installing-a-Javascript-Enabled-Browser.rst b/docs/source/programming_resources/shared/installing_javascript_browser/Installing-a-Javascript-Enabled-Browser.rst index cd5359dc8..2ce491117 100644 --- a/docs/source/programming_resources/shared/installing_javascript_browser/Installing-a-Javascript-Enabled-Browser.rst +++ b/docs/source/programming_resources/shared/installing_javascript_browser/Installing-a-Javascript-Enabled-Browser.rst @@ -1,13 +1,13 @@ Installing a Javascript Enabled Browser ======================================= -In order to be able to program your Robot Controller using the Blocks +In order to be able to program your :term:`Robot Controller` using the Blocks Programming Tool or the OnBot Java Programming tool, your laptop will need a Javascript-enabled browser. Both tools are Javascript applications that are served up by the Program and Manage server of the Robot Controller. -The Blocks Programming Tool and the OnBot Java Programming Tool should +The :term:`Blocks Programming Tool` and the :term:`OnBot Java Programming Tool` should work with most modern web browsers. However, *FIRST* strongly recommends the use of Google Chrome with these tools. If you would like to use Google Chrome as your browser, you can download it for free from the diff --git a/docs/source/programming_resources/shared/installing_kotlin/Installing-Kotlin.rst b/docs/source/programming_resources/shared/installing_kotlin/Installing-Kotlin.rst index 80235bebb..0912fa0cc 100644 --- a/docs/source/programming_resources/shared/installing_kotlin/Installing-Kotlin.rst +++ b/docs/source/programming_resources/shared/installing_kotlin/Installing-Kotlin.rst @@ -8,8 +8,8 @@ What Is Kotlin? The Kotlin programming language is a modern alternative to the Java programming language that compiles and runs on the Java Virtual Machine (JVM) and can be used to develop Android -applications. It was developed by JetBrains, the same company that developed the IntelliJ IDE -(the basis for Android Studio). +applications. It was developed by JetBrains, the same company that developed the IntelliJ :term:`IDE` +(the basis for :term:`Android Studio`). * https://kotlinlang.org/ diff --git a/docs/source/programming_resources/shared/managing_control_hub/Managing-a-Control-Hub.rst b/docs/source/programming_resources/shared/managing_control_hub/Managing-a-Control-Hub.rst index 5752b415a..8513cf478 100644 --- a/docs/source/programming_resources/shared/managing_control_hub/Managing-a-Control-Hub.rst +++ b/docs/source/programming_resources/shared/managing_control_hub/Managing-a-Control-Hub.rst @@ -4,20 +4,20 @@ Managing a Control Hub Changing the Name ~~~~~~~~~~~~~~~~~ -By default, the Control Hub has a name that begins with the phrase +By default, the :term:`Control Hub` has a name that begins with the phrase "FTC-" and ends with four characters that are assigned at the factory. -In order to comply with the Competition Manual, the name should be +In order to comply with the :term:`Competition Manual`, the name should be changed. -The name of a Control Hub (or Robot Controller phone) can be changed +The name of a Control Hub (or :term:`Robot Controller` phone) can be changed from a paired DS app, as shown in :ref:`Changing the Name`. As an alternate, you can change the name of a Control Hub at the -*Manage* page from a connected Driver Station or laptop, as described +*Manage* page from a connected :term:`Driver Station` or laptop, as described below. Click ``Apply Wi-Fi Settings`` when done. .. important:: Changing the name of a Control Hub changes the name - of the Hub's wireless network. Once the name is changed, you will have + of the :term:`Hub`'s wireless network. Once the name is changed, you will have to connect your devices (Driver Station and programming laptop) to the new network. @@ -99,7 +99,7 @@ reset the Hub's name and password back to their factory default values. .. important:: Resetting a Control Hub will restore its default network name and password. However, existing configuration files and op modes should not be affected by the reset. This includes op modes that - were created using the Blocks, OnBot Java and Android Studio tools. + were created using the :term:`Blocks`, :term:`OnBot Java` and :term:`Android Studio` tools. Resetting Instructions ----------------------- @@ -160,7 +160,7 @@ Station screen. Downloading the Log File ~~~~~~~~~~~~~~~~~~~~~~~~ -It's often helpful when troubleshooting problems with the Control System +It's often helpful when troubleshooting problems with the :term:`Control System` to download the log file from the Control Hub. This can be done from the *Manage* page. Note that the log file name is *robotControllerLog.txt* by default. @@ -187,11 +187,11 @@ Downloading the Log File Instructions Updating the Expansion Hub Firmware ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Control Hub has its own built-in REV Robotics Expansion Hub. The +The Control Hub has its own built-in REV Robotics :term:`Expansion Hub`. The purpose of the Expansion Hub board is to facilitate communication -between the Control Hub's Android controller and the motors, servos, and -sensors of the robot. Periodically, REV Robotics will release new -versions of the firmware which contains fixes and improvements for the +between the Control Hub's Android controller and the motors, :term:`servos `, and +:term:`sensors ` of the robot. Periodically, REV Robotics will release new +versions of the :term:`firmware ` which contains fixes and improvements for the Expansion Hub. The firmware releases are in the form of a binary (.bin) file. @@ -211,7 +211,7 @@ shown below. These three methods do not apply to updating the firmware of an Expansion Hub connected to a Control Hub via RS485 data wire. Standalone Expansion Hubs must be updated by direct USB plug-in to a laptop running -the REV Hardware Client or to a Robot Controller phone. +the :term:`REV Hardware Client` or to a Robot Controller phone. Uploading and Updating the Expansion Hub Firmware ------------------------------------------------- @@ -373,7 +373,7 @@ Uploading a Custom Webcam Calibration File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Robot Controller app has built-in calibration information for a -variety of commonly available webcams. Users can also create their own +variety of commonly available :term:`webcams `. Users can also create their own custom calibration files and then upload these files to a Control Hub. A commented example of what the contents of a calibration file should diff --git a/docs/source/programming_resources/shared/managing_smartphone_ds/Managing-a-Smartphone-Driver-Station.rst b/docs/source/programming_resources/shared/managing_smartphone_ds/Managing-a-Smartphone-Driver-Station.rst index 19061b105..1d5e50cc6 100644 --- a/docs/source/programming_resources/shared/managing_smartphone_ds/Managing-a-Smartphone-Driver-Station.rst +++ b/docs/source/programming_resources/shared/managing_smartphone_ds/Managing-a-Smartphone-Driver-Station.rst @@ -5,13 +5,13 @@ REV Driver Hub ~~~~~~~~~~~~~~ The `REV Driver Hub `__ -is preloaded with the Driver Station (DS) app. The procedures -described below for a REV Driver Hub, also apply to a using an Android phone as a DS. +is preloaded with the :term:`Driver Station` (DS) app. The procedures +described below for a REV :term:`Driver Hub`, also apply to a using an Android phone as a DS. Changing the Name ~~~~~~~~~~~~~~~~~ -In order to comply with the Competition Manual, the name of the Driver +In order to comply with the :term:`Competition Manual`, the name of the Driver Station (DS) should be changed. Configure devices for your team number. The ROBOT CONTROLLER, DRIVER STATION, and any spares used must be configured/named to correspond to the correct team number as follows: @@ -35,7 +35,7 @@ The Driver Hub name can be changed in the DS app, as described below. If you see a yellow circled exclamation icon on your DS screen and touch it, a message will pop up temporarily and say "*DS* does not match *DS*, see the FTC Competition Manual". - Note: *DS* is the current name of the Driver Station, and *RC* is the current Robot Controller name. + Note: *DS* is the current name of the Driver Station, and *RC* is the current :term:`Robot Controller` name. This is because the DS and RC names do not match. You should change both names to include your team number as indicated above, as required by the Competition Manual. @@ -106,8 +106,8 @@ As of 2021, all apps (v 6.1 and higher) are no longer available on Google Play. The `REV Hardware Client software `__ -will allow you to download the apps to approved devices: REV Control Hub, REV -Expansion Hub, REV Driver Hub, and approved Android devices. Here +will allow you to download the apps to approved devices: REV :term:`Control Hub`, REV +:term:`Expansion Hub`, REV Driver Hub, and approved Android devices. Here are some of the benefits: - Connect a REV Control Hub via WiFi. @@ -117,7 +117,7 @@ are some of the benefits: - Install and switch between DS and RC applications on Android Devices. - Access the Robot Control Console on the Control Hub. -All teams using Blocks, OnBot Java or Android Studio can use the REV +All teams using :term:`Blocks`, :term:`OnBot Java` or :term:`Android Studio` can use the REV Hardware Client to update the Driver Station (DS) app on a DS phone. NOTE: it will take an estimated 7.5 minutes per device to complete this diff --git a/docs/source/programming_resources/shared/managing_smartphone_rc/Managing-a-Smartphone-Robot-Controller.rst b/docs/source/programming_resources/shared/managing_smartphone_rc/Managing-a-Smartphone-Robot-Controller.rst index 88ed62ec2..a5a8afc07 100644 --- a/docs/source/programming_resources/shared/managing_smartphone_rc/Managing-a-Smartphone-Robot-Controller.rst +++ b/docs/source/programming_resources/shared/managing_smartphone_rc/Managing-a-Smartphone-Robot-Controller.rst @@ -4,23 +4,23 @@ Managing a Smartphone Robot Controller Changing the Name ~~~~~~~~~~~~~~~~~ -In order to comply with the Competition Manual, the name of the Robot +In order to comply with the :term:`Competition Manual`, the name of the Robot Controller (RC) smartphone should be changed. This can be done in the RC app or in a paired DS app, as described -below. (These steps also work for changing the name of a Control Hub, +below. (These steps also work for changing the name of a :term:`Control Hub`, from a paired DS app.) As an alternate, :ref:`Renaming Devices` show how to rename a smartphone using the Android Settings activity of the phone. .. important:: Once the name of your Robot Controller is changed, - you might need to reconnect your devices (Driver Station and programming + you might need to reconnect your devices (:term:`Driver Station` and programming laptop) to the newly changed network. Changing the Name of a Robot Controller --------------------------------------- -1. On the Robot Controller phone or paired Driver Station phone, +1. On the :term:`Robot Controller` phone or paired Driver Station phone, touch the three dots in the upper right hand corner to display a pop-up menu. @@ -119,7 +119,7 @@ Network: section under the Robot Controller's name Downloading the Log File ~~~~~~~~~~~~~~~~~~~~~~~~ -It's often helpful when troubleshooting problems with the Control System +It's often helpful when troubleshooting problems with the :term:`Control System` to download the log file from the Robot Controller. This can be done from the *Manage* page. Note that the log file name is *robotControllerLog.txt* by default. @@ -177,10 +177,10 @@ Updating the Expansion Hub Firmware ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A Robot Controller phone connects to a standalone REV Robotics Expansion -Hub using a USB connection. The purpose of the Expansion Hub is to +Hub using a USB connection. The purpose of the :term:`Expansion Hub` is to facilitate communication between the Robot Controller and the motors, -servos, and sensors of the robot. Periodically, REV Robotics may release -new versions of the firmware which contains fixes and improvements for +:term:`servos `, and :term:`sensors ` of the robot. Periodically, REV Robotics may release +new versions of the :term:`firmware ` which contains fixes and improvements for the Expansion Hub. The firmware releases are in the form of a binary (".bin") file. @@ -228,10 +228,10 @@ computer to the Robot Controller. The words "Firmware upload complete" should appear once the file has been uploaded successfully. 3. Make sure that your Expansion Hub is turned on and powered by a -freshly charged 12V battery and that the Robot Controller phone is +freshly charged 12V :term:`battery ` and that the Robot Controller phone is connected to the Expansion Hub through a USB connection. Note that the Robot Controller does **not** need to have the Expansion Hub -included in an active configuration file in order for the update to +included in an active :term:`configuration file ` in order for the update to work. .. image:: images/ConfiguringHardwareStep4.jpg @@ -316,7 +316,7 @@ Play. The `REV Hardware Client software `__ will allow you to download the apps to approved devices: REV Control Hub, REV -Expansion Hub, REV Driver Hub, and approved Android devices. Here +Expansion Hub, REV :term:`Driver Hub`, and approved Android devices. Here are some of the benefits: * Connect a REV Control Hub via WiFi. @@ -326,7 +326,7 @@ are some of the benefits: * Install and switch between DS and RC applications on Android Devices. * Access the Robot Control Console on the Control Hub. -Teams using Blocks or OnBot Java for programming can use the REV +Teams using :term:`Blocks` or :term:`OnBot Java` for programming can use the REV Hardware Client to update the Robot Controller (RC) app on an RC phone. Note it will take an estimated 7.5 minutes per device to complete this @@ -344,8 +344,8 @@ This process is called "side-loading". number. .. important:: Teams using Android Studio should not update the RC - app with the REV Hardware Client or by side-loading. Instead, by - updating to the newest version of the Android Studio project folder, + app with the :term:`REV Hardware Client` or by side-loading. Instead, by + updating to the newest version of the :term:`Android Studio` project folder, you will update the Robot Controller app when you build the project and install it on your RC device. You can download the newest version of the project folder @@ -355,7 +355,7 @@ Uploading a Custom Webcam Calibration File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Robot Controller app has built-in calibration information for a -variety of commonly available webcams. Users can also create their own +variety of commonly available :term:`webcams `. Users can also create their own custom calibration files and then upload these files to a Control Hub. A commented example of what the contents of a calibration file should diff --git a/docs/source/programming_resources/shared/myblocks/annotation/annotation.rst b/docs/source/programming_resources/shared/myblocks/annotation/annotation.rst index d96f431c0..e8d62f1af 100644 --- a/docs/source/programming_resources/shared/myblocks/annotation/annotation.rst +++ b/docs/source/programming_resources/shared/myblocks/annotation/annotation.rst @@ -11,7 +11,7 @@ custom **comment**, **tooltip**, and **parameter labels**. Comment ~~~~~~~ -- The **comment** text appears in a balloon when the Blocks user clicks +- The **comment** text appears in a balloon when the :term:`Blocks` user clicks the blue question-mark icon. Tell the user **how to use your myBlock**. - Must be entered on a **single line**, with no ‘line breaks’. This diff --git a/docs/source/programming_resources/shared/myblocks/driving_example/driving-example.rst b/docs/source/programming_resources/shared/myblocks/driving_example/driving-example.rst index 7c088e7a4..6b7752ef7 100644 --- a/docs/source/programming_resources/shared/myblocks/driving_example/driving-example.rst +++ b/docs/source/programming_resources/shared/myblocks/driving_example/driving-example.rst @@ -4,12 +4,12 @@ Driving Example Here is the Java code (method only) for converting an **inches of driving** target into an **encoder counts** target. The conversion depends on the drive motors’ counts-per-rotation (CPR), and the diameter -of the drive wheels. This example assumes 1:1 gear ratio between the +of the drive wheels. This example assumes 1:1 :term:`gear ratio ` between the motor and wheel. .. image:: images/a0400-inchesToCounts-Java.png -This method takes three inputs from the Blocks user, and **returns** one +This method takes three inputs from the :term:`Blocks` user, and **returns** one output (of type ``int`` or integer) to the regular Block that **calls** the myBlock. diff --git a/docs/source/programming_resources/shared/myblocks/editing/editing.rst b/docs/source/programming_resources/shared/myblocks/editing/editing.rst index c04d81d9f..366fa8629 100644 --- a/docs/source/programming_resources/shared/myblocks/editing/editing.rst +++ b/docs/source/programming_resources/shared/myblocks/editing/editing.rst @@ -2,7 +2,7 @@ Editing a myBlock ================= If you edit and re-Build a myBlock’s Java code, you might need to -**replace** that myBlock in the Blocks OpMode. It depends on whether you +**replace** that myBlock in the :term:`Blocks` :term:`OpMode`. It depends on whether you change the myBlock’s visible or external features: annotation fields, input parameters or returned outputs. @@ -18,7 +18,7 @@ If your edit affects only the myBlock’s **internal** processing, it might update automatically after “Build Everything”, without needing a fresh replacement from the Java Classes menu. In some cases you might not even need to click Save OpMode in the Blocks screen – you could -simply re-run the OpMode on the Driver Station with INIT and Start. This +simply re-run the OpMode on the :term:`Driver Station` with INIT and Start. This can allow very fast testing of minor/internal changes to the myBlock. In any case, consider adding **versions** to your myBlock names, such as diff --git a/docs/source/programming_resources/shared/myblocks/hardware_example/hardware-example.rst b/docs/source/programming_resources/shared/myblocks/hardware_example/hardware-example.rst index c101b65e9..c4c944a4b 100644 --- a/docs/source/programming_resources/shared/myblocks/hardware_example/hardware-example.rst +++ b/docs/source/programming_resources/shared/myblocks/hardware_example/hardware-example.rst @@ -2,7 +2,7 @@ Hardware Example: control a servo ================================= Here’s a very simple example to illustrate how a myBlock can access the -**robot hardware**. Here, the Blocks user enters the servo’s name as a +**robot hardware**. Here, the :term:`Blocks` user enters the :term:`servo `’s name as a **parameter** of the myBlock. .. image:: images/a0300-wiggle-OBJ-short.png @@ -27,14 +27,14 @@ Line 17 shows how to access **hardwareMap**, the configured devices list provided from BlocksOpModeCompanion. That single line of Java does this: - declare a new variable called myServo, of type (class) Servo - **get** the properties (methods and variables) of the named servo from -hardwareMap - assign those properties to the new variable myServo +:term:`hardwareMap` - assign those properties to the new variable myServo Line 20 is a **for loop**, which you can learn about `here `__ or `here `__. It runs the specified servo back and forth, using the specified duration and number of cycles. This **for loop** has the added condition -``opModeIsActive()``, to monitor and verify the OpMode has not been +``opModeIsActive()``, to monitor and verify the :term:`OpMode` has not been stopped. Lines 22 and 24: the object myServo uses a method ``setPosition()`` from @@ -77,7 +77,7 @@ OpMode like this: .. image:: images/a0320-wiggle-OpMode.png -The final ``.sleep`` Block allows any telemetry to remain visible on the +The final ``.sleep`` Block allows any :term:`telemetry ` to remain visible on the DS screen, before this sample OpMode ends. diff --git a/docs/source/programming_resources/shared/myblocks/ideas/ideas.rst b/docs/source/programming_resources/shared/myblocks/ideas/ideas.rst index a002b0297..31cb1b8ac 100644 --- a/docs/source/programming_resources/shared/myblocks/ideas/ideas.rst +++ b/docs/source/programming_resources/shared/myblocks/ideas/ideas.rst @@ -2,7 +2,7 @@ Ideas for Other myBlocks ======================== MyBlocks offer great potential for creativity and robot capability. -Start by programming myBlocks for tasks that an existing group of Blocks +Start by programming myBlocks for tasks that an existing group of :term:`Blocks` can do. Later, add functions that are **not available** with regular Blocks. Here are some examples of both: @@ -20,10 +20,10 @@ Blocks. Here are some examples of both: info is :ref:`here `. -- One of the above examples controls a servo specified by the Blocks +- One of the above examples controls a :term:`servo ` specified by the Blocks user. This could lead to a **family of separate myBlocks** to interact with 1 device, 2 devices, etc. Or a generic single myBlock - could interact with, say, up to 4 DC motors. The Java method would + could interact with, say, up to 4 :term:`DC motors `. The Java method would process only those DC motors with a filled-in parameter name. - Control the **LED flashlight** on the RC phone? @@ -46,7 +46,7 @@ Here are some tips for efficiency, from the developer Liz Looney: task. - Limit the number of parameters. If your myBlock needs certain - information that won’t change during the OpMode, use an **initialize + information that won’t change during the :term:`OpMode`, use an **initialize method** that’s called once at the start of the OpMode. The initialize method stores that information, to avoid repeatedly passing the same parameter each time the myBlock is called. diff --git a/docs/source/programming_resources/shared/myblocks/intro/intro.rst b/docs/source/programming_resources/shared/myblocks/intro/intro.rst index 180554b48..ec8e91314 100644 --- a/docs/source/programming_resources/shared/myblocks/intro/intro.rst +++ b/docs/source/programming_resources/shared/myblocks/intro/intro.rst @@ -2,8 +2,8 @@ Introduction ============ This tutorial shows how to make **custom Blocks**, to be used in -regular Blocks programs. These **“myBlocks”** are programmed in Java, -with OnBot Java or Android Studio. +regular :term:`Blocks` programs. These **“myBlocks”** are programmed in Java, +with :term:`OnBot Java` or :term:`Android Studio`. .. figure:: images/a0100-introSample.png @@ -40,7 +40,7 @@ Notes on Java ~~~~~~~~~~~~~ - This tutorial builds myBlocks with :ref:`OnBot Java `, - a programming tool running on the Control Hub or Robot Controller + a programming tool running on the :term:`Control Hub` or :term:`Robot Controller` (RC) phone. Students already using :ref:`Android Studio ` can easily follow the same programming. diff --git a/docs/source/programming_resources/shared/myblocks/method_example/method-example.rst b/docs/source/programming_resources/shared/myblocks/method_example/method-example.rst index d9fb352cd..448365c1c 100644 --- a/docs/source/programming_resources/shared/myblocks/method_example/method-example.rst +++ b/docs/source/programming_resources/shared/myblocks/method_example/method-example.rst @@ -10,12 +10,12 @@ To illustrate, consider the Driving Example above. Imagine you want to create myBlocks to support **two** different robots. - Robot A has **4-inch** drive wheels with AndyMark **NeveRest 40** motors. - Robot B has **3-inch** drive wheels with NeveRest **Orbital 20** motors. - You -want the myBlocks to be **very simple** for your Blocks programming +want the myBlocks to be **very simple** for your :term:`Blocks` programming teammates. Your solution: - One MyBlock per robot. - Each Blocks user needs to specify only the distance to drive, in inches. - Each myBlock uses the -appropriate wheel size and motor encoder CPR. - The myBlocks share a +appropriate wheel size and motor :term:`encoder ` CPR. - The myBlocks share a ‘utility’ method to convert distance to encoder counts. .. image:: images/a0500-non-myBlock-method-Java.png @@ -31,7 +31,7 @@ of the ‘utility’ method – but their types should match. At line 38, **(int)** converts, or **casts**, a decimal number to integer type. This is called **type casting**. Programmers must pay -close attention to compatible data types. For example, a DC motor +close attention to compatible data types. For example, a :term:`DC motor ` ``set .TargetPosition`` Block should be given an encoder value as a simple integer, not a decimal number. diff --git a/docs/source/programming_resources/shared/myblocks/parameter/parameter.rst b/docs/source/programming_resources/shared/myblocks/parameter/parameter.rst index 2a78af6a2..f504fcac8 100644 --- a/docs/source/programming_resources/shared/myblocks/parameter/parameter.rst +++ b/docs/source/programming_resources/shared/myblocks/parameter/parameter.rst @@ -3,7 +3,7 @@ More about Parameter Types Do not type or run the following myBlock example. Its dummy inputs simply illustrate various **parameter types**. This myBlock does -correctly read the robot battery voltage, but Blocks now offers a +correctly read the robot :term:`battery ` voltage, but :term:`Blocks` now offers a **VoltageSensor** Block in the **Sensors** menu. .. figure:: images/a0280-batteryVoltage.png diff --git a/docs/source/programming_resources/shared/myblocks/rw_example/rw-example.rst b/docs/source/programming_resources/shared/myblocks/rw_example/rw-example.rst index 0ce5db154..96c91c31f 100644 --- a/docs/source/programming_resources/shared/myblocks/rw_example/rw-example.rst +++ b/docs/source/programming_resources/shared/myblocks/rw_example/rw-example.rst @@ -1,7 +1,7 @@ Example: Read-Write File Access =============================== -The current version of regular Blocks (SDK 7.0) does not provide +The current version of regular :term:`Blocks` (SDK 7.0) does not provide **read/write access to an external file**, other than automatic Log or Match Log file entries. File access is a useful capability, available so far to Java programmers only. Now it can be done with myBlocks! @@ -12,19 +12,19 @@ value to a specified filename, and a companion myBlock can later .. image:: images/a0550-file-access-Blocks.png -The file is stored on the Control Hub or RC phone, in the FIRST/settings -folder. It exists separately from the RC app, OpModes, and other +The file is stored on the :term:`Control Hub` or RC phone, in the FIRST/settings +folder. It exists separately from the RC app, :term:`OpModes `, and other files. Write and read actions can happen in the same OpMode or **different OpModes**, allowing various scenarios: -- Autonomous passes information to TeleOp. For example, what was the - latest value of a sensor or encoder? +- :term:`Autonomous` passes information to :term:`TeleOp `. For example, what was the + latest value of a :term:`sensor ` or :term:`encoder `? -- A special **set-up OpMode** allows gamepad input to choose an +- A special **set-up OpMode** allows :term:`gamepad ` input to choose an autonomous strategy and adjust key parameters. The robot could then - be idle for a long time, even turned off. When the match begins, the + be idle for a long time, even turned off. When the :term:`match ` begins, the Autonomous OpMode would read those settings and implement the chosen/adjusted actions. @@ -35,8 +35,8 @@ OpModes**, allowing various scenarios: The Java code for this example is available below, with **extensive comments** that explain some unfamiliar Java -expressions. The code can be copied and pasted directly into OnBot Java -or Android Studio. +expressions. The code can be copied and pasted directly into :term:`OnBot Java` +or :term:`Android Studio`. Programming tip: Instead of memorizing every possible Java command, programmers often study and modify existing code for a similar task. diff --git a/docs/source/programming_resources/shared/myblocks/simple_example/simple-example.rst b/docs/source/programming_resources/shared/myblocks/simple_example/simple-example.rst index c0b902f02..38b81e4b8 100644 --- a/docs/source/programming_resources/shared/myblocks/simple_example/simple-example.rst +++ b/docs/source/programming_resources/shared/myblocks/simple_example/simple-example.rst @@ -4,20 +4,20 @@ Simple Example: create myGreeting Start with a simple myBlock that creates a greeting “Hello World” (of course!). -Open a Chrome browser connected via Wi-Fi to a Control Hub or RC phone. +Open a Chrome browser connected via Wi-Fi to a :term:`Control Hub` or RC phone. Go to the address **http://192.168.43.1:8080** (CH) or **http://192.168.49.1:8080** (RC), and click the **OnBot Java** tab. .. note:: A computer can usually connect to only one Wi-Fi network at a time. To follow this tutorial while programming please use the PDF version - of FTC Docs. If you need internet and programming together, + of :term:`FTC Docs`. If you need internet and programming together, connect an Ethernet cable to an internet router **or** try adding a USB Wi-Fi dongle. Click the large **plus-sign icon** to open a new file; call it **SampleMyBlocks.java**. Use the default ‘teamcode’ folder location. -Don’t choose a Sample OpMode, and use the default setting ‘Not an -OpMode’. Click OK. +Don’t choose a :term:`Sample OpMode`, and use the default setting ‘Not an +:term:`OpMode`’. Click OK. .. image:: images/a0120-Hello-OBJ-circle.png @@ -54,7 +54,7 @@ When you enter that line, the OBJ software **automatically** creates an ``import`` statement, making the parent class available. Convenient! Programming note: classes inherited from BlocksOpModeCompanion - include OpMode, LinearOpMode, Telemetry, HardwareMap, and Gamepad. + include OpMode, :term:`LinearOpMode`, :term:`Telemetry`, HardwareMap, and :term:`Gamepad`. All very useful! Your myBlock method can directly use **objects** or **instances** of these classes without declaring them. Examples follow below. @@ -100,7 +100,7 @@ inside the parentheses, indicating the method takes one **input** named The method contains only one line of instruction, on Line 15: **three text items are joined to form a single text string**. The middle text item is the input parameter greetingRecipient, to be entered by the -Blocks user. The longer combined string is returned to the program that +:term:`Blocks` user. The longer combined string is returned to the program that called this method. Namely, the combined string is provided to the Block that uses your new myBlock. @@ -155,14 +155,14 @@ OpMode, before **Telemetry.update**. Click **Save OpMode**. .. image:: images/a0190-Hello-run-OpMode-circle.png -On a connected Driver Station device, select this OpMode called +On a connected :term:`Driver Station` device, select this OpMode called Test_myBlocks_v01, touch **INIT** and the **Start Arrow**. Look at the Driver Station (DS) screen to see the traditional greeting for new programmers. .. image:: images/a0200-Hello-run-screenshot-circle.png -\ **Congratulations!** You are now an OnBot Java programmer and myBlocks +\ **Congratulations!** You are now an :term:`OnBot Java` programmer and myBlocks creator. For extra fun: try the **Telemetry.speak** Block, followed by a 1500 diff --git a/docs/source/programming_resources/shared/myblocks/summary/summary.rst b/docs/source/programming_resources/shared/myblocks/summary/summary.rst index b0a4cc914..5ae60e4f2 100644 --- a/docs/source/programming_resources/shared/myblocks/summary/summary.rst +++ b/docs/source/programming_resources/shared/myblocks/summary/summary.rst @@ -2,7 +2,7 @@ Summary: Benefits of myBlocks ============================= 1. MyBlocks now provide access to the full range of Java in the - Software Development Kit (SDK). Blocks programming can now perform + :term:`Software Development Kit` (SDK). :term:`Blocks` programming can now perform tasks **previously unavailable** to Blocks-only teams. This now includes :ref:`External Libraries ` or :term:`encoder ` data. A higher interval can ease the RC-DS communication bandwidth load. Here’s the Java code for the method only: diff --git a/docs/source/programming_resources/shared/myblocks/timer_example/timer-example.rst b/docs/source/programming_resources/shared/myblocks/timer_example/timer-example.rst index a6e808e74..de3234ba3 100644 --- a/docs/source/programming_resources/shared/myblocks/timer_example/timer-example.rst +++ b/docs/source/programming_resources/shared/myblocks/timer_example/timer-example.rst @@ -8,10 +8,10 @@ you can easily apply its lessons to Java programs. When creating myBlocks, be careful when converting or ‘packaging’ a section of existing Java code into a myBlock method. As a programmer, -you must consider **where** your myBlock might be placed in the OpMode. +you must consider **where** your myBlock might be placed in the :term:`OpMode`. For example, if the myBlock is placed inside a **repeat while loop**, the Java method will be called many times – this may or may not be what -you intended. Use the annotation **comment** to tell the Blocks user how +you intended. Use the annotation **comment** to tell the :term:`Blocks` user how your myBlock should be run, including looping (or not). A particular caution with timers: creating or **instantiating** a new @@ -61,11 +61,11 @@ always show **zero**. Or, a programmer might use Line 15 to **replace** Line 29, since they “do the same thing”. But the object **myStopwatch** is needed at Line 24 -also, for telemetry. Moving the telemetry to be **after** Line 29 does -not help. If the operator has not yet pressed gamepad button X, the +also, for :term:`telemetry `. Moving the telemetry to be **after** Line 29 does +not help. If the operator has not yet pressed :term:`gamepad ` button X, the object does not exist and the program will crash. -When you clicked “Build Everything” in OnBot Java, all of the code in +When you clicked “Build Everything” in :term:`OnBot Java`, all of the code in your SampleMyBlocks class was processed. That included creating the object myStopwatch, which became available for any method in that class. It was not necessary to declare it inside the myBlock method. In this @@ -83,7 +83,7 @@ clear. .. note:: This tutorial intends for you to **manually type** the Java code above. OnBot Java helps by suggesting some code as you type, and - by entering import statements when classes are used. Android Studio + by entering import statements when classes are used. :term:`Android Studio` helps even more. If you require pre-typed text of this example see below. The linked copy includes more Java comments, omitted above to focus on the Java code. Also not shown are the package and import diff --git a/docs/source/programming_resources/shared/phone_pairing/phone-pairing.rst b/docs/source/programming_resources/shared/phone_pairing/phone-pairing.rst index bee94f39c..678bcd889 100644 --- a/docs/source/programming_resources/shared/phone_pairing/phone-pairing.rst +++ b/docs/source/programming_resources/shared/phone_pairing/phone-pairing.rst @@ -4,7 +4,7 @@ Phone Pairing Introduction ------------ -The Robot Controller and Driver Station apps are extremely +The :term:`Robot Controller` and :term:`Driver Station` apps are extremely reliable for pairing, including between **all models of legal phones**. Please see the `Competition Manual `__ for list of phone models currently legal to use at *FIRST* @@ -14,7 +14,7 @@ When the Android phones have been suitably prepared, pairing via Wi-Fi Direct is **fast** and usually **automatic**. Here is a procedure that addresses various **pre-existing conditions** that can impede pairing. -This article does not cover the REV Control Hub or REV Driver Hub. +This article does not cover the REV :term:`Control Hub` or REV :term:`Driver Hub`. Phone Cleanup and Prep ---------------------- @@ -29,7 +29,7 @@ Phone Cleanup and Prep 3. RC phone, Apps/Settings/Wi-Fi. Manually select and Forget any saved Networks. -4. RC phone, still in WiFi menu: navigate to Wi-Fi Direct menu (via More +4. RC phone, still in WiFi menu: navigate to :term:`Wi-Fi Direct` menu (via More Settings or Advanced). - Select and forget/disconnect any connections with Peer Devices, diff --git a/docs/source/programming_resources/shared/pid_coefficients/pid-coefficients.rst b/docs/source/programming_resources/shared/pid_coefficients/pid-coefficients.rst index 6c11a7883..75df08ff8 100644 --- a/docs/source/programming_resources/shared/pid_coefficients/pid-coefficients.rst +++ b/docs/source/programming_resources/shared/pid_coefficients/pid-coefficients.rst @@ -1,7 +1,7 @@ Changing PID Coefficients ========================== -The REV Robotics Control Hub and REV Robotics Expansion Hub allow a user to change the PID +The REV Robotics :term:`Control Hub` and REV Robotics :term:`Expansion Hub` allow a user to change the PID coefficients used for closed loop motor control. The PID coefficients are channel and mode specific. diff --git a/docs/source/programming_resources/shared/pidf_coefficients/pidf-coefficients.rst b/docs/source/programming_resources/shared/pidf_coefficients/pidf-coefficients.rst index 9847fff7c..499f8c62b 100644 --- a/docs/source/programming_resources/shared/pidf_coefficients/pidf-coefficients.rst +++ b/docs/source/programming_resources/shared/pidf_coefficients/pidf-coefficients.rst @@ -1,11 +1,11 @@ Changing PIDF Coefficients =========================== -The REV Robotics Control Hub or REV Robotics Expansion Hub allows a user to change the PIDF +The REV Robotics :term:`Control Hub` or REV Robotics :term:`Expansion Hub` allows a user to change the :term:`PIDF` coefficients used for closed loop motor control. The PIDF coefficients are specific to each channel (motor port) and to each RunMode. -The following sample OpMode uses an extended or enhanced DcMotor class +The following sample :term:`OpMode` uses an extended or enhanced DcMotor class (called “DcMotorEx”) to change the PIDF coefficients for the RUN_USING_ENCODER RunMode for a motor named “left_drive”. The OpMode uses the setPIDFCoefficients method of the DcMotorEx class to change the diff --git a/docs/source/programming_resources/shared/program_and_manage_network/Connecting-a-Laptop-to-the-Program-&-Manage-Network.rst b/docs/source/programming_resources/shared/program_and_manage_network/Connecting-a-Laptop-to-the-Program-&-Manage-Network.rst index 30d0cca6f..862842bea 100644 --- a/docs/source/programming_resources/shared/program_and_manage_network/Connecting-a-Laptop-to-the-Program-&-Manage-Network.rst +++ b/docs/source/programming_resources/shared/program_and_manage_network/Connecting-a-Laptop-to-the-Program-&-Manage-Network.rst @@ -4,9 +4,9 @@ Connecting a Laptop to the Program & Manage Network Connecting Your Laptop to the Program & Manage Network ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to write an Op Mode, you will need to connect your programming +In order to write an :term:`Op Mode `, you will need to connect your programming laptop to the Program & Manage Wi-Fi network. The Program & Manage Wi-Fi -network is a wireless network created by your Robot Controller. Before +network is a wireless network created by your :term:`Robot Controller`. Before you begin this exercise, please make sure that your Windows laptop has the most current service pack and system update from Microsoft installed. @@ -30,7 +30,7 @@ access information. | 2. The Program & Manage screen displays important information that -you can use to connect your laptop to the Blocks or OnBot Java +you can use to connect your laptop to the :term:`Blocks` or :term:`OnBot Java` Programming Mode server. .. image:: images/ProgramAndManageScreen.jpg @@ -51,7 +51,7 @@ network name will begin with the phrase "DIRECT-". | -If you are using a Control Hub, then the wireless network name will be whatever you specified when you configured your Control Hub. If you haven't changed the Control Hub's name yet, then by default the wireless network's name will begin with "FTC-". If you haven't changed its password yet, then by default the wireless network's passphrase will be "password". +If you are using a :term:`Control Hub`, then the wireless network name will be whatever you specified when you configured your Control Hub. If you haven't changed the Control Hub's name yet, then by default the wireless network's name will begin with "FTC-". If you haven't changed its password yet, then by default the wireless network's passphrase will be "password". In the screenshot below, the Control Hub's wireless network name is "FTC-1Ybr" and the secure passphrase is "password". diff --git a/docs/source/programming_resources/shared/required_materials/Required-Materials.rst b/docs/source/programming_resources/shared/required_materials/Required-Materials.rst index 1d58713c3..06aa21058 100644 --- a/docs/source/programming_resources/shared/required_materials/Required-Materials.rst +++ b/docs/source/programming_resources/shared/required_materials/Required-Materials.rst @@ -50,13 +50,13 @@ tutorials, you will need to have the following materials available: * - Required Item(s) - Image - * - A REV Robotics Control Hub to be used as a ROBOT CONTROLLER. - Alternately, the Competition Manual does allow teams to instead - use a REV Robotics Expansion Hub and a select list of Android + * - A REV Robotics :term:`Control Hub` to be used as a ROBOT CONTROLLER. + Alternately, the :term:`Competition Manual` does allow teams to instead + use a REV Robotics :term:`Expansion Hub` and a select list of Android phones. - |chandphones| |exhub| - * - A REV Robotics Driver Hub to be used as a DRIVER STATION device. + * - A REV Robotics :term:`Driver Hub` to be used as a DRIVER STATION device. Alternately, the Competition Manual does allow teams to instead use a select list of Android phones. See rule R901 for the full details. @@ -65,7 +65,7 @@ tutorials, you will need to have the following materials available: * - Wireless Internet access. - |wifi| - * - Laptop with Microsoft Windows 7, 8, 10 or 11 and Wi-Fi capability. Note that your laptop should have the most current service packs and system updates from Microsoft. If you are using a different type of machine (such as a Chromebook, Android Tablet, etc.) as your programming device, the steps might differ slightly on how to access the Programming Server on the Robot Controller. Refer to your device’s user documentation for details on how to connect to a Wi-Fi network. + * - Laptop with Microsoft Windows 7, 8, 10 or 11 and Wi-Fi capability. Note that your laptop should have the most current service packs and system updates from Microsoft. If you are using a different type of machine (such as a Chromebook, Android Tablet, etc.) as your programming device, the steps might differ slightly on how to access the Programming Server on the :term:`Robot Controller`. Refer to your device’s user documentation for details on how to connect to a Wi-Fi network. - |laptop| * - Javascript-enabled web browser (Google Chrome is the recommended browser). @@ -81,26 +81,26 @@ tutorials, you will need to have the following materials available: - |motor| - * - If you are using an approved 12V battery that has a Tamiya connector (like the Tetrix W39057 battery) you will need a REV Robotics Tamiya to XT30 Adapter Cable (REV-31-1382). If you have a REV Robotics Slim Battery (REV-31-1302) then you will not need this adapter since the REV battery already has an XT30 connector. + * - If you are using an approved 12V :term:`battery ` that has a Tamiya connector (like the Tetrix W39057 battery) you will need a REV Robotics Tamiya to XT30 Adapter Cable (REV-31-1382). If you have a REV Robotics Slim Battery (REV-31-1302) then you will not need this adapter since the REV battery already has an XT30 connector. - |tamiya| * - REV Robotics Anderson to JST VH Cable (REV-31-1381). - |jst| - * - 180-Degree Standard Scale Servo (such as Hitec HS-485HB). + * - 180-Degree Standard Scale :term:`Servo` (such as Hitec HS-485HB). - |servo| - * - REV Robotics Color Sensor with 4-Pin Cable (REV-31-1154). + * - REV Robotics Color :term:`Sensor` with 4-Pin Cable (REV-31-1154). - |color| - * - REV Robotics Touch Sensor with 4-Pin Cable( REV-31-1425). + * - REV Robotics :term:`Touch Sensor` with 4-Pin Cable( REV-31-1425). - |touch| - * - Logitech F310 USB Gamepad. + * - Logitech F310 USB :term:`Gamepad`. - |f310| * - If you are using a smartphone as your Robot Controller, you will need a USB Type A male to type mini-B male cable. Control Hub users do not need this cable. - |usba| - * - If you are using a smartphone as your Robot Controller, you will need two (2) micro USB OTG adapters. If you are using a Control Hub as your Robot Controller, you will need one(1) micro USB OTG adapter. + * - If you are using a smartphone as your Robot Controller, you will need two (2) micro USB :term:`OTG adapters `. If you are using a Control Hub as your Robot Controller, you will need one(1) micro USB OTG adapter. - |otg| |otg| diff --git a/docs/source/programming_resources/shared/using_android_device/Using-Your-Android-Device.rst b/docs/source/programming_resources/shared/using_android_device/Using-Your-Android-Device.rst index ae0b70b93..ad3205165 100644 --- a/docs/source/programming_resources/shared/using_android_device/Using-Your-Android-Device.rst +++ b/docs/source/programming_resources/shared/using_android_device/Using-Your-Android-Device.rst @@ -7,14 +7,14 @@ familiarize yourself with the basic operation of your Android device. REV Robotics Driver Hub ~~~~~~~~~~~~~~~~~~~~~~~ -Teams who are using the REV Robotics Driver Hub as their DRIVER STATION +Teams who are using the REV Robotics :term:`Driver Hub` as their DRIVER STATION should refer to the `official documentation from REV Robotics `_ for instructions on how to set up and use the REV Robotics Driver Hub. Android Smartphone ~~~~~~~~~~~~~~~~~~ -While not recommended, the Competition Manual does allow select Android +While not recommended, the :term:`Competition Manual` does allow select Android smartphones to be used as a DRIVER STATION or ROBOT CONTROLLER. See rule R704 for the full details. diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/controlling_a_servo/Controlling-a-Servo-(Android-Studio).rst b/docs/source/programming_resources/tutorial_specific/android_studio/controlling_a_servo/Controlling-a-Servo-(Android-Studio).rst index 9e9c0e8a6..cf16358a0 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/controlling_a_servo/Controlling-a-Servo-(Android-Studio).rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/controlling_a_servo/Controlling-a-Servo-(Android-Studio).rst @@ -1,8 +1,8 @@ Controlling a Servo :bdg-success:`AS` ===================================== -In this section, you will modify your op mode to control a servo motor -with the buttons of the gamepad. +In this section, you will modify your op mode to control a :term:`servo ` motor +with the buttons of the :term:`gamepad `. What is a Servo Motor? ~~~~~~~~~~~~~~~~~~~~~~ @@ -24,7 +24,7 @@ even if external forces are applied to the shaft of the servo. | Servo motors are useful when you want to do precise movements (for -example, sweep an area with a sensor to look for a target or move the +example, sweep an area with a :term:`sensor ` to look for a target or move the control surfaces on a remotely controlled airplane). Modifying Your Op Mode to Control a Servo @@ -95,8 +95,8 @@ F310 gamepad are pressed. If the Y button is pressed, it will move the servo to the 0-degree position. If either the X button or B button is pressed, it will move the servo to the 90-degree position. If the A button is pressed, it will move the servo to the 180-degree position. -The op mode will also send telemetry data on the servo position to the -Driver Station. +The op mode will also send :term:`telemetry ` data on the servo position to the +:term:`Driver Station`. After you have modified your op mode, you can build it and then run it. Verify that gamepad #1 is still configured and then use the colored diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/creating_op_modes/Creating-and-Running-an-Op-Mode-(Android-Studio).rst b/docs/source/programming_resources/tutorial_specific/android_studio/creating_op_modes/Creating-and-Running-an-Op-Mode-(Android-Studio).rst index 50a71dd93..14b29ec03 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/creating_op_modes/Creating-and-Running-an-Op-Mode-(Android-Studio).rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/creating_op_modes/Creating-and-Running-an-Op-Mode-(Android-Studio).rst @@ -4,10 +4,10 @@ Creating and Running an OpMode :bdg-success:`AS` TeamCode Module ~~~~~~~~~~~~~~~ -If you successfully imported the Android Studio project folder, you +If you successfully imported the :term:`Android Studio` project folder, you will see on the project browser an Android module named ``TeamCode``. The Android Studio project folder will be used to build a version of the -Robot Controller app that includes the custom OpMode that you will +:term:`Robot Controller` app that includes the custom :term:`OpMode` that you will write to control your competition robot. .. image:: images/teamcodeFolder.jpg @@ -23,7 +23,7 @@ Studio project folder. Javadoc Reference Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Javadoc reference documentation for the SDK is available online. +The :term:`Javadoc` reference documentation for the SDK is available online. Visit the following URL to view the SDK documentation: * https://javadoc.io/doc/org.firstinspires.ftc @@ -206,16 +206,16 @@ replace the ``@TeleOp`` with an ``@Autonomous`` annotation instead. You can see from the sample code that an OpMode is defined as a Java class. In this example, the OpMode name is called ``MyFIRSTJavaOpMode`` -and it inherits characteristics from the LinearOpMode class. +and it inherits characteristics from the :term:`LinearOpMode` class. .. code-block:: java public class MyFIRSTJavaOpMode extends LinearOpMode { -You can also see that the OnBot Java editor created five private member +You can also see that the :term:`OnBot Java` editor created five private member variables for this OpMode. These variables will hold references to the five configured devices that the OnBot Java editor detected in the -configuration file of your Robot Controller. +:term:`configuration file ` of your Robot Controller. .. code-block:: java @@ -253,16 +253,16 @@ Note that when you attempt to retrieve a reference to a specific device in your OpMode, the name that you specify as the second argument of the ``HardwareMap.get`` method must match the name used to define the device in your configuration file. For example, if you created a configuration -file that had a DC motor named ``motorTest``, then you must use this same +file that had a :term:`DC motor ` named ``motorTest``, then you must use this same name (it is case sensitive) to retrieve this motor from the ``hardwareMap`` object. If the names do not match, the OpMode will throw an exception indicating that it cannot find the device. In the next few statements of the example, the OpMode prompts the user to push the start button to continue. It uses another object that is -available in the ``runOpMode`` method. This object is called telemetry and +available in the ``runOpMode`` method. This object is called :term:`telemetry ` and the OpMode uses the ``addData`` method to add a message to be sent to the -Driver Station. The OpMode then calls the update method to send the +:term:`Driver Station`. The OpMode then calls the update method to send the message to the Driver Station. Then it calls the ``waitForStart`` method, to wait until the user pushes the start button on the driver station to begin the OpMode run. @@ -306,8 +306,8 @@ that the laptop has USB debugging permission for the phone. | -Or, if you are using a Control Hub, verify that the Control Hub is -powered by a freshly charged 12V battery, and that it is connected to +Or, if you are using a :term:`Control Hub`, verify that the Control Hub is +powered by a freshly charged 12V :term:`battery `, and that it is connected to your laptop through its USB Type C port. Note that the Control Hub should automatically have USB debugging permission enabled. @@ -441,7 +441,7 @@ Modifying Your OpMode to Control a Motor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's modify your OpMode to control the DC motor that you connected and -configured for your REV Robotics Control Hub or REV Robotics Expansion Hub. Modify the code for the program +configured for your REV Robotics Control Hub or REV Robotics :term:`Expansion Hub`. Modify the code for the program loop so that it looks like the following: .. code-block:: java @@ -473,7 +473,7 @@ negative value of the gamepad1's left joystick: tgtPower = -this.gamepad1.left_stick_y; The object ``gamepad1`` is available for you to access in the ``runOpMode`` -method. It represents the state of gamepad #1 on your Driver Station. +method. It represents the state of :term:`gamepad ` #1 on your Driver Station. Note that for the F310 gamepads that are used during the competition, the Y value of a joystick ranges from -1, when a joystick is in its topmost position, to +1, when a joystick is in its bottommost position. @@ -513,7 +513,7 @@ or other approved gamepad to the Driver Station. Connect the gamepad to the Driver Station. If using a REV Robotics Driver Hub, you can directly connect the gamepad to one of the USB-A ports. On a -DRIVER STATION phone, you will need a Micro USB OTG adapter cable. +DRIVER STATION phone, you will need a Micro USB :term:`OTG adapter ` cable. .. image:: images/GamepadDHConnection.jpg :align: center diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/downloading_as_project_folder/Downloading-the-Android-Studio-Project-Folder.rst b/docs/source/programming_resources/tutorial_specific/android_studio/downloading_as_project_folder/Downloading-the-Android-Studio-Project-Folder.rst index f070bc5bc..b3b307801 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/downloading_as_project_folder/Downloading-the-Android-Studio-Project-Folder.rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/downloading_as_project_folder/Downloading-the-Android-Studio-Project-Folder.rst @@ -3,7 +3,7 @@ Downloading the Android Studio Project Folder :bdg-success:`AS` The SDK can be downloaded from a GitHub repository. GitHub is a web-based version control company that lets individuals and organizations host content -online. In order to access the Android Studio software, you will need to have a +online. In order to access the :term:`Android Studio` software, you will need to have a GitHub account. You can create one for free by visiting the GitHub website: * https://github.com/ diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/enabling_developer_options/Enabling-Developer-Options.rst b/docs/source/programming_resources/tutorial_specific/android_studio/enabling_developer_options/Enabling-Developer-Options.rst index f512dd2dd..f91f3899c 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/enabling_developer_options/Enabling-Developer-Options.rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/enabling_developer_options/Enabling-Developer-Options.rst @@ -4,11 +4,11 @@ Enabling Developer Options :bdg-success:`AS` After you have configured your Android phone, you will also have to make sure that your phone is in developer mode before you will be able to install apps onto the phone using the tools that are included with -Android Studio. +:term:`Android Studio`. .. important:: Control Hub Users - The Control Hub has Developer Options automatically enabled from the factory, so you do **NOT** need to do - this step for your Control Hub. + this step for your :term:`Control Hub`. The Android Developer website contains information on how to enable Developer Options onto your phone. If you visit the following link and diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/fork_and_clone_github_repository/Fork-and-Clone-From-GitHub.rst b/docs/source/programming_resources/tutorial_specific/android_studio/fork_and_clone_github_repository/Fork-and-Clone-From-GitHub.rst index 7b139109e..f2b7f9cf9 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/fork_and_clone_github_repository/Fork-and-Clone-From-GitHub.rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/fork_and_clone_github_repository/Fork-and-Clone-From-GitHub.rst @@ -5,7 +5,7 @@ Fork and Clone from GitHub :bdg-success:`AS` This approach assumes a basic familiarity with `git `_ and `GitHub `_. As with most things related to git there are many different ways to satisfy any objective. This documentation describes one method for Windows users. - Users not comfortable with command line tools and git should obtain the SDK + Users not comfortable with command line tools and git should obtain the :term:`SDK` via :doc:`Downloading the SDK as a zip archive <../downloading_as_project_folder/Downloading-the-Android-Studio-Project-Folder>`. diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst index c1763ea3c..bb1c80087 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst @@ -4,7 +4,7 @@ Installing Android Studio :bdg-success:`AS` Android Developer Website ~~~~~~~~~~~~~~~~~~~~~~~~~ -Android Studio is distributed freely by Google, and the most up-to-date +:term:`Android Studio` is distributed freely by Google, and the most up-to-date reference for installing and using the Android Studio software can be found on the Android developer website: diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/using_sensors/Using-Sensors-(Android-Studio).rst b/docs/source/programming_resources/tutorial_specific/android_studio/using_sensors/Using-Sensors-(Android-Studio).rst index d424759ff..e420a5279 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/using_sensors/Using-Sensors-(Android-Studio).rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/using_sensors/Using-Sensors-(Android-Studio).rst @@ -4,7 +4,7 @@ Using Sensors :bdg-success:`AS` Color-Distance Sensor ~~~~~~~~~~~~~~~~~~~~~ -A sensor is a device that lets the Robot Controller get information +A :term:`sensor ` is a device that lets the :term:`Robot Controller` get information about its environment. In this example, you will use a REV Robotics Color-Distance sensor to display range (distance from an object) info to the driver station. @@ -16,8 +16,8 @@ time this document was most recently edited, the REV Color-Range sensor saturates around 2" (5cm). This means that for distances less than or equal to 2", the sensor returns a measured distance equal to 2" or so. -Modify your op mode to add a telemetry statement that will send the -distance information (in centimeters) to the Driver Station. +Modify your op mode to add a :term:`telemetry ` statement that will send the +distance information (in centimeters) to the :term:`Driver Station`. .. code-block:: java @@ -38,8 +38,8 @@ sensor saturates at around 5 cm. Touch Sensor ~~~~~~~~~~~~ -The REV Robotics Touch Sensor can be connected to a digital port on the -Control Hub or Expansion Hub. The Touch Sensor is HIGH (returns TRUE) when it is not +The REV Robotics :term:`Touch Sensor` can be connected to a digital port on the +:term:`Control Hub` or :term:`Expansion Hub`. The Touch Sensor is HIGH (returns TRUE) when it is not pressed. It is pulled LOW (returns FALSE) when it is pressed. .. image:: images/REVTouchSensor.jpg diff --git a/docs/source/programming_resources/tutorial_specific/blocks/blocks_reference/Blocks-Reference-Material.rst b/docs/source/programming_resources/tutorial_specific/blocks/blocks_reference/Blocks-Reference-Material.rst index 4a1f74138..e5422e3f1 100644 --- a/docs/source/programming_resources/tutorial_specific/blocks/blocks_reference/Blocks-Reference-Material.rst +++ b/docs/source/programming_resources/tutorial_specific/blocks/blocks_reference/Blocks-Reference-Material.rst @@ -6,7 +6,7 @@ Blocks Reference Manual As you start to write more complicated op modes, you will need to use more features of the FIRST Tech Challenge software development kit -(SDK). Bruce Schafer of the Oregon Robotics Tournament & Outreach +(SDK). Bruce Schafer of the Oregon Robotics :term:`Tournament` & Outreach Program (ORTOP) created a useful reference document that describes the programming blocks that are available with the Blocks Programming Tool: @@ -17,7 +17,7 @@ Manual ` you learned how to use -the Blocks Programming Tool to write an op mode that controls a 12V -DC motor. In this section, you will learn how to write an op mode that -controls a servo motor. +the :term:`Blocks Programming Tool` to write an op mode that controls a 12V +:term:`DC motor `. In this section, you will learn how to write an op mode that +controls a :term:`servo ` motor. What is a Servo Motor? ~~~~~~~~~~~~~~~~~~~~~~ @@ -27,7 +27,7 @@ even if external forces are applied to the shaft of the servo. | Servo motors are useful when you want to do precise movements (for -example, sweep an area with a sensor to look for a target or move the +example, sweep an area with a :term:`sensor ` to look for a target or move the control surfaces on a remotely controlled airplane). Modifying Your Op Mode to Control a Servo @@ -35,7 +35,7 @@ Modifying Your Op Mode to Control a Servo Let's modify your op mode to add the logic required to control a servo motor. For this example, you will use the buttons on the Logitech F310 -gamepad to control the position of the servo motor. +:term:`gamepad ` to control the position of the servo motor. With a typical servo, you can specify a target position for the servo. The servo will turn its motor shaft to move to the target position, and @@ -289,7 +289,7 @@ field. This set of blocks will send the current servo position value to the DRIVER STATION while the op mode is running. 25. Save your op mode and verify that it was saved successfully to -the Robot Controller. +the :term:`Robot Controller`. .. image:: images/ControlServoStep25ControlHub.jpg :align: center diff --git a/docs/source/programming_resources/tutorial_specific/blocks/creating_op_modes/Writing-an-Op-Mode-with-FTC-Blocks.rst b/docs/source/programming_resources/tutorial_specific/blocks/creating_op_modes/Writing-an-Op-Mode-with-FTC-Blocks.rst index 7a4cb82f7..235cf5636 100644 --- a/docs/source/programming_resources/tutorial_specific/blocks/creating_op_modes/Writing-an-Op-Mode-with-FTC-Blocks.rst +++ b/docs/source/programming_resources/tutorial_specific/blocks/creating_op_modes/Writing-an-Op-Mode-with-FTC-Blocks.rst @@ -5,7 +5,7 @@ Creating Op Modes :bdg-warning:`Blocks` What's an Op Mode? ~~~~~~~~~~~~~~~~~~ -During a typical *FIRST* Tech Challenge match, a team's robot must +During a typical *FIRST* Tech Challenge :term:`match `, a team's robot must perform a variety of tasks to score points. For example, a team might want their robot to follow a white line on the competition floor and then score a game element into a goal autonomously during a match. Teams @@ -21,8 +21,8 @@ Tool to write an op mode for a robot. The Blocks Programming Tool ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Blocks Programming Tool is a user-friendly programming tool that -is served up by the Robot Controller. A user can create custom op modes +The :term:`Blocks Programming Tool` is a user-friendly programming tool that +is served up by the :term:`Robot Controller`. A user can create custom op modes for their robot using this tool and then save these op modes directly onto the Robot Controller. Users drag and drop jigsaw-shaped programming blocks onto a design "canvas" and arrange these blocks to create the @@ -46,7 +46,7 @@ Blocks Programming Tool. | Note that the process used to create and edit an op mode is identical if -you are using a Control Hub as your Robot Controller. +you are using a :term:`Control Hub` as your Robot Controller. .. image:: images/BlocksPicture2b.jpg :align: center @@ -120,7 +120,7 @@ navigate to the main Blocks Programming screen. | - The main Blocks Programming screen is where you create new op modes. It is also the screen where you can see a list of existing Blocks Op Modes on a Robot Controller. Initially this list will be empty until you create and save your first op mode. + The main Blocks Programming screen is where you create new op modes. It is also the screen where you can see a list of existing Blocks :term:`Op Modes ` on a Robot Controller. Initially this list will be empty until you create and save your first op mode. .. image:: images/WritingFirstOpModeStep3bControlHub.jpg :align: center @@ -247,14 +247,14 @@ Controlling a DC Motor ~~~~~~~~~~~~~~~~~~~~~~ In this section, you will add some blocks to your op mode that will -allow you to control a DC motor with a gamepad. +allow you to control a :term:`DC motor ` with a :term:`gamepad `. Note that you will need an estimated 15 minutes to complete this task. .. important:: The programming blocks for user configured devices (motors, servos and sensors) will only be visible in the Blocks tool if there is an active configuration file with the configured devices included in the file. If a type of device is not included in the active configuration file, then its programming blocks will be missing from the palette of blocks. If you did not :doc:`create and activate a configuration file yet ` please follow :doc:`this link ` -to do so. After you created and activated your configuration file, +to do so. After you created and activated your :term:`configuration file `, you can close and then reopen your op mode so that the programming blocks for the newly configured devices will be visible. @@ -395,11 +395,11 @@ Inserting Telemetry Statements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Your op mode is just about ready to run. However, before continuing, you -will add a couple of telemetry statements that will send information +will add a couple of :term:`telemetry ` statements that will send information from the Robot Controller to the DRIVER STATION for display on the DRIVER STATION user interface. This telemetry mechanism is a useful way to display status information from the robot on the DRIVER STATION. You -can use this mechanism to display sensor data, motor status, gamepad +can use this mechanism to display :term:`sensor ` data, motor status, gamepad state, etc. from the Robot Controller to the DRIVER STATION. Note that you will need an estimated 15 minutes to complete this task. diff --git a/docs/source/programming_resources/tutorial_specific/blocks/managing_opmodes/managing-opmodes.rst b/docs/source/programming_resources/tutorial_specific/blocks/managing_opmodes/managing-opmodes.rst index 3ea334e57..aa25858bb 100644 --- a/docs/source/programming_resources/tutorial_specific/blocks/managing_opmodes/managing-opmodes.rst +++ b/docs/source/programming_resources/tutorial_specific/blocks/managing_opmodes/managing-opmodes.rst @@ -1,7 +1,7 @@ Managing OpModes in Blocks :bdg-warning:`Blocks` ================================================ -Blocks is a programming language that uses graphical programming elements to +:term:`Blocks` is a programming language that uses graphical programming elements to create programs. As such its file format is different than, say, a JAVA or other text-based programming language file. Blocks programs are saved with a **.blk** extension, but its contents are actually formatted as XML (Extensible @@ -9,8 +9,8 @@ Markup Language). The actual XML format in a Blocks program is beyond the scope of this document, except to say that it's not intended to be read/viewed/interpreted by any other program than Blocks. There is not a general program on a MAC or a PC that can view or edit the Blocks program, it -must always be done through the Blocks interface within the Robot Controller -App (running on a REV Control Hub or legal Android SmartPhone) - that is, to +must always be done through the Blocks interface within the :term:`Robot Controller` +App (running on a REV :term:`Control Hub` or legal Android SmartPhone) - that is, to say, you cannot simply double-click on the file to open it up in an editor program that lives on your computer. @@ -21,14 +21,14 @@ There is a :doc:`great tutorial for creating OpModes <../creating_op_modes/Writing-an-Op-Mode-with-FTC-Blocks>` that also explains a lot about the Blocks interface and helps you to understand what a Blocks program does. It is recommended to check out this document for learning how to -work with Blocks OpModes. +work with Blocks :term:`OpModes `. Saving an OpMode ---------------- It's important to understand what is meant by **"Saving"** an OpMode. When programming/editing an OpMode, you're using either a web browser (Chrome, etc.) -or you are using a program *acting* as a web browser (REV Hardware Client, +or you are using a program *acting* as a web browser (:term:`REV Hardware Client`, etc.). The program that you are creating/editing only *ephemerally* exists within the web browser; there is no auto-save or feature to ensure that the program is ultimately saved back onto the device (REV Control Hub or approved diff --git a/docs/source/programming_resources/tutorial_specific/blocks/running_op_modes/Running-Your-Op-Mode.rst b/docs/source/programming_resources/tutorial_specific/blocks/running_op_modes/Running-Your-Op-Mode.rst index 4652a7502..21c875fe1 100644 --- a/docs/source/programming_resources/tutorial_specific/blocks/running_op_modes/Running-Your-Op-Mode.rst +++ b/docs/source/programming_resources/tutorial_specific/blocks/running_op_modes/Running-Your-Op-Mode.rst @@ -1,10 +1,10 @@ Running Your OpMode (All Languages) ----------------------------------- -If your OpMode requires input from a gamepad, then you will need to +If your :term:`OpMode` requires input from a :term:`gamepad `, then you will need to connect a Logitech F310 or other approved gamepad to the DRIVER STATION. Note that you can have up to two gamepads connected to a DRIVER STATION. If using a phone, -this will require a USB hub. However, in this example, we will only have +this will require a :term:`USB hub `. However, in this example, we will only have a solitary gamepad connected. Note that you will need an estimated 10 minutes to complete this task. @@ -13,7 +13,7 @@ Running Your OpMode Instructions --------------------------------- 1. Connect the gamepad to the DRIVER STATION. If using a phone, you will -need a Micro USB OTG adapter cable. +need a Micro USB :term:`OTG adapter ` cable. .. image:: images/GamepadDHConnection.jpg :align: center @@ -42,7 +42,7 @@ as user #1. 3. On the DRIVER STATION screen, touch the triangular-shaped, "TeleOp" dropdown list button to display a list available OpModes. You should see your recently saved OpMode among the list of -available OpModes that reside on your Robot Controller. +available OpModes that reside on your :term:`Robot Controller`. .. image:: images/TeleopRunDH.png :align: center @@ -97,7 +97,7 @@ to start the OpMode run. | 7. Use the left joystick of the gamepad to control the operation of -the DC motor. As you manipulate the left joystick up and down, the +the :term:`DC motor `. As you manipulate the left joystick up and down, the target power and the motor power should be displayed in the upper right hand corner of the screen. diff --git a/docs/source/programming_resources/tutorial_specific/blocks/using_sensors/Using-Sensors-(Blocks).rst b/docs/source/programming_resources/tutorial_specific/blocks/using_sensors/Using-Sensors-(Blocks).rst index 73407d5fc..c65c7324c 100644 --- a/docs/source/programming_resources/tutorial_specific/blocks/using_sensors/Using-Sensors-(Blocks).rst +++ b/docs/source/programming_resources/tutorial_specific/blocks/using_sensors/Using-Sensors-(Blocks).rst @@ -4,7 +4,7 @@ Using Sensors :bdg-warning:`Blocks` Color-Distance Sensor ~~~~~~~~~~~~~~~~~~~~~ -A sensor is a device that lets the Robot Controller get information +A :term:`sensor ` is a device that lets the :term:`Robot Controller` get information about its environment. In this example, you will use a REV Robotics Color-Distance sensor to display range (distance from an object) info to the DRIVER STATION. @@ -27,7 +27,7 @@ Controller's Program & Manage Wi-Fi network. 2. Verify that "MyFIRSTOpMode" is opened for editing. If it is not, you can click on the FIRST logo in the upper left hand corner of the browser window on the laptop. This should take you to the main -Blocks Development Tool project screen. +:term:`Blocks` Development Tool project screen. .. image:: images/DistanceSensorStep2ControlHub.jpg :align: center @@ -104,9 +104,9 @@ to run your updated op mode. Touch Sensor ~~~~~~~~~~~~ -For this example, we assume that the REV Robotics Touch Sensor has been +For this example, we assume that the REV Robotics :term:`Touch Sensor` has been configured as a digital touch sensor in the Robot Controller's active -configuration file. We will use the "isPressed" programming block to +:term:`configuration file `. We will use the "isPressed" programming block to determine if the button on the sensor is currently pressed or not. .. image:: images/REVTouchSensor.jpg @@ -114,7 +114,7 @@ determine if the button on the sensor is currently pressed or not. | -The Control Hub or Expansion Hub digital ports contain two digital pins per port. When +The :term:`Control Hub` or :term:`Expansion Hub` digital ports contain two digital pins per port. When you use a 4-wire JST cable to connect a REV Robotics Touch sensor to a Control Hub or Expansion Hub digital port, the Touch Sensor is wired to the second of the two digital pins within the port. The first digital pin of the @@ -222,5 +222,5 @@ to run your updated op mode. | - As you run the op mode and push or release the button, the telemetry message on the DRIVER STATION should update to reflect the current state of the digital Touch Sensor. + As you run the op mode and push or release the button, the :term:`telemetry ` message on the DRIVER STATION should update to reflect the current state of the digital Touch Sensor. diff --git a/docs/source/programming_resources/tutorial_specific/onbot_java/controlling_a_servo/Controlling-a-Servo-(OnBot-Java).rst b/docs/source/programming_resources/tutorial_specific/onbot_java/controlling_a_servo/Controlling-a-Servo-(OnBot-Java).rst index d5e57e7d7..6821f715d 100644 --- a/docs/source/programming_resources/tutorial_specific/onbot_java/controlling_a_servo/Controlling-a-Servo-(OnBot-Java).rst +++ b/docs/source/programming_resources/tutorial_specific/onbot_java/controlling_a_servo/Controlling-a-Servo-(OnBot-Java).rst @@ -1,8 +1,8 @@ Controlling a Servo :bdg-info:`OBJ` =================================== -In this section, you will modify your op mode to control a servo motor -with the buttons of the gamepad. +In this section, you will modify your op mode to control a :term:`servo ` motor +with the buttons of the :term:`gamepad `. What is a Servo Motor? ~~~~~~~~~~~~~~~~~~~~~~ @@ -24,7 +24,7 @@ even if external forces are applied to the shaft of the servo. | Servo motors are useful when you want to do precise movements (for -example, sweep an area with a sensor to look for a target or move the +example, sweep an area with a :term:`sensor ` to look for a target or move the control surfaces on a remotely controlled airplane). Modifying Your Op Mode to Control a Servo @@ -95,8 +95,8 @@ F310 gamepad are pressed. If the Y button is pressed, it will move the servo to the 0-degree position. If either the X button or B button is pressed, it will move the servo to the 90-degree position. If the A button is pressed, it will move the servo to the 180-degree position. -The op mode will also send telemetry data on the servo position to the -Driver Station. +The op mode will also send :term:`telemetry ` data on the servo position to the +:term:`Driver Station`. After you have modified your op mode, you can build it and then run it. Verify that gamepad #1 is still configured and then use the colored diff --git a/docs/source/programming_resources/tutorial_specific/onbot_java/creating_op_modes/Creating-and-Running-an-Op-Mode-(OnBot-Java).rst b/docs/source/programming_resources/tutorial_specific/onbot_java/creating_op_modes/Creating-and-Running-an-Op-Mode-(OnBot-Java).rst index 49a564d48..e0b69f52f 100644 --- a/docs/source/programming_resources/tutorial_specific/onbot_java/creating_op_modes/Creating-and-Running-an-Op-Mode-(OnBot-Java).rst +++ b/docs/source/programming_resources/tutorial_specific/onbot_java/creating_op_modes/Creating-and-Running-an-Op-Mode-(OnBot-Java).rst @@ -6,7 +6,7 @@ The Java Programming Language This tutorial assumes that you have a sound understanding of the Java programming language. If you do not know Java, then you should consider -using the Blocks Programming Tool, which is a visual development +using the :term:`Blocks Programming Tool`, which is a visual development tool. Information about the Blocks Programming Tool can be found at the following link: @@ -20,24 +20,24 @@ https://docs.oracle.com/javase/tutorial/ What's an Op Mode? ~~~~~~~~~~~~~~~~~~ -During a typical *FIRST* Tech Challenge match, a team's robot must perform +During a typical *FIRST* Tech Challenge :term:`match `, a team's robot must perform a variety of tasks to score points. For example, a team might want their robot to follow a white line on the competition floor and then score a game element into a goal autonomously during a match. Teams write programs called *OpModes* (which stands for "operational modes") to -specify the behavior for their robot. These OpModes run on the Robot +specify the behavior for their robot. These :term:`OpModes ` run on the Robot Controller phone after being selected on the DRIVER STATION device. Teams who are participating in the *FIRST* Tech Challenge have a variety of programming tools that they can use to create their own OpModes. -This document explains how to use the OnBot Java Programming Tool to +This document explains how to use the :term:`OnBot Java Programming Tool` to write an op mode for a robot. The OnBot Java Programming Tool ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The OnBot Java Programming Tool is a user-friendly programming tool -that is served up by the Robot Controller phone. A user can create +The :term:`OnBot Java` Programming Tool is a user-friendly programming tool +that is served up by the :term:`Robot Controller` phone. A user can create custom op modes for their robot using this tool and then save these op modes directly onto the Robot Controller. Users write their op modes using Java. The op modes are compiled very quickly on the Robot @@ -152,11 +152,11 @@ your new file. For this example, specify "MyFIRSTJavaOpMode" as the File Name in the New File dialog box. - Using the Sample dropdown list control, select "BlankLinearOpMode" from the list of available sample op modes (see image above). By selecting "BlankLinearOpMode" the OnBot Java editor will automatically generate a basic LinearOpMode framework for you. + Using the Sample dropdown list control, select "BlankLinearOpMode" from the list of available sample op modes (see image above). By selecting "BlankLinearOpMode" the OnBot Java editor will automatically generate a basic :term:`LinearOpMode` framework for you. Check the option labeled "TeleOp" to ensure that this new file will be configured as a tele-operated (i.e., driver controlled) op mode. - Also, make sure you check the "Setup Code for Configured Hardware" option. If this option is enabled, the OnBot Java editor will look at the hardware configuration file for your Robot Controller and automatically generate the code that you will need to access the configured devices in your op mode. + Also, make sure you check the "Setup Code for Configured Hardware" option. If this option is enabled, the OnBot Java editor will look at the hardware :term:`configuration file ` for your Robot Controller and automatically generate the code that you will need to access the configured devices in your op mode. Press the "OK" button to create your new op mode. @@ -287,7 +287,7 @@ when a user selects and runs the op mode. public void runOpMode() { At the start of the runOpMode method, the op mode uses an object named -hardwareMap to get references to the hardware devices that are listed in +:term:`hardwareMap` to get references to the hardware devices that are listed in the Robot Controller's configuration file: .. code-block:: java @@ -305,14 +305,14 @@ Note that when you attempt to retrieve a reference to a specific device in your op mode, the name that you specify as the second argument of the HardwareMap.get method must match the name used to define the device in your configuration file. For example, if you created a configuration -file that had a DC motor named "motorTest", then you must use this same +file that had a :term:`DC motor ` named "motorTest", then you must use this same name (it is case sensitive) to retrieve this motor from the hardwareMap object. If the names do not match, the op mode will throw an exception indicating that it cannot find the device. In the next few statements of the example, the op mode prompts the user to push the start button to continue. It uses another object that is -available in the runOpMode method. This object is called telemetry and +available in the runOpMode method. This object is called :term:`telemetry ` and the op mode uses the addData method to add a message to be sent to the DRIVER STATION. The op mode then calls the update method to send the message to the DRIVER STATION. Then it calls the waitForStart method, to @@ -521,7 +521,7 @@ Modifying Your Op Mode to Control a Motor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's modify your op mode to control the DC motor that you connected and -configured for your REV Expansion Hub. Modify the code for the program +configured for your REV :term:`Expansion Hub`. Modify the code for the program loop so that it looks like the following: .. code-block:: java @@ -553,7 +553,7 @@ negative value of the gamepad1's left joystick: tgtPower = -this.gamepad1.left_stick_y; The object gamepad1 is available for you to access in the runOpMode -method. It represents the state of gamepad #1 in your OPERATOR CONSOLE. +method. It represents the state of :term:`gamepad ` #1 in your OPERATOR CONSOLE. Note that for the F310 gamepads that are used during the competition, the Y value of a joystick ranges from -1, when a joystick is in its topmost position, to +1, when a joystick is in its bottommost position. @@ -592,7 +592,7 @@ Running Your Op Mode with a Gamepad Connected F310 gamepad to the DRIVER STATION. Connect the gamepad to the DRIVER STATION. If using a phone, you will -need a Micro USB OTG adapter cable. +need a Micro USB :term:`OTG adapter ` cable. .. image:: images/GamepadDHConnection.jpg :align: center diff --git a/docs/source/programming_resources/tutorial_specific/onbot_java/onbot_java_reference/OnBot-Java-Reference-Info.rst b/docs/source/programming_resources/tutorial_specific/onbot_java/onbot_java_reference/OnBot-Java-Reference-Info.rst index 7f16e5665..f7172b077 100644 --- a/docs/source/programming_resources/tutorial_specific/onbot_java/onbot_java_reference/OnBot-Java-Reference-Info.rst +++ b/docs/source/programming_resources/tutorial_specific/onbot_java/onbot_java_reference/OnBot-Java-Reference-Info.rst @@ -6,7 +6,7 @@ Javadoc Reference Pages As you start to write more complicated op modes, you will need to use more features of the *FIRST* Tech Challenge software development kit -(SDK). You can reference online Javadoc material that provide +(SDK). You can reference online :term:`Javadoc` material that provide descriptions of the available *FIRST* Tech Challenge-related classes and methods, at the following web address: @@ -15,7 +15,7 @@ https://javadoc.io/doc/org.firstinspires.ftc Sample Op Modes ~~~~~~~~~~~~~~~ -The OnBot Java Programming Tool has several built-in example OpModes and projects +The :term:`OnBot Java Programming Tool` has several built-in example :term:`OpModes ` and projects that demonstrate how to do different tasks with the *FIRST* Tech Challenge control system. As you create a new file, you can use the Sample dropdown list control to display a list of available sample OpModes or diff --git a/docs/source/programming_resources/tutorial_specific/onbot_java/using_sensors/Using-Sensors-(OnBot-Java).rst b/docs/source/programming_resources/tutorial_specific/onbot_java/using_sensors/Using-Sensors-(OnBot-Java).rst index e917caed7..c9203a98a 100644 --- a/docs/source/programming_resources/tutorial_specific/onbot_java/using_sensors/Using-Sensors-(OnBot-Java).rst +++ b/docs/source/programming_resources/tutorial_specific/onbot_java/using_sensors/Using-Sensors-(OnBot-Java).rst @@ -4,7 +4,7 @@ Using Sensors :bdg-info:`OBJ` Color-Distance Sensor ~~~~~~~~~~~~~~~~~~~~~ -A sensor is a device that lets the Robot Controller get information +A :term:`sensor ` is a device that lets the :term:`Robot Controller` get information about its environment. In this example, you will use a REV Robotics Color-Distance sensor to display range (distance from an object) info to the driver station. @@ -16,8 +16,8 @@ time this document was most recently edited, the REV Color-Range sensor saturates around 2" (5cm). This means that for distances less than or equal to 2", the sensor returns a measured distance equal to 2" or so. -Modify your op mode to add a telemetry statement that will send the -distance information (in centimeters) to the Driver Station. +Modify your op mode to add a :term:`telemetry ` statement that will send the +distance information (in centimeters) to the :term:`Driver Station`. .. code-block:: java @@ -37,8 +37,8 @@ Number") it probably means that your sensor is too far from the target Touch Sensor ~~~~~~~~~~~~ -The REV Robotics Touch Sensor can be connected to a digital port on the -Control Hub or Expansion Hub. The Touch Sensor is HIGH (returns TRUE) when it is not +The REV Robotics :term:`Touch Sensor` can be connected to a digital port on the +:term:`Control Hub` or :term:`Expansion Hub`. The Touch Sensor is HIGH (returns TRUE) when it is not pressed. It is pulled LOW (returns FALSE) when it is pressed. .. image:: images/REVTouchSensor.jpg diff --git a/docs/source/programming_resources/vision/camera_calibration/camera-calibration.rst b/docs/source/programming_resources/vision/camera_calibration/camera-calibration.rst index 2b1c25851..b33950cf6 100644 --- a/docs/source/programming_resources/vision/camera_calibration/camera-calibration.rst +++ b/docs/source/programming_resources/vision/camera_calibration/camera-calibration.rst @@ -10,7 +10,7 @@ process that mathematically models how a camera & lens combination ultimately sees the world, for example how wide the field of view is. Calibrating your camera is a must if you desire to use it for high-precision tasks, such as performing precision measurements using the camera or obtaining accurate 6DOF pose data from -fiducial marker systems like AprilTags. +fiducial marker systems like :term:`AprilTags `. *"Without a camera calibration, the best you could achieve is being able to turn towards the target. Range information would be @@ -18,7 +18,7 @@ fiducial marker systems like AprilTags. The calibration values are called **lens intrinsics**. It's important to note that they are not only specific to the camera and lens, but also specific to the -resolution used on a particular camera as well! A webcam that offers 18 +resolution used on a particular camera as well! A :term:`webcam ` that offers 18 resolutions wants a separate calibration for each one. Does your camera already have calibration data? @@ -50,7 +50,7 @@ either switch to a calibrated resolution or generate your own values. .. note:: This table can fall behind the SDK. The authoritative source is the SDK file - ``builtinwebcamcalibrations.xml``; in Android Studio, find it under the + ``builtinwebcamcalibrations.xml``; in :term:`Android Studio`, find it under the ``RobotCore``, ``res``, ``xml`` subfolders. Android device cameras also need calibration data for good pose estimates. The @@ -61,7 +61,7 @@ Capturing calibration frames Every calibration tool works from a set of photographs taken by the camera you are calibrating, at the resolution you are calibrating. The SDK provides a -utility OpMode to capture them. +utility :term:`OpMode` to capture them. Create an OpMode from the Java Sample ``UtilityCameraFrameCapture.java``. Android Studio teams can find this utility program in the External Samples @@ -69,16 +69,16 @@ folder; OnBot Java teams can copy it into their teamcode folder. Modify the parameters at the top -- most importantly the resolution -- according to your needs. -FTC Blocks teams can duplicate this OpMode, requiring a custom myBlock only for +FTC :term:`Blocks` teams can duplicate this OpMode, requiring a custom myBlock only for the method ``saveNextFrameRaw()``. At some future time, this Java method may become available as a regular Block, avoiding the need for a myBlock. Learn more about myBlocks here: - :ref:`MyBlocks Tutorial `. -The OpMode captures a camera frame (image) and stores it on the Robot -Controller with each press of the gamepad button X (or Square). To illustrate, -it stores the first two captured images as: +The OpMode captures a camera frame (image) and stores it on the +:term:`Robot Controller` with each press of the :term:`gamepad ` button X +(or Square). To illustrate, it stores the first two captured images as: - ``VisionPortal-CameraFrameCapture-000000.png`` - ``VisionPortal-CameraFrameCapture-000001.png`` @@ -95,7 +95,7 @@ Android file transfer. Choosing a calibration tool --------------------------- -There are many methods to calibrate cameras, including OpenCV, MATLAB, MRCAL +There are many methods to calibrate cameras, including :term:`OpenCV`, MATLAB, MRCAL etc. - For advanced teams, using `MRCAL `__ is @@ -130,7 +130,7 @@ Calibrating with 3DF Zephyr Calibration warnings from the SDK --------------------------------- -Running ``ConceptDoubleVision`` (or any AprilTag Sample OpMode) with an +Running ``ConceptDoubleVision`` (or any AprilTag :term:`Sample OpMode`) with an uncalibrated camera gives the following error message on both devices: .. figure:: images/010-RC-warning.png diff --git a/docs/source/programming_resources/vision/vision_overview/vision-overview.rst b/docs/source/programming_resources/vision/vision_overview/vision-overview.rst index e6fcab127..4b9c6d3a6 100644 --- a/docs/source/programming_resources/vision/vision_overview/vision-overview.rst +++ b/docs/source/programming_resources/vision/vision_overview/vision-overview.rst @@ -7,7 +7,7 @@ Introduction The *FIRST* Tech Challenge control system software has built-in support for two computer vision technologies: -1. AprilTags - +1. :term:`AprilTags ` - :doc:`AprilTags <../../../apriltag/vision_portal/apriltag_intro/apriltag-intro>` are fiducial markers similar in design to a QR code that can be used for identification and localization. AprilTags are used as reference @@ -28,7 +28,7 @@ computer vision technologies: feature in the *FIRST* Tech Challenge SDK that provides the ability to process colors using `OpenCV `__. - - Color Sensor can detect the exact color in an image, which can + - Color :term:`Sensor` can detect the exact color in an image, which can help determine what is in front of a robot. - Color Locator can look for a specific color and return information about the size, shape and location of the color in the camera frame. diff --git a/docs/source/robot_building/wiring_guide/wiring-guide.rst b/docs/source/robot_building/wiring_guide/wiring-guide.rst index 39e012403..1e6f18797 100644 --- a/docs/source/robot_building/wiring_guide/wiring-guide.rst +++ b/docs/source/robot_building/wiring_guide/wiring-guide.rst @@ -32,9 +32,9 @@ rules take precedence over recommendations made here. Please refer to these sources before embarking on the electrical wiring task. .. note:: This guide primarily uses the REV Robotics Expansion Hub in its examples, but the guidelines - apply equally well to the REV Robotics Control Hub. These Hubs provide electronic input/output - (or "I/O") ports that are used to "talk" to a robot's motors, servos, and sensors. The layout of - I/O ports is the same for both the Expansion Hub and Control Hub. + apply equally well to the REV Robotics :term:`Control Hub`. These :term:`Hubs ` provide electronic input/output + (or "I/O") ports that are used to "talk" to a robot's motors, :term:`servos `, and :term:`sensors `. The layout of + I/O ports is the same for both the :term:`Expansion Hub` and Control Hub. One of the important differences between the Expansion Hub and the Control Hub is the external Android device used with the Expansion Hub, @@ -210,7 +210,7 @@ wiring will: - The metallic chassis beams are insulated with plastic strips to prevent electrostatic discharges as the robot rolls off its metal platform. Wires should be tied down (secured) at regular intervals to prevent them -from moving or shaking loose during a match. It is best to run wires +from moving or shaking loose during a :term:`match `. It is best to run wires along stationary parts of a robot. Zip ties offer a sturdy way to secure wires, but electrical tape or Velcro straps can also be used. @@ -354,7 +354,7 @@ pinch/entanglement points. Battery Security ^^^^^^^^^^^^^^^^^ -The placement, connectors, and methods for securing the battery +The placement, connectors, and methods for securing the :term:`battery ` properly will ensure safety and enhance the life of the battery. The battery is often one of the heaviest parts of the robot, and its @@ -479,7 +479,7 @@ Protective Side Shields Most FTC games involve Robot-to-Robot and Robot-to-Game element contact. This contact may be intentional or accidental, and it can sometimes extend into the inner workings of your robot. To prevent -damage or interference (such as ESD), it is desirable to prevent +damage or interference (such as :term:`ESD`), it is desirable to prevent external objects from being able to contact critical internal electrical components. @@ -510,13 +510,13 @@ lights or mechanisms. Wi-Fi Considerations ^^^^^^^^^^^^^^^^^^^^^ -The Robot Controller device (Control Hub or Android smartphone) uses a -wireless radio to communicate with the Driver Station. Choose the +The :term:`Robot Controller` device (Control Hub or Android smartphone) uses a +wireless radio to communicate with the :term:`Driver Station`. Choose the placement of the Hub/phone with the following considerations: - It is important to protect the phone and Control Hub from robot-to-robot contact. Attach the phone or Hub to the robot in a place protected from physical impact. - Choose a location on the robot where the radio waves traveling to or from the phone or Control Hub will not be blocked/reflected by large pieces of metal or by a 12V battery or a motor. -- Choose a location on the robot where the radio waves traveling to or from the phone or Control Hub will not be disrupted by electromagnetic interference that could potentially be generated by a 12V DC motor. +- Choose a location on the robot where the radio waves traveling to or from the phone or Control Hub will not be disrupted by electromagnetic interference that could potentially be generated by a 12V :term:`DC motor `. - Reduce the risk of an electrostatic shock between the phone and the metallic frame of the robot by mounting the phone on an insulator, like plastic or wood. .. list-table:: @@ -546,9 +546,9 @@ isolated from its frame, the same practices covered throughout this guide (strain relief, wire routing, keeping connectors away from exposed metal) also reduce ESD risk. A few wiring-specific tips: -- Use ferrite chokes on sensor, encoder, and servo cables to help block the current spikes seen in an ESD event. +- Use ferrite chokes on sensor, :term:`encoder `, and servo cables to help block the current spikes seen in an ESD event. - Keep connectors and exposed wire ends away from the metal frame of the robot; an air gap of at least 3/8" (10 mm), or a wrap of electrical tape, reduces the chance of a shock disrupting a port. -- Wheel material and design can affect how much static charge a robot builds up. Mecanum wheels, for example, may produce more static than other wheel types. +- Wheel material and design can affect how much static charge a robot builds up. :term:`Mecanum` wheels, for example, may produce more static than other wheel types. For a complete explanation of ESD, how robots become charged, and full grounding and insulation procedures, see @@ -567,7 +567,7 @@ the controller to stop communicating with the robot. This can cause loss of control of the robot at a critical time. To ensure stable and consistent operation, it is recommended to mount -the Driver Station phone, USB hub, and game controller connectors to a +the Driver Station phone, :term:`USB hub `, and game controller connectors to a rigid base plate. This base plate should be non-metallic (wood or plastic), and it can also provide an easy way to store the game controllers. Items can be attached to the base plate with Velcro, zip @@ -618,7 +618,7 @@ However, there have been credible reports of occasional disconnects between the XT30 connectors provided with the REV Robotics hardware. If you suspect that you might have a loose XT30 connection, conduct a -careful physical inspection of the connection. Check to make sure the +careful physical :term:`inspection ` of the connection. Check to make sure the connectors fit snugly together and there is a slight amount of retention between the connectors when you try to pull them apart. Also check to make sure that power is not disrupted when the ends of the @@ -662,7 +662,7 @@ The following steps explain how to install Anderson Powerpoles on a battery (TETRIX, REV, and current MATRIX). The same steps can be modified to install Anderson Powerpoles on any wire. -1. Remove the fuse from the battery. +1. Remove the :term:`fuse ` from the battery. .. figure:: images/fuse-removal.png :alt: Three ATM fuses shown with wires attached, illustrating the fuse being removed from a battery lead. @@ -715,7 +715,7 @@ Level Shifters There are two voltage levels commonly used for logic on integrated circuits (like the chips in a REV Robotics Expansion Hub): 5V and 3.3V. The REV Expansion Hub uses 3.3V logic levels, but some third-party -devices work using 5V logic levels. If you would like to use a 5V I2C +devices work using 5V logic levels. If you would like to use a 5V :term:`I2C` sensor with the REV Robotics Expansion Hub, then you will need: - Logic level converters (also known as level shifters) to convert the signals to and from the sensor. diff --git a/docs/source/sponsors/software/software.rst b/docs/source/sponsors/software/software.rst index 60ea80ebb..e8297da36 100644 --- a/docs/source/sponsors/software/software.rst +++ b/docs/source/sponsors/software/software.rst @@ -23,7 +23,7 @@ requirement. Read details below for each product for more information. **What**: - * Autodesk CAD software (including Fusion 360, Inventor, 3ds Max, and more...) + * Autodesk :term:`CAD` software (including Fusion 360, Inventor, 3ds Max, and more...) **Expires**: Contact Autodesk for exact details. diff --git a/docs/source/team_resources/team_resources.rst b/docs/source/team_resources/team_resources.rst index 9f07d3f45..a8b418b39 100644 --- a/docs/source/team_resources/team_resources.rst +++ b/docs/source/team_resources/team_resources.rst @@ -14,6 +14,6 @@ Pages and Links | FTC Technical Support - https://ftc-community.firstinspires.org | FTC Avatar Submission - https://community.firstinspires.org/team-avatars | FTC Scoring Site (for avatar and hybrid event portfolio submission) - https://ftc-scoring.firstinspires.org -| FTC Competition Manual - https://ftc.game/manual +| FTC :term:`Competition Manual` - https://ftc.game/manual | FTC Competition Manual (HTML) - https://ftc.game/cm-html | FTC Competition Manual AI Chatbot - https://ftc-cmchatbot.firstinspires.org \ No newline at end of file diff --git a/docs/source/tech_tips/tech-tips.rst b/docs/source/tech_tips/tech-tips.rst index 66fe034fd..3a2d1f9fe 100644 --- a/docs/source/tech_tips/tech-tips.rst +++ b/docs/source/tech_tips/tech-tips.rst @@ -30,8 +30,8 @@ Legacy Tech Tips: **Android Studio 2024.2.1 LadyBug Update and the FTC SDK** - This is an important message for teams who use Android Studio to program - their robots. Teams who use Blocks or OnBot Java are not impacted. + This is an important message for teams who use :term:`Android Studio` to program + their robots. Teams who use :term:`Blocks` or :term:`OnBot Java` are not impacted. On October 1, 2024 `Android Studio `__ released a new version of @@ -82,7 +82,7 @@ Legacy Tech Tips: **AprilTag Localization** - This week's Tech Tip is all about AprilTag Localization. How can your robot + This week's Tech Tip is all about :term:`AprilTag` Localization. How can your robot determine where it is on the field by looking at an AprilTag? A new set of APIs have been added to SDK 10.0 to provide just that information, and it works for any static (immobile) AprilTag on the competition field. Check out @@ -133,10 +133,10 @@ Legacy Tech Tips: **REV Driver Hub Batteries** - This week’s Tech Tip of the Week focuses on the REV Driver Hub. Sure, we + This week’s Tech Tip of the Week focuses on the REV :term:`Driver Hub`. Sure, we already did a pretty thorough deep dive on the REV Driver Hub in the 11/06/2023 Tech Tip "Driver Hub or Smartphone?", but we never really covered - the batteries used in the Driver Hub themselves - and, of course, this topic + the :term:`batteries ` used in the Driver Hub themselves - and, of course, this topic was recently brought up in a team question. The question was, “Why aren’t batteries for the REV Driver Hub interchangeable?” @@ -194,7 +194,7 @@ Legacy Tech Tips: connected to the USB-C port on the Driver Hub to provide consistent power (use USB-A to USB-C cables only). The battery pack will sustain your Driver Hub and keep it from being additionally depleted by any high-power-drain - gamepads (such as the Sony DualShock and Sony DualSense gamepads) that your + :term:`gamepads ` (such as the Sony DualShock and Sony DualSense gamepads) that your team may be using. @@ -202,7 +202,7 @@ Legacy Tech Tips: .. _servopowerinjectors: - This week’s Tech Tip of the Week is intended to be a short treatise on Servo + This week’s Tech Tip of the Week is intended to be a short treatise on :term:`Servo` Power Injectors. Servo Power Injectors have been used in FIRST Tech Challenge for several years now, but do you really understand what they are and how they work? What is a Servo Power Injector and how might servos behave differently @@ -212,7 +212,7 @@ Legacy Tech Tips: a signal. The actual command signal for the servo travels on the signal wire, and the power used to power the servo travels on the other two wires. A servo power injector is a device that removes the power provided by the servo controller - (REV Control Hub or REV Expansion Hub for FTC) and provides a new, usually higher + (REV :term:`Control Hub` or REV :term:`Expansion Hub` for FTC) and provides a new, usually higher wattage power source. Both the REV Servo Power Module and Studica Servo Power Block replace the 5V/10W power provided by the REV Control/Expansion Hubs with a 6V power source with a higher maximum wattage. @@ -230,11 +230,11 @@ Legacy Tech Tips: directly from the robot battery - using power injectors means you could consume all of the power on the robot just from the servos alone! This will result in the robot power system browning out (resulting in loss of communications or loss of - power to the control system) or even blowing the 20A battery fuse. + power to the control system) or even blowing the 20A battery :term:`fuse `. Using a servo power injector can also expose different behaviors in servos that were not present when using the REV Control/Expansion Hub directly. The biggest - behavior is the “Lost Signal” behavior. When an OpMode ends, the REV + behavior is the “Lost Signal” behavior. When an :term:`OpMode` ends, the REV Control/Expansion hubs stop the signal and also cut power to the servo ports - this leads to the servos “going limp” as they lose power. With a servo power injector, the servos never lose power, and so “lost signal” behaviors will often @@ -313,7 +313,7 @@ Legacy Tech Tips: - *Mechanical Power(W) = torque (N-m) x angular speed (rad/s)* - Mechanical Power for a DC motor generally follows a very specific curve, + Mechanical Power for a :term:`DC motor ` generally follows a very specific curve, based on its efficiency, stall current, stall torque, speed, and a bunch of other factors. The general performance curve of a DC motor can be seen in Figure 1. @@ -789,7 +789,7 @@ Legacy Tech Tips: Wi-Fi is a line-of-sight technology, that means Wi-Fi does best when there’s a straight unobstructed path from the antenna on the Control Hub to the antenna on the Driver Hub. Where is the antenna in a Control Hub? It’s right - under the plastic on the “face” of the hub on the logo side. If the Control + under the plastic on the “face” of the :term:`hub ` on the logo side. If the Control Hub can be mounted so that its antenna is generally not covered/surrounded/blocked by metal, 5GHz should be your target band. However, if your Control Hub is buried deep inside the robot and surrounded @@ -815,7 +815,7 @@ Legacy Tech Tips: for transmission of Wi-Fi frequencies. But how do you know for sure how well your robot’s Wi-Fi is performing? You - can monitor the Wi-Fi signal’s strength through the Driver Station App. + can monitor the Wi-Fi signal’s strength through the :term:`Driver Station App`. Check out the **2024/02/12 Team Blast Tech Tip** for info on how to view and understand Wi-Fi Signal Strength. If your signal is strong when using 5GHz at maximum field range (from the Driver Hub) and @@ -1124,7 +1124,7 @@ Legacy Tech Tips: Challenge robot, this reason is actuator (motor and servo) current draw. Motors and Servos can pull a considerable amount of current when they’re being used, especially when they’re being used in low-torque configurations. - Motors that are geared closer to 1:1 gear ratio can spin faster - they can + Motors that are geared closer to 1:1 :term:`gear ratio ` can spin faster - they can propel your robot’s drivetrain across the field much faster - but have less torque because of the lower gear ratio. Motor configurations that have less torque consume significantly more current to operate (when driving the same @@ -1133,7 +1133,7 @@ Legacy Tech Tips: consume larger amounts of current, and this can cause even healthy batteries to have their voltages “sag” during periods of high use. Teams must consider their power consumption very carefully when optimizing their battery and - motor utilization during a match, even though that’s often an afterthought + motor utilization during a :term:`match `, even though that’s often an afterthought for most teams. .. dropdown:: Week of 03/18/2024 "Battery Fuses" @@ -1197,7 +1197,7 @@ Legacy Tech Tips: .. _ferritecore: - For those about to use sensors, we salute you - with our Tech Tip of the + For those about to use :term:`sensors `, we salute you - with our Tech Tip of the Week! This week’s Tech Tip focuses on signal noise and how to eliminate it with ferrite cores. @@ -1219,7 +1219,7 @@ Legacy Tech Tips: Some buses and wiring are more sensitive to electrical noise than others. On a FIRST Tech Challenge robot, long signal-carrying wires (such as Servo wires - or I2C sensor wires) are most susceptible to induced noise. So how can we + or :term:`I2C` sensor wires) are most susceptible to induced noise. So how can we eliminate this noise? The easiest way to remove noise is through the use of a Ferrite Core. Ferrite Cores, also known as Ferrite Beads, are made of a ceramic material called ferrite that has incredibly useful magnetic @@ -1231,7 +1231,7 @@ Legacy Tech Tips: increase the efficiency of the noise filtering in cases where excessive noise is being generated. You can find ferrite cores already installed in cables meant for high-noise environments or highly sensitive devices such as USB - webcam cables and monitor cables. It’s best to place ferrite cores on the + :term:`webcam ` cables and monitor cables. It’s best to place ferrite cores on the wire closest to the connector leading into the Control/Expansion Hub port. .. dropdown:: Week of 03/04/2024 "Motor Modes" @@ -1243,7 +1243,7 @@ Legacy Tech Tips: lesser-known behaviors of well-known interfaces. Today we’re talking about motor modes. The `REV Robotics documentation `__ - for encoder feedback has a really good description of the four primary run + for :term:`encoder ` feedback has a really good description of the four primary run modes, namely: - DcMotor.RunMode.STOP_AND_RESET_ENCODER mode @@ -1258,7 +1258,7 @@ Legacy Tech Tips: .setPower() method. There’s really no more to see here. The last two modes are a bit more interesting. These two modes use a feature - of the Control/Expansion hub firmware to externally (from robot code) control + of the Control/Expansion hub :term:`firmware ` to externally (from robot code) control the motors. Using this feature you can do a lot more with the motors such as set the maximum velocity of the motor (nominally in encoder-ticks-per-second) using the .setVelocity() method, and :ref:`change the actual PIDF algorithm @@ -1266,7 +1266,7 @@ Legacy Tech Tips: PIDF Coefficients>` being used by the motor mode (using the .setPIDFCoefficients() methods). Because these two motor modes rely on knowing specific motor characteristics, it’s VERY important to set the - correct motor type for the motor in the Robot Configuration! + correct motor type for the motor in the :term:`Robot Configuration`! Finally, one final note about RUN_TO_POSITION. When setting a Power or a Velocity for the motor in RUN_TO_POSITION mode, the value is intended to be @@ -1292,7 +1292,7 @@ Legacy Tech Tips: Several years ago, FIRST Tech Challenge gave permission for the OpenFTC project to extract AAR’s from our SDK releases and publicly post an - extracted version of the Robot Controller source code. The `Extracted-RC + extracted version of the :term:`Robot Controller` source code. The `Extracted-RC `__ repository has `branches `__ that contain source code for each release of the SDK, as far back as SDK 5.2 through SDK @@ -1368,7 +1368,7 @@ Legacy Tech Tips: .. _wifisignalstrength: Welcome to the Tech Tip of the Week! One common question we get is how to - determine the Wi-Fi signal strength between the Driver Station and the + determine the Wi-Fi signal strength between the :term:`Driver Station` and the Robot. Because there are a lot of factors that can play into your robot performance on the field, it’s important to know that your robot is getting the strongest Wi-Fi signal possible. @@ -1416,7 +1416,7 @@ Legacy Tech Tips: How does a joystick know where “center” is on a gamepad? On virtually all gamepads the analog joysticks have an electrical device (usually a - potentiometer) that electrically measures the motion of the stick. If the + :term:`potentiometer `) that electrically measures the motion of the stick. If the electrical device’s value at “center” does not coincide with the value the gamepad thinks should be center, the stick will have a non-zero value at its center position; this is called drift. In a video game, drift is what causes @@ -1452,7 +1452,7 @@ Legacy Tech Tips: take a few additional steps to keep it running optimally. 1. Make sure your REV Driver Hub time/date is set correctly! This is the cause - of a number of inspection nightmares and Robot Controller log file + of a number of :term:`inspection ` nightmares and Robot Controller log file confusion, the first step should always be to check to make sure the Date/Time on the Driver Hub is set correctly. This is set through the normal Android System Settings by pulling down the Android Quick Settings pull-down @@ -1622,7 +1622,7 @@ Legacy Tech Tips: This week’s Tech Tip of the Week is a gentle reminder that strong passwords and regular backups make for good competition. Even when competing at a - Scrimmage before your competition season starts, be sure to change your + :term:`Scrimmage` before your competition season starts, be sure to change your Wi-Fi password on your Control Hub from the default password of “password” to something only your team knows. Anyone who knows your password can easily gain access to your robot and change or delete your programs, change @@ -1642,7 +1642,7 @@ Legacy Tech Tips: :ref:`automatically load your Driver Controlled OpMode ` as soon as your Autonomous OpMode has - completed? Lots of teams go into panic mode immediately after Autonomous has + completed? Lots of teams go into panic mode immediately after :term:`Autonomous` has completed - they’re trying to navigate and select the proper Driver Controlled OpMode, Initialize, and Run the OpMode while also picking up their gamepads and preparing to drive. Skip all that panic and confusion and @@ -1690,7 +1690,7 @@ Legacy Tech Tips: .. _huskylensintro: This week’s Tech Tip of the Week comes to us from Chris Johannesen, 2023 - *FIRST* Tech Challenge Volunteer of the Year and author of many ftc-docs + *FIRST* Tech Challenge :term:`Volunteer` of the Year and author of many ftc-docs tutorials. Have you heard of the HuskyLens and want to learn how to properly connect one to a Control Hub, learn how to use it to detect Team Props, and use the HuskyLens samples included with SDK 9.0.0 and newer? Chris has this @@ -1712,7 +1712,7 @@ Legacy Tech Tips: correctly. There is a tool within the Driver Station App 3-dot menu called the “Self-Inspect” feature that can help teams perform a quick check to ensure their hardware and software is configured correctly. Depending on - your hardware configuration the Self-Inspect screens may be formatted + your hardware configuration the :term:`Self-Inspect` screens may be formatted differently or have different options listed, so :ref:`there is a handy reference on ftc-docs ` @@ -1760,7 +1760,7 @@ Legacy Tech Tips: - A single 10,000mAh External battery pack allows Control Hub to be used non-stop over the course of an entire day. - - Driver Hub has 3 USB-A ports, so no external USB hubs and additional + - Driver Hub has 3 USB-A ports, so no external :term:`USB hubs ` and additional cables are required for using multiple USB gamepads. This makes the Driver Hub very compact and easy to manage. @@ -1887,7 +1887,7 @@ Legacy Tech Tips: software-counted. This means higher counts-per-revolution encoders (like the REV Through-Bore Encoder) should be placed on Ports 0 or 3 to ensure counts aren’t missed, and lower counts-per-revolution encoders (like the - goBILDA Odometry Pods or most motors) can be connected to any port. + goBILDA :term:`Odometry` Pods or most motors) can be connected to any port. - Servo port pairs (0,1), (2, 3), and (4,5) each share a common power supply, so if you’re using higher-current servos (like a goBILDA torque @@ -1903,14 +1903,14 @@ Legacy Tech Tips: each sensor carefully! - The USB 2.0 port shares the same USB bus as the internal Control Hub - radio. ESD or other electrical interference that affects devices (like + radio. :term:`ESD` or other electrical interference that affects devices (like webcams) plugged into that port may cause a loss of communications. When using a USB webcam, use the USB 3.0 port first. - USB C-to-C cables do not work properly with the Control Hub, only USB A-to-C cables do. - - If you’re utilizing the onboard IMU, Do not plug I2C devices into Port 0 + - If you’re utilizing the onboard :term:`IMU`, Do not plug I2C devices into Port 0 unless absolutely necessary. Port 0 shares an I2C bus with the IMU, and misbehaving devices (or devices that don’t “play well with others”) plugged into Port 0 can cause the IMU to stop communicating. diff --git a/docs/source/tech_tips/tech-tips/tech-tip-annual-maintenance/tech-tip-annual-maintenance.rst b/docs/source/tech_tips/tech-tips/tech-tip-annual-maintenance/tech-tip-annual-maintenance.rst index e849ddb52..c188cddad 100644 --- a/docs/source/tech_tips/tech-tips/tech-tip-annual-maintenance/tech-tip-annual-maintenance.rst +++ b/docs/source/tech_tips/tech-tips/tech-tip-annual-maintenance/tech-tip-annual-maintenance.rst @@ -16,7 +16,7 @@ Just like "spring cleaning," an annual check-up for your robot's electronics and software is essential to prevent common issues caused by aging components. * Secure XT30 Connections: If your power cables feel loose in the REV Control - Hub or Expansion Hub's XT30 connectors, avoid using glues like hot glue to + Hub or :term:`Expansion Hub`'s XT30 connectors, avoid using glues like hot glue to keep the connection together. These only hide an unstable connection between the metal contacts, which can lead to intermittent power loss under shock. Instead, the metal pins on the device's XT30 connectors likely need to be @@ -24,7 +24,7 @@ and software is essential to prevent common issues caused by aging components. `__ for proper maintenance of these pins. -* Battery Rejuvenation (Charge Cycling): Older NiMH batteries can develop +* :term:`Battery` Rejuvenation (Charge Cycling): Older NiMH batteries can develop crystalline structures internal to the battery chemistry, increasing internal resistance and reducing power output. Charge cycling — discharging slowly to 10V (at between 500-600mA) then recharging — can break down these crystals @@ -36,15 +36,15 @@ and software is essential to prevent common issues caused by aging components. However, draining a battery below 10V or charging a battery over 2A too often can greatly decrease the expected life of a battery by up to 40%! -* Continuous Wiring Inspection: Make wiring inspection an ongoing task, not +* Continuous Wiring :term:`Inspection`: Make wiring inspection an ongoing task, not just an annual one. Regularly check for frayed insulation, loose connections, or bent pins. Specifically, ensure no exposed wire is visible where it meets XT30 connector housings to prevent potential shorts. -* Software Updates Are Key: Always update your Control Hub OS to the latest +* Software Updates Are Key: Always update your :term:`Control Hub` OS to the latest version (e.g., 1.1.6 for Wi-Fi driver security) and your FIRST Tech Challenge SDK (e.g., SDK 11.0) for improved performance and better support from - tournament staff. + :term:`tournament ` staff. Following these tips will help ensure your robot's electronics and software are reliable and competition-ready. diff --git a/docs/source/tech_tips/tech-tips/tech-tip-practice-timer/tech-tip-practice-timer.rst b/docs/source/tech_tips/tech-tips/tech-tip-practice-timer/tech-tip-practice-timer.rst index 92a9be5e3..50bd1fd44 100644 --- a/docs/source/tech_tips/tech-tips/tech-tip-practice-timer/tech-tip-practice-timer.rst +++ b/docs/source/tech_tips/tech-tips/tech-tip-practice-timer/tech-tip-practice-timer.rst @@ -12,17 +12,17 @@ is included in the blast with the rest of the content here. **FTC Driver Station Practice Timer** -Did you know there's a powerful tool lurking within your FTC Driver Station App, +Did you know there's a powerful tool lurking within your FTC :term:`Driver Station App`, designed to help your team dominate match timing? Forget the need for complex -event software – your Driver Station has a built-in Practice Match timer that +event software – your :term:`Driver Station` has a built-in Practice Match timer that simulates the entire match flow, or any part of it! Imagine perfecting your autonomous routine, nailing the Auto-TeleOp transition, or optimizing your endgame strategy, all without the pressure of a real competition. This (not so) hidden gem allows teams to practice match timing for every critical phase: -* Autonomous - Fine-tune your robot's pre-programmed actions. -* Auto-TeleOp Transition - Seamlessly swap control from autonomous to TeleOp. +* :term:`Autonomous` - Fine-tune your robot's pre-programmed actions. +* Auto-TeleOp Transition - Seamlessly swap control from autonomous to :term:`TeleOp `. * TeleOp - Maximize your scoring potential during the main TeleOp period. * Endgame - Strategize and execute your final, high-scoring moves. @@ -33,7 +33,7 @@ Ready to unlock your team's full potential? *How does it work?* In the upper-left corner of the Driver Station App you will see the "Practice Timer Window". This has the heading "Practice Timer" and has the remaining time (in a possible practice match) as well as a "PLAY" button. -This Practice Timer area is always visible regardless of what OpModes are +This Practice Timer area is always visible regardless of what :term:`OpModes ` are running or any other activities (on the same screen). This Practice Timer also runs independently of other activities, therefore OpModes can be selected, started, stopped, reselected, and so on while the Practice Timer is running @@ -51,7 +51,7 @@ without affecting the timer. at sufficient volume to hear the cues for match transitions. Press the tiny "Play" button in the Practice Timer window, and the software -will prompt where in the match to start the timer at. Options are: +will prompt where in the :term:`match ` to start the timer at. Options are: * Autonomous * Auto -> TeleOp Transition