2021-2022 FIRST Tech Challenge OnBot Java Guide


2021-2022 FIRST Tech ChallengeOnBot Java Guide

Sponsor Thank YouThank you to our generous sponsors for your continued support of the FIRST Tech Challenge!

Revision1Date08/12/2021DescriptionInitial ReleaseRevision HistoryContentsContents .3Introduction .6What is FIRST Tech Challenge? . 6Gracious Professionalism . 61.Introduction to OnBot Java Programming . 72.The FTC Control System . 73.2.1.Introduction . 72.2.Autonomous Vs. Driver Controlled . 72.3.Point-to-Point Control System. 72.4.REV Robotics Expansion Hub . 82.5.REV Robotics Control Hub . 92.6.What's an Op Mode? . 10Required Materials. Your Android Device . 164.1.Unlocking Your Screen . 164.2.Navigating in Android. 17Displaying Available Apps on your Android Phone. 195.1.Android Marshmallow Users . 195.2.Android Nougat Users . 20Configuring Your Android Devices . 216.1.7.Required Materials List . 11What Needs to Be Configured for My Control System? . 216.1.1.Control Hub Users . 216.1.2.Users with Two Android Smartphones . 216.2.Renaming Your Smartphones . 226.3.Installing the FTC Apps . 276.4.Placing Phones into Airplane Mode with Wi-Fi On . 35Pairing the Driver Station to the Robot Controller. . 367.1.Control Hub Users . 36

7.2.8.Users with Two Android Smartphones . 43Connecting Devices to a Control or Expansion Hub. 438.1.Connecting 12V Power to the Hub . 438.2.Connecting a Motor to the Hub . 468.3.Connecting a Servo to the Hub . 489.Connecting a Color-Distance Sensor to the Hub . 499.1.10.Connecting a Color-Distance Sensor to the Hub. 50Connecting a Touch Sensor to the Hub . 5110.1.11.Connecting a Touch Sensor to the Hub. 51Configuring Your Hardware . 5311.1.Before You Begin. . 5311.2.Connecting an Android Smartphone to an Expansion Hub . 5311.3.Getting the Control Hub Ready . 5511.4.Creating a Configuration File Using the Driver Station. 5511.5.Configuring a DC Motor. 5911.6.Configuring a Servo . 6111.7.Configuring a Color Distance Sensor . 6411.8.Configuring a Digital Touch Sensor . 6711.9.Saving the Configuration Information . 6812.Installing a Javascript Enabled Browser . 7112.1.13.Installing a Javascript-Enabled Browser . 71Connecting a Laptop to the Program & Manage Network . 7313.1.Introduction . 7313.2.Connecting Your Laptop to the Program & Manage Network . 7313.3.Troubleshooting Your Wireless Connection. 7814.Creating and Running an Op Mode (OnBot Java) . 7814.1.The Java Programming Language . 7814.2.What's an Op Mode?. 7914.3.The FTC OnBot Java Programming Tool . 7914.4.Creating Your First Op Mode. 8014.4.1.Examining the Structure of Your Op Mode . 8514.5.Building Your Op Mode . 8814.6.Troubleshooting Build Messages . 8914.7.Running Your Op Mode. 90

14.8.Modifying Your Op Mode to Control a Motor . 9314.9.Running Your Op Mode with a Gamepad Connected . 9415.Controlling a Servo (OnBot Java) . 9615.1.What is a Servo Motor? . 9615.2.Modifying Your Op Mode to Control a Servo . 9716.Using Sensors (OnBot Java) . 9916.1.Color-Distance Sensor . 9916.2.Touch Sensor. 9917.OnBot Java Reference Info . 10017.1.Javadoc Reference Pages . 10017.2.Sample Op Modes . 10017.3.Technology Forum . 10117.4.REV Robotics Expansion Hub Documentation . 10117.5.REV Driver Hub and Control Hub Tutorial Videos . 101Appendix A – Resources . 102Game Forum Q&A . 102Volunteer Forum . 102FIRST Tech Challenge Game Manuals . 102FIRST Headquarters Pre-Event Support . 102FIRST Websites . 102FIRST Tech Challenge Social Media . 102Feedback . 102

IntroductionWhat is FIRST Tech Challenge?FIRST Tech Challenge is a student-centered program that focuses on giving students a unique and stimulatingexperience. Each year, teams engage in a new game where they design, build, test, and program autonomousand driver operated robots that must perform a series of tasks. To learn more about FIRST Tech Challenge andother FIRST Programs, visit www.firstinspires.org.Gracious Professionalism FIRST uses this term to describe our programs’ intent.Gracious Professionalism is a way of doing things that encourages high-quality work, emphasizes the valueof others, and respects individuals and the community.Watch Dr. Woodie Flowers explain Gracious Professionalism in this short video.

1. Introduction to OnBot Java ProgrammingThis tutorial will take you step-by-step through the process of configuring, programming, and operating yourControl System. This tutorial uses the OnBot Java Programming Tool to help you get started programming yourrobot.The FTC OnBot Java Programming Tool is a text-based programming tool that lets programmers use a webbrowser to create, edit and save their Java op modes. This tool is recommended for programmers who have basicto advanced Java skills and who would like to write text-based op modes.2. The FTC Control System2.1. IntroductionThe FIRST Tech Challenge seeks to inspire youth to become the next generation of STEM leaders andinnovators through participation in mentor-guided robotics competition. Teams who participate in the FIRST TechChallenge must build a robot that performs a variety of tasks. The tasks vary from season to season, and arebased on a set of game rules that are published at the start of each season. The more tasks that a robot cancomplete, the more points a team will earn.2.2. Autonomous Vs. Driver ControlledA FIRST Tech Challenge match has an autonomous phase and a driver-controlled or tele-operated phase. In theautonomous phase of a match the robot operates without any human input or control. In the driver-controlledphase, the robot can receive input from up to two human drivers.2.3. Point-to-Point Control SystemThe FIRST Tech Challenge uses Android devices to control its robots. During a competition, each team has twoAndroid devices.

One Android device is mounted onto the robot and is called the Robot Controller. The Robot Controller acts asthe “brains” of the robot. It does all of the thinking for the robot and tells the robot what to do. It consists of anAndroid device running an FTC Robot Controller app. There are two hardware options currently being used: REVRobotics 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 deviceis known as the Driver Station. The Driver Station is sort of like a remote control that you might use to control yourtelevision. The Driver Station allows a team to communicate remotely (using a secure, wireless connection) to theRobot Controller and to issue commands to the Robot Controller. The Driver Station consists of an Android device(smartphone or REV Driver Hub) running an FTC Driver Station app. The REV Driver Hub has the FTC DriverStation app pre-installed on the device. Note: You do not have to reinstall the app on the Hub once charged andconnected to Wi-Fi.2.4. REV Robotics Expansion HubThe REV Robotics Expansion Hub is the electronic input/output (or “I/O”) module that lets the Robot Controllertalk to the robot’s motors, servos, and sensors. The Robot Controller communicates with the Expansion Hubthrough a serial connection. For the situation where an Android smartphone is used as the Robot Controller, aUSB 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 haveits own independent battery. If a REV Robotics Control Hub is used as the Robot Controller, then the Control Hubwill use the main 12V battery to power its internal Android device.

2.5. REV Robotics Control HubThe Control Hub has an integrated version of the Robot Controller. It combines an Android device built into thesame case as a REV Robotics Expansion Hub.The Control Hub, which has its built-in Android device connected directly to the Expansion Hub using an internalserial bus, eliminates the need for an external USB connection between the Android Robot Controller and the I/Omodule.

2.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 toscore points. For example, a team might want their robot to follow a white line on the competition floor and thenscore a game element (such as a ball) into a goal autonomously during a match. Teams write “op modes” (whichstand 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 RobotController can execute a selected op mode to perform certain tasks during a match.Teams who are participating in the FIRST Tech Challenge have a variety of programming tools that they can useto create their own op modes. Teams can use a visual ("drag and drop") programming tool called the FTC BlocksProgramming Tool to create their op modes. Teams can also use a text-based Java tool known as the FTC OnBotJava Programming Tool or Google's Android Studio integrated development environment (also known as an"IDE") to create their op modes.

3. Required Materials3.1. Required Materials ListThis guide contains tutorials that demonstrate how to configure, program, and operate the FTC control system. Inorder to complete the tutorials, you will need to have the following materials available:Required Item(s)ImageTwo (2) FIRST-approved* Androiddevices (A Robot Controller smartphoneand a Driver Station smartphone orDriver Hub).Or.One (1) Control Hub and one (1) FIRSTapproved* Android smartphone.*For a list ofFIRST-approved Android smartphones, refer to the current FTCGame Manual Part 1, rule RE06 .Wireless Internet access.Or.

Required Item(s)Laptop with Microsoft Windows 7, 8 or10 and Wi-Fi capability.Note: that your laptop should have themost current service packs and systemupdates from Microsoft.If you are using a different type ofmachine (such as a Chromebook,Android Tablet, etc.) as yourprogramming device, the steps mightdiffer slightly on how to access theProgramming Server on the RobotController. Refer to your device's userdocumentation for details on how toconnect to a Wi-Fi network.Javascript-enabled web browser (GoogleChrome is the recommended browser).If you are using a smartphone as yourRobot Controller, you will also need aREV Robotics Expansion Hub (REV-311153) to connect to the motors, servos,and sensors. Control Hub users will usethe integrated Expansion Hub.Image

Required Item(s)ImageREV Robotics Switch, Cable, & Bracket(REV-31-1387).If you are using an approved 12V batterythat has an Tamiya connector (like theTetrix W39057 battery) you will need a REV Robotics Tamiya to XT30 AdapterCable (REV-31-1382).If you have a REV Robotics Slim Battery(REV-31-1302) then you will not needthis adapter since the REV batteryalready has an XT30 connector.FIRST-approved* 12V Battery (such asTetrix W39057 or REV Robotics REV31-1302).*For a list ofFIRST-approved 12V batteries, refer to the current FTC GameManual Part 1, rule RE03 .Or.

Required Item(s)FIRST-approved* 12V Battery (such asTetrix W39057 or REV Robotics REV31-1302).*For a list ofFIRST-approved 12V batteries, refer to the current FTC GameManual Part 1, rule RE03 .FIRST-approved* 12V DC Motor (suchas Tetrix W39530, with power cableW41352).*For a list of FIRST-approved 12V motors, refer to the current FTC Game ManualPart 1, rule RE09 .REV Robotics Anderson to JST VHCable (REV-31-1381).Image

Required Item(s)180-Degree Standard Scale Servo (suchas Hitec HS-485HB).REV Robotics Color Sensor with 4-PinCable (REV-31-1154).REV Robotics Touch Sensor with 4-PinCable (REV-31-1425).If you are using a smartphone as yourRobot Controller, you will need a USBType A male to type mini-B male cable.Control Hub users do not need thiscable.Image

Required Item(s)ImageIf you are using a smartphone as yourRobot Controller, you will need two (2)micro USB OTG adapters.If you are using a Control Hub as yourRobot Controller, you will need one (1)micro USB OTG adapter.Logitech F310 USB Gamepad.4. Using Your Android DeviceBefore you get started with your control system, it is helpful if you familiarize yourself with the basic operation ofyour Android device.4.1. Unlocking Your ScreenWhen you first power on an Android phone, it usually starts off with the screen in a "locked" state. For theMotorola smartphones that are used in the FIRST Tech Challenge, you must touch the locked screen and thenslide your finger upwards along the screen to unlock the phone. Note that different devices might require a slightlydifferent procedure to unlock the screen.

Depending on your security settings, you might be challenged for a pass code or PIN number. Use the touchscreen to enter in the pass code or PIN value and tap on the check mark to log into the device.4.2. Navigating in AndroidYour phone should display its home screen if you just powered it on and unlocked it. Note that the actual screenson your smartphone might differ slightly from the screens depicted in this tutorial.

At the bottom of the screen there should be some buttons that you can use to navigate the screens on yourAndroid device.The leftmost button (see image above) is the "Back" button. You can use this button to return to the previousscreen on your Android device.The center button is the "Home" button. Pressing this button should take you back to the home or opening screenof your Android device.The rightmost button is the "Recent Apps" button. If you click on this button it will display the apps that wererecently run and are dormant in the background. You can close a recent app by tapping the "X" button on theapp's listing.

Note: Some Android smartphones have an auto-hide feature which automatically hides the bottomnavigation buttons. If your smartphone has this feature, you might need to swipe up from the bottom of thescreen to display the navigation buttons.5. Displaying Available Apps on your Android Phone5.1. Android Marshmallow UsersIf you are using a device with Android Marshmallow (6.x) or earlier, you can display the available apps using theAndroid 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 thecenter 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 thatare available on your Android device. You can scroll through the App Drawer screens to find and launch an app.5.2. Android Nougat UsersIf you are using a device with Android Nougat (7.x) or newer, you can display the available apps by simplyswiping upwards from the bottom of the touchscreen. Newer versions of Android no longer have the App Drawerfeature.

6. Configuring Your Android Devices6.1. What Needs to Be Configured for My Control System?6.1.1. Control Hub UsersTeams who are using a Control Hub with the integrated Robot Controller will only need to configure a singleAndroid device 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 teamnumber).Install the Driver Station app onto the Driver Station phone. Note: the REV Driver Hub has pre-installedsoftware.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 NOTE: Eventually the Control Hub will need be renamed so that its name complies with GameManual rule RS01 , but for now we will use the Control Hub with its default name. You can learn how to managea Control Hub (and modify its name, password, etc.) in this tutorial.6.1.2. Users with Two Android SmartphonesTeams who have two smartphones and are not using a Control Hub will need to configure one smartphone foruse as a Robot Controller and a second smartphone for use as a Driver Station. The process is as follows, Rename one smartphone to " TEAM NUMBER -RC" (replace TEAM NUMBER with your teamnumber).Install the Robot Controller app onto the Robot Controller phone.Rename a second smartphone to " TEAM NUMBER -DS" (where TEAM NUMBER is replaced by yourteam number).Install the Driver Station app onto the Driver Station phone.Put your phones into Airplane Mode (with the WiFi radios still on).Pair (i.e., wirelessly connect) the Driver Station to the Robot Controller.

6.2. Renaming Your SmartphonesThe official rules of the FIRST Tech Challenge (see RS01 ) require that you change the Wi-Fi name of yoursmartphones to include your team number and “-RC” if the phone is a Robot Controller or “-DS” if it is a DriverStation. A team can insert an additional dash and a letter (“A”, “B”, “C”, etc.) if the team has more than one set ofAndroid phones.If, for example, a team has a team number of 9999 and the team has multiple sets of phones, the team mightdecide to name one phone “9999-C-RC” for the Robot Controller and the other phone “9999-C-DS” for the DriverStation. The “-C” indicates that these devices belong to the third set of phones for this team.NOTE: it will take an estimated 5 minutes per phone to complete this task.

Step1. Browse the list of available apps on the smartphone and locatethe Settings icon. Click on Settings icon to display the Settingsscreen.2. Click on Wi-Fi to launch the Wi-Fi screen.Image

Step3. Touch the three vertical dots to display a pop-up menu.4. Select Advanced from the pop-up menu.Image

Step5. Select Wi-Fi Direct from the Advanced Wi-Fi screen.6. Touch the three vertical dots to display a pop-up menu.Image

Step7. Select Configure Device from the pop-up menu.8. Use touch pad to enter new name of device. If the device will be a Robot Controller, specifyyour team number and "-RC".If the device will be a Driver Station, specify your teamnumber and "-DS".You can also set the Wi-Fi Direct inactivitytimeout to "Never disconnect" and then hit theSAVE button to save your changes. NOTE: In the screenshot shown to the right,the team number is “9999”. The “-C” indicatesthat this is from the third pair of smartphones forthis team. The “-RC” indicates that this phonewill be a Robot Controller.9. After renaming phone, power cycle the device.Image

6.3 Installing the FTC AppsAs of 2021, the FTC apps (v 6.1 and higher) are not available on Google Play. The REV Hardware Clientsoftware will allow you to download the apps to FTC devices: REV Control Hub, REV Expansion Hub, REVDriver Hub, FTC-approved android devices. Here are some of the benefits: Connect a REV Control Hub via WiFi. One Click update of all software on connected devices. Pre-download software updates without a connected device. 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 FTC app releases are available on the FTCRobotController Github.NOTE: it will take an estimated 7.5 minutes per device to complete this task.

Step1. From the Android Wi-Fi screen look for the name ofyour wireless network (“CE NET” in this example) andtouch the wireless network name to log into thenetwork.Image

Step2. Specify the password using the touch keypad andpress CONNECT to connect to this wireless network.Image

Step3. Grant Google Chrome permission to install fromunknown sources:a. Go to Settings, then Apps & notifications.b. Select Advanced, then Special app access.Image

Stepc. Install unknown apps, then select Chrome.d. Allow access for Google ChromeImage

Step4. Uninstall the old application.5. Download the desired FTC app from theFtcRobotController GitHub repositoryImage

Step6. After you have successfully installed the app, youshould forget the external wireless network on yourphone.7. Go to the Android Wi-Fi screen, find the name ofthe currently connected network, and tap on thenetwork name to bring up a pop-up box with infoabout the network.Image

Step8. Click on the FORGET button to forget the wirelessnetwork.Image

6.3. Placing Phones into Airplane Mode with Wi-Fi OnFor the FIRST Tech Challenge competitions, it is important that you place your Robot Controller and DriverStation phones into Airplane mode but keep their Wi-Fi radios turned on. This is important because you do notwant any of the cellular telephone functions to be enabled during a match. The cellular telephone functionscould disrupt the function of the robot during a match.NOTE: it will take an estimated 2.5 minutes per phone to complete this

Control System. This tutorial uses the OnBot Java Programming Tool to help you get started programming your robot. The FTC OnBot Java Programming Tool is a text-based programming tool that lets programmers use aweb browser to create, edit and save their Java op modes. This tool is recommended for program