2023-2024 FIRST Tech Challenge

Android Studio Guide

FIRST Tech Challenge Documentation

Sponsor Thank You Thank you to our generous sponsors for your continued support of the FIRST Tech Challenge!
 0
FTC Docs Android Studio Guide, i

Contents

1 Introduction AS 2
1.1 Control System Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Required Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Using Your Android Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Configuring your Hardware AS 16

2.1 Configuring your Android Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2 Connecting Devices To a Control or Expansion Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.3 Configuring Your Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

3 Installing Android Studio AS 131

3.1 Installing Android Studio AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
3.2 Downloading the Android Studio Project Folder AS Legacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
3.3 Disabling Android Studio Instant Run Legacy AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

4 Managing an Android Studio Project AS 148

4.1 Fork and Clone from GitHub AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

5 Writing an Op Mode AS 165

5.1 Enabling Developer Options AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.2 Creating and Running an Op Mode AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
5.3 Controlling a Servo AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.4 Using Sensors AS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

6 Version Information 193

6.1 Document Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.2 Git Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.3 Document License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 0
FTC Docs Android Studio Guide, 1
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 robot.
Android Studio is 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 recommended for advanced users who have extensive
Java programming experience.

Note: AS indicates that the content is specific to Android Studio Programming

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1

FTC Docs Android Studio Guide, 2

Chapter 1

Introduction AS

1.1 Control System Introduction

1.1.1 About FIRST Tech Challenge

FIRST Tech Challenge seeks to inspire youth to become the next generation of STEM leaders and innovators through par-
ticipation in mentor-guided robotics competition. Teams who participate in FIRST Tech Challenge must build a robot that
performs a variety of tasks. The tasks vary from season to season, and are based on a set of game rules that are published
at the start of each season. The more tasks that a robot can complete, the more points a team will earn.

(Photo courtesy of Dan Donovan, ©2017 Dan Donovan / www.dandonovan.com)

1.1.2 AUTO vs. TELEOP

A FIRST Tech Challenge match has an AUTO phase and a 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.

1.1.3 Point-to-Point Control System

FIRST Tech Challenge uses Android devices to control its robots. During a competition, each team has two Android devices.

Release 0.2 03/12/2024

 1

FTC Docs Android Studio Guide, 3

One Android device is mounted onto the robot and is called the Robot Controller. The 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. There are two hardware options currently being used: REV Robotics Expansion Hub or the REV
Robotics Control Hub.
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. The DRIVER STATION is sort of 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.

1.1.4 REV Robotics Expansion Hub

The REV Robotics Expansion Hub is the electronic input/output (or “I/O”) module that lets the Robot Controller talk to the
robot’s motors, servos, and sensors. The Robot Controller communicates with the Expansion Hub through a serial connec-
tion. For the situation where an Android smartphone is used as the Robot Controller, a USB cable is used to establish the
serial connection. For the situation where a REV Robotics Control Hub is used, an internal serial connection exists between
the built-in Android device and the Expansion Hub.
The Expansion Hub is also connected to a 12V battery which is used to power 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. If a REV Robotics Control Hub is used as the Robot Controller, then the Control Hub will use the main 12V battery to
power its internal Android device.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1

FTC Docs Android Studio Guide, 4

1.1.5 REV Robotics Control Hub

The REV Robotics Control Hub is an integrated version of the Robot Controller. It combines an Android device built into the
same case as a REV Robotics Expansion Hub.

Release 0.2 03/12/2024

 1

FTC Docs Android Studio Guide, 5

The Control Hub, which has its built-in Android device connected directly to the Expansion Hub using an internal serial bus,
eliminates the need for an external USB connection between the Android Robot Controller and the I/O module.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1
FTC Docs Android Studio Guide, 6

1.1.6 What’s an Op Mode?

During a typical FIRST Tech Challenge match, a team’s robot has to perform a variety of tasks in an effort 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
(such as a ball) into a goal autonomously during a match. Teams write “op modes” (which stand for “operational modes”)
to specify the behavior for their robot.
Op modes are computer programs that are used to customize the behavior of a competition robot. The Robot Controller can
execute a selected op mode to perform certain tasks during a match.
Teams who are participating in FIRST Tech Challenge have a variety of programming tools that they can use to create their
own op modes. Teams can use a visual (“drag and drop”) programming tool called the Blocks Programming Tool to create
their op modes. Teams can also use a text-based Java tool known as the OnBot Java Programming Tool or Google’s Android
Studio integrated development environment (also known as an “IDE”) to create their op modes.

1.2 Required Materials

This wiki contains tutorials that demonstrate how to configure, program, and operate the FIRST Tech Challenge control
system. In order to complete the tutorials, you will need to have the following materials available:

Required Item(s) Image

Two (2) FIRST-approved* Android devices OR One (1) Con- Or

trol Hub and one (1) FIRST-approved* Android device for the
DRIVER STATION

Wireless Internet access.

continues on next page

Release 0.2 03/12/2024

 1
FTC Docs Android Studio Guide, 7
Table 1 – continued from previous page
Required Item(s) Image

Laptop with Microsoft Windows 7, 8 or 10 and Wi-Fi capa-

bility. 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 Chrome-
book, Android Tablet, etc.) as your programming device, the
steps might differ slightly on how to access the Program-
ming Server on the Robot Controller. Refer to your device’s
user documentation for details on howto connect to a Wi-Fi
network.

Javascript-enabled web browser (Google Chrome is the

recommended browser).

If you are using a smartphone as part of your Robot Con-

troller, you will also need a REV Robotics Expansion Hub
(REV-31-1153) to connect to the motors, servos, and sen-
sors. Control Hub users will use the integrated ports built
into the Control Hub to connect motors, servos, and sen-
sors.
continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1
FTC Docs Android Studio Guide, 8
Table 1 – continued from previous page
Required Item(s) Image

REV Robotics Switch, Cable, & Bracket (REV-31-1387).

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). Ifyou have a REV Robotics Slim Battery (REV-31-
1302) then you will not need this adapter since the REV bat-
tery already has an XT30 connector.

FIRST-approved* 12V Battery (such as Tetrix W39057 or Or

REV Robotics REV-31-1302).*Fora list of FIRST-approved
12V batteries, refer to the current Competition Manual.

FIRST-approved* 12V DC Motor (such as Tetrix W39530,

with power cable W41352).*For a list of FIRST-approved
12V motors,refer to the current Competition Manual.

REV Robotics Anderson to JST VH Cable (REV-31-1381).

continues on next page

Release 0.2 03/12/2024

 1
FTC Docs Android Studio Guide, 9
Table 1 – continued from previous page
Required Item(s) Image

180-Degree Standard Scale Servo (such as Hitec HS-

485HB).

REV Robotics Color Sensor with 4-Pin Cable (REV-31-1154).

REV Robotics Touch Sensor with 4-Pin Cable( REV-31-

1425).

If you are using a smartphone as your Robot Controller, you

will need a USB Type A male to type mini-B male cable. Con-
trol Hub users donot need this cable.

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.

Logitech F310 USB Gamepad.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1
1.3 Using Your Android Device
FTC Docs Android Studio Guide, 10
Before you get started with your control system, it is helpful if you familiarize yourself with the basic operation of your Android
device.

1.3.1 Unlocking Your Screen

When you first power on an Android phone, it usually starts off with the screen in a “locked” state. For the Motorola smart-
phones that are used in the FIRST Tech Challenge, you must touch the locked screen and then slide your finger upwards
along the screen to unlock the phone. Note that different devices might require a slightly different procedure to unlock the
screen.

Depending on your security settings, you might be challenged for a pass code or PIN number. Use the touch screen to enter
in the pass code or PIN value and tap on the check mark to log into the device.

Release 0.2 03/12/2024

 1

FTC Docs Android Studio Guide, 11

1.3.2 Navigating in Android

Your phone should display its home screen if you just powered it on and unlocked it. Note that the actual screens on your
smartphone might differ slightly from the screens depicted in this tutorial.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1
FTC Docs Android Studio Guide, 12

Release 0.2 03/12/2024

 1
FTC Docs Android Studio Guide, 13
At the bottom of the screen there should be some buttons that you can use to navigate the screens on your Android device.

The leftmost button (see image above) is the “Back” button. You can use this button to return to the previous screen on your
Android device.
The center button is the “Home” button. Pressing this button should take you back to the home or opening screen of your
Android device.
The rightmost button is the “Recent Apps” button. If you click on this button it will display the apps that were recently run
and are dormant in the background. You can close a recent app by tapping the “X” button on the app’s listing.

Note that some Android smartphones have an auto-hide feature which automatically hides the bottom navigation buttons.
If your smartphone has this feature, you might need to swipe up from the bottom of the screen to display the navigation
buttons.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 1
FTC Docs Android Studio Guide, 14
1.3.3 Displaying Available Apps on your Android Phone

Android Marshmallow Users

If you are using a device with Android Marshmallow (6.x) or earlier, you can display the available apps using the Android App
Drawer button that is available on the home screen.
There should be another row of buttons visible above the “Back”, “Home” and “Recent Apps” buttons. In the center of this
row of buttons is a button that has an array of dots or squares.

Tapping on this button will launch the Android App Drawer. The App Drawer displays a list of all of the apps that are available
on your Android device. You can scroll through the App Drawer screens to find and launch an app.

Release 0.2 03/12/2024

 1
FTC Docs Android Studio Guide, 15
Android Nougat Users

If you are using a device with Android Nougat (7.x) or newer, you can display the available apps by simply swiping upwards
from the bottom of the touchscreen. Newer versions of Android no longer have the App Drawer feature.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 16

Chapter 2

Configuring your Hardware AS

2.1 Configuring your Android Devices

2.1.1 What Needs to Be Configured for My Control System?

Control Hub Configuration

Note: References to the DRIVER STATION smartphone may instead apply to the REV Driver Hub, which is preloaded with
the Driver Station (DS) app.

Teams who are using a 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 “<TEAM NUMBER>-DS” (where <TEAM NUMBER> is replaced by your team number).
• Install the Driver Station (DS) app onto the DRIVER STATION device. (The DS app is pre-installed on the REV Driver
Hub.)
• Put your phone into Airplane Mode (with the WiFi radio still on).
• Pair (i.e., wirelessly connect) the DRIVER STATION to the Control Hub.

Important: Eventually the Control Hub will need be renamed so that its name complies with the 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 this tutorial.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 17
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 smartphone for use as an DRIVER STATION. The process is as follows,
• Rename one smartphone to “<TEAM NUMBER>-RC” (replace <TEAM NUMBER> with your team number).
• Install the Robot Controller app onto the Robot Controller phone.
• Rename a second smartphone to “<TEAM NUMBER>-DS” (where <TEAM NUMBER> is replaced by your team number).
• Install the Driver Station app onto the DRIVER STATION device. (The DS app is pre-installed on the REV Driver Hub.)
• Put your phones into Airplane Mode (with the WiFi radios still on).
• Pair (i.e., wirelessly connect) the DRIVER STATION to the Robot Controller.

2.1.2 Renaming Your Smartphones

The official rules of the FIRST Tech Challenge (see <RS01>) require that you change the Wi-Fi name of your smartphones to
include your team number and “-RC” if the phone is a Robot Controller or “-DS” if it is a DRIVER STATION. A team can insert
an additional dash and a letter (“A”, “B”, “C”, etc.) if the team has more than one set of Android phones.
If, for example, a team has a team number of 9999 and the team has multiple sets of phones, the team might decide to
name one phone “9999-C-RC” for the Robot Controller and the other phone “9999-C-DS” for the DRIVER STATION. The “-C”
indicates that these devices belong to the third set of phones for this team.
The name of a Robot Controller phone can be changed in the RC app, using instructions found here. It can also be changed
at the Manage page from the RC app, a paired DS app, or a connected laptop; click Apply Wi-Fi Settings when done.
The name of a DRIVER STATION device can be changed in the DS app, using instructions found here.
As an alternate, the device names can be changed at the Android system level, as described below.

Note: It will take an estimated 5 minutes per phone to complete this task.

Step Image
continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 18
Table 1 – continued from previous page

1. Browse the list of available apps on the smartphone

and locate the Settings icon. Click on Settings icon
to display the Settings screen.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 19
Table 1 – continued from previous page

2. Click on Wi-Fi to launch the Wi-Fi screen.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 20
Table 1 – continued from previous page

3. Touch the three vertical dots to display a pop-up

menu.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 21
Table 1 – continued from previous page

4. Select Advanced from the pop-up menu.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 22
Table 1 – continued from previous page

5. Select Wi-Fi Direct from the Advanced Wi-Fi screen.

6. Touch the three vertical dots to display a pop-up

menu.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 23
Table 1 – continued from previous page

7. Select Configure Device from the pop-up menu.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 24
Table 1 – continued from previous page

8. Use touch pad to enter new name of device. If the de-

vice will be a Robot Controller, specify your team num-
ber 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.

9. After renaming phone, power cycle thedevice.

2.1.3 Installing the FIRST Tech Challenge Apps

As of 2021, the SDK 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 devices: REV Control Hub, REV Expansion Hub,
REV Driver Hub, and other approved Android devices (see section below, called Updating Apps on Android Phones). Here are
some of the benefits:
• Connect to a REV Control Hub via WiFi.
• One Click update of all software on connected devices.
• Pre-download software updates without a connected device.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 25
• Back up and restore user data from Control Hub.
• Install and switch between DS and RC applications on Android Devices.
• Access the Robot Control Console on the Control Hub.
The app releases are also available on the FTCRobotController Github repository. It is possible to “side-load” the apps onto
the Robot Controller (RC) and Driver Station (DS) phones. However, this section of the document does not include such
instructions; other document pages describe side-loading the RC app and the DS app.

Updating Apps and Firmware on REV Devices (REV Expansion Hub, REV Control Hub, REV Driver Hub)

The REV Hardware Client software is used to install and update apps, 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 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 Control Hub, update the Driver Station (DS) app on a REV Driver Hub, or update firmware.

Updating Apps on Android Phones

The REV Hardware Client software is used to install, uninstall, and update apps on Android phones. However, the phones
must have Developer Options enabled in order for the phone to be properly recognized and updated by the REV Hardware
Client software. The process for enabling Developer Options is as follows:

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 26
Step Image

1. Go to “Settings”, then tap “About device” or “About

phone”.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 27
Table 2 – continued from previous page
Step Image

2. Scroll down, then tap Build number seven times. De-

pending on your device and operating system, you
may need to tap Software information, then tap Build
number seven times.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 28
Table 2 – continued from previous page
Step Image

3. Enter your pattern, PIN or password to enable the De-

veloper options menu.

4. The “Developer options” menu will now appear in your

Settings menu. Depending on your device, it may ap-
pear under Settings >General > Developer options.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 29
Table 2 – continued from previous page
Step Image

5. To disable the Developer options at anytime, tap the

switch.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 30
2.1.4 Placing Phones into Airplane Mode with Wi-Fi On

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 the robot
during a match.

Note: It will take an estimated 2.5 minutes per phone to complete this task. Also note that the screens displayed on your
Android devices might differ slightly from the images contained in this document.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 31

Step Image

1. On the main Android screen of each smartphone,

use your finger to slide from the top of the screen
down towards the bottom ofthe screen to display
the quick configuration screen. Note that for some
smartphones you might have to swipe down more
than once to display the quick configuration screen,
particularly if there are messages or notifications dis-
played at the top of your screen. Look for the Airplane
mode icon (which is shaped like an airplane) and if the
icon is not activated, touch the icon to put the phone
into airplane mode.

2. Placing the phone into airplane mode will turn off

the Wi-Fi radio. If the Wi-Fi icon has a diagonal line
through it (see Step 1 above), then the Wi-Fi radio is
disabled. You will need to touch the Wi-Fi icon on the
quick configuration screen to turn the Wi-Fi radio back
on.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 32
2.1.5 Pairing the DRIVER STATION to the Robot Controller

Control Hub Pairing

The REV Robotics Control Hub should come with the Robot Controller app 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. 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 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.

Also note that it will take an estimated 10 minutes to complete this task.

Step Image

1. Connect an approved 12V battery to the power switch

(REV-31-1387) and make sure the switch is in the off
position. Connect the switch to an XT30 port on the
Control Hub and turn the switch on. The LED should
initially be blue on the Control Hub.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 33
Table 3 – continued from previous page
Step Image

2. It takes approximately 18 seconds for the Control Hub

to power on. The Control Hub is ready to pair with the
Driver Station when the LED turns green. Note: the
light blinks blue every ~5 seconds to indicate that the
Control Hub is healthy.

3. On the Driver Station device, browse the available

apps and locate the ** FTC Driver Station** icon. Tap
on the icon to launch the Driver Station app. Note that
the first time you launch the app your Android device
might prompt you for permissions that the app will
need to run properly. Whenever prompted, press Al-
low to grant the requested permission.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 34
Table 3 – continued from previous page
Step Image

4. Touch the three vertical dots on the upper right hand

corner of the main screen of the Driver Station app.
This will launch a pop-up menu.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 35
Table 3 – continued from previous page
Step Image

5. Select Settings from the pop-up menu.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 36
Table 3 – continued from previous page
Step Image

6. From the Settings screen, look for and select Pairing

Method to launch the Pairing Method screen.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 37
Table 3 – continued from previous page
Step Image

7. Touch the words Control Hub to indicate that this

DRIVER STATION will be pairing with a Control Hub.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 38
Table 3 – continued from previous page
Step Image

8. From the Settings screen, look for and select Pair with
Robot Controller to launch the Pair with Robot Con-
troller screen.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 39
Table 3 – continued from previous page
Step Image

9. From Pair with Robot Controller screen,look for and

press the Wifi Settings button to launch the device’s
Android WifiSettings screen.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 40
Table 3 – continued from previous page
Step Image

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 pre-
fix FTC- (FTC-1Ybr in this example). The default net-
work name should be listed on a sticker attached to
the bottom side of the Control Hub.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 41
Table 3 – continued from previous page
Step Image

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 Con-
trol Hub network is password. Also note that when
you connect to the Control Hub’s WiFi network suc-
cessfully, the DRIVER STATION will not have access
to the Internet.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 42
Table 3 – continued from previous page
Step Image

12. After you successfully connected to the Hub, use the

back arrow to navigate to theprevious screen. You
should see the name of the WiFi network listed un-
der “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.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 43
Table 3 – continued from previous page
Step Image

13. Verify that the DRIVER STATION screen has changed

and that it now indicates that it is connected to the
Control Hub. The name of the Control Hub’s WiFi net-
work (FTC-1Ybr in this example) should be displayed
in the Network field on the Driver Station.

Two Android Smartphone Pairing

Important: If your DRIVER STATION was previously paired to a Control Hub, and you currently would like to connect to
an Android smartphone Robot Controller, then before attempting to pair to the Robot Controller, you should forget the Wi-
Fi network for the previous Control Hub (using the Android Wifi Settings screen on the DRIVER STATION) and then power
cycle the DRIVER STATION phone. If the previous Control Hub is powered on and if you haven’t forgotten this network, then
the DRIVER STATION might try and connect to the Control Hub and might be unable to connect to the Robot Controller
smartphone.

Once you have successfully installed the apps onto your Android phones, you will want to establish a secure wireless con-
nection between the two devices. This connection will allow your DRIVER STATION device to select op modes on your Robot
Controller phone and send gamepad input to these programs. Likewise, it will allow your op modes running on your Robot
Controller phone to send telemetry data to your DRIVER STATION device where it can be displayed for your drivers. The
process to connect the two phones is known as pairing.
Note that it will take an estimated 10 minutes to complete this task.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 44
continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 45
Table 4 – continued from previous page
Step Image
Step Image

1. On the Robot Controller device, browse the available

apps and locate the FTC Robot Controller icon. Tap
on the icon to launch the Robot Controller app. Note
that the first time you launch the app your Android de-
vice might prompt you for permissions that the app
will need to run properly. Whenever prompted, press
Allow to grant the requested permission.

continues
Gracious Professionalism® - “Doing your best work while treating others with respect and kindness on next
- It’s what page
makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 46
Table 4 – continued from previous page
Step Image

2. Verify that the Robot Controller app is running. The

Robot Status field should read running if it is working
properly.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 47
Table 4 – continued from previous page
Step Image

3. On the DRIVER STATION device, browse the available

apps and locate the FTC Driver Station icon. Tap on
the icon to launch the Driver Station app. Note that
the first time you launch the app your Android device
might prompt you for permissions that the app will
need to run properly. Whenever prompted, press Al-
low to grant the requested permission.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 48
Table 4 – continued from previous page
Step Image

4. Touch the three vertical dots on the upper right hand

corner of the main screen of the Driver Station app.
This will launch a pop-up menu.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 49
Table 4 – continued from previous page
Step Image

5. Select Settings from the pop-up menu.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 50
Table 4 – continued from previous page
Step Image

6. From the Settings screen, look for and select Pairing

Method to launch the Pairing Method screen.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 51
Table 4 – continued from previous page
Step Image

7. Verify that the Wifi Direct mode is selected, which

means that this DRIVER STATION will be pairing with
another Android device.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 52
Table 4 – continued from previous page
Step Image

8. From the Settings screen, look for and select Pair with
Robot Controller to launch the Pair with Robot Con-
troller screen.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 53
Table 4 – continued from previous page
Step Image

9. Find the name of your Robot Controller from the list

and select it. After you have made your selection, use
the back-arrow key to return to the Settings screen.
Then press the back-arrow key one more time to re-
turn to the main DRIVER STATION screen.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 54
Table 4 – continued from previous page
Step Image

10. When the DRIVER STATION returns to its main screen,

the first time you attempt to connect to the Robot Con-
troller a prompt should appear on the Robot Controller
screen. Click on the ACCEPT button to accept the
connection request from the DRIVER STATION.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 55
Table 4 – continued from previous page
Step Image

11. Verify that the DRIVER STATION screen has changed

and that it now indicates that it is connected to the
Robot Controller. The name ofthe Robot Controller’s
remote network (9999-C-RC in this example) should
be displayed in the Network field on the DRIVER STA-
TION.

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 56
Table 4 – continued from previous page
Step Image

12. Verify that the Robot Controller screen has changed

and that it now indicates that it is connected to the
DRIVER STATION.The Network status should read ac-
tive, connected on the Robot Controller’s main screen.

2.2 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 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.
The images in this section use an Expansion Hub to demonstrate how to connect the devices. The process, however, is
identical for a Control Hub.
When the instructions in this section use the word “Hub”, they are referring to a Control Hub or Expansion Hub.

Release 0.2 03/12/2024

 2
2.2.1 Connecting 12V Power to the Hub
FTC Docsdraws power from a 12V rechargeable battery. For safety reasons, the battery has a 20A fuse
The Hub Android
built Studio Guide, 57
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.

Connecting 12V Power to the Hub Instructions

1. If your 12V battery has a Tamiya style connector, connect the Tamiya to XT30 adapter cable to the matching end of the
switch cable.

Note: Do not connect the 12V battery to the Tamiya adapter yet. We will connect the battery during a later step.

2. Connect the other end of the switch cable to a matching XT30 port on the Hub.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 58

3. Verify that the switch is in the OFF position.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 59

4. Connect the 12V battery to the Tamiya to XT30 cable.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 60

5. Turn on the switch and verify that the Hub is drawing power from the battery. Note that the Hub’s LED should be illuminated
(notice the blue LED in upper right-hand corner of the Hub in the image below).

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 61

6. Turn off the switch and verify that the Hub is off. Note that the Hub’s LED should not be illuminated.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 62

2.2.2 Connecting a Motor to the Hub

The Hub can drive up to four (4) 12V 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 Powerpole connectors to the Hub motor port (see FIRST Tech Challenge Robot
Wiring Guide for more information).

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 63

For the examples in this tutorial, FIRST recommends that the user build a simple rig to secure the motor in place and prevent
it from moving about during the test runs. The image above shows a Tetrix motor installed in a rig built with a Tetrix motor
mount and some Tetrix C-channels. A gear was mounted on the motor shaft to make it easier for the user to see the rotation
of the shaft.
Note that it will take an estimated 2.5 minutes to complete this task.

Connecting a 12V Motor to the Hub Instructions

1. Connect the Anderson Powerpole end of the motor’s power cable to the Powerpole end of the Anderson to JST VH adapter
cable.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 64

2. Connect the other end of the Anderson to JST VH adapter cable into the motor port labeled “0” on the Hub.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 65

2.2.3 Connecting a Servo to the Hub

The Hub has 6 built-in 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.
Note that it will take an estimated 2.5 minutes to complete this task.

Connecting a Servo to the Hub Instructions

1. Connect the servo cable to the servo port labeled “0” on the Hub. Note that the ground pin is on the left side of the servo
port.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 66

2. Verify that the black ground wire of the servo cable matches the ground pin of the servo port (which is aligned on the left
side of the port).

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 67

2.2.4 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 #0 on the Hub.
Note that it will take an estimated 2.5 minutes to complete this task.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
Connecting a Color-Distance Sensor to the Hub Instructions

FTC Docs one end of the 4-pin JST PH cable to the REV Robotics Color-Distance sensor.
1. Connect Android Studio Guide, 68

2. Plug the other end of the 4-pin JST PH cable to the I2C port labeled “0” on the Hub.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 69

2.2.5 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 ports.
Note that in the case of the REV Robotics Touch 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 that gets connected when a standard REV Robotics 4-pin JST PH cable is used. For the
“0-1” port, it is the pin labeled “1” that gets connected through the 4-pin cable. Similarly, for the “2-3” port, it is the pin labeled
“3” that gets connected through the 4-pin cable.
Note that it will take an estimated 2.5 minutes to complete this task.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 70
Connecting a Touch Sensor to the Hub Instructions

1. Connect one end of the 4-pin JST PH cable to the REV Robotics Touch sensor.

2. Plug the other end of the 4-pin JST PH cable to digital I/O port labeled “0” on the Hub.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 71
2.3 Configuring Your Hardware

This page contains information on configuring your control system hardware such that you may use them in your own
projects.

2.3.1 Getting Started

Getting a Smartphone Robot Controller Ready

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 Controller will know what hardware is
available on the Control Hub’s or Expansion Hub’s external ports.

Connecting an Android Smartphone to an Expansion Hub

If you are using an Android smartphone as a Robot Controller, you must physically connect the Robot Controller smartphone
to the Expansion Hub using a USB cable and an On-The-Go (OTG) adapter. Also, you should verify that the DRIVER STATION
is currently paired to the Robot Controller.

Connecting an Android Smartphone to an Expansion Hub Instructions

1. Power on the Expansion Hub by turning on the power switch.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
2. Plug the Type B Mini end of the USB cable into the USB mini port on the Expansion Hub.

FTC Docs Android Studio Guide, 72

3. Plug the Type A end of the USB cable into the OTG adapter.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 73

4. Verify that your Robot Controller smartphone is powered on and unlocked. Plug in the USB Micro OTG adapter into the
OTG port of the Robot Controller phone.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 74

Note that when the OTG adapter is plugged into the smartphone, the phone will detect the presence of the Expansion Hub
and launch the Robot Controller app.
5. The first time you connect the Robot Controller smartphone to the Expansion Hub, the Android operating system should
prompt you to ask if it is OK to associate the newly detected USB device (which is the Expansion Hub) with the Robot
Controller app.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 75

Important: You might be prompted multiple times to associate the USB hardware with the Robot Controller. Whenever you
are prompted by your phone with this message, you should always select the “Use by default for this USB device” option and
hit the “OK” button to associate the USB device with the Robot Controller app. If you fail to make this association, then the
Robot Controller app might not reliably connect to this Expansion Hub the next time you turn your system on.

Getting the Control Hub Ready

If you are using a Control Hub, you do not need to make any additional connections. You simply need to make sure that the
Control Hub is powered on and paired to the DRIVER STATION.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
Creating a Configuration File Using the DRIVER STATION

FTC Docs Android Studio Guide, 76

Although the configuration file needs to reside on the Robot Controller, for this tutorial we will use the DRIVER STATION app
to create the configuration file remotely. The DRIVER STATION can be used to create a configuration file for a Control Hub
or for an Android smartphone Robot Controller.

Creating a Configuration File on the Robot Controller using the DRIVER STATION Instructions

1. Touch the three vertical dots in the upper right hand corner of the Driver Station app. This will launch a pop-up menu.

2. Select Configure Robot from the pop up menu to display the Configuration screen.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 77

3. If your Robot Controller does not have any existing configuration files, the screen will display a message indicating that
you need to create a file before proceeding.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 78

Hit the New button to create a new configuration file for your Robot Controller.
4. When the new configuration screen appears, the Robot Controller app will do a scan of the serial bus to see what devices
are connected to the Robot Controller.

Release 0.2 03/12/2024

 2
It will display the devices that it found in a list underneath the words “USB Devices in configuration.” You should see an entry
that says something like “Expansion Hub Portal 1” in the list.
FTC Docs Android Studio Guide, 79
Your Expansion Hub is listed as a Portal because it is directly connected to the Robot Controller phone through the USB
cable or in the case of the Control Hub through the internal serial bus.
If you do not see your Expansion Hub Portal listed and you are using a smartphone as a Robot Controller, check the wired
connections to make sure they are secure and then press the Scan button one or two times more to see if the smartphone
detects the device on a re-scan of the USB bus.
5. Touch the Portal listing (“Expansion Hub Portal 1” in this example) to display what Expansion Hubs are connected through
this Portal.

Since we only have a single Expansion Hub connected, we should only see a single Expansion Hub configured (“Expansion
Hub 2” in this example).
6. Touch the Expansion Hub listing (“Expansion Hub 2” in this example) to display the Input/Output ports for that device.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 80

The screen should change and list all the motor, servo and sensor ports that are available on the selected Expansion Hub.

2.3.2 Configuring a DC Motor

Now that you’ve created a file, you will need to add a DC Motor to the 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 Saving the Configuration Information step.

Release 0.2 03/12/2024

 2
Configuring a DC Motor Instructions

FTC Docsthe word Motors on the screen to display the Motor Configuration screen.
1. Touch Android Studio Guide, 81

2. Since we installed our motor onto port #0 of the Expansion Hub, use the dropdown control for port 0 to select the motor
type (Tetrix Motor for this example).

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 82

3. Use the touch screen keypad to specify a name for your motor (“motorTest” in this example).

4. Press the Done button to complete the motor configuration. The app should return to the previous screen.

Release 0.2 03/12/2024

 2
2.3.3 Configuring a Servo
FTC Docs
You will Android
also want to add a servo to the configuration file. In this example, you are using a standard Studio
180-degree Guide, 83
servo.

Configuring a Servo Instructions

1. Touch on the word Servos on the screen to display the Servo Configuration screen.

2. Use the dropdown control to select “Servo” as the servo type for port #0.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 84

3. Use the touch pad to specify the name of the servo (“servoTest” for this example) for port #0.

4. Press the Done button to complete the servo configuration. The app should return to the previous screen.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 85

2.3.4 Configuring a Color Distance Sensor

The REV Robotics Color Distance Sensor is an 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 that in this tutorial, the word “distance” is used interchangeably with the word “range”.

Configuring a Color Distance Sensor Instructions

1. Touch the words I2C Bus 0 on the screen to launch the I2C configuration screen for this I2C bus.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 86

The 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 Expansion Hub has its own
built-in inertial measurement unit (IMU) sensor. This sensor can be used to determine the orientation of a robot, as well as
measure the accelerations on a robot.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 87

The built-in IMU is internally connected to I2C Bus 0 on each Expansion Hub. Whenever you configure an 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.
3. Press the Add button to add another I2C device to this bus.

4. Select “REV Color/Range Sensor” from the dropdown selector for this new device. Use the touchscreen keyboard to name
this device “sensorColorRange”.

5. Press the Done button to complete the I2C sensor configuration. The app should return to the previous screen.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 88

2.3.5 Configuring a Digital Touch Sensor

The REV Robotics Touch Sensor is a digital sensor. An 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.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 89

2. Use the touch screen to add a “REV Touch Sensor” for port #1 and name the device “testTouch”.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 90

Notice that we are configuring the Touch Sensor on port #1 instead of port #0. This is because when the REV Robotics Touch
Sensor is connected to a digital port using a standard 4-wire JST sensor cable, it is the second digital pin that is connected.
The first pin remains disconnected.
3. Press the Done button to return to the previous screen.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 91

2.3.6 Configuring an External UVC Camera and a Powered USB Hub

Introduction

Game rules and in the Game Manual Part 1 have been modified to allow the use of USB Video Class (UVC) Compatible
Cameras for computer vision-related tasks. Teams have the option of using an externally connected camera instead of the
Android smartphone’s built-in camera 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 Robot Controller-related tasks.
The disadvantage of using an external camera is there is additional complexity introduced with the USB-connected camera.
An external camera adds costs and weight to a robot and it needs to be wired correctly to run properly.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 92
What type of External Camera can be Used?

The system supports a “UVC” or USB Video Device Class cameras. Theoretically, if a camera is UVC compliant, then it should
work with the system. However, there are a couple of recommended web cameras that have been tested with the FIRST Tech
Challenge software and have been calibrated to work accurately with this software:
• Logitech HD Webcam C310
• Logitech HD Pro Webcam C920
Note that calibrating a UVC camera is an advanced task. Details on how to create a calibration file can be found in the
comments of the teamwebcamcalibrations.xml file that is available as part of the ftc_app project folder (visit this link for an
online copy of the file).

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 93
USB Hub

Teams who would like to use an external camera will need a USB hub to connect their Android Robot Controller to the external
camera and the REV Robotics Expansion Hub. To work properly, the USB hub should meet the following requirements:
1. Compatible with USB 2.0.
2. Supports a data transfer rate of 480Mbps.
Note that the Modern Robotics Core Power Distribution Module cannot be used for this task since its data transfer speed is
not fast enough to work with the USB-connected webcam.
Also note that rule c(iii) permits the use of a powered USB hub to make this connection. If a team uses a powered USB hub,
the power to operate the USB hub can only come from either of the following sources:
1. An externally connected USB 5V Battery Pack.
2. The 5V DC Aux power port of a REV Robotics Expansion Hub (note that this requires advanced skills to implement).
FIRST has tested a few USB 2.0 powered hubs and recommends one from Anker. At the time this document was written,
this hub was available from Anker.com.

The Anker 4-port powered hub is convenient because it has a Micro USB port that is used to connect the hub to a 5V power
source (highlighted with orange circle in figure below).

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 94

This port allows a user to plug a standard USB type B Micro Cable into the hub, and then connect the other end of the cable
(which has a USB Type A connector) into the output port of an external 5V USB battery pack. In the image below, the Anker
4 port hub is powered by a “limefuel” external 5V battery pack using a standard Type A to Type B USB Micro cable. Note the
battery is highlighted by the yellow outline in the figure below.

A USB hub can also draw power from the 5V auxiliary ports on the REV Robotics Expansion Hub. This configuration requires
that the user have a special cable that on one end can be plugged into the 5V Auxiliary port and on the other end can be
plugged into the power port of the USB hub.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 95

Note that teams can create this special cable using one end of a servo extension cable (to plug into the 5V aux port) and
one end of a Micro 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 guidance from an adult mentor who has expertise in electronics and wiring! It is
extremely important that the polarity is correct for this special cable. If the polarity is reversed it could damage your
electronic equipment.

Sample Op Modes

There are sample Blocks and Java Op Modes that demonstrate how to use the external UVC web camera for Vuforia or
TensorFlow operations. Before a team can use the external UVC camera, a configuration file must be configured with the
external camera defined as one of the USB-connected devices.
Once a valid configuration file has been defined and activated, the programmer can use the external UVC camera, instead of
the internal Android cameras, for vision-related tasks.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 96

2.3.7 Configuring an External Webcam with a Control Hub

Introduction

The Game Manual Part 1 allows USB Video Class (UVC) cameras for robot vision tasks. If you are using a REV Robotics
Control Hub, then you will need to use an external webcam, since the Control Hub does not include a built-in camera. This
document describes how to connect, configure and use an external webcam with a Control Hub.
Special thanks to Chris Johannesen of Westside Robotics (Los Angeles) for putting together this documentation.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 97
Type of External Camera

Theoretically, any USB Video Class (UVC) camera should work with the system. However, FIRST recommends using UVC
web cameras from Logitech. The following cameras have been tested and calibrated to work accurately with SDK software:
• Logitech C270 HD Webcam
• Logitech C310 HD Webcam
• Logitech C920 HD Webcam
Calibrating a UVC camera is an optional, advanced task. Instructions for creating a calibration file are in the comments of
the teamwebcamcalibrations.xml file in the ftc_app project folder (visit this link for an online copy of the file).

Connecting the Camera

The UVC camera plugs directly into the USB 2.0 port on the REV Control Hub. Unlike the REV Expansion Hub, there is no
need for an external powered USB hub.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 98
Camera Configuration

Before using the external camera, it must be added to the active 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 configuration file. Note that the Scan operation for the Configure Robot activity should detect
the webcam and give it a default name of “Webcam 1”.

You can keep this default name (the sample Op Modes reference this name) or change it. If you change the webcam name,
make sure your Op Modes refer to this new name.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 99
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 Vuforia or TensorFlow operations.

Before opening and editing an Op Mode, verify that the intended configuration (with camera) is active. Also verify that the
name referenced in the Op Mode matches the name specified in the configuration file.

Image Preview

The FIRST Tech Challenge apps provide camera preview for ‘stream-enabled’ Op Modes using Vuforia or TensorFlow Object
Detection (TFOD).
On a paired DRIVER STATION device, with the camera connected and configured, select a stream-enabled Op Mode. Press
the INIT button, and wait briefly for streaming software to initialize; do not press the START button. Instead open the main
menu (the 3 dots in upper right hand corner of the screen) and select Camera Stream. This option appears only at this time,
during which the game pads and START button are disabled for safety.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 100

The camera image will appear on the DRIVER STATION screen. Manually touch the image to refresh it. To preserve band-
width, only one frame is sent at a time.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 101

This option may be used to adjust the camera, with frequent manual image refreshing as needed. When finished, open the
main menu and select Camera Stream again to turn off the preview. The preview image will close, the game pads will be
enabled, and the START button may be pressed to continue running the Op Mode.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 102

Important Note: Because the Camera Stream feature is only available during the INIT phase of an Op Mode, you must ensure
that the Vuforia library is activated in your Op Mode before the waitForStart command:

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 103

If you do not see the Camera Stream option in your main menu on your DRIVER STATION, then verify that the Vuforia function
is activated before the waitForStart command in your Op Mode. Also make sure you’ve given the system enough time to
initialize the Vuforia software before you check to see if Camera Stream is available.

External HDMI Monitor

Alternatively, camera output can be viewed on a display monitor or other device plugged into the HDMI port on the REV
Control Hub.

Important Note: While a portable display monitor can be used to view or troubleshoot the camera stream on your Control
Hub, teams are not allowed to have a portable display monitor connected to their Control Hub during a match.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 104
Advanced Users

For custom streams, advanced users of Android Studio may consult the API documentation for CameraStreamClient, Cam-
eraStreamServer and CameraStreamSource classes.

2.3.8 Using Two Expansion Hubs

Introduction

A single REV Robotics Control or Expansion Hub has a limited amount of input/output (I/O) ports available. In some in-
stances, you might want to use more devices than there are ports available. For these instances you might need to connect
a second Expansion Hub to your first Hub to add more I/O ports.
This document describes how to connect and configure two Expansion Hubs for use in the FIRST Tech Challenge. Note that
the FIRST Tech Challenge Competition Manual limits the maximum number of Expansion Hubs on a single robot to two.
Important Note: This document describes the process for setting up a smartphone Robot Controller with two Expansion
Hubs. Control Hubs have a reserved address, so you do not need to worry about an Expansion Hub’s address when it is the
only Expansion Hub connected to a Control Hub. However, the process for physically connecting and configuring them is
the same.

Equipment Needed

To follow along with the instructional steps in this document, you will need the following items:

Required Item(s) Image

Two (2) FIRST-approved Android smartphones. One should

have the Robot Controller app installed and the other should
have the Driver Station app installed. For a list of FIRST-
approved Android smartphones, refer to the current Game
Manual Part 1, rule <RE06>.

USB Type A male to type mini-B male cable.

Micro USB OTG adapter.

continues on next page

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 105
Table 5 – continued from previous page
Required Item(s) Image

REV Robotics Switch, Cable, & Bracket (REV-31-1387).

REV Robotics Tamiya to XT30 Adapter Cable (REV-31-

1382).

FIRST-approved 12V Battery (such as Tetrix W39057). For

a list of FIRST-approved 12V batteries, refer to the current
Game Manual Part 1, rule <RE03>.

Two(2) REV Robotics Expansion Hubs (REV-31-1153).

REV Robotics (or equivalent) 3-Pin JST PH Cable (REV-35-

1414, 3 pack shown but only one needed).

continues on next page

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 106
Table 5 – continued from previous page
Required Item(s) Image

REV Robotics XT30 Extension Cable (REV-31-1394).

Changing the Address of an Expansion Hub

You can use the Advanced Settings menu of the Robot Controller App to change the address of any connected Expansion
Hubs.
Important Note: If both of your Expansion Hubs have the same address or were just removed from the box (by default, the
address is set to 2), you need to change the address of one of them _before_ connecting them together. This guide assumes
that you will be setting the address of the first Expansion Hub before connecting the second Expansion Hub.
With your first Expansion Hub connected to the 12V battery and to the Robot Controller, launch the Settings menu from the
Robot Controller app (note you can also do this from the Driver Station app, if the DRIVER STATION is paired to the Robot
Controller).
1. Select the Advanced Settings item to display the Advanced Settings menu.
2. Then select the Expansion Hub Address Change item to display the Expansion Hub address screen.
3. The USB serial number of the Expansion Hub and its currently-assigned address should be displayed.
Important Note: If any Expansion Hubs that are physically connected and powered are not displayed, there may be an
address conflict. If this happens, disconnect all Expansion Hubs except the one whose address you want to change.
4. Use the dropdown list control on the right hand side to change an Expansion Hub’s address. Addresses that conflict with
other currently-connected Expansion Hubs won’t be available.
Push the “Done” button to change the address. You should see a message indicating that the Expansion Hub’s address has
been changed.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 107

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 108

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 109

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 110

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 111

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 112
Connecting the Two Expansion Hubs

1. After you have changed the address of one of the Hubs, you can use the 3-pin JST PH cable and the XT30 cable to daisy
chain the two Hubs together. Before you do this, disconnect the 12V battery and power switch from the first Expansion Hub.
Use the XT30 extension cable to connect an XT30 power port on one of the Expansion Hubs to an XT30 power port on the
other Hub.

2. The Expansion Hubs use the RS-485 serial bus standard to communicate between devices. You can use the 3-pin JST PH
cable to connect one of the ports labeled “RS485” on one Expansion Hub to one of the ports labeled “RS485” on the other
Expansion Hub.
Note that it is not important which “RS485” port that you select on an Expansion Hub. Either port should work.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 113

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 114

3. Once you have the two devices daisy chained together (12V power and RS-485 signal) you can reconnect the battery and
power switch, and then connect the Robot Controller and power on the devices.

Configuring Your Expansion Hubs

If you successfully daisy chained your two Expansion Hubs, then you should be able to create a new configuration file that
includes both devices.
Note: If you already have a configuration that contains just the USB-connected Expansion Hub, you can add the second
Expansion Hub by editing the configuration and pressing the “Scan” button.
Connect the Robot Controller and select the Configure Robot option from the Settings menu. Press the New button to create
a new configuration file. When you first scan for hardware, your Robot Controller should detect the Expansion Hub that is
immediately connected to the Robot Controller via the OTG adapter and USB cable. The Robot Controller will automatically
label this device as an Expansion Hub “Portal”. The Robot Controller will talk through this portal to the individual Expansion
Hubs.
If you click on the Portal item in the configuration screen, you should see two Expansion Hubs listed, each with their respective
addresses as part of their default device name.
You can save this configuration file and return to the main screen of the Robot Controller. After the robot has been restarted,
each Hub’s LED should be blinking in the manner that indicates its individual address.
Congratulations, you are now ready to use your dual Expansion Hubs! You can configure and operate these Hubs as you
would an individual Hub.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 115

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 116

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 117

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 118
2.3.9 Managing Electrostatic Discharge Effects

Introduction

Electrostatic discharge (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.
Note that this section only provides a brief overview of the physical phenomenon that causes ESD disruptions. You can use
the following link to view an in-depth white paper, written by Mr. Eric Chin (a FIRST alumnus and a 2018 summer engineering
intern), which examines and quantifies the efficacy of various ESD mitigation techniques:
Eric Chin’s White Paper on ESD Mitigation Techniques and their Efficacy
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 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 sun!

What is an Electrostatic Discharge Event?

An electrostatic discharge (ESD) event occurs when a highly charged conductive object (like the metal frame of a robot)
touches an uncharged or oppositely charged conductive object and discharges to it. Because of the high voltages involved
(up to tens of kilovolts), ESD events can produce extremely high electrical currents as the charge that was accumulated on
one object flows through a conductive path to the neutral or oppositely charged object.

Fig. 1: Positively charged robot next to neutral field wall.

How Robots Become Charged

Consider what happens when you shuffle your feet on a carpet in wool socks and then touch a door knob. You’ll almost
certainly get a shock. What causes this phenomenon? When two surfaces interact, there is a small amount of adhesion.
This means that they share electrons and if they are made from different materials the electron sharing may be uneven.
When the surfaces are taken apart, they can become charged. This is called the triboelectric effect.
A robot’s wheels moving on field tiles build charge on the robot frame just like your wool socks moving on carpet build charge
on your body. Many other plastic and rubber materials behave similarly. It is important to note that triboelectric charging
takes charge from one object and gives it to another, so the charges are mirrored. In the case of a FIRST Tech Challenge
robot, positive charge accumulates on the wheels and negative charge accumulates on the tiles.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 119

Fig. 2: Robots become charged due to the triboelectric effect.

Note that a robot with wheels that slide across the soft tiles of a competition field will build electrostatic charge on its frame
more rapidly than a robot with wheels that roll across the tiles.

Discharging a Robot

Current “wants” to flow from objects at higher potential to the objects at lower potential to equalize the voltage difference
between them and it will if given a conductive path to do so (like an uninsulated wire). In the case of a robotics competition,
if a robot is at a higher potential than another metallic object (such as a portion of the game field), an ESD event will occur
if the frame of the charged robot contacts the other object.
If the potential difference is high enough, it is also possible for current to flow through the air in the form of an electrical arc.
Arcing occurs when the air between two differently charged conductors becomes ionized and allows current to flow from
one conductor to the other. Arcs at voltages seen on FIRST Tech Challenge robots can jump air gaps of more than 3/8” (1
cm). Arcs behave almost like direct contact, so they can carry a significant amount of current. Visible sparks go with large
electrostatic arcs.

Fig. 3: Electric arc between two spheres of opposite charge.

What Steps can be Taken to Mitigate the Risk of an ESD Disruption?

Step 1: Treating the Tile Floor with Anti-Static Spray (Event Hosts Only)

One of the most effective ways to reduce the risk of disruption by ESD events is to treat the tile floors of a competition field
with anti-static spray. Anti-static spray increases electrical conductivity of the surface of the tiles. This helps prevent the
build-up of electrostatic charge on the robots as the move across the tile floor.
FIRST recommends the use of ACL Heavy Duty Staticide spray to treat the tiles. This spray is extremely effective at preventing
charge build up on the robots. Also, this spray only needs to be applied once and it will last for an entire event (and it will
work across multiple days).

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 120

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 121
Note that treating the tile floor is something that only the event host is authorized to do. Teams are not permitted to treat
the tile floor themselves.

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 a shock.

Fig. 4: A snap-on ferrite choke.

Using ferrite chokes can be a very effective method for mitigating the effects of ESD:
1. Use USB cables that have built-in or snap-on ferrite chokes.
2. Install snap-on ferrite chokes onto your signal cables:
• Sensor cables
• Encoder cables
• 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 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 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.
Electrically isolating or insulating the electronics from the frame can help avoid disruptions due to this type of shock.

Sub Step A: Mounting Electronics on a Non-Conductive Material

Mounting the Control System Electronics on a non-conductive material, such as a thin sheet of plywood or a sheet of PVC
type A, can help reduce the risk of an ESD event between the frame and the electronics. Using a non-conductive, rigid panel
can also help with wire management and strain relieving.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 122

Sub Step B: Isolate Exposed or Poorly Insulated Parts of the Electronics

Certain parts of the Control System’s electronics have exposed metal or are poorly insulated. If these parts are placed too
close to the metal frame, a shock can occur if a charge accumulates on the frame.

Fig. 5: Electrostatic shocks can occur at poorly insulated or exposed portions 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 charge accumulates on the metal frame of the robot, and the end of sensor cable is placed close to the
frame, a shock can occur and this shock can disrupt or even damage the I2C port of an Expansion Hub.
Similarly, some servo extension cables (see figure above) have exposed portions of metal that could be vulnerable to ESD
unless properly isolated or insulated.

Fig. 6: Keep exposed portions of the electronics more than 3/8” (10mm) away from the frame.

Moving these vulnerable areas of the electronics system away from the frame (with an air gap greater than 3/8” or 10mm)
can help reduce the risk of an ESD disruption. Using electrical tape to insulate these areas can be equally effective and may
be easier to implement.

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 123

Fig. 7: Electrical tape can be used to insulate exposed or poorly insulated metal.

Step 3: Covering Exterior Metal Features with Electrically Insulated Material

Another ESD mitigation strategy is to cover exposed portions of metallic frame pieces with an electrically insulating material.
Covering the conductive exterior parts of a robot with a non-conductive material reduces the risk that they will touch a
conductive object at a different electrical potential and trigger an ESD event. Wooden bumpers, electrical tape, and other
non-conductive coatings are all effective.

Fig. 8: Insulating portions of the robot that touch other metallic objects on the field can help.

In past seasons, teams who have done this have observed reductions in the frequency and severity of ESD events on their
robots.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 124
Step 4: Ground Electronics to Metal Frame with an Approved Cable

Because it is difficult to perfectly isolate the electrical system, it is beneficial to ground the electrical system to the frame
of the robot to prevent a potential difference from building up between the frame and the electronics. Doing this can help
reduce the risk that a shock can occur between the frame of a robot and the Control System electronics.

Fig. 9: The REV Resistive Grounding Strap (REV-31-1269) is an approved grounding cable.

It is important that the grounding only be done using a FIRST-approved, commercially manufactured cable (i.e., the REV-31-
1269 Resistive Grounding Strap). A FIRST-approved cable has an appropriately sized inline resistor. This resistor is critical
because it acts as a safeguard to prevent excessive current from flowing through the frame of the robot if a “hot” (positive)
wire of the electronics system is inadvertently short circuited to the frame of the robot. Also, the commercially manufactured
grounding cable has a keyed connection, which is designed to prevent a user from inadvertently connecting a hot (12V) line
to the frame of robot.
Note that if your team uses Anderson Powerpole connectors, then you will need to use the REV Robotics Anderson Powerpole
to XT30 Adapter cable in conjunction with REV Robotics’ Resistive Grounding Strap:
To ground the electronics, plug one end of the FIRST-approved cable into a spare XT30 port on the Control System electronics.
Then bolt the other end using a conductive (i.e., metal) bolt to the frame of the robot.
It might initially seem contradictory to both insulate the electronic components of the control system from the frame and
to also ground the electronics to the frame. However, if the electronics are not grounded to the frame, shocks can occur
if a charge builds on the robot frame and an exposed or poorly insulated portion of the electronics (such as the base of a

Release 0.2 03/12/2024

 2
FTC Docs Android Studio Guide, 125

Fig. 10: The REV-31-1385 adapter is approved for use with REV’s Resistive Grounding Strap.

Fig. 11: Ground the electronics to the frame using a FIRST-approved cable.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
REV Robotics color sensor) gets close it. If the electronics are grounded to the frame, the grounding wire helps keep the
electronics at the same potential as the frame, preventing arcs between the two systems.
FTC Docs Android Studio Guide, 126

2.3.10 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 lost and the robot controller will be unable to communicate with your hardware.

Saving the Configuration Information Instructions

1. Press the Done button to go up one level in the configuration screens.

2. Press the Done button again to return to the highest level in the configuration screens.

3. Press the Save button.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 127

4. When prompted, specify a configuration file name using the touchscreen’s keypad (use “TestConfig” for this example).

5. Press the OK button to save your configuration information using that file name.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2

FTC Docs Android Studio Guide, 128

6. After the configuration file has been saved, touch the Android back-arrow button to return to the main screen of the app.

Release 0.2 03/12/2024

 2

FTC Docs Android Studio Guide, 129

7. Verify that the configuration file is the active configuration file on the main DRIVER STATION screen.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 2
FTC Docs Android Studio Guide, 130

Release 0.2 03/12/2024

 3
FTC Docs Android Studio Guide, 131

Chapter 3

Installing Android Studio AS

3.1 Installing Android Studio AS

3.1.1 Android Developer Website

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:
• https://developer.android.com/studio
Android Studio is available on the Windows, MacOS, and Linux operating systems.

3.1.2 System Requirements

Before you download and install the Android Studio you should first check the list of system requirements on the Android
developer’s website to verify that your system satisfies the list of minimum requirements:
• Windows
• MacOS
• Linux

Caution: With the introduction of Android Studio Ladybug, the JDK that is packaged with Android Studio is incompatible
with the FtcRobotController workspace. If you install or update an existing installation to Android Studio Ladybug, you
will need to install JDK 17 separately.
Upon initial load of the FtcRobotController workspace using Android Studio Ladybug, an error will be displayed during the
Gradle sync and Android Studio will recommend that you upgrade Gradle. Do not upgrade Gradle.
For more detailed instructions see: Configuring

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3
3.1.3 Downloading and Installing Android Studio
FTC
OnceDocs
you have verified that your laptop satisfies the minimum system requirements, you can go Android Studio developer’s
to the Android Guide, 132
website to download and install Android Studio:
• https://developer.android.com/studio
Click on the green “DOWNLOAD ANDROID STUDIO” button to start the download process.

Accept the license terms and then push the blue “DOWNLOAD ANDROID STUDIO” button on the Android Developer webpage
to download the software.

Release 0.2 03/12/2024

 3

FTC Docs Android Studio Guide, 133

Once the setup package has downloaded, launch the application and follow the on-screen instructions to install Android
Studio.

3.1.4 Configuring Android Studio (Ladybug and later)

Note: See the Caution above for why this is necessary.

Note: Android Studio Ladybug updates the underlying JetBrains IntelliJ version such that the interface is a VSCode look
alike. The screenshots in this documentation use the JetBrains/Android Studio Classic UI which is no longer supported
natively by JetBrains. To follow along, users should install the Classic UI plugin.

1. Install JDK 17 If you did not already have this installed independently of Android Studio. e.g. If you were using Android
Studio’s bundled JDK, then when Ladybug is installed Android Studio will unhelpfully overwrite your old bundled JDK
version. Note there’s a bug in the Settings Build Tools Gradle dialog that may make you think your old version of the
JDK is there, but it is not. You must use an unbundled version of the JDK.
2. Go to File -> Settings and under Build, Execution, Deployment -> Build Tools -> Gradle use the Add JDK from disk option
to select the newly installed JDK 17. In the image below take careful note of the directory paths for the options labeled
jbr-17 and jbr-21. Note that they are the same. This is the aforementioned UI bug, and that is Android Studio overwriting
your old JDK. In this image you’ll see I’ve selected the JDK that was installed independently.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3
FTC Docs Android Studio Guide, 134

3.1.5 Do Not Upgrade Gradle

If you have upgraded Android Studio from an earlier version to Ladybug, or you did not install and configure the JDK prior to
loading a FtcRobotController workspace, then Android Studio may present an error and recommend that you upgrade Gradle.

Do not do this. The FtcRobotController build is incompatible with upgraded Gradle. If you do, you will presented with another,
even more, indecipherable error.

Release 0.2 03/12/2024

 3
To recover, you need to rollback the changes that Android Studio made upon that click. To do that select Git -> Uncommitted
Changes -> Show Shelf
FTC Docs Android Studio Guide, 135

That will show the changes you have in your workspace. You want to rollback the 4 gradle files shown in the following image.
You can either select the Changes checkbox to select all files, or individually select the gradle files. Note that if you have
changes in your workspace that haven’t been committed, you want to be careful not to select those files or you may lose
work.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3

FTC Docs Android Studio Guide, 136

Once you have the proper files selected, click the Rollback button.
Resync and that should revert you to the error that prompted you to upgrade Gradle in the first place. From there follow the
instructions above to install JDK 17.

3.2 Downloading the Android Studio Project Folder AS Legacy

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 GitHub
account. You can create one for free by visiting the GitHub website:
• https://github.com/
The software is stored in a repository called “FtcRobotController” under the FIRST-Tech-Challenge GitHub organization:
• https://github.com/FIRST-Tech-Challenge/FtcRobotController

Important: Advanced GitHub Users - this tutorial assumes that the user is a novice with respect to using GitHub and the git
version control software. If you are a GitHub power user, you can use git to clone a local copy of the public GitHub repository.
This document, however, does not explain how to use git to access the repository. It provides instructions on downloading
the repository as a .ZIP file instead.

Release 0.2 03/12/2024

 3
FTC Docs Android Studio Guide, 137

From the main repository web page, click on the “releases” link to jump to the Releases page for the repository. The Releases

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3
FTC Docs Android Studio Guide, 138
page should list the available software releases for the repository. The latest release should be displayed near the top of the
page.

Release 0.2 03/12/2024

 3
Each software release should include an Assets section that you can use to download the software that you will need to
program your robot. Note that you might have to click on the triangular symbol to expand this Assets section.
FTC Docs Android Studio Guide, 139

Click on the Source code (zip) link to download the compressed Android Studio project folder.

3.2.1 Extracting the Contents of the Archived Project File

Once you have downloaded the archived (.ZIP) project file you can move this file to the location of your choice.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3

FTC Docs Android Studio Guide, 140

Before you can import the project into Android Studio, you must first extract the contents of the archived project file. For
Windows users, right mouse click on the file and select “Extract All” from the pop up menu. Windows should prompt you to
select a destination for the extracted project folder. The dialog that appears should look similar to the one show in the figure
below.

Release 0.2 03/12/2024

 3
FTC Docs Android Studio Guide, 141

Highlight the suggested name for the destination folder (in the figure above, the suggested name is “FtcRobotController-6.0”)
and change the destination folder name into something more user friendly. In this example, we will change the name of the
destination folder to “mycopy”.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3
After you have renamed the destination folder, extract the contents of the archive to the folder. After the extraction process
is complete, verify that the project folder was successfully extracted to its target destination.
FTC Docs Android Studio Guide, 142

Once you have successfully extracted the contents of the archived file, you are ready to import the project into Android
Studio.

3.2.2 Importing the Project into Android Studio

In order to import the Project, you will need to launch the Android Studio software on your computer. On the main Android
Studio Welcome screen, select the option to “Import project (Gradle, Eclipse, ADT, etc.)” to begin the import process.

Release 0.2 03/12/2024

 3

FTC Docs Android Studio Guide, 143

Android Studio should prompt you to select the project folder that you would like to import. Use the file browser in the pop
up dialog box to locate and then select the folder that you extracted in an earlier section of this document. Make sure you
select the extracted project folder (and not the .ZIP file which might have a similar name to the extracted folder). Hit the
“OK” button to import the selected project into Android Studio.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3

FTC Docs Android Studio Guide, 144

In the figure above the project folder called “FtcRobotController-6.0” is selected to be imported into Android Studio. It might
take Android Studio several minutes to import the project. Once the project has been successfully imported, the screen
should look similar to the one depicted in the image below.

Release 0.2 03/12/2024

 3
FTC Docs Android Studio Guide, 145

3.3 Disabling Android Studio Instant Run Legacy AS

Attention: Instant Run was removed in Android Studio version 3.5, and is no longer an issue for versions of Android
Studio that are Android Studio 3.5 or newer. However, this article remains for those using FIRST Tech Challenge Software
Development Kit (SDK) v7.1 and older with previous versions of Android Studio.

3.3.1 Introduction

If you are an Android Studio user, one of the most important steps to take is to disable Android Studio Instant Run. Instant
Run is a feature that is designed to streamline the development process by reducing the time to apply code changes to your
app. Unfortunately, Instant Run is limited in function and when used with the FIRST Tech Challenge Android Studio project
folder, can cause severe and difficult-to-troubleshoot problems.
Teams who use Android Studio must disable Instant Run.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 3
FTC Docs Android Studio Guide, 146
3.3.2 Locating Instant Run Settings

When you first launch Android Studio a Welcome screen should appear. You can navigate to the Instant Run Settings from
this Welcome screen by selecting the “Configure->Settings” item from the “Configure” dropdown list in the lower right hand
corner of the screen.

On the left hand side of the Settings window, there should be a category called “Build, Execution, Deployment”. Within
this category, click on the “Instant Run” subcategory to display the Instant Run settings for your Android Studio installa-
tion. By default, Instant Run is enabled when you first install Android Studio. Uncheck the “Enable Instant Run to hot swap
code/resource changes on deploy (default enabled)” option and then click on the “OK” button to disable Instant Run.

Release 0.2 03/12/2024

 3
FTC Docs Android Studio Guide, 147

3.3.3 Additional Information

The Google Android Developer website has additional information about Instant Run. It also has instructions on how to
disable this feature:
https://developer.android.com/studio/run

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 148

Chapter 4

Managing an Android Studio Project AS

4.1 Fork and Clone from GitHub AS

Important: 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 via Downloading the SDK as a zip archive.

4.1.1 Forks vs. Clones

A Fork on GitHub is a copy of another repository on GitHub from one account to another account. The new
forked repository retains a parent-child relationship with the origin repository. Forks are typically used when soft-
ware will have an independent line of development, such as when FTC teams develop their own team code using the
FIRST-Tech-Challenge/FtcRobotController repository as a basis. FTC teams should create a Fork of the FIRST-Tech-
Challenge/FtcRobotController repository as a convenient way to manage their software development process. Thanks to
the parent-child relationship, when changes are made to the parent repository those changes can be easily tracked and
fetched/merged into the forked repository, keeping the forked repository up to date.

Warning: Teams should not issue pull requests against the upstream parent, the FIRST-Tech-
Challenge/FtcRobotContoller repository. Forks of the FIRST-Tech-Challenge/FtcRobotContoller repo may always
fetch changes, but should never attempt to push changes up to the repo.

A Clone is a copy of a repository, typically on a local computer. A team member creates a feature branch of the team’s
repository for feature development, and clones the branch to a local computer. Software development and testing then
happens completely within their local clone. Once they’re finished, or they’ve reached a checkpoint, the changes within the
local clone can then be pushed from their local clone back to the team fork. That feature branch can then be merged into the
team’s main repository branch once it has been accepted by the team. Multiple different developers can work seamlessly
using this process.

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 149

Fig. 1: The relationship between forks and clones. The clone exists on your local laptop while the fork exists on GitHub
servers.

4.1.2 Branch Strategies

A branch is a series of commits that are independent of any other lines of development and is typically used to develop
new features for the repository. The default branch for the FtcRobotController repository, and its forks and clones, is master
(though for all newer repositories created by GitHub the default branch is called main). Using branches judiciously can help
developers collaborate on a common set of software by isolating changes, keeping the default branch clean, and providing
space for feature development to iterate independent of software that’s been deemed ‘production ready’.

Fig. 2: A single branch with the default name of master

Each circle represents a commit to a branch. The name of the branch always points to the most recent commit, also known
as the HEAD. While there may be many branches there is only one HEAD and it always, unless it is in a detached state, points
to the latest commit of the currently checked out branch. All other commits point to their immediate parent.
A commit is a snapshot of the entire workspace at a point in time. Git does not store diffs. If you make a change to a file, and
create a new commit with the changed file, it stores the entire changed file in the commit. To avoid unnecessary duplication
of files, if your repository consists of three files - one changed and the other two were unchanged - then the snapshot merely
points back to the unchanged files rather than containing unchanged data.
Note that each commit has a parent which allows git to determine reachability of commits from different branches. It also
allows git to determine the common ancestor commit of any two branches, which is important when merging branches.
More on that later.
So what is a branch? A branch is simply a named pointer to a commit. When a branch is created you are just telling git

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 150
to create a name, and point it at a commit. Being on a branch simply means that when you add a new commit, git moves
the branch name to the new commit and the new commit’s parent is the commit that the branch name was pointing to
previously. Since this creates a line of development independent of the parent, developers can experiment, make changes,
develop new features, all without disrupting the work of other team members. When a developer is satisfied that a branch
is stable enough to be shared, the branch can be merged back into the parent.

Fig. 3: Two branches that point to the same commit.

Immediately after creating a branch the new branch name simply points to the latest commit from the branch that the new
branch was created from. Now imagine that we create a new commit on that branch.

Fig. 4: New commit on the feature branch.

Note how the new commit caused the name pointer of the feature branch to move to the new commit, while the name pointer
for the master branch remains on the prior commit, but the parent of the new commit is the commit that the name pointer
for master points to. If a new commit is added to the master branch then the parent of the new commit is also the commit
that master is pointing to thereby creating independent lines of development.
Eventually you typically want to merge that feature branch back into the main line of development represented by the master
branch. When you merge one branch into another, git traverses the ancestor commits of the branches to find the common
ancestor. It then determines what changed from the common ancestor, to the head of each branch, and applies those
changes to a new commit called a merge commit. An artifact of this process is that the merge commit will have two parents.
As shown above, the feature branch still exists. New commits added to the feature branch will diverge again from the master

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 151

Fig. 5: Two independent lines of development.

Fig. 6: Merging the feature branch back into the master branch.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 152
branch. However if development of the feature is finished, the branch can be deleted. Deletion of the branch simply results
in the name pointer being deleted. Branch deletion does not result in the deletion of any commits that were made on that
branch. As you can see here, the commit that was on the feature branch still exists and is reachable by referencing the
correct parent from the merge branch.
It can be useful to ensure that the default branch in team forks and clones matches the default branch for FIRST-Tech-
Challenge/FtcRobotController. However a typical development pattern will have team developers committing team software
back to the master branch, whether via merges from feature branches, or direct commits to master.

Fig. 7: FIRST-Tech-Challenge/FtcRobotController master vs. typical team repository master.

Team commits are represented by blue circles, while commits containing SDK updates are represented by green circles. The
purple circle is a merge commit. More on merges later. In this instance team commits are interleaved with SDK updates (1),
which produces a situation where the two default branches do not match.
(1) Not really, or maybe depending upon how the commit parentage lays out. This is a vastly simplified view of
things, but is sufficient to demonstrate the logical concept and is the view of things you get if you simply execute
git log. For an in-depth, approachable, explanation of exactly what is happening with commits as they relate to
branches see this tutorial.
While this is a perfectly acceptable, and a very common branch management strategy, certain benefits can be obtained if we
isolate the default branch so that it always matches the parent. The following figure demonstrates a clone whose master
branch is tracking the master branch from FIRST-Tech-Challenge/FtcRobotController.
The purple commit is a merge of v7.1 into the competition branch. In this diagram, v7.2 and v8.0 remain unmerged and the
competition branch will be building against v7.1 of the SDK.
Following this model means that commit history for the master branch for the team’s repository will always match the commit
history for the FIRST-Tech-Challenge/FtcRobotController’s master branch. All software that teams intend to compete with
is merged into a competition branch. Features, new software, experiments, etc, are worked on in child branches of the
competition branch and merge back into the competition branch, not the master branch. SDK updates to a team clone’s
master branch should always be conflict free, updates can be done independent of merges into a competition branch, and if

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 153

Fig. 8: Team repository’s master always matches FIRST-Tech-Challenge/FtcRobotController’s master branch.

something goes sideways when doing a merge of an SDK update into development it can be more straightforward to recover
as opposed to backing out of an update straight into master where the branches do not match.
More detailed information on the mechanics of branching can be found here Using Branches

4.1.3 Getting Started (Quick-Start Guide)

Important: The following assumes all operations are done on the master branch of your local repository.

1. Obtain and install GitForWindows This software contains a git client along with a bash shell. All of the command line
snippets below assume you are using a bash shell and that git is in your path. GitForWindows is the easiest way to
provide this for Windows machines. Macs have a built in bash shell called terminal, but git must be installed separately.
2. Fork the FIRST-Tech-Challenge/FtcRobotController repository into your account on GitHub.

Tip: This step requires you to have a GitHub account, and you need to be logged in to GitHub in order to Fork a
repository.

Forking the repository is as easy as clicking the “ Fork” button shown in the image above. This will take you to the “Create
a new fork” page, and will auto-fill the “Owner” and “Repository name” fields. Just enter a description (optional), leave
the “Copy the master branch only” option checked, and click the green “Create fork” button.
Once created, your new fork will be located at github.com/<username>/FtcRobotController unless you edited
the fork name.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 154

Fig. 9: Forking a GitHub repository.

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 155
3. Clone from your fork onto your local computer. Note in the image below the account is FIRST-Tech-Challenge, but after
your fork, the account should be your team account. In all other respects the user interface will be identical.

Fig. 10: Cloning a forked repository.

To clone your fork of the FtcRobotController, follow these steps:

1. Click the green “ Code” button shown in the image above.
2. Ensure the “Local” and “HTTPS” sub-tabs are selected.
3. Click the “” button to copy the url in the text entry box.
4. Open a “Git Bash” shell in a suitable directory. This is easily done on Windows by opening the File Explorer, finding
the directory you want to clone the repository into, right clicking on that directory folder and selecting “Git Bash
here”
5. Within the Git Bash shell, execute the following command

git clone <copied-url>

4. Git will download a clone of your repository. When it’s done, Code away…
5. This is the point where you can create a branch for feature development, if desired. To create a branch, we can create
and switch to a new branch via the following git-checkout command:

git checkout -b <branchname>

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 156
Using the -b option creates the new branch specified by <branchname> and automatically switches to that branch.
Omitting the -b option will simply switch to an existing branch if one exists.

Best Practices

• Do not make changes to software in the FtcRobotController directory within the repository. SDK updates will be much
easier if you do not change anything within the FtcRobotController directory.
• Limit the use of long-lived branches. Branches should implement a feature. Branches should not track milestones. For
example a branch named ‘league-meet-1’ is tracking a milestone. It is much better if your branches track smaller units
of development. ‘detect-target’, ‘drive-to-parking’, ‘drop-game-element’. Break your software down into tasks for the
robot to do, and use branches to implement those tasks. This will allow for much easier collaborative development,
much smaller change sets when merging, and much easier fetches and merges.
• Try to keep your git index clean. This will make fetches and merges easier. git status is your best friend here. Use
git status often to see what has changed in your local workspace. Commit often in logical chunks so that it is easy
to see the most recent changes.
• Use short, meaningful, commit messages. Do not use slang, offensive, or personal messaging in a commit message.
When you push your software to GitHub, those commit messages will be public. If you plan to eventually become a
professional software developer, and you retain your existing GitHub account any potential employer will be able to
review your commit messages. Tread lightly here.

4.1.4 Updating your Fork and Local Clone.

Updating the SDK involves pulling newly released software into both your local clone’s and your fork. There are two ways
to go about this. Either directly fetch and merge software from the parent into your fork on github, then fetch and merge to
your local, or fetch from the parent into your local clone, merge locally and then push to your fork.
This author prefers the latter because it gives the developer the opportunity test new software before pushing to the fork. It
also allows for merge conflict resolution locally instead of through GitHub’s UI.

Obtaining the Latest Software

When describing how to update a repository many basic tutorials will use the git pull command. The git pull command
is actually doing a fetch and merge for the user behind the scenes. This can be fine, but it is useful to understand the concepts
of fetching and merging as independent operations. If things go south, and you have a good concept of the underlying
mechanics, you are much more likely to be able to fix any subsequent problems.

Remotes

Git is fundamentally built around the idea that there can be many copies of a repository floating about on the internet, or
other people’s machines, or corporate file servers, or any number of locations. And that these repositories can linked to each
other remotely. A remote repository is simply defined as a version of a repository hosted somewhere else. In the preceding
examples, your fork of FtcRobotController is a remote of your local clone.

Remotes may be referenced in git commands and a repository can have any number of remotes. The default name for the
remote of a repository that has been cloned is ‘origin’. The conventional name of a remote that tracks the parent of a fork is
‘upstream’.

To see what remote are established for a given repository

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 157

Fig. 11: Illustration of FtcRobotController as remote named origin.

Fig. 12: A local repository with two remotes.

$ git remote -v

To add the parent of your team’s fork as a remote of your local clone

$ git remote add upstream https://github.com/FIRST-Tech-Challenge/FtcRobotController.git

Important: Setting the FIRST Tech Challenge FtcRobotController repository as an upstream remote of your local clone
allows you to fetch changes from the FIRST-Tech-Challenge/FtcRobotController to your local clone using the alias name
‘upstream’. This is very powerful. If the reason why this is important isn’t immediately obvious, please re-read the two
paragraphs under header marked Updating your Fork and Local Clone above.

The rest of this tutorial assumes that you have added FIRST-Tech-Challenge/FtcRobotController as an upstream in your
local clone.

Fetching

Fetching is the process of downloading software changes from a remote repository. Note specifically that fetching does not
modify any of the existing software in the repository that you are fetching into, git isolates the changes in the local repository.
If you are working with a team, and a teammate has pushed software to your FtcRobotController fork, you may fetch that
software to a local clone by running

$ git fetch origin

This will download any changes in all branches on the remote named origin that are not present in the local repository.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 158

Fig. 13: Fetching changes from origin.

Merging

Merging is the process of merging fetched software into a branch, most commonly the current branch of the repository. A
merge is where things are most likely to get a bit confusing. However, if you are simply merging from a remote master into
a local master, and your local master is always tracking the remote, your merges should go smoothly.

Fig. 14: Merging fetched changes from the origin repository.

Ensure you are on the master branch and run the following:

$ git merge origin/master

The master branch should be clean (i.e. git status on the master branch shows no files that are modified but uncom-
mitted) when this operation is performed. Team members should be doing development work in feature branches, not in
the master branch.

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 159
Conflicts

Conflicts, or “What happens when more than one change is pending for a given piece of code.” It’s best to read this great
tutorial on Git merge conflicts. Merge conflicts are a normal part of working in teams, and only with experience can you learn
to effectively manage conflicts. Always approach with patience and a deep respect for the process.

4.1.5 Updating the SDK to the Latest Version

Important: Remember to use git remote -v to ensure that the upstream has been set as a remote on your clone. If
not, be sure to review the “Remotes” section again to add the FtcRobotController repository to the upstream remote on your
clone.

To update from the SDK, we simply fetch from upstream, FIRST-Tech-Challenge/FtcRobotController, the parent of your team
fork, then merge and push to origin to complete the update.

Fig. 15: Fetching changes from the upstream repository.

Instead of fetching from origin, fetch from upstream. This copies in any commits that you don’t already have in your local
clone. In the diagram above that is the v8.0 commit. Your local master is not changed. It is still pointing to, and represent-
ing, the v7.2 commit. Since a commit is a complete snapshot of a workspace at a point in time, nothing changes in your
workspace, but your repository has a new commit with the branch name upstream/master.

$ git fetch upstream

After fetching, merge the upstream/master branch into master. If your local master matches your upstream master then a
merge is as simple as moving the master branch label to the commit that upstream/master is pointing to. This is referred to

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 160

Fig. 16: Merging fetched changes from the upstream repository.

as a fast-forward merge. And since a commit is a complete snapshot of a workspace at a point time, your local workspace
now contains the snapshot represented by v8.0.

$ git merge upstream/master

Once you’ve merged the upstream/master into your local clone’s master branch, push those changes to GitHub so that your
GitHub clone reflects the upstream repository.

$ git push origin master

If you were working in a feature branch and want to bring the new SDK changes into that feature branch you merge from
master into the branch by checking out the branch and running the merge command. This is where things might get dicey
as this is where you are most likely to encounter merge conflicts.

$ git checkout <feature-branch>

$ get merge master

4.1.6 Downgrading the SDK to a Previous Version

Typically, the working branch of a local repository, whether it’s master, or a competition branch will eventually contain a
series of team commits interleaved with SDK update commits. In this scenario a team can not simply roll back to a prior
SDK version without also rolling back all of their team commits. Consider the following diagram.

If you just chopped off the branch at M7.2, you’d lose the three blue team commits. In order to retain team work, instead
create a new merge commit that reverts the 8.0 commit. Do not revert merge commits, e.g. M8.0. The merge commit itself
may contain work that represents the divergence of the the two branches that were merged. This is not what you want. You
want to revert the parent of the merge commit that represents the new, old, SDK version.

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 161

Fig. 17: Pushing fetched and merged changes back to your team fork.

Fig. 18: A repository with both team commits and SDK update commits.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 162
A Short Digression on Tags

A tag is simply a named pointer to a commit, that unlike a branch pointer, or HEAD, never moves. Since a commit is a
snapshot in time of an entire workspace, this allows a developer to tag a point in time in an immutable fashion. FIRST uses
tags to track SDK versions through a standard semantic versioning naming scheme. When a new SDK version is released,
the FTC engineering team pushes a release candidate branch to FIRST-Tech-Challenge/FtcRobotController, then merges that
branch into master. This results in two commits, the new SDK version commit that contains all the good stuff, and a merge
commit representing the merge from the candidate branch into master. The release is then formally cut, where a tag is then
created, on the merge commit.
Tags from remotes are not automatically copied into a repository on a clone. To retrieve tags execute.

$ git fetch --all --tags

The –all option fetches at once from all remotes, the –tags option tells git to fetch the tags. Tags always follow the semantic
versioning rules. e.g. v7.0, v7.1, v7.2, v8.0, etc.
The ^ syntax allows one to reference parents of a commit and can be applied to tag names. tag^ is the immediate parent of
the commit tag points to. For commits with multiple parents such as merge commits one can apply a number to refer to a
specific parent. tag^1 is the same as tag^ and is the first parent of the commit, tag^2 is the second parent of the commit.

Merging the Inverse of an SDK Update

The diagram below shows the v8.0 tag pointing to the v8.0 merge commit along with references to the parents of v8.0.

Fig. 19: v8.0 tag pointing to the v8.0 merge commit.

Release 0.2 03/12/2024

 4
FTC Docs Android Studio Guide, 163

Important: If any commits have dependencies on new features or APIs introduced in the reverted versions, then your build
will break. You will have to manually figure out how to fix your software so that it is no longer depends upon reverted software.

Remember that Git does not delete commits (with a few exceptions), so in order to revert a commit we must create a new
commit that is the inverse of the commit you want to revert from. And you’ll want to do this for every version, in reverse
order, that you want to undo. The target of the command below is the tag of the version you want to undo, not the tag of the
version you want to revert to.

Fig. 20: Result of revert - a new merge commit representing the revert from v8.0 to v7.2.

Because the merge commit has two parents, and you want to reference the SDK version commit, use the tag name you want
to roll back and append ^2. For example to roll back v8.0, resulting in the SDK compiling against v7.2 use.

$ git revert -Xtheirs v8.0^2

The -Xtheirs option is a convenience that says, “If there are any conflicts, automatically take the software from the v8.0^2
side.”

Warning: If you want to downgrade more than one revision you must revert each revision in sequence otherwise you
could wind up with changes remaining after reversion from the SDK version in between latest and the target you are
referring to. For example if you need to downgrade from v8.1.1 to v8.0, for reference all SDK versions can be found here,
you must revert v8.1.1 followed by v8.1. If you don’t follow this order, then changes in v8.1.1 that don’t overlap with v8.1
will remain in your workspace and that’s not what you want.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 4
FTC Docs Android Studio Guide, 164
4.1.7 Summary

Assumes all commands are run from the root directory of your local clone. Also assumes you are not committing team code
to your local master branch, but instead are working in a competition branch.

Add FIRST-Tech-Challenge/FtcRobotController as a remote

$ git remote add upstream https://github.com/FIRST-Tech-Challenge/FtcRobotController.git

Update the to latest SDK version

$ git checkout master

$ git fetch upstream
$ git merge upstream/master
$ git push origin master
$ git checkout competition
$ git merge master

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 165

Chapter 5

Writing an Op Mode AS

5.1 Enabling Developer Options 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.

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.

The Android Developer website contains information on how to enable Developer Options onto your phone. If you visit the
following link and read the section entitled “Enabling On-device Developer Options” you will see that you can enable Developer
Options on your Android phone by going to Settings->About phone on the phone, and then tapping the Build number seven
times.
• https://developer.android.com/studio/run/device#setting-up
In order to be able to use the Android Studio tools to install apps onto your phone, you will need to make sure that the
Developer Options and USB debugging are enabled for both of your phones.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5

FTC Docs Android Studio Guide, 166

When you first connect a phone to your computer with Android Studio running, the phone might prompt you if it is OK to allow
the computer to have USB debugging access to the phone. If this happens, make sure that you check the “Always allow from
this computer” option and hit the OK button to allow USB debugging.

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 167

5.2 Creating and Running an Op Mode AS

5.2.1 TeamCode Module

If you successfully imported the 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 op modes that you will write to control your competition robot.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5

FTC Docs Android Studio Guide, 168

When you create your classes and op modes, you will to create them in the org.firstinspires.ftc.teamcode package
that resides in the TeamCode module. This package is reserved for your use within the Android Studio project folder.

5.2.2 Javadoc Reference Information

The 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

5.2.3 Enabling Auto Import

The auto import feature of Android Studio is a convenient function that helps save time as you write your op mode. If you
would like to enable this feature, select the Editor->General->Auto Import item from the Android Studio Settings screen. This
will display the editor’s auto import settings.
Check the “Add unambiguous imports on the fly” so that Android Studio will automatically add the required import statements
for classes that you would like to use in your op mode.

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 169

5.2.4 Sample Op Modes

A great way to learn how to program a robot is to examine the sample op modes that are included with the Android Studio
project folder. You can locate these files in the FtcRobotController module in the package org.firstinspires.ftc.
robotcontroller.external.samples.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5

FTC Docs Android Studio Guide, 170

If you would like to use a sample op mode, copy it from the org.firstinspires.ftc.robotcontroller.external.
samples package and move it to the org.firstinspires.ftc.teamcode package.
In your newly copied op mode, look for the following annotation,
@Disabled
and comment out this line to enable the op mode and allow it to be run on the Robot Controller:
//@Disabled

5.2.5 Creating Your FIRST Op Mode

Right mouse click on the org.firstinspires.ftc.teamcode package and select New->Java Class from the pop-up
menu. The Create New Class dialog box appear. Specify the name of the new class as MyFIRSTJavaOpMode and specify
as its superclass the class LinearOpMode which is in the package com.qualcomm.robotcore.eventloop.opmode.

Release 0.2 03/12/2024

 5
FTC Docs Android Studio Guide, 171

Press the OK button to create the new class. The source code for the new class should appear in the editing pane of the
Android Studio user interface.

Modify the main portion of your op mode so that it looks like the following code (note that the package definition and some
import statements have been omitted in the following source code):
@TeleOp

public class MyFIRSTJavaOpMode extends LinearOpMode {

private Gyroscope imu;
(continues on next page)

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
(continued from previous page)
private DcMotor motorTest;
FTC Docs
private DigitalChannel digitalTouch; Android Studio Guide, 172
private DistanceSensor sensorColorRange;
private Servo servoTest;

@Override
public void runOpMode() {
imu = hardwareMap.get(Gyroscope.class, "imu");
motorTest = hardwareMap.get(DcMotor.class, "motorTest");
digitalTouch = hardwareMap.get(DigitalChannel.class, "digitalTouch");
sensorColorRange = hardwareMap.get(DistanceSensor.class, "sensorColorRange");
servoTest = hardwareMap.get(Servo.class, "servoTest");

telemetry.addData("Status", "Initialized");
telemetry.update();
// Wait for the game to start (driver presses PLAY)
waitForStart();

// run until the end of the match (driver presses STOP)

while (opModeIsActive()) {
telemetry.addData("Status", "Running");
telemetry.update();

}
}
}

We will use this source code as the framework for your first op mode. Note that Android Studio automatically saves your
source code as you are editing it.
Congratulations! You’ve written an op mode. It does not do much, but we will modify it to make it more useful.

5.2.6 Examining the Structure of Your Op Mode

It can be helpful to think of an op mode as a list of tasks for the Robot Controller to perform. For a linear op mode, the Robot
Controller will process this list of tasks sequentially. Users can also use control loops (such as a while loop) to have the
Robot Controller repeat (or iterate) certain tasks within a linear op mode.

Release 0.2 03/12/2024

 5
FTC Docs Android Studio Guide, 173

If you think about an op mode as a list of instructions for the robot, this set of instructions that you created will be executed
by the robot whenever a team member selects the op mode called MyFIRSTJavaOpMode from the list of available op modes
for this Robot Controller.
Let’s look at the structure of your newly created op mode. Here’s a copy of the op mode text (minus some comments, the
package definition, and some import package statements):

@TeleOp

public class MyFIRSTJavaOpMode extends LinearOpMode {

private Gyroscope imu;
private DcMotor motorTest;
(continues on next page)

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 174
(continued from previous page)
private DigitalChannel digitalTouch;
private DistanceSensor sensorColorRange;
private Servo servoTest;

@Override
public void runOpMode() {
imu = hardwareMap.get(Gyroscope.class, "imu");
motorTest = hardwareMap.get(DcMotor.class, "motorTest");
digitalTouch = hardwareMap.get(DigitalChannel.class, "digitalTouch");
sensorColorRange = hardwareMap.get(DistanceSensor.class, "sensorColorRange");
servoTest = hardwareMap.get(Servo.class, "servoTest");

telemetry.addData("Status", "Initialized");
telemetry.update();
// Wait for the game to start (driver presses PLAY)
waitForStart();

// run until the end of the match (driver presses STOP)

while (opModeIsActive()) {
telemetry.addData("Status", "Running");
telemetry.update();

}
}
}

At the start of the op mode there is an annotation that occurs before the class definition. This annotation states that this is
a tele-operated (i.e., driver controlled) op mode:
@TeleOp
If you wanted to change this op mode to an autonomous op mode, you would replace the @TeleOp with an @Autonomous
annotation instead.
You can see from the sample code that an op mode is defined as a Java class. In this example, the op mode name is called
MyFIRSTJavaOpMode and it inherits characteristics from the LinearOpMode class.

public class MyFIRSTJavaOpMode extends LinearOpMode {

You can also see that the OnBot Java editor created five private member variables for this op mode. These variables will
hold references to the five configured devices that the OnBot Java editor detected in the configuration file of your Robot
Controller.

private Gyroscope imu;

private DcMotor motorTest;
private DigitalChannel digitalTouch;
private DistanceSensor sensorColorRange;
private Servo servoTest;

Next, there is an overridden method called runOpMode. Every op mode of type LinearOpMode must implement this
method. This method gets called when a user selects and runs the op mode.

@Override
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 the Robot Controller’s configuration file:

Release 0.2 03/12/2024

 5
imu = hardwareMap.get(Gyroscope.class, "imu");
motorTest = hardwareMap.get(DcMotor.class, "motorTest");
FTC Docs
digitalTouch = hardwareMap.get(DigitalChannel.class, "digitalTouch");
Android Studio Guide, 175
sensorColorRange = hardwareMap.get(DistanceSensor.class, "sensorColorRange");
servoTest = hardwareMap.get(Servo.class, "servoTest");

The hardwareMap object is available to use in the runOpMode method. It is an object of type HardwareMap class.
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
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 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 wait until the user pushes the start button on the driver station
to begin the op mode run.

telemetry.addData("Status", "Initialized");
telemetry.update();
// Wait for the game to start (driver presses PLAY)
waitForStart();

Note that all linear op modes should have a waitForStart statement to ensure that the robot will not begin executing the
op mode until the driver pushes the start button.
After a start command has been received, the op mode enters a while loop and keeps iterating in this loop until the op mode
is no longer active (i.e., until the user pushes the stop button on the Driver Station):

// run until the end of the match (driver presses STOP)

while (opModeIsActive()) {
telemetry.addData("Status", "Running");
telemetry.update();

As the op mode iterates in the while loop, it will continue to send telemetry messages with the index of “Status” and the
message of “Running” to be displayed on the Driver Station.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
5.2.7 Building and Installing Your Op Mode
FTC Docs
Verify Android permission
that the Robot Controller phone is connected to your laptop and that the laptop has USB debugging Studio Guide,
for176
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 your laptop through its USB Type C port. Note that the Control Hub should automatically have USB debugging
permission enabled.

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 177

When using the Control Hub, please make sure you use the Type C port (and not the USB Mini port) to connect the Control
Hub to your development laptop.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5

FTC Docs Android Studio Guide, 178

Look towards the top of the Android Studio user interface and find the little green Play or Run button (which is represented
by a green triangle) next to the words Team Code. Press this green button to build the Robot Controller app and to install it
onto your phone.

Android Studio should prompt you to select a target device to install the Robot Controller app. Your screen might look
something like the image shown below.

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 179

Make sure that you select the correct target device. In the figure above the Motorola phone is selected as the target device.
Hit OK to build the APK file and install it on the target device.
Note that if you previously installed a copy of the Robot Controller app from the Google Play store, the installation of your
newly built app will fail the first time you attempt to install it. This is because Android Studio detects that the app that you
just build has a different digital signature than the official version of the Robot Controller app that was installed from Google
Play.

If this happens, Android Studio will prompt you if it’s OK to uninstall the previous (official) version of the app from your device
and replace it with the updated version of the app. Select OK to uninstall the previous version and to replace it with your newly
created Robot Controller App (see image above).

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 180

If the installation was successful, the Robot Controller app should be launched on the target Android device. If you are using

Release 0.2 03/12/2024

 5
an Android phone as your Robot Controller, you should see the main Robot Controller app screen displayed on the phone.
Although
FTC Docsthe Control Hub lacks a built in screen, if you are Control Hub user, you can verify that Android
the app was installed
Studio Guide,onto
181
your Control Hub properly by looking at your Driver Station. If the Driver Station indicates that it is successfully connected to
the Control Hub (after momentarily disconnecting while the update was occurring) then the app was successfully updated.

5.2.8 Running Your Op Mode

If you successfully built and installed your updated Android app with your new op mode, then you are ready to run the op
mode. Verify that the Driver Station is still connected to the Robot Controller. Since you designated that your example op
mode is a tele-operated op mode, it will be listed as a TeleOp op mode.
On the Driver Station, use the TeleOp dropdown list control to display the list of available op modes. Select your op mode
(“MyFIRSTJavaOpMode”) from the list.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5

FTC Docs Android Studio Guide, 182

Press the “INIT” button to initialize the op mode.

The op mode will execute the statements in the runOpMode method up to the waitForStart statement. It will then wait until
you press the start button (which is represented by the triangular shaped symbol) to continue.

Release 0.2 03/12/2024

 5

FTC Docs Android Studio Guide, 183

Once you press the start button, the op mode will continue to iterate and send the “Status: Running” message to the Driver
Station. To stop the op mode, press the square-shaped stop button.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 184

Congratulations! You ran your first java op mode!

Release 0.2 03/12/2024

 5
FTC Docs Android Studio Guide, 185
5.2.9 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 loop so that it looks like the following:

// run until the end of the match (driver presses STOP)

double tgtPower = 0;
while (opModeIsActive()) {
tgtPower = -this.gamepad1.left_stick_y;
motorTest.setPower(tgtPower);
telemetry.addData("Target Power", tgtPower);
telemetry.addData("Motor Power", motorTest.getPower());
telemetry.addData("Status", "Running");
telemetry.update();

If you look at the code that was added, you will see that we defined a new variable called target power before we enter the
while loop.

double tgtPower = 0;

At the start of the while loop we set the variable tgtPower equal to the 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. 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. In the example code
above, you negate the left_stick_y value so that pushing the left joystick forward will result in a positive power being
applied to the motor. Note that in this example, the notion of forwards and backwards for the motor is arbitrary. However,
the concept of negating the joystick y value can be very useful in practice.

The next set of statements sets the power of motorTest to the value represented by the variable tgtPower. The values for
target power and actual motor power are then added to the set of data that will be sent via the telemetry mechanism to the
Driver Station.

tgtPower = -this.gamepad1.left_stick_y;
motorTest.setPower(tgtPower);
telemetry.addData("Target Power", tgtPower);
telemetry.addData("Motor Power", motorTest.getPower());

After you have modified your op mode to include these new statements, press the build button and verify that the op mode
was built successfully.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
5.2.10 Running Your Op Mode with a Gamepad Connected
FTC
YourDocs
op mode takes input from a gamepad and uses this input to control a DC motor. To run yourAndroid Studio
op mode, Guide,
you will 186
need to
connect a Logitech F310 gamepad to the Driver Station.
Before you connect your gamepad to the phone, verify that the switch on the bottom of the gamepad is set to the “X” (i.e.,
the “Xbox” mode) position.

Connect the gamepad to the Driver Station using the Micro USB OTG adapter cable.

Release 0.2 03/12/2024

 5
FTC Docs Android Studio Guide, 187

Your example op mode is looking for input from the gamepad designated as the user or driver #1. Press the Start button
and the A button simultaneously on the Logictech F310 controller to designate your gamepad as user #1. Note that pushing
the Start button and the B button simultaneously would designate the gamepad as user #2.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 188
If you successfully designated the gamepad to be user #1, you should see a little gamepad icon above the text “User 1” in
the upper right hand corner of the Driver Station Screen. Whenever there is activity on gamepad #1, the little icon should be
highlighted in green. If the icon is missing or if it does not highlight in green when you use your gamepad, then there is a
problem with the connection to the gamepad.
Select, initialize and run your MyFIRSTJavaOpMode op mode.
If you configured your gamepad properly, then the left joystick should control the motion of the motor. As you run your op
mode, be careful and make sure you do not get anything caught in the turning motor. Note that the User #1 gamepad icon
should highlight green each time you move the joystick. Also note that the target power and actual motor power values
should be displayed in the telemetry area on the Driver Station.

Release 0.2 03/12/2024

 5
5.3 Controlling a Servo AS
FTC Docs Android Studio Guide, 189
In this section, you will modify your op mode to control a servo motor with the buttons of the gamepad.

5.3.1 What is a Servo Motor?

A servo motor is a special type of motor. A servo motor is designed for precise motion. A typical servo motor has a limited
range of motion.
In the figure below, “standard scale” 180-degree servo is shown. This type of servo is popular with hobbyists and with FIRST
Tech Challenge teams. This servo motor can rotate its shaft through a range of 180 degrees. Using an electronic module
known as a servo controller you can write an op mode that will move a servo motor to a specific position. Once the motor
reaches this target position, it will hold the position, 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 control surfaces on a remotely controlled airplane).

5.3.2 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.
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 then maintain that position, even if moderate forces are applied to try and disturb its position.
For the FIRST Tech Challenge control system, you can specify a target position that ranges from 0 to 1 for a servo. A target
position of 0 corresponds to zero degrees of rotation and a target position of 1 corresponds to 180 degrees of rotation for
a typical servo motor.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 190

In this example, you will use the colored buttons on the right side of the F310 controller to control the position of the servo.
Initially, the op mode will move the servo to the midway position (90 degrees of its 180-degree range). Pushing the yellow
“Y” button will move the servo to the zero-degree position. Pushing the blue “X” button or the red “B” button will move the
servo to the 90-degree position. Pushing the green “A” button will move the servo to the 180-degree position.

Modify your op mode to add the following code:

Release 0.2 03/12/2024

 5
FTC Docs Android Studio Guide, 191
// run until the end of the match (driver presses STOP)
double tgtPower = 0;
while (opModeIsActive()) {
tgtPower = -this.gamepad1.left_stick_y;
motorTest.setPower(tgtPower);
// check to see if we need to move the servo.
if(gamepad1.y) {
// move to 0 degrees.
servoTest.setPosition(0);
} else if (gamepad1.x || gamepad1.b) {
// move to 90 degrees.
servoTest.setPosition(0.5);
} else if (gamepad1.a) {
// move to 180 degrees.
servoTest.setPosition(1);
}
telemetry.addData("Servo Position", servoTest.getPosition());
telemetry.addData("Target Power", tgtPower);
telemetry.addData("Motor Power", motorTest.getPower());
telemetry.addData("Status", "Running");
telemetry.update();

This added code will check to see if any of the colored buttons on the 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.
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 buttons to move the position of the servo.

5.4 Using Sensors AS

5.4.1 Color-Distance Sensor

A sensor is a device that lets the 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.
The Color-Range sensor uses reflected light to determine the distance from the sensor to the target object. It can be used to
measure close distances (up 5” or more) with reasonable accuracy. Note that at the 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.

telemetry.addData("Servo Position", servoTest.getPosition());

telemetry.addData("Target Power", tgtPower);
telemetry.addData("Motor Power", motorTest.getPower());
telemetry.addData("Distance (cm)", sensorColorRange.getDistance(DistanceUnit.CM));
telemetry.addData("Status", "Running");
telemetry.update();

After you have modified your op mode, build and install the updated Robot Controller app, then run the op mode to verify that
it now displays distance on your Driver Station. Note that if the distance reads “NaN” (short for “Not a Number”) it probably
means that your sensor is too far from the target (zero reflection). Also note that the sensor saturates at around 5 cm.

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”
 5
FTC Docs Android Studio Guide, 192
5.4.2 Touch Sensor

The REV Robotics Touch Sensor can be connected to a digital port on the Expansion Hub. The Touch Sensor is HIGH (returns
TRUE) when it is not pressed. It is pulled LOW (returns FALSE) when it is pressed.

The 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 an 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 4-wire cable remains disconnected.
For example, if you connect a Touch Sensor to the “0,1” digital port of the Expansion Hub, the Touch Sensor will be connected
to the second pin (labeled “1”) of the port. The first pin (labeled “0”) will stay disconnected.
Modify the code in your op mode that occurs before the waitForStart command to set the digital channel for input mode.

// set digital channel to input mode.

digitalTouch.setMode(DigitalChannel.Mode.INPUT);

telemetry.addData("Status", "Initialized");
telemetry.update();
// Wait for the game to start (driver presses PLAY)
waitForStart();

Also, modify the code in your while loop to add an if-else statement that checks the state of the digital input channel. If the
channel is LOW (false), the touch sensor button is pressed and being pulled LOW to ground. Otherwise, the touch sensor
button is not pressed.

// is button pressed?
if (digitalTouch.getState() == false) {
// button is pressed.
telemetry.addData("Button", "PRESSED");
} else {
// button is not pressed.
telemetry.addData("Button", "NOT PRESSED");
}

telemetry.addData("Status", "Running");
telemetry.update();

Build and install the updated Robot Controller app, then reinitialize and restart your op mode. The op mode should now
display the state of the button (“PRESSED” or “NOT PRESSED”).

Release 0.2 03/12/2024

 6
FTC Docs Android Studio Guide, 193

Chapter 6

Version Information

6.1 Document Information

Author: FIRST Tech Challenge

Version: 0.2
Release Date: 03/12/2024
Generation Time: 15:17

6.2 Git Information

Git Hash: 2d07aa7241a7e455365ea2732e617c83b25a9952

Git Branch: main
Git Commit Date: 2024-12-03 15:13:29
Git Commit Author: Elizabeth G <45825543+emcclurg@users.noreply.github.com>

6.3 Document License

License: BSD 3-Clause

Gracious Professionalism® - “Doing your best work while treating others with respect and kindness - It’s what makes
FIRST, first.”