Java Koans for the FRC

Table of content

• Overview
• Getting Started with VS Code
• Getting Started with GitHub Codespaces
• Learning to code with the Java Koans for the FRC
• Java cheat sheet
• And then what?
• Mentors
• Credits
• License

Overview

Java Koans for the FRC is an interactive, step by step, course to teach Java to students engaged in the First Robotics Competition. It requires no previous experience in programming. It does not intend to teach the entirety of the Java language, but rather most of the fundamentals required to start learning how to program a FRC robot.

Getting Started with VS Code

To get started you will need to either install VS Code or use GitHub Codespaces, which is a browser based IDE. If you are unable to install VS Code, because you're on a Chromebook or do not have permissions to install an application, you can skip ahead to Getting Started with GitHub Codespaces

To install VS Code, you will need to install WPILib first to run the Java Koans for the FRC.

Once installed, download the latest release of the Java Koans.

Then, extract it somewhere on your computer. Go to the folder where you have downloaded the koans, righ-click on the koans zip file, and choose 'Extract All'. Choose your destination folder, for example, a /src folder within your Documents folder.

Then, open WPILib VSCode:

And open the folder in which you extracted the koans (for example, C:\Users\Jane\Documents\src\FrcJavaKoans):

Note: VS Code will ask you if you trust the code within the folder. You'll have to answer 'yes' to proceed.

You are ready to go!

Getting Started with GitHub Codespaces

GitHub Codespaces provides a cloud-based development environment. It allows you to effortlessly set up and access a consistent development environment directly from your web browser. This is useful when your students only have access to Chromebooks or for other reasons are not able to install and configure VS Code.

To get started with GitHub Codespaces, simply click the "Code" button and select "Create codespace on Master" to create or access your development environment.

For more information GitHub Codespaces, including cost, check out Codespaces Description

Learning to code with the Java Koans for the FRC

A koan is a challenge a zen master is throwing at you to help you learn something. Here, your mission is to solve koans which will help you learn about programming in Java.

Ask the master for koans

When you open the Java Koans for the FRC in VS Code, you should see something similar to this:

Expand the src folder, then right click on the file src\main\java\EnglishPathToEnlightment.java and choose Run Java:

Note: Windows Defender might ask you to authorize VS Code to use the network. You'll have to authorize it.

This will open what is called a terminal at the bottom of the VS Code window and run the Java Koans for the FRC. Ignore all the cryptic text generated by VS Code for now and focus on this part:

The master of the Java Koans is telling you a lot of things at once, so let's decompose a bit:

First, it tells you that it is trying to teach you AboutConsoleAndVariables. Then it tells you that you did not complete the Displaying some text in the console koan. Which is normal, because you have not even started yet! Then it shows a mysterious Console box, which we will ignore for now. At the very bottom, it tells you you can look for Displaying some text in the console in the src/main/java/koans/english/AboutConsoleAndVariables.java file.

Opening the koan file

Open that file in VS Code:

Wow, there is a lot going on! In order to understand what is all of this, we need to learn a few things about Java.

Java files

All the code written in Java must go in files with the .java extension. The content of these files follow a pretty strict organisation. First at the top, there are a few lines helping Java knowing which other files it will need to get in order to make sense of this one:

package koans.english;

import static engine.Helpers.readLine;

We will not explain the details of these lines for now and ignore them. Don't worry, when done with the koans, you will understand them!

The class

Next in the file, we can see this:

public class AboutConsoleAndVariables {

This tells Java that we are creating a AboutConsoleAndVariables class. All the bits of code in Java are organised in classes. You can think of a class like a drawer or a shelf containing bits of code. You can only have one class in a java file, and the name of the file must be the name of the class, with the .java extension. This is why the file we are looking at is named AboutConsoleAndVariables.java. All the code of a class is contained between the opening { and the closing } at the bottom of the file.

Note: everywhere in Java where you will need to 'enclose' a bit of code, we will use an opening { and a closing }. This will tell Java that everything between those curly brackets are belonging to the same thing.

The koan instructions

Next, we can see these lines, colored in green:

    /**
     * # Displaying some text in the console
     * 
     * Display 'Hello!' in the console.
     * 
     * ---------   TIPS --------------
     * 
     * All lines of code in Java must end with the ';' character. Ex:
     * 
     *      System.out.println("Apple");
     * 
     * You can use the method System.out.println([some value]) to display a value in the console.
     * 
     * You can tell Java that some value is text by enclosing it between double quotes. Ex:
     * 
     *      "This is text"
     * 
     * -------------------------------
     * 
     * Expected result in the console:
     * 
     * Hello!
     * 
     */

These lines are forming what's called a 'comment'. All the text between a /* and a */ is a comment. A comment is a piece of information that is ignored by Java. It is not code. It is very useful for documenting your code while you are writing Java. The master is putting each Koan's instructions for you in such a comment.

The first line of the comment tells you the title of the Koan: # Displaying some text in the console.

Then comes the goal of the koan at the top of each such comment: Display 'Hello!' in the console.. The console is the simplest way for a Java program to communicate with you by displaying simple text in a terminal. Remember what was displayed when running the Koans? You saw this bit:

Console:
---------


---------

This is where the text will appear when you will program something displaying text in the console.

After the goal of the koan, the comment goes on with tips on how to solve the koan. For example, it is telling you to use System.out.println([some value]). Note: when you see square brackets '[' and ']' in the master's instructions, it is not something to type in directly, but rather it is a placeholder for you to type something else.

Finally, the last section of the comment is showing you what result your code is expected to produce.

When trying to solve a koan, take your time to understand all the information that is given to you to successfully solve it.

The koan method

Finally, we arrive at the part of the file where you will be able to code in Java! In Java all the code must be part of a "program chunk" called a method. A method is really nothing else than a mini-program. Here is the method of the first koan:

    public static void sayHelloInConsole() {

    }

We will ignore the public static void part for now. What comes next is the name of the method: sayHelloInConsole. All the code chunks in Java have names, allowing to refer to it later, if we want to run that piece of code. Then comes parentheses: (). This is basically telling Java that sayHelloInConsole is a method. And at last, the opening { and closing }. All the code you will write will have to go in between those 2 curly brackets, and nowhere else. If you write code outside of the curly brackets of a method, Java will show you an error.

So let's try so solve this first koan. To do it, we have to display "Hello!" in the console. The first tip for doing so is:

     * All lines of code in Java must end with the ';' character.

Ok, so we can at least put a ';' at the end of our line, so we don't forget:

    public static void sayHelloInConsole() {
        ;
    }

The next piece of tip is:

     * You can use the method System.out.println([some value]) to write something in the console.

So we know we should use this command, and find a way to replace [some value] by the Hello! text later. Let's write down the command without the value for now:

    public static void sayHelloInConsole() {
        System.out.println();
    }

Next the final tip is telling us how to write a text value:

     * You can tell Java that some value is text by enclosing it between double quotes.

Perfect! So let's place the value within the previous command:

    public static void sayHelloInConsole() {
        System.out.println("Hello");
    }

Running the koans again

Now that we think we completed the koan, let's ask the master what he thinks and see what happens. To run the koans, right-click on EnglishPathToEnlightment.java and choose Run Java. You should see this output:

Oops, we made a mistake! The master was expecting us to display Hello!, but we forgot the exclamation mark. Let's fix it in src/main/java/koans/english/AboutConsoleAndVariables.java:

    public static void sayHelloInConsole() {
        System.out.println("Hello!");
    }

And run the koans again:

That's a completely different message! This is because we successfully completed the first koan! So our master is telling us about our progress and about the next koan.

Congratulations, you completed your first koan! You can now look at the next koan in the src/main/java/koans/english/AboutConsoleAndVariables.java file and try to figure out how to complete the next koan!

Java cheat sheet

To help you remember the bits of Java syntax you are learning while completing your koans, you can print a copy of the Java Cheat Sheet.

And then what?

After completing the koans, you are ready to learn how to program an actual robot. Mykah, from team 9153 - Bearcat Robotics, is maintaining a wonderful compendium of FRC programming resources from which you can dig for your next steps.

Once you understand how to program a simple TimedRobot, you can come back here and practice with bonus koans you will find in src/main/java/bonuses/english. These koan series are independant of each other and can be followed in any order. To run them, right click on the one you are interested, for example src/main/java/bonuses/english/AboutArrays.java and choose Run Java directely on the koans file itself.

Experience is the name everyone gives to their mistakes.

Oscar Wilde

Mentors

This course intent to come batteries included, with 100% of the information needed by a motivated student to learn Java from Scratch without any other ressource at hand. However, it is best used with assisting mentors.

We have found that students learn faster if mentors are not giving solutions to students' issues, but instead ask them open questions about what they don't understand about the exercise instructions or displayed error. Programming is, most of the time, about figuring out what little detail have been overlooked. Thus, helping students to look for answers by themselves in the koans' text will help them become more autonomous faster when it will be time to program and debug a robot.

Full curiculum suggestion

1. Start with the students completing all the initial koan series ("EnglishPathToEnlightment").
2. Not part of the FRC Java Koans: make them program their first robot with a simple TimedRobot. It is suggested to have a simple differential drive robot.

• Super simple auto mode making the robot go forward at 20% speed for 1 second.
• Simple teleop mode making the robot move with a joystick.

3. Students can now follow the src/main/java/bonuses/english/AboutInterfaces.java bonus koans.
4. Not part of the FRC Java Koans: make them program the simple robot again, but using commands based programming.

Optional:

Before teaching them to deal with a Swerve Drive, the students could follow src/main/java/bonuses/english/AboutArrays.java to learn arrays and for loops.

Topics included

• Printing to and reading from the console
• Variables
• int, boolean, String, double basic types
• if, else, if else construct
• Methods
• for loops
• Arrays
• Packages and classes with static methods
• Objects, constructors, fields

In the bonus koans:

• Arrays and for loops
• Functional interfaces

Contributing and learning more

If you are interested in learning more about this course or contributing to it, please take a look at CONTRIBUTING.md :)

Credits

Created by a mentor from the 3550 Robotronix team (Montréal, Canada).

Heavily inspired by the wonderful Ruby Koans.

The Github Codespaces feature is a contribution of jmcconne10.

Typos have been fixed by someonesomething.

Many thanks to early testers who gave me feedback: Andy, Noémie, Chenxin, and Dumitru.

Edited for use for FRC 4143 by Cole Hunt

License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.