This tutorial covers the basics of getting started with Alicorn for the FIRST Tech Challenge (FTC) robotics program.

Important Notice

Spheres are now referred to as Shards. Their functionality is identical; only the name has changed in order to support new development of the core Alicorn platform. Changes as large as this one will not happen again during this competition season. We promise.

All of your current Spheres will continue to work; however, it's advised that you move them from the spheres folder to the automatically generated shards folder as soon as possible, and that you delete any of the default Spheres still left in your spheres folder before you launch Alicorn for the first time after upgrading.

Things You'll Need

Before using Alicorn with your FTC robot, you're going to need a few things:

  • Some knowledge of Javascript (Ruby is also supported, but official documentation for it is not available until we iron out some stability issues it has).
  • A computer with some kind of text editor installed. If you don't have a text editor yet, we suggest Atom.
  • Two Android phones that are legal for use in FTC. One of them should have the FTC Driver's Station app installed, and you'll be installing Alicorn onto the other one.
  • An FTC robot.

Installing Alicorn

The first step in using Alicorn is to install it onto the Android device that will be acting as your robot controller. This is surprisingly easy, and can be accomplished in just a few simple steps:

  1. Uninstall ALL of the FTC apps on your Android device. Alicorn likes to conflict with them.
  2. Download the official FTC app for Alicorn from the Alicorn download page.
  3. Get the APK file onto your Android device using whatever means necessary.
  4. On the device, navigate to the APK file using a file browser and then click it.
  5. You'll be prompted to install the FTC Alicorn Server application. Do so now and then continue.
  6. Once installed, start the FTC Alicorn Server app so that it can initialize your environment.

With that, you're now ready to begin using Alicorn!

The Layout Of Alicorn

Upon launching Alicorn for the first time, a new folder called alicorn will be created in the root directory of your phone's SD card. This folder contains a few important things that you'll use while developing and debugging Shards for Alicorn:

  • A logs.txt file containing all logging data produced by the Alicorn server. The easiest way to log something from a Shard is to use Javascript's console.log, which will automatically be redirected to Alicorn's logger.

  • A alicorn.json file containing the configuration information for the Alicorn server. Since the FTC Alicorn Server is running on an embedded system and thus has unique configuration requirements, it's best to leave this file alone.

  • A shards folder (formerly the shards folder) containing all of the different Shards that you write for Alicorn. For the purposes of the FTC Alicorn Server, each Shard file in this folder will be treated as a single OpMode by the FTC Driver's Station.

Your First Shard

In Alicorn, every program you write is called a Shard. These used to be called Spheres, but for a variety of wondrous reasons we decided to change the name; if you still have any Spheres and you've upgraded to a later version of Alicorn, they'll automatically be loaded as Shards the next time you run Alicorn. However, it's in your best interest to update any of your existing code to use Shards instead of Spheres; we'll be removing legacy support for Spheres in the future!

In the case of the FTC Alicorn Server, Shards are equivalent to OpModes, and the terms can be used interchangeably. With Alicorn successfully installed onto your robot controller, it's time for you to write your first Shard. Go ahead and create a new file on your computer, name it MyRobot.js and then open it in your text editor. Once that's done, go ahead and write the following code within the file:


var sdk, joy1;
alicorn.shard("MyRobot")
    .create(function(self) {
        sdk = self.require("AndroidFTC");
        joy1 = sdk.get("gamepad_1);
    })
    .update(function(self) {
        var x = joy1.get("x2");
        var y = joy1.get("y1");
        
        var left = (x - y).require(0.05);
        var right = (x + y).require(0.05);
        
        sdk.set("motor_1", left);
        sdk.set("motor_2", right);
    });

Let's break down what the code you just wrote does:

  • Every Shard begins with a line that looks like alicorn.shard("MyRobot"). This tells Alicorn that we're creating a new Shard called MyRobot, allowing Alicorn to load the MyRobot OpMode when the time is right. You can use any name in the place of MyRobot, but it's recommended that the name of your JS file matches the name of your Shard (e.g., the file MyEpicAutonomous.js should contain the Shard/OpMode MyEpicAutonomous).

  • After that line, we register two functions with the shard: create and update.

    • create is called one time when the operator hits the "play" button on the driver's station.
    • update is called many times every second after the operator hits the "play" button on the driver's station.
  • Within the create method, we obtain "references" to two things:

    • The Android FTC SDK, sdk = require("AndroidFTC"), which is crucial to any Shard written for the FTC Alicorn Server.
    • The first gamepad connected to the driver's station, joy1 = sdk.get("gamepad_1"), which is used to control the robot.
  • Within the update method, we perform some math on the values of the second joystick's X-axis (var x = joy1.get("x2");) and the first joystick's Y-axis (var y = joy1.get("y1");). The .require(0.05) function tacked onto the end of the simple arithmetic we performed tells Alicorn to set the value of those numbers to zero if their absolute values do not exceed at least 0.05. Once that's done, we assign the values to "motor_1" and "motor_2" via sdk.set("motor1, left"); and sdk.set("motor_2", right); respectively.

Go ahead and save the file if you haven't done so already.

Downloading and Running Shards

With your first Shard, MyRobot.js, written, you're now ready to test it. Go ahead and follow these steps to get the Shard onto your phone:

  1. Plug the phone running Alicorn into your computer.
  2. Navigate to the /alicorn/shards folder on your phone (from your computer).
  3. Copy the MyRobot.js file into the /alicorn/shards folder on your phone.

With that, you're now ready to run the Shard on your robot. But first, we need to configure the phone to work with our Shard's code:

  1. Disconnect the phone from your computer, connect it to your robot, and turn the robot on.
  2. Within the FTC Alicorn Server app, assuming your robot has two drive motors, configure one of them to be named motor_1 and the other motor_2.

Of course, you could always name the motors whatever you want - you'd just have to change the code within MyRobot.js to use the correct names.

Now, with the FTC Alicorn Server on and connected to your robot, launch the FTC Driver's Station app and connect it to the phone running the FTC Alicorn Server - this process is identical to what you'd do if you were using the Android SDK or App Inventor. Once connected, go ahead and select the MyRobot OpMode from the dropdown menu within the driver's station - you'll notice that Alicorn automatically detected and loaded the MyRobot.js file, and knows to treat it like an OpMode.

With the MyRobot OpMode selected, go ahead and hit the play button - congratulations! You've successfully written your first Shard, and should now have a simple program that makes your robot drive around. From here, you can expand on the code you've written to read from sensors, control more complex drivetrains and so on.

Autonomous and Teleoperated Shards

With the introduction of the new FTC Robot Controller API that differentiates between Autonomous and Teleoperated programs, how you name your shards has a slight impact on how they'll work. More specifically, Shards that contain the letters auton in their name will be automatically registered as Autonomous Op Modes, whereas Shards that don't will be registered as Teleop Op Modes. The capitalization/casing of your Shard names does not matter in any way. Here are some examples of Shard names and what kind of Op Mode they'd be registered as:

  • K9 would be a Teleop Op Mode.
  • AutonomousModeOne would be an Autonomous Op Mode.
  • myAutoProgram would be a Teleop Op Mode; it does not contain auton.
  • myAuToNProgram would be an Autonomous Op Mode; it contains auton.

Naming Conventions

Javascript Conventions

Unlike the Ruby conventions, there's only one rule to follow when naming Javascript Shards and their files: the name of a Shard as it appears in a file (e.g., alicorn.shard("MyShard")) should be identical to the name of the file itself (e.g., MyShard.js)) and vice-versa. Changing a file name will NOT change the name of the Shard when Alicorn attempts to load it. Examples include:

  • The file containing alicorn.shard("MyShard") would be named MyShard.js.
  • The file containing alicorn.shard("K9") would be named K9.js.
  • The file containing alicorn.shard("AutonomousModeOne") would be named AutonomousModeOne.js.

Ruby Conventions

  • Class names for Shards must be written in camel case. Examples include:

    • MyShard
    • K9
    • AutonomousModeOne
  • Names of files containing Shards must be written in snake case and correspond to the name of the class within the file. For example:

    • The file containing MyShard would be named my_shard.rb.
    • The file containing K9 would be named k9.rb.
    • The file containing AutonomousModeOne would be named autonomous_mode_one.rb.

Technical Details

While the core of the FTC Alicorn Server is completely identical to that of the current desktop release of Alicorn, Shards for the FTC Alicorn Server can only be written in Javascript and Ruby due to the way Android and the Dalvik VM handle dynamic Java classloading.

Further Reading

If you're looking for more info on how the Alicorn API for FTC works, take a look at the FTC API reference for Alicorn!