Tetrix

Overview: 
Examine the details of using OnBot or Android Studio to create OpMode classes.
Objectives: 

Understand how to use OnBot or Android Studio to create OpMode classes, compile and download (AS only) them to the robot controller phone.

Content: 

Now its time to get more familiar with OnBot or Android Studio and writing OpModes. All of the code samples in this curriculum will work in either OnBot or AS.


If you are using OnBot, you will be connecting to the controller device via WiFi right away, no USB cable needed. You interact with OnBot using a web browser (Chrome recommended) from a PC, a tablet or a Chrome book. The web browser is the only software tool you need to have installed on your development device. Once you connect to OnBot with a browser, a simplified interactive development environment is displayed (like a web site) in the browser. This IDE is being served by the controller device. In this IDE you create Java source files and edit code in these files in a manner similar to Android Studio. Once you have written a program, you click a button to compile your program and it becomes available on the controller device (and visible on the driver station phone) immediately. There is no deployment step as with AS. Each time you change your code, you must click the button to recompile in order for your changes to be incorporated into the controller app.

Here are several video tutorials (simple, detailed) and a text tutorial discussing OnBot in more detail. When using a cell phone as the controller device, you should view at least the first tutorial in order to learn how to connect your development PC to the controller phone, start OnBot and then how to enter and run Java code. The quick summary of using OnBot is to open the 3 dot menu on the controller phone and select Program and Manage. Here you will see the name of the WiFi Direct network being published by the phone. On your development PC, this name should appear in the list of available WiFi connections (may take a few second after starting controller app). Connect to this network. The phone also shows the password that Windows will ask for. Check the automatically connect box to avoid having to enter the password again. Once connected, browse to http://192.168.49.1:8080 and OnBot will appear.

When using the Control Hub, connect your development PC to the WiFi name of the Control Hub using the password you configured in the Control Hub in the earlier lesson. Check the automatically connect box to avoid having to enter the password again. Once connected, browse to http://192.168.43.1:8080 and OnBot will appear. Note the IP address is different that the address used with the cell phone.

Note: You should download any code written in OnBot to your development device to make sure your code is not lost if something happens to the controller phone.


If you are using Android Studio, Watch this video on writing OpModes.

Remember, each time we change an OpMode's source code, we must recompile and download the newly updated robot controller app to the controller device. Compiling in Android Studio will take care of the download as long as your PC is connected to the controller device with a USB cable or via WiFi. We will start using the cable and graduate to WiFi.

The first time you connect your controller device to your PC with a USB cable, the device should install the USB driver needed for AS to communicate with your device. If this driver install is unsuccessful, disconnect and reconnect the device. Once the install is complete the device should now be visible to AS. Driver install requires an internet connection and on Windows versions after 7, the install may take several minutes to complete. Driver installs will not complete on metered connections. Controller device will appear as a media player (MTP) in the Devices and Printers control panel applet.

As of this writing, the Control Hub USB driver install fails on Windows 7. In this case, download this file and extract. Run DriverInstall.exe. When it is finished, reconnect the Control Hub to the PC. The hub USB driver install should now complete.

Also, the first time you connect a controller phone to your PC, the phone will prompt you accept the RSA Security Key presented by your PC to the phone. Set the option to always accept the RSA Key from this PC and click Ok.


Note: It is possible to use both AS and OnBot at the same time but not recommended. If you do use both IDEs, if any class has the same name in both IDEs, an error will be generated, and on controller restart, the first class on the phone will be automatically renamed to resolve the name collision. Also, any shared classes used by OnBot classes must exist in the OnBot file list in order to compile.

 

Navigation:

Overview: 
Explore how physical robot hardware devices are mapped to names that can be used in programs to access those devices.
Objectives: 

Understand robot hardware mapping including controller phone configuration files and how to access hardware devices in software via the mapping scheme.

Content: 

Two more preparatory topics and then we can write some code!

A key function of the FTC SDK, and of any robotics API, is to provide software access to the physical hardware of a robot. A way must be provided to allow programmers to identify, in software, hardware devices on the robot so that they can write programs that interact with that hardware. On the Tetrix/REV platform, this is called hardware mapping.

Hardware mapping consists of two parts, hardware configuration on the controller device and hardware mapping in your OpMode class.

When you power on or connect the robot controller phone to the REV Expansion Hub or power on the REV Control Hub, the controller app will use the active hardware configuration file to understand what hardware devices (motors, servos, sensors) are connected to the hub. The controller app will validate that it can communicate with the configured devices and display an error if any problems are found. 

You may have multiple configuration files defined on the controller device. These would allow for different sets of hardware to be connected to the hub or allow for the controller device to be used with different robots. In any case, there is only one active configuration, or none if you have not activated one. The current configuration file name is shown in the upper right area of the phone controller app screen or on the Driver Station screen. You create or access configuration files by clicking the three vertical dots in the upper right corner of the phone controller app main screen or the Driver Station screen for the Control Hub. On the menu, select Settings and then Configure Robot. If you already have one or more configuration files, they will be listed. If you have no configuration files, you will be asked to create a new one. You can edit (change), delete or activate an existing configuration file.

We will get into the details of the hardware configuration in a moment. Once a configuration has been created, when you are done you click Save at the top of the screen. This will save the configuration into a file, which you will be prompted to assign a name. After that you will see it on the list of available configuration files. Then use the back button to return to the main screen. The controller will verify the active configuration and if there are no problems, the main screen should display Robot Status as running and Op Mode as Stop Robot, with no error messages below that. The controller app is now ready to run the robot.

Configuration is all about telling the controller app which hardware devices (motors, servos, sensors) are on your robot, which hub port they are plugged into and assigning each device a name by which it will be known in the code you write.

Here is a video that shows the configuration process. Here is a detailed discussion of the process. The process is the same for the phone or Control Hub but with the Control Hub, you must do the configuration from the Driver Station phone.

Once you have a hardware configuration file defined and active on your controller device, you can proceed to the software side of hardware mapping.

In order to control your robot, you will need to create software object instances that control each of your hardware devices and connect those instances to the actual hardware devices. This is done through the hardwareMap static class. For example, lets say our robot has two DC motors, named left_motor and right_motor in the phone configuration and we want to control them in code:

Here we create two DCMotor type instance reference variables and then use the hardwareMap.dcMotor static class and call its method get with the names we assigned in our hardware configuration file. The get method creates a DCMotor object instance and maps it to the appropriate motor controller port using the name supplied and returns a reference to the instance to the leftMotor or rightMotor reference variables. Now we can control those motors using the various methods available on the DCMotor class like setPower(), which sets the power level of the motor.

This code appears in your OpMode class. The hardware device definitions typically are at the top of your class. The hardware mapping should occur in your initialization section, either in the init_loop() function of a regular OpMode or before the waitForStart() call in a linear OpMode. The setPower() calls would appear in your loop() method for a regular OpMode or after waitForStart(), to control actual robot movement.

There is a class for every hardware device and the hardwareMap package has subclasses to map every device. You will need to review the FTC API documentation to become familiar with the device classes available and the fields and methods each class has.

In this manner we map all of a robot's hardware devices to object instances of the appropriate class. We then use those object instances to interact with the devices.

Note that the OpMode classes (that you extend) provide built-in access to the Xbox controllers through the variables gamepad1 and gamepad2. This means you don't have to do the hardware mapping for the controllers.

Here is a set of videos discussing hardware configuration in more detail.

Finally, you can work with phone based hardware configurations from the Driver Station app as well as the Robot Controller app. This is handy as you don't need to remove the controller phone from the robot to access it's screen.

 

Navigation:

Overview: 
Explore the purpose and content of the FTC SDK Library.
Objectives: 

Understand what the FTC SDK Library is and how to use it to interact with robot hardware.

Content: 

The FTC SDK Library is a library of classes that allow your programs to access and control all aspects of the Tetrix robot control system and the hardware devices attached to it. This library is the API for the control system and robot hardware. The library is included in the FTC SDK. You can access the library with the following import statement in an OpMode class:

com.qualcomm.robotcore.<class/class-group>;

This provides access to the highest level of the library. All of the hardware and software classes are divided up into groups and each group will contain classes or lower level groups. You will need to import the classes you use in your OpModes. All OpModes need one of the following imports to make a base OpMode class available for your OpMode class to extend:

com.qualcomm.robotcore.eventloop.opmode.OpMode

or

com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;

Another import you will always need is for the robot hardware classes:

com.qualcomm.robotcore.hardware.*;

Remember that the trailing * imports all classes contained in the named group (hardware in this example). You can import all of the hardware classes or just the specific classes you intent to use. Either way is valid.

The documentation for the FTC SDK Library is very important to read over to get a basic understanding of what classes are available for your use.

The documentation can be found online. You should bookmark this location.

If you are using Android Studio, the documentation is also located in the FTC SDK install directory (ftc_app-master-n.n) in the sub directory doc.javadoc. Click on the file index.html to display the documentation in your browser. The doc is in web format so you must use a browser to view it. You should create a bookmark to the index.html file. Don't forget to update this bookmark when installing new versions of the SDK.

There is a tutorial on the robot control system located online in the FTC SDK wiki.

Don't forget the example code that is included in the SDK in the FtcRobotController\java folder of the SDK project. All of these examples are also available in OnBot in a drop down list when you create a new Java file.

 

Navigation:

Overview: 
Explore the details of the linear OpMode model.
Objectives: 

Understand how linear OpModes work and how to use them.

Content: 
The Linear OpMode is much simpler than the regular OpMode. You extend LinearOpMode and there is only one method to override: runOpMode(). This method is called after the Init button is pressed on the DS. So how do you separate initialization from actually starting the program running? You use the waitForStart() method inherited from the base LinearOpMode class.
 
So from the start of your code in runOpMode() to the waitForStart() method call, you would place all of your initialization activity. When the Init button is pressed, all of your code up to the waitForStart() is executed and then your program waits for the Start button to be pressed. After that your program is in control until the end of the game period. You will most likely need a loop of some sort where you monitor the controllers and take action, but in the autonomous mode you may just execute a set of sequential instructions. In any case, your program must end at the appropriate time. When looping, you can monitor the OpModeIsActive() function (part of the base LinearOpMode class) to determine when you should stop your program.
 
Lets modify the NullOp OpMode sample to be of the linear form:

We use a while loop to continue executing as long as the OpMode is active (opModeActive() returns true).

Note that we call telemetry.update() after the addData() calls. The update() method actually sends the data added with any preceeding addData() calls to the Driver Station. This is different than the regular OpMode.

We also need to call the idle() method at the end of any looping we do to share the phone's processor with other processes on the phone.

 

Navigation:

Overview: 
Explore the details of regular model OpModes.
Objectives: 

Understand how regular OpModes function, what calls are made when and how to use a regular OpMode.

Content: 

The regular OpMode type that you would write extends the OpMode class in the FTC SDK. To add functionality, your code will override one or more of the following methods that exist in the base OpMode class:

  • init()
  • init_loop()
  • start()
  • stop()
  • loop()

These methods are called at the appropriate time in response to button presses on the driver station (DS).

The init() method is called when you select an OpMode from the list of OpModes on the DS. This is called one time, when you do the selection. It is used for very basic initialization functions your code may need to perform. It is not required.

The init_loop() method is called when you press the Init button on the DS. This method is called each time you press Init, so it will be called each time to run the same OpMode. This is the main place to perform your initialization activities. It is not required.

The start() method is called when the Start button is pressed on the DS. You can perform initialization activities more closely related to the start of program execution here. It is not required.

Note that neither init(), init_loop() or start() is required but one of them must be present to hold your code that sets up your hardware map. You should not set up your hardware map in the loop() method. The init_loop() method is recommended.

The stop() method is called when the Stop button is pressed on the DS. You can perform any activities required to stop your program. It is not required.

The loop() method is the workhorse of the regular OpMode. Once Start is pressed on the DS, the loop() method will be called repeatedly until the Stop button is pressed. In this method you should do your robot control activities. The key idea is that you determine the current state of the robot or control inputs, respond as needed and then exit the method. The loop() method  should be kept short.

Lets look at the NullOp sample OpMode from the FTC SDK:  

This simple example shows the key components of the regular OpMode style of program. You can see this example in the FTC SDK source code and compile it to the controller phone to see it work.

Note that the base OpMode class has useful fields and methods you can access by typing their names. A trick to see what is available is to type this. and wait. AS will show you the available items. You can also look at the documentation for the OpMode class. The field telemetry is an example. This is an object reference field on the base OpMode class that points to an object that allows you to send data to the driver station app to be displayed below the Start button. To use telemetry, you call the addData function with two strings. The first is a label or title for the data you want to display. The second string is the data to be displayed. You can call addData multiple times. The telemetry class has many capabilities to display data on the driver station. It is worthwhile to read the documentation for this class.

Note that the telemetry data sent to the DS is not remembered (by default) between calls to loop() or any of the other methods. You must add everything you want displayed on each loop call. This behavior can be changed if you wish.

The class ElapsedTime is a utility class in the FTC SDK provided for you to track OpMode run time. You can create an instance of ElapsedTime (here called runtime) and use it to track the time the OpMode has been  running. This is done in this example so you can see that the OpMode is running and doing something. Note that the OpMode class provides a field called time and a method called getRuntime() that both provide the same information. Either way is valid.

We also use the built-in Java classes Date and SimpleDateFormat to create a formatted string containing the nicely formatted date and time of  OpMode start as an example of using Java classes and displaying information about what is happening in the OpMode.

 

Navigation:

Overview: 
Explore what OpModes are, how they work and how to get started creating your own OpModes.
Objectives: 

Understand what OpModes are, the difference between looping and linear OpModes, how we create and use OpModes.

Content: 

The term OpMode or Operational Mode (also Op Mode and opmode) refers to a class located within the FTC SDK (robot controller app source code). You create this class to add your code to the controller app. Your code is really just a part of the controller app, with the rest of the app supplied by the FTC source code. We don't modify that other part of the code, we just create the custom robot behavior we want by adding our own OpModes. Here is a quick video overview of OpModes.

So how do we do this? We create a new class and extend the FTC provided OpMode class. In essence, we add functionality to the base application by adding new OpModes to it. Each "program" we write for our robot is a class that “extends” the OpMode class. A class that is an extension of another class is a descendant or sub-class: it has (inherits) the properties and methods of the original, but those can be changed or added to. We discuss extending classes in this lesson. When a robot is being operated, the driver station is used to select an OpMode and the controller phone runs only that OpMode.

A quick refresher on robot coding. All robot programs are essentially a looping activity. Your code repeatedly runs in a loop obtaining input, acting on that input and doing it again. 

OpModes are of two types, regular and linear. In a regular OpMode, the predefined method loop() is called repeatedly during robot operation. You write code to respond to these calls to loop(). The key idea is that you do not write a "loop" in your code, the base OpMode provides that for you by calling the loop method repeatedly on a timed basis. This is similar to an event based programming model. Your code responds to the "loop" event. This model is somewhat more difficult for beginners to use.

The linear OpMode is a traditional sequential execution model. Your code is started by the base OpMode and runs on its own until execution is over. In this model you must provide the loop in your code. This model is simpler to use and understand. Note that either model is valid and the choice of OpMode is up to the programmer, however the lessons in this Unit will focus on the linear OpMode.

In either case, when you add a new OpMode (a class file) you need to tell the base controller app that you have done so. You do this by using a Java special statement called an Annotation. An Annotation is an instruction to the Java compiler and is used by the FTC SDK to register your OpMode. The Annotation is placed in your code just above the OpMode class name and contains a title for your OpMode and classifies the OpMode as autonomous or teleop. You can further place your OpModes into groups of your choosing. You can temporarily remove an OpMode by adding another Annotation which disables the OpMode. We will show exactly how this is done in the program examples we will be looking at shortly. This registration process is what makes your OpMode visible to the robot controller phone and available to run.

Either type of OpMode can be used to program the two modes of robot control program execution, autonomous and teleop. In autonomous, the robot is not under the control of humans and as such will receive no input from the driver station phone. This mode is timed and is typically 30 seconds long. A timer on your driver station phone can be used to control the autonomous period, stopping your robot for you or you can manually stop the robot by pressing Stop (square black button) on the driver station. Your code will have to make all decisions and handle everything the robot is designed to do in the autonomous period.

In teleop mode, the robot is operated with input from humans via the Xbox controllers attached to the driver station. This mode is typically 2 minutes long and is stopped manually (Stop button) under direction of the match referee. In this mode your code will monitor Xbox controller input and translate that input into robot actions.

Both modes are started by pressing the Init button and then the Start (arrow) button on the driver station when directed by the referee. The Init button is used to tell your (teleop only) code it should perform whatever initialization functions you have programmed and the Start button begins program execution. We will explore these modes of execution and the driver station controls in more detail shortly.

 

Navigation:

Overview: 
Explore the procedures to install the software tools needed to develop Java programs for Tetrix robots.
Objectives: 

Complete the installation of all of the software tools needed to program Tetrix robots with Java.

Content: 

This course will not delve into Tetrix/REV hardware details or discuss how to build the physical robot. It is assumed you will learn about these topics elsewhere. The code exercises for this unit can be run on the classic example robot "pushbot", build instructions here.


Note: Starting with 2019-20 season, FIRST has renamed pushbot to "basicbot" and changed it's construction. We think the original pushbot is a better match for this curriculum and recommend you use the pushbot guide linked above. 


Note: Previous to the 2019-20 season, FTC robots were only constructed from the Tetrix robot hardware platform. Starting with 2019-20, REV Robotics will also offer a hardware platform for constructing FTC legal robots. While these hardware platforms are different, the control system, motors and sensors are the same.


Tetrix robots can use two different control systems, the older one by Modern Robotics (MR, see bottom of this page) and the newer system by REV Robotics (REV). This course is focused on REV hardware (see bottom of this page for more).

The control system consists of a driver station device which connects to a robot controller device over WiFi. The controller device may be a cell phone connected to a REV Expansion Hub or the REV Control Hub. The Control Hub integrates the robot side cell phone into the Expansion Hub (video).

Here is a diagram of the REV control system hardware components using a robot controller cell phone and Expansion Hub. Here is a video discussing the wiring of the REV components. Here is a diagram of the REV control system hardware components using a Control Hub instead of a robot located cell phone.

As mentioned, the REV control system may consist of two cell phones, a robot controller phone and a driver station phone. You download the driver station phone application (app) from Google Play. Search Play for "FTC Robot". You do not modify the driver station app. You should also download the basic version of the controller app onto the controller phone. This allows you to get some familiarity with the two apps and how they are configured for FTC use. The controller phone must be configured to know about the specific hardware devices (motors, sensors) that are part of your robot (we will cover more on this later). Here is a video (watch to 4:42) on these two apps showing how to operate them. 

The control system may also consist of the driver stations phone and the REV Control Hub instead of the second robot-located phone. The driver station phone is set up the same as discussed in the previous paragraph. The Control Hub comes with the controller app preinstalled. The Control Hub must also be configured to know about the specific hardware devices (motors, sensors) that are part of your robot (we will cover more on this later). Here is a getting started video for the Control Hub. There are more Control Hub resources at the bottom of this page.

The control system may also consist of the REV Driver Hub and the Control Hub, thus eliminating both cell phones.

Note: The Control Hub setup instructions show you how to change the hub name (also the network name) to something custom to your environment. When you change the controller name, after you get the confirmation message, you need to power the hub off and back on before reconnecting. The Control Hub has three software components that may need updating, the firmware, the OS and the Robot Controller App. You can update these items by following the instructions here but the best way to update the Control Hub is with the REV Hardware Client found here. Expansion Hubs only have firmware that may need updating and you can do that with the REV Hub Interface found on the same page. You can also update either hub from the OnBot web page under the Manage tab (See the Start Programming lesson).

FIRST has official tutorials for robot construction and programming as well as kit of parts information on the firstinspires.org web site. Information resources for participation in the FTC competition can be found here. Information on team management can be found here.


With a basic introduction to the hardware done, we can now look at the two programming environments available, OnBot Java and Android Studio. OnBot Java is a much easier way to get started writing code since you don't have to install anything on your PC. Android Studio is far a more powerful tool, but is more complex to install, learn and use. It makes sense to start with OnBot and move to Android Studio later if appropriate.

OnBot Java is an IDE hosted by the robot controller device. You access OnBot with a web browser and essentially write your code "on" the controller device. In this case, the Java tools and FTC SDK are installed on the device when you install the base controller app from Google Play or by compiling the FTC SDK at least once. We will discuss how to use OnBot in more detail shortly.

Android Studio is a professional level tool used to create the complete robot control program from source code. The source code for the robot controller app is available to you to download and install into Android Studio (AS). This is now you create your own robot control programs, by modifying the FIRST supplied controller app source code (adding your robot programs into the controller app). This source code is called the FTC SDK. Experience with AS will carry over to using other advanced IDEs if you plan to move up to FRC and RoboRio. 

If you choose to develop your code using Android Studio, you will need to complete the installation of AS and the FTC SDK on your PC as described below. If you choose to use OnBot, you can skip to the last section of this lesson.


The procedures for installing the software tools you need to use Android Studio are discussed in this video. Links to the components discussed in the video are below. Review the rest of this page before starting.

Note: The Java runtime and SDK are now included in the Android Studio install. The links to these individual items are retained here should the need arise to install them manually, but normally you can skip that and they will be installed with AS.

Here is a link to download the Java runtime.

Here is a link to download the Java SDK. Download the i586 file for 32-bit Windows, x64 for 64-bit Windows. When installing, you only need the Development Tools, you can X out Source Code and Public JRE. The public JRE is the same as the Java runtime installed above. You could skip the Java runtime install above and include the public JRE during the SDK install. Either way works.

Here is the link to download the FTC SDK from github. On the github page for the SDK, click the Code button. Then click Download ZIP. As a suggestion, create a folder called FTC Java Projects in your My Documents folder and extract the FTC SDK (FtcRobotController-master folder) from within the zip file into the FTC Java Projects folder. Then rename that folder to include the FTC SDK version, ie: FtcRobotController-master-6.0. This will allow you to keep older versions of the SDK when you install new versions. You should not overlay an existing version with a newer version. You can find the version by scrolling down on the github page to the Release Information section. The version of the SDK will be shown there. You will need at least version 5.4 for the example code in the lessons. 

If you install a newer version of the SDK, locate the Team Code folder inside your previous FtcRobotController-master-n.n folder with Windows Explorer and copy your source code to the Team Code folder of the new version.

Here is a link to download Android Studio. This curriculum expects you to be on AS 3.4.2 or later. FTC SDK 6.0 requires you to be on AS 4.0 or later. The AS install process involves several long downloads so perform the AS install and the project import (below) on a fast internet connection.

Starting with FTC SDK version 5.5, robot controller and driver station phones must be Android 6.0 or later.

As shown in the video, at the end of the AS install process,  you will be prompted to tell AS what project to start with. You will want to select Import Project (Gradle) and select the folder (and click Open) where you installed your FTC SDK (FtcRobotController-master-n.n) project. At this point AS will use Gradle to import and analyze your project.

Gradle is the name of the tool used with AS to compile and deploy the robot controller app. On first import of the controller project, Gradle will scan the project and determine what Android components are needed by the project and flag any missing components as errors along with a link you can double click to install the missing item. This scan/download process can take a long time. There can be a number of install operations flagged during the initial Gradle sync. Be patient and complete each flagged install. After the downloads complete, Gradle will run for some time to complete the import. Watch the status bar at the bottom of the AS screen to see when all Gradle activity ceases. When done you can minimize the status display area at the bottom of the screen with the minimize button just right of the gear icon on the status display area top bar.

After Gradle processing completes, AS will show a blank editing area on the right and the project navigation window on the left. AS may also show a single blank editing area. On the vertical bar left of the navigation window or editing area, select Project. Then on the tabs at the top of the project window, in the view drop down list, select Android. This will give you the simplest view of the project. You should see two main folders, FtcRobotController and TeamCode. FtcRobotController contains the low level FIRST provided components of the robot controller app. You will not need to modify any part of this code. However, the FIRST provided example code is located here. You can open the folders to java then org.firstinspires.ftc.robotcontroller (a package) then folder external.samples to see the example code. This example code is a very valuable resource to learn how to program many robot functions and use various sensor devices once you have completed this course.

The TeamCode folder is where you will put all of your source code. Open that folder and then java and then org.firstinspires.ftc.teamcode which is the folder (also the package) where your code will be.

Finally, open File->Settings->Build->Experimental. Uncheck Only Sync the Active Variant then click Ok.

Note: If you are in a class room or other situation where multiple users, with different Windows user names, will share a single PC to work on this curriculum, please see these instructions on Android Studio shared by multiple users on the same PC.

We will learn more about how to use Android Studio in a later lesson.

Here is more documentation on robot controller programming.


The rest of this curriculum assumes the use of REV control and sensor hardware.

If you are using the REV Robotics control hardware, here is a documentation package by REV that discusses using the Expansion Hub controller. Note that we will cover robot hardware configuration in a later lesson. Besides the video above, here are resources to help you get started with the Control Hub:

Control Hub Home Page

Control Hub User Manual

FIRST's Control Hub Documentation

If you are still using Modern Robotics control hardware, here is a refresher (watch first 4:30) on the MR hardware environment. Here is a diagram of the MR system hardware components and a diagram of the basic wiring of the MR control system. Here is a lesson package by Modern Robotics that explores the hardware components in great detail. You don't need to explore this now but you may wish to look at this material later to gain much more detailed information about the hardware components, how they work and what you can do with them. When you visit the Modern Robotics Education web site, you will be prompted to login. Click on guest access below the login boxes to access the site without registering. 

A great resource to use while working with the FTC platform is the FTC Technology Forum.

 

Navigation:

Overview: 
Introduction to Java programming for the Tetrix platform.
Objectives: 

Understand the main concepts of the Tetrix robot control system hardware and software.

Content: 

This lesson is the first in the "off ramp" unit for Tetrix/REV programmers. This unit contains a detailed exploration of writing Java programs for the control system used on Tetrix/REV based robots. Don't forget to complete the rest of the Java curriculum starting with Unit 12.

We have been learning a lot about the Java programming language. Now its time to explore how we actually write, compile and deploy Java programs to the robotics control system.

Tetrix/REV based robots use a far more complex control system than the EV3 (FLL) based robots. In FTC game play robots engage in autonomous activity, meaning the robot is not under the control of a human, just like EV3 robots. However, autonomous activity is a relatively small part of the match that is played in competition. The larger portion of match time is teleoperated activity, where the robot is under remote control by human operators. As such, the control system consists of two hardware devices, a robot controller device and a driver station device. The two devices are connected (paired) over a WiFi Direct network. With the Tetrix/REV system, the two devices were initially Android based cell phones but better options are available now.

The driver station cell phone is fairly straight forward. The software for the driver station is provided by FIRST and is not modified by you. Xbox game controllers plug into the driver station phone and are the input devices for robot control.

The robot controller cell phone is more complex. This phone is attached to the robot and connects to the REV Expansion Hub hardware interface that allows the phone to connect to the various robot hardware devices like motors and sensors. The programmer writes an Android phone app that runs on the controller phone and operates the robot with input from the driver station phone's game controllers.

Starting with the 2020-21 FTC season, a new controller option, the REV Control Hub is available. The Control Hub eliminates the robot controller cell phone by integrating the Android execution environment into the Expansion Hub. The  driver station phone and the Control Hub are connected (paired) over a regular WiFi network instead of WiFi Direct. Given that the robot controller can now be either a cell phone or the Control Hub, and they mostly work the same, we are going to refer to them generically as the  robot controller device and discuss differences between them only when needed. You can find more information and documentation for the control Hub here.

Starting with the 2021-22 FTC season, a new driver station option, the REV Driver Hub is available. This option eliminates the driver station cell phone with an Android based device focused solely on robot control and eliminates all of the issues related to using cell phones. Your driver station can now be either a cell phone or the Driver Hub and they mostly work the same, we are going to refer to them generically as the robot driver station device and discuss differences between them only when needed. You can find more information and documentation for the Driver Hub here.

You can write programs for these robots with block based programming tools or with Java (discussion). This curriculum only deals with Java. Java programs can be developed on a Windows PC using the Android Studio (AS) IDE or directly on the controller device using the OnBot Java IDE. The Java exercises in this curriculum will work with either AS or OnBot Java.

The software tools we will be using to write Tetrix/REV robot control programs are:

  • Driver Station device program
  • Robot Controller device program
  • Interactive Development Environment (AS or OnBot)
  • Robot Control program SDK from FIRST for FTC (AS or OnBot)

We will discuss each of these tools and how to install them in detail in the following lesson.

The Driver Station phone software is provided by FIRST and downloaded from Google Play. You connect the phone to the internet and download the appropriate program. You can download a sample robot controller phone app as well but the point of all this is to write your own controller app. There is no downloadable sample for the Control Hub. Software updates for the Control Hub can be downloaded and installed with the Rev Hardware Client utility. The Driver Hub has a built-in software manager for updates.

An Interactive Development Environment (IDE) is a tool that makes it easy to create, compile and deploy programs to devices. 

The Android Studio (AS) IDE is similar to Eclipse or Visual Studio but is optimized for creating Android applications. There are plugins to AS supplied by FIRST that customize AS for use in developing robot control programs.

OnBot Java is a web browser based IDE hosted on the controller device that allows you to write Java programs directly on the controller device.

The final piece is the FTC SDK provided by FIRST. Since the robot control program is an Android phone application, FIRST has provided a base application which handles the details of Android applications and includes the libraries (API) needed to access robot hardware and communicate with the Driver Station phone. The design of this base application allows you to modify the application by simply adding your own classes (called OpModes) to the base application. The base application hides the details of Android applications so you can focus on programming your robot. The base application does not do any robot control, that is the responsibility of the classes you add. This base application is delivered to you as an Android Studio project that compiles into the controller application. This project, for the base application, is referred to as the FTC SDK.

The robot controller application, wether downloaded or compiled by AS, contains an embedded version of the FTC SDK for use by OnBot Java programs.

 

Navigation:

Overview: 
Explore advanced topics related to objects and how they are used.
Overview: 
Explore the difference between passing primitive parameters and reference parameters.
Objectives: 

Understand the difference in behavior of primitive data type parameters and reference data type parameters in methods.

Content: 

In the lesson on passing parameters we learned that primitive parameters are passed by value, that is, a copy of the calling code's variable value is given to the method for it's internal use. Reference variable (object instance pointer) parameters are passed the same way but there is an important distinction to make in how reference parameters (objects) are used in methods.

For this lesson, we are going to use the String object and a new object called StringBuffer. StringBuffer is part of the standard Java API library. We will use String and StringBuffer to illustrate show Java manages object instances and reference variables.

 String objects are immutable, meaning that once they are created they can't be changed. So if we do this:

The first statement created a String object instance with the value "abc". Java allocates computer memory and places a String object containing the characters abc into that memory and places a reference (pointer) to that memory location in the variable myString. The second statement creates a new String object instance with the value "xyz" and places a reference to that new object in the same variable, myString. At this point the reference (pointer) to the original object containing "abc" is now no longer available to us. "abc" still exists in memory but we overlayed the reference to "abc" with a reference to "xyz". The String object "abc" is now orphaned, meaning it no longer is connected to a variable in our program and will be discarded by Java. This is called garbage collection.

Note that the String object has no methods that change it's contents. Strings are modified by making a new String object from the old one. Here is another example:

Here again, we did not modify the string "abc" with the second statement. A new string is created containing the characters myString references, "abc" in this case, and concatenates the string "xyz" to create a new string containing "abcxyz" and a reference to this new string is stored in myString. The original string containing "abc" is no longer referenced by this code and will be garbage collected.

Now the StringBuffer class does provide methods to change it's contents without creating a new object. So if we do this:

The first statement creates a new StringBuffer object instance and places "abc" into it. The second statement calls a method on the StringBuffer object that adds "xyz" to the "abc" already inside the StringBuffer object instance without creating a new instance. When done, mySB is still a reference to the same StringBuffer object which now contains "abcxyz".

So with all of that out of the way we can discuss the nuances of using reference parameters in a method.

Consider this example:

The intent of the method is to append "xyz" to whatever is in the String str. After the call to myMethod(), what is in the String myStr? The answer is "abc". Why? The parameter myStr is passed as a copy and placed into the method variable str. In the method, we change the contents of str. Str now points to a new String object instance containing "abcxyz". However, this new String object instance reference is not passed back to the calling code. myStr still points to "abc". Now consider this example:

After the call to myMethod1(), what does mySB contain? The answer is "abcxyz". Why? Because we called a method on the mySB object instance using the copy of mySB passed into the method's sb variable. This means that sb also references or points to the same object instance as mySB. With the StringBuffer object's append method, we change the internal state of the object instance jointly pointed to by sb and mySB.

After the call to myMethod2(), what does mySB contain? The answer is still "abcxyz". Why? Because we created a new StringBuffer object instance containing "xyz" and stored the reference to it in sb. For the rest of the method sb contains a reference to "xyz". Since we changed the object instance that sb points to, the method lost its pointer to mySB and can't reference it after that point. Note that at the end of the method sb, which contains "123456", will be released since variables created in a method only exist while that method is executing.

As a final point, in our first example the method wanted to append "xyz" to whatever string was passed into it, but it does not change the string that was passed in. Here is how you could fix that method:

Here the method concatenates the two strings using the + operator and creates a new string with it's reference deposited into str. The method then returns this new string reference and the calling code replaces the original string reference with the returned string reference and so myStr ends up pointing to the string instance "abcxyz".

A final note about garbage collection. In the last example, str will go out of scope when the method ends. You might think the new string pointed to by str would be orphaned and then garbage collected. However, since a reference to the actual string object instance in memory was passed back to the calling program and placed into myStr, the string object is not orphaned and will continue to exist. When a reference to an object instance is stored in a variable, the JVM keeps track of that by incrementing the object instance's reference count. When a variable that references an object goes out of scope or the variable has something new stored in it, the JVM decrements the object instance reference count. This is how the JVM knows when an object instance is orphaned, when its reference count goes to zero (no variable is pointing to it). When no variable is pointing to an object instance in memory, that object instance is no longer accessible and the memory can be released.

Here is a video about the difference between primitive and reference variables and how they are passed to methods.

Here are the examples on CodingGround.

 

Navigation:

Pages