Hello Robot - Configuration

Configuration is one of the most commonly misunderstood, or forgotten, steps required for programming a robot. This section sets out to explain the importance of configuration and common misconceptions of configuration by answering the following questions:

1. What is configuration?

2. How do you configure hardware elements?

3. What are common issues that are caused by a problem with the configuration file?

The Importance of Configuration

While every REV Control Hub is the same, the robots being controlled by the Control Hub are not. Each Control Hub has the same number of motor ports, servo ports, digital ports, and the like, but how each user utilizes these ports varies from system to system. For instance, a Color Sensor V3 may be plugged in to I2C Bus 1 on one users Hub, but another user might use the same bus to host a 2m Distance Sensor.

The Control Hub knows that there is an I2C device attached to the port. But it doesn't naturally have the information needed to translate that information to an Op Mode or tell the op mode which drivers need to be accessed in order to use this sensor. A user needs to provide additional information, so that the internal software in the Hub can take information from the Op Mode and apply it to a corresponding external hardware port and vice versa. This process is known as hardware mapping. Hardware mapping is a two step process that includes: the creation of a readable file known as a configuration file and calls to the hardware map within an Op Mode.

The Configuration File

The configuration file is a readable file created by the user through the Driver Station Application. When creating a configuration file users are required to assign each device to a port, select the type of device it is from options provided by the SDK, and give it a unique name.

In programming its important to distinguish between variables, by giving each variable a different name.

Once a configuration file is saved or activated the robot will restart. This restart is so the SDK can read the file, determine what devices are present, and add the devices to the hardwareMap class.

The Hardware Map

On the user-created op mode side of the fence is the hardwareMap class. This class is where the information created in the configuration is available for use in Blocks, OnBot Java, or Android Studio code.

The level of access or interaction a user has with the hardwareMap class depends on which programming tool they are using. Since Blocks is a collection of predetermined code snippets, it creates references to the hardwareMap whenever a variable code snippet, corresponding to an external hardware, is first referenced. However, with Onbot Java and Android Studio the reference to the hardwareMap requires that a variable be created and assigned to an external hardware unit within the hardwareMap

Information on referencing the hardwareMap class in Java will be further explained in the Test Bed - OnBot Java section.

Configuring Common Hardware Devices

Accessing the Configuration Utility

Select the menu in the stop right corner of the Driver Station. Then select Configure Robot.
In the Available configurations page, select New.
In the USB Devices in configuration page select the Control Hub Portal. Note: If you have an Expansion Hub it will appear as an Expansion Hub Portal.
Within the Hub Portal select the device you want to configure. In this use case, select the Control Hub. Note: if you have an Expansion Hub connected to a Control Hub, the Expansion Hub will also appear as a configurable device in the portal.
This will bring you to the page shown in the image. From here you can configure motors, servos and sensors that you are using. Follow through the rest of the guide to figure out how to configure devices that will be used in the Test Bed section. Note: The way that Digital and Analog devices are configured versus how I2C devices are configure differ significantly. This is because each physical I2C port is a different bus that can host multiple different sensors. For more information on the different types of sensors check out the sensors section.

Configuring Hardware

The following section will show how to configure components that will be used in the Test Bed. The hardware type and names have been chosen in consideration for the Hello World lesson plan. Users should heed notes within the steps to consider when creating configuration files for other instances.

Motor

Configuring a Motor

Select Motors.
The Motor page will allow you to configure all four motor ports on the Hub. On Port 0 open the drop down menu and select REV Robotics Core Hex Motor. Note: In your configuration file you should configure the motor ports to the type of motor you are using.
Name the motor test_motor. Select done. Note: remember when naming hardware in the configuration file that the REV Control System is Case Sensitive.

Servo

Configuring a Servo

Select Servos.
The Servo page will allow you to configure all six servo ports on the Hub. On Port 0 open the drop down menu and select Servo. Note: REV Servos can be configured as a Servo or a Continuous Rotation Servo. The type of device a servo is configured as should correspond with the mode the sensor is in. For more information on Sensor modes visit the Sensor section.
Name the servo test_servo. Select done. Note: remember when naming hardware in the configuration file that the REV Control System is Case Sensitive.

Digital Device

Configuring a Digital Device

Select Digital Devices.
The Digital Devices page will allow you to configure all eight digital ports on the Hub. On Port 1 open the drop down menu and select Digital Device . Note: Touch Sensors must always be configured on odd number ports. Check out the Digital Sensor section for more information. Note: Touch Sensors can be configured as a REV Touch Sensor or a Digital Device. In the FTC SDK the type of device it is configured as changes the classes and methods that can be used.
Name the motor test_touch. Select done. Note: remember when naming hardware in the configuration file that the REV Control System is Case Sensitive.

I2C Device

Configuring an I2C Device

Select I2C Bus 0.
Select Add. Note: Each I2C Bus can host more than one I2C sensor as long as the I2C addresses do not conflict. Bus 0 will always host the internal IMU. For more information on I2C sensors visit the I2C section.
On Port 1, which was created in the previous step, open the drop down menu and select REV Color Sensor V3. Note: If you are using Color Sensors V1 or V2 select REV Color/Range Sensor. For more information on configuring with the REV Color Sensors visit the Color Sensor Datasheets.
Name the motor test_color. Select done. Note: remember when naming hardware in the configuration file, that the REV Control System is Case Sensitive.

Saving the Configuration File

Hit Done twice until you reach the USB Devices in configuration page. On the USB Devices in configuration page hit Save.
Name the configuration helloRobotTest and then select Ok. Note: The FTC SDK does not force you to abide by a naming convention for but it is common to name configurations in lowerCamelCase.
Press back to activate the saved configuration. Your Robot Controller will restart once you activate a new configuration.

Common Errors in Hardware Mapping

Within the programming and software world errors come in many different forms and types. When hardware mapping there are two major errors that you may run into. Both errors fall into common categories of software errors:

• Interface Errors - are errors between how an interface should work and how it actually behaves

• Runtime Errors - are errors that occur when a program is being executed

Interface Errors

Interface errors occur in the SDK when the parameters of the SDK interface are not met. In the hardware mapping process the most common interface error occurs with the Blocks Programming Tool. As mentioned in the Introduction to Programming section, Blocks hides complexities of the SDK library from the users. One way it does this is by automatically creating references to the hardwareMap when code snippets for an external hardware unit are used.

In order to automate the hardwareMap calls the Blocks interface reads the configuration file and creates hardware variables based off of the information it finds. For this reason it is important to create a configuration file before trying to code.

The image below shows two different interface versions of Blocks. In the version with no configuration file there are no drop down menus to access code snippets specific to actuators or sensors. In the version of the interface with a configuration file the drop down menus are present and the motor-specific code snippets are access

Runtime Errors

Within the SDK runtime errors occur during initialization or run. One of the most common runtime errors within the REV Control System is exhibited in the image below.

This error is indicative of an inconsistency between how a hardware device is called within the code and how that compares against the name used in the configuration file. There are two different ways this error can occur.

The first occurrence of this error is when there is no configuration file found. This can mean that a configuration file has not been created, a file has been created but is not active, or the wrong file is being used. When any of these instances happen, the code is requesting a device name and type that the hardware map is unable to locate in the configuration file. The program stops on the first such device name it's unable to locate.

An incorrect reference to the hardwareMap can also cause this error to occur. Unlike Blocks, OnBot Java and Android Studio require that a programmer hard code the hardwareMap call. If the reference name in the call does not correspond with the name of the device in the configuration file (it is case sensitive) the code will build without failure but the runtime error will occur. Lets use the configuration file from the previous section as an example; where there is a touch sensor named "test_touch" and a motor name "test_motor" .

The quotations marks indicate that"test_touch" and "test_motor" represent a string variable that corresponds with the names of the devices in the configuration.

public class HR_test extends LinearOpMode{
    private DigitalChannel test_touch;
    private DcMotor test_motor;
    
    @Override
    public void runOpMode(){
        //get the touch sensor and motor from hardwareMap 
        test_touch = hardwareMap.get(DigitalChannel.class, "test_touch");
        test_motor = hardwareMap.get(DcMotor.class, "test_moto");
        
    }
}

Notice in the example lines of code that the hardwareMap.get() for test_motor is written as "test_moto" rather than "test_motor." When the code is building, there is no immediate check that the name requested is in the hardwareMap. This check is done when code is run on the robot. When the communication to the hardwareMap is initiated it looks for "test_moto" and when it can not find it, it creates the runtime error referenced above.