Stress-Free FTC Hardware Configurations

Building the Hardware Map By Hand

Many FTC teams only interaction with the hardware map is through the robot controller and using “Configure Robot” on their smartphone. However, if your team is using Android Studio to develop their robot software, you may want to consider creating and managing your hardware map with the IDE itself.

There are many good reasons for not using the phone to manage the hardware map.

First, and probably most important, is that if the robot configuration is performed using the phone, that configuration travels with the phone. This means if the phone were to be lost, physically damaged, or stop working correctly, the configuration will need to be re-created from scratch. This requires entering names of each connected motor, servo and sensor with the tiny phone keyboard, and taking great pains to make sure they match the names used in your code. This exercise is often done under extreme pressure, getting ready for robot inspection, or in between crucial matches at a qualifying or championship event.

If instead, your hardware map is created in Android Studio, and stored with your sources, getting a new robot controller up and running with a known-good hardware map is is as straightforward as “Run -> Team Code” in Android Studio with the new phone. Any new phone – the spares you hopefully carry, or one that some graciously professional team loans to you to make it through the rest of the competition.

Second, swapping out malfunctioning or damage REV hubs is straightforward if you manage your hardware map from Android Studio. Simply replace the serial number and port number of the primary hub in an XML file if that is the one you are replacing, or simply the port number of the secondary hub.

Third, if your team is unfortunate enough to lose or corrupt their code, they can restore the existing configuration from a backup, or their revision control system. Hopefully your team is regularly backing up their code!

While it’s not necessary to use a revision control system like Git to manage your code, our team does, and has found it to be worth the effort. It’s trivial to go back through time and figure out what changed, when, including changes to the hardware map and the code that uses it. There is no such option for configurations created on the phone.

Getting Started

To create a hardware map that is stored with your robot code and automatically installed when you execute “Run -> Team Code”, you create an XML file with a certain format, and place it in the res/xml directory in your Team Code project:

To add the new file, navigate to the “xml” folder under “res” in your TeamCode project. Right click on the “xml” folder, choose “New -> File”. A dialog will appear. Make sure to use a descriptive file name (because it will be what is displayed when choosing a configuration when running the robot) and use a “.xml” extension. Good choices are the robot’s name (if it has one), or the name of this season’s challenge. There are restrictions on the filename, it must only contain the characters a-z, 0-9 or an underscore character.

The file below can serve as a template for hardware maps created in this manner. You can copy and paste this XML into your newly-created hardware map file and then edit it to match the physical configuration of your robot.

There is little documentation on the allowed tags that can be used to represent different devices, the ones in this file are extracted from configurations pulled from robot controller phones, or from reading the sources in the “Hardware-release-sources.jar” file that ships with the SDK.

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>

<Robot type="FirstInspires-FTC">


NOTE: The name “Expansion Hub Portal 1” is what the FTC robot controller
will call this if you scan for it, so leave it set to this value for

You can retrieve the serial number value of the hub by configuring
it from the robot controller phone, and taking note of the value 
found there. We always put that serial number (and the port numbers) 
on a label somewhere visible on the hub - to make it straightforward 
to swap in case one becomes damaged.

If you need to use two REV expansion hubs, you will need to change 
the port number of at least one to something other than the default 
value of ‘2’, see the documentation from FIRST on how to do this at

Everywhere that [...] appears, is a value that you must provide:

* For serial numbers, this must match the value in the physical 

* For a control hub, on the LynxUsbDevice element, the serial number must be
"(embedded)", the parent module address is as given by the control hub
itself, but is "2" by default.

* For port numbers, this must match the actual physical socket 
on the REV hub

* For names, any value may be used. We always use the same name 
in the XML file, as is used for the variable in Java that refers 
to the physical hardware. We have found that this makes it easier 
to keep things straight.

        name="Expansion Hub Portal 1"
        serialNumber="[...]" parentModuleAddress="5">

        <LynxModule name="[...]" port="[...]">

            <!-- The built-in IMU is always port="0" bus="0" -->
            <LynxEmbeddedIMU name="imu" port="0" bus="0" />

<!-- **********************************************************

DC Motors

The "port" value refers to the physical port where the motor
is connected to the REV expansion hub, numbered 0 - 3.

The element named "Motor" is generic, but it will not set
tuned PID(F) values for the type of motor plugged into the hub.

You will observe more consistent velocity PID (RUN_WITH_ENCODERS)
or RUN_TO_POSITION behavior if you can use the specific motor types
provided by the SDK.

In this first example, you'll notice a color comment. We've found
that it is very helpful to use wire marking tape on the ports on
the expansion hub, the cables that plug into them, both sides
of any connections between the hub and the device, and the devices
itself. It makes it very easy to identify what to check or replace
when something is not working correctly.

************************************************************* -->

            <Motor name=".."  port="[...]" /> <!-- Yellow -->

            Andymark Gearmotors

            IMPORTANT: The NeveRest20GearMotor type does not contain
            appropriate values for the orbital gear motor! You will need to
            set these directly in software (at least for now)

            <NeveRest3.7v1Gearmotor name="[...]" port="[...]" />
            <NeveRest20Gearmotor name="[...]" port="[...]" />
            <NeveRest40Gearmotor name="[...]" port="[...]" />
            <NeveRest60Gearmotor name="[...]" port="[...]" />

            REV Robotics Gearmotors

            <RevRobotics20HDHexMotor name="[...]" port="[...]" />
            <RevRobotics40HDHexMotor name="[...]" port="[...]" />
            <RevRoboticsCoreHexMotor name="[...]" port="[...]" />

            GoBILDA Gearmotors

            <goBILDA5201SeriesMotor name="[...]" port="[...]" />
            <goBILDA5202SeriesMotor name="[...]" port="[...]" />

            Tetrix Gearmotors

            <TetrixMotor  name="[...]" port="[...]" />

            <!-- *************************************************************

            Servos are pretty straightforward. Ports are numbered 0-5

            Configuring a servo as a ContinuousRotationServo in this file
            will present an interface in software that "feels" more like a
            DCMotor for servos that are, or are able to be put into continuous
            rotation mode.

            See com.qualcomm.robotcore.hardware.CRServo in the SDK for more

            ************************************************************* -->

            <Servo name="[...] port=[...]" />
            <ContinuousRotationServo name="[...]" port="[...]" />


            REV SparkMinis plug into a servo port, and allow you to use a 12V
            gearmotor as you would a ContinuousRotationServo. When used from
            your code they are of type DcMotorSimple.


            <RevSPARKMini name="[...]" port="[...]" />

            <!-- *************************************************************

            Digital Devices on REV hubs look like this.

            REV's magnetic limit switch (
            sends output voltage on 'n' and 'n+1', so odd or even port
            numbers work for the same sensor.

            However, REV's touch sensor, which can either be configured as
            a plain "DigitalDevice" or "RevTouchSensor" always sends on n+1,
            so that will always be an odd port number.

            Since we don't use any of REV's splitter cables on our robots,
            we try and always use the odd port number in case we switch
            one type of sensor out for the other.

            If you're attaching something else to your REV Hub to the digital
            I/O ports, check your spec sheet for which pin will send output
            signal, and set "port" appropriately.

            ************************************************************* -->

            <DigitalDevice name="[...]" port="[... (odd)]" />
            <RevTouchSensor name="[...] port=[... (odd)]" />

            <!-- *************************************************************

            I2C Devices

            Bus numbers (sockets on the hub) run from 0 to 3. An I2C device
            plugged into the physical socket labeled "0" on the hub should use
            port="1" and bus="0". I2C devices plugged into sockets labeled 1-3
            on the hub should use port="0" and bus="[socket number on hub]"

            ************************************************************* -->

            <!-- REV Time-of-Flight 2m Distance Sensor -->
            <REV_VL53L0X_RANGE_SENSOR name="[...]" port="0" bus="[...]" />

            <!-- V1 and V2 of the REV color/distance sensor -->

            <LynxColorSensor name="[...]" port="0" bus="[...]" />


            Use for the current v3 REV color sensor. NOTE that color and
              distance values for v3 differ from V1-V2!



            <RevColorSensorV3 name="[...]" port="0" bus="[...]" />

            <RevBlinkinLedDriver name="[...]" port="0" bus="[...]" />

        <LynxModule name="Secondary Hub" port="3">

          <!-- *************************************************************

          Add devices here that are plugged into the secondary REV expansion
          hub, following the syntax above.

          ************************************************************* -->


Once you are finished editing the file, you can push it to your robot controller phone with “Run -> Team Code”. Once the application has restarted tell the robot controller to use the configuration as you would normally by choosing “Configure Robot” from the drop-down menu:

Next, choose the configuration that matches the filename you used, and press the “Activate” button on your screen, and then the “Back” button to get back to the main robot controller screen:

Hopefully this post will save teams that are able to use Android Studio some stressful moments when dealing with their hardware configurations. If you have any questions, please leave a comment!

1 thought on “Stress-Free FTC Hardware Configurations

  1. Added some changes to show how you would reference a REV Control Hub.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this:
search previous next tag category expand menu location phone mail time cart zoom edit close