Resources

Programming Documentation & Tutorial

For a Word file of this tutorial, please click here.

Created by Sean and finalized August 1, 2023

Re-formatted to website by Piyush and published December 14, 2024

--------

Introduction

This tutorial explains how to use Android Studio for FIRST Tech Challenge programming, as well as Git version control, on a Windows environment. This tutorial assumes a basic working understanding of Java and some fundamental programming concepts (while loops, importing other classes, basics of object-oriented programming, etc.).

Android Studio [AS] is an integrated development environment [IDE] designed specifically for developing applications for Android devices. The app that you will be developing is the FtcRobotController app. Your REV Robotics Control Hub is essentially a screenless Android phone with hardware ports, and you will be developing the Operation Modes (OpModes) that make your robot move.

AS is very helpful in customizing your code and your coding environment. It allows you to import custom libraries for tools such as RoadRunner, FTC Dashboard, and OpenCV, it allows you to customize the look and feel of your environment.

Git is a version control Command Line Interpreter [CLI] program that allows you to store backups of your code in remote repositories (repos). For this tutorial, you will be setting up your own Github account and repo, in which you will store all of your code for the season. Be sure to create a new Github repository at the beginning of each new season. Avoid making past repositories public, as if people request to see your code you can give them access to your repo on a case-by-case basis.

Throughout this tutorial, commands for terminals may have an argument in brackets, e.g. “git config -- global --user.name [username]”. In this case, you would enter the command as written, but remove “[username]” (including removing the brackets) and replace it with the specific Github username that you chose. Commands and Java code snippets will be in a separate font in order to tell the code apart from information.

This tutorial will teach you how to set up Git Bash for storing your code on GitHub, set up Android Studio for programming, add external dependencies to Android Studio, and write some OpModes.

Setting up Git Bash

1. If the team doesn’t already have an account, go to github.com and create an account. Be sure to copy down your username, password, and email, as this will be important. I recommend making one in the name of the team, and hosting the repositories on that account. You may send contributions to that repository using personal accounts, but host the repository on the team account.

2. Download Git Bash from https://github.com/git-for-windows/git/releases/download/v2.39.0.windows.2/Git-2.39.0.2-64-bit.exe and run the installer. You don’t need to set any custom settings in the installer, you can always click the next button and it will install correctly.
   a. If you need to select any options, choose whatever is recommended by Git.

3. Next, you will be running some basic configuration of your Git Bash Command Line. This will allow you to push your programs to a private Github Repository as a backup. Open Git Bash and run the following commands:
   a. git config --global --user.name [username]
   b. git config --global --user.email [email]
   c. git config --global --core.editor notepad

4. Next, you will be generating SSH keys and adding them to your ssh-agent (the Git Bash terminal). These next instructions come directly from Github Docs.
   a. Generate an SSH key by running the following command:

   1. 1. 1. 1. ssh-keygen -t ed25519 -C [email]

            2. When prompted to enter a file in which to save the key, press the Enter key

            3. When prompted to enter a passphrase, enter a passphrase. You will be prompted to type it again and confirm it. Make sure you write down the passphrase, as you will be entering it every time you push your programs to your Github repo.

b. Start the ssh-agent by running the following command:

1. eval “$(ssh-agent -s)”

c. Add your SSH key to the agent by running the following command:

1. ssh-add ~/.ssh/id_ed25519

d. Add your SSH key to the agent by running the following command:

1. clip < ~/.ssh/id_ed25519.pub

e. Open github.com and log in to your account. Then go to account settings. Under the “Access” section, click SSH and GPG keys.

f. Click New SSH Key.

g. Title your SSH Key based on the computer you’re using for your FTC programming. Name it something recognizable.

h. Ensure that Key Type is set to “Authentication Key”

i. Paste your SSH Key into the “key” box and click “Add SSH Key"

5. Now that your SSH terminal is properly set up, you can create your own repository (repo).
   a. Go to github.com, log in, and click the green “New” button

b. Name your repository. I suggest naming it by season, so you can use different repos for different seasons and not mix up different versions of your code.

c. You can write a quick description if you want. You can write a more detailed README file once you have your repo set up.

d. Set the access to public or private. I suggest making it private by default and changing access on a case-by-case basis. You don’t need to share your code with the rest of the league, although you can if you would like.

e. Click “create repository”

6. Now, you will be cloning the FTC Software Development Kit (SDK) to properly program your robot in AS.
   a. Create an FTC folder where you’ll store your code. For the purposes of this tutorial, the pathway will be ~/Desktop/FTC.

   1. 1. 1. 1. Side note: in Bash terminals, the ~ denotes the user’s directory. It’s the equivalent of a Windows Command Prompt showing the working directory as C:\Users\[user]\.

b. If not open already, open Git Bash and issue the following commands:

1. cd desktop

   1. cd stands for “change directory”. cd is a command both in Windows Command Prompt and in Bash terminals.

   2. You can then type cd [filepath] to enter a subfolder, or you can enter cd .. (two periods) to move up one folder.

a. For example, if the working directory is ~/Desktop/FTC and I issue cd .., the working directory will change to ~/Desktop.

1. 3. If you don’t know where to change directories to, type dir and it will list all files and directories in the current working directory.

2. mkdir FTC

   1. mkdir stands for “make directory”, which creates a folder with the specified name. If you want to make a folder with a space in the name, put a backslash \ before each space. The interpreter automatically takes any spaces between names to mean that it should create multiple directories, one for each word separated by a space. Putting a backslash in front of a space is called an escape sequence, and that tells the interpreter to make the directory name with as many words as are separated by the space escape sequences.

3. cd FTC

   1. If you don’t know where to change directories to, type dir and it will list all files and directories in the current working directory.

4. git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git

   1. This may take a couple minutes, as it is downloading the entire FTC SDK. It will create a folder in ~/Desktop/FTC titled FtcRobotController. Issue the next command once the FtcRobotController repository has been fully downloaded.

5. rm -rf .git

   1. What this does is severs any connections to the FtcRobotController remote, so that any code you may commit will only ever go to your own repository.

7. Now, you will be adding access to the repo that you created. Issue the following commands to Git Bash:
   a. If you are already in ~/Desktop/FTC/FtcRobotController

   1. 1. 1. 2. 1. cd TeamCode/src/main/java/org/firstinspires/ftc/teamcode/

b. If you are not:

1. cd ~/Desktop/FTC/FtcRobotController/TeamCode/src/main/java/org/firstinspires/ftc/teamcode/

2. This file pathway is where all of your code will be stored.

c. git init

d. git remote add origin https://github.com/[username]/[repositoryname].git

1. Now you can reference your own code repo.

Congratulations! Git Bash is now configured for usage.

Updating the FtcRobotController app

If FTC requires you to update the version of your FtcRobotController app, run the following commands in Git Bash:

1. git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git

2. cd FtcRobotController

3. rm -rf .git

4. cd TeamCode/src/main/java/org/firstinspires/ftc/teamcode/

5. git init

6. git remote add origin https://github.com/[username]/[repositoryname].git

7. git pull origin master