Team 25's robot code. Code has been uploaded here so team members can become familiar with the code before working on it for the first time. @Author Varun Chari, K2SO. No license included, because I don't have ownership to this code.
- A Working knowledge of Java.
- Computer: Code can be developed on any operating system, but can only be easily executed from Windows. And of course, it can only be actually executes from our Driver Station, because it has the joysticks.
- How to Use Git (and Github): If you make untracked changes, and push it to the robot, it can easily be tracked back to you.
- How-to-open-source : reading documentation, installing dependencies, reverse-engineering code and understanding it's intent. These skills are a must for a committed contributor to Team 25's codebase. This tutorial was created so we can all be up to speed and transparent about what we do. Cough Cough.
- When you've acquired sufficient time and experience (read: become a computer wizard), it will be evident how to avoid Eclipse & Windows. FIRST claims to be open-source and transparent about how the build system works, but is plagued by lack of proper documentation and directions. FIRST has simplified project development so that teams need nothing more than a knowledge of Java to code. Working without Windows/Eclipse is difficult and not worth the trouble for someone just looking to create Auton-Modes (most people).
- Install a Java Development Kit (JDK) for your operating system (OS). There are 2 nearly identical versions, OpenJDK (open-source) and OracleJDK (from Oracle). OpenJDK is preferred because it may or may not be illegal to develop commercial apps using Oracle's JDK without a license. FIRST says Java 9+ isn't supported (2019 season), but srsly, it doesn't matter much.
- Install Eclipse for Java. It's ok if you install an old version, or a variant for a different language or objective. All the different variants just have different plugins, so it's always possible to customize your Eclipse install to suit your needs by installing the necessary plugins.
- Install the FIRST FRC Eclipse Plugin. Follow the provided instructions. The gist of it is that you add an update source to Eclipse ( a website that provides Eclipse plugins ), download the Java shtuff (or C++ if you're feeling adventurous). Team 25 uses Java, but it is up to each team to decide what they want. From within Java, it is possible to call C/C++ code (look up "Java native keyword" and "Java Native interface", or even Python (look up Jython).
- Before we continue, you'll need to know a few things. Java has an import system so you can add other libraries to your code. When compiling a Java program, you must provide the location of any libraries you use. You should already know this. However, the FRC plugin looks in a very specific place for it's libraries, the $HOME/wpilib directory. If you're on Windows, this is C:\Users\USERNAME\wpilib. If you're on macOS, it's /Users/SHORTUSERNAME/wpilib. If you're on Linux, you already know how to change your home dir to wherever you want. IMPORTANT: Add your personal libraries to ../wpilib/user/libs.
- Either create a fresh robot project using New > Project > WPI Whatever, or clone your team's code to a project in your Eclipse workspace. Most conveniently, if a directory already exists in your workspace, and you create a project with the same name, Eclipse will just add the stuff it needs to the directory, not overwriting it. If you've cloned an existing java project, Eclipse will effectively just add the project name to Package Explorer ( a file manager within Eclipse that shows you all of your projects and their files ).
- Team 25 uses Cross the Road Electronics's Phoenix and KauiLabs' AHRS. It is inherently unsafe to blindly download and run random installers, like that from KauiLabs, becasue they do not provide publicly available source code. If you're on macOS / Linux, you use Wine/an emulator/virtual machine to run the installer and copy the libraries from the simulated C drive.
The entry point for the robot's code (i.e. the class the actually is run) is org.usfirst.team#.Robot. The Robot class extends one of IterativeRobot, TimedRobot, or CommandRobot. All of these classes have methods that start the robot, begin autonomous mode, continue auton, begin teleop, continue teleop, and finally disable the robot. Each team will override these methods to perform the required tasks. The appropriate method is called automatically by the robot's JVM, in response to what portion of the match the field is in. It might be confusing to not see any main methods anywhere; this is because you personally do not dictate what code runs when. This is so the field has the final authority over what the robot does, to make sure each robot follows the rules (and of course, for safety reasons). In Iterative Robot, the appropriate method is called every 0.2 secs, in keeping with the rate at which network packets (containing the joystick readings) are sent from the Driver Station. TimedRobot allows the refresh rate to be customized. However, keep in mind that field uses relatively old hardware, so refreshing faster than every 20ms might result in packets being dropped during a match (and the Robot performing erroneously). Actions that take longer than a single refresh cycle will cause the succeeding packets to be dropped, until the current task has finished. As such, multi-threading is mostly out of the question. To perform tasks concurrently, FIRST has provided CommandRobot. As Team 25 does not use it, it will not be explained here. Check out the sidelinks in the provided website. To cope with the refresh rate, some form of state is stored in every class used. In the Robot class, this is the selected autonmode (m_autonChosen). In AutonController (each method is an auton mode), this is m_step. In the DriveBase class, this is m_drivingStep. Each of these variables keeps track of what step the currently executing method is on, and is only updated once the method has completed its work. This allows a single method to perform different steps of the same action. In any of the auton modes, you'll see that the actions are placed in sequence in a massive if/else or switch. The appropriate step is executed, the state is updated (in this case, m_step is incremented). Then when the method is called again, it will perform the next step. The caller of such a method will repeatedly call it until the method returns a finished state. The caller will then proceed with the next action.
We have created classes to represent parts of the robot ourselves, like DriveBase, Elevator, Grabber, and Hanger. These classes wrap the motors and allow us to move by distance instead of just setting motor speed and having to manually track when the correct distance has been reached. We reuse the drivebase every year, so the code is also reused. The OI class performs all Teleop tasks. It reads the joystick output, and uses this to set the drive speed. The Constants class is exactly what it sound like. Check each class out to figure out what fields have been predefined. To all the newbies: the strength of OOP is really showing here.
For those of you with the knowhow, a WPI Robot project is an ant build.
- Ant sets the entry point to the Robot class
- Builds the jar using the wpilib folder as the classpath
- Scans for the Robot's IP address (10.TE.AM.2)
- SSH's into the robot, copies over the JAR. Note that the ssh account has an empty password.
- A shell script is run to execute the jar. Note that means the roboRIO runs Linux!!
- There is also a script to kill the robot, currently unknown how it is called.
- All of this, and more, can be learnt by checking out a project's build.xml. The included one sources a global build.xml located at ../wpilib/ant