Lesson: Hardware Mapping

Explore how physical robot hardware devices are mapped to names that can be used in programs to access those devices.

Understand robot hardware mapping including controller phone configuration files and how to access hardware devices in software via the mapping scheme.


A key function of the FTC SDK, and of any robotics API, is to provide access to the physical hardware of a robot to the software. A way must be provided to allow programmers to identify, in software, hardware devices on the robot so that they can write programs that interact with that hardware. On the Tetrix/FTC platform, this is called hardware mapping.

Hardware mapping consists of two parts, hardware configuration on the controller phone and hardware mapping in your OpMode class.

When the controller phone is attached to the robot's Core Power Distribution Module, the various control modules and devices plugged into the modules should be recognized by the phone. This is called scanning, and it is performed each time the phone is connected (or the robot is powered on). This set of hardware information is called a configuration. You may have more that one configuration stored on the phone. You access the configuration by clicking the three vertical dots in the upper right corner of the controller app main screen. On the menu, select Settings and then Configure Robot. If you already have one or more configuration files, they will be listed. If you have no configuration files, you will shown a list of the hardware controllers recognized by the controller app.

We will get into the details of the hardware configuration in a moment. Once a configuration has been created, when you are done you click Save Configuration at the bottom of the controller hardware list. This will save the configuration into a file, which you will be prompted to assign a name. After that you will see the list of available configuration files. For each file, you can Edit (change), Activate or Delete. Click Activate to make the selected configuration the current active configuration, which will be displayed in the title bars of each screen. Then use the back button to return to the main screen. The controller will make sure it can reach each controller module in the configuration and if there are no problems, the main screen should display Robot Status as running and Op Mode as Stop Robot, with no error messages below that. The controller is now ready to run the robot.

When editing a hardware configuration you access each controller module and for each hardware device recognized by that module, assign a unique name by which you will access that device in your programs. You can also assign more meaningful names to the controller modules themselves though this is generally not needed. 

When you click on a motor or servo controller, you will see a list of the ports the controller has. You will have plugged motors or servos into these ports when constructing your robot. On the list, check the attached box next to a port if you have attached a device to that port. Then assign a meaningful name to that device. For instance, if you have the motor on the left side of your robot plugged into port 1, you could assign the name left_motor to port 1. This name is what you will use in your OpMode to control that motor. So configuration is all about telling your software which hardware devices (motors, servos, sensors) are on your robot, which port they are plugged into and assigning the device a name by which it will be known in your program.

Here is a lesson that describes the configuation process in more detail.

New for 2017-18 season is the Rev Robotics Expansion Hub. This device replaces the 3 controller modules of the Modern Robotics control scheme. You plug all your motors and sensors into the Expansion Hub(s) (Hubs can be daisy-chained). The process of creating the hardware configuration file on the controller phone is very much the same as with the Modern Robotics modules, but there is just one control module, the Hub. Here is a detailed discussion of creating the hardware configuration file for the Expansion Hub.

Once you have a hardware configuration file defined and active on your controller phone, you can proceed to the software side of hardware mapping.

In order to control your robot, you will need to create objects that control each of your hardware devices and connect the objects to the actual hardware devices. This is done through the hardwareMap static classes. For example, lets say our robot has two DC motors, named left_motor and right_motor in the phone configuration and we want to control them in code:

Here we create two DCMotor type reference variables and then use the hardwareMap.dcMotor static class and call its method get with the names we assigned in our hardware configuration file. The get method creates a DCMotor object and maps it to the appropriate motor controller port and returns a reference to the object into leftMotor or rightMotor reference variables. Now we can control those motors using the various methods available on the DCMotor class like setPower(), which sets the power level of the motor.

This code appears in your OpMode class. The motor definitions typically are at the top of your class. The hardware mapping should occur in your initialization section, either in the init_loop() function of a regular OpMode or before the waitForStart() call in a linear OpMode. The setPower() calls would appear in your loop() method for a regular OpMode or after waitForStart(), to control actual robot movement.

There is a class for every hardware device and the hardwareMap package has subclasses to map every device. You will need to review the FTC API documentation to become familiar with the device classes available and the fields and methods each class has.

In this manner we map all of a robots hardware devices to object instances of the appropriate class. We then use the object instances to interact with the devices.

Note that the OpMode classes (that you extend) provide built-in access to the Xbox controllers through the variables gamepad1 and gamepad2. This means you don't have to do the hardware mapping for the controllers.