Lesson: Hardware Mapping

Two more preparatory topics and then we can write some code!

A key function of the FTC SDK, and of any robotics API, is to provide software access to the physical hardware of a robot. 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/REV platform, this is called hardware mapping.

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

When you power on or connect the robot controller phone to the REV Expansion Hub or power on the REV Control Hub, the controller app will use the active hardware configuration file to understand what hardware devices (motors, servos, sensors) are connected to the hub. The controller app will validate that it can communicate with the configured devices and display an error if any problems are found. 

You may have multiple configuration files defined on the controller device. These would allow for different sets of hardware to be connected to the hub or allow for the controller device to be used with different robots. In any case, there is only one active configuration, or none if you have not activated one. The current configuration file name is shown in the upper right area of the phone controller app screen or on the Driver Station screen. You create or access configuration files by clicking the three vertical dots in the upper right corner of the phone controller app main screen or the Driver Station screen for the Control Hub. 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 be asked to create a new one. You can edit (change), delete or activate an existing configuration file.

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 at the top of the screen. This will save the configuration into a file, which you will be prompted to assign a name. After that you will see it on the list of available configuration files. Then use the back button to return to the main screen. The controller will verify the active 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 app is now ready to run the robot.

Configuration is all about telling the controller app which hardware devices (motors, servos, sensors) are on your robot, which hub port they are plugged into and assigning each device a name by which it will be known in the code you write.

Here is a video that shows the configuration process. Here is a detailed discussion of the process. The process is the same for the phone or Control Hub but with the Control Hub, you must do the configuration from the Driver Station phone.

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

In order to control your robot, you will need to create software object instances that control each of your hardware devices and connect those instances to the actual hardware devices. This is done through the hardwareMap static class. 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 instance 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 instance and maps it to the appropriate motor controller port using the name supplied and returns a reference to the instance to the 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 hardware device 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 robot's hardware devices to object instances of the appropriate class. We then use those 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.

Here is a set of videos discussing hardware configuration in more detail.

Finally, you can work with phone based hardware configurations from the Driver Station app as well as the Robot Controller app. This is handy as you don't need to remove the controller phone from the robot to access it's screen.