YAML Robot Map (old)

From Team 449 Wiki

(Redirected from Robot Map)

Although the reusable 'back end' of our team's robot code, i.e. the central repo, is written in Java, each individual robot essentially just comprises a single YAML file called the "robot map." (Or, alternatively, the map, the config file, the YAML file, etc.) It's basically one massive constructor for a robot, containing constructors for the objects that the robot contains. This setup allows us to quickly tweak individual parameters of the robot during testing, without even having to deploy any new Java code. A repository's map is usually found under src/main/resources/map.yml.

Even after understanding maps in general, robot maps can appear long and intimidating when you first look at one. This page goes through how to read a typical robot map.

Top-level structure

The top-level structure of a robot map is as follows:

---
logger:
    ...
defaultCommands:
    ...
teleopStartupCommand:
    ...
buttons:
    ...
autoStartupCommand:
    ...
updater:
    ...

Now we can look at each of these fields individually.

Logger

The logger creates a log of the robot's status over the course of a run. The logs can be used for later reference when debugging past runs. It looks something like this:

logger:
  '@id': logger
  eventLogFilename: "/home/lvuser/logs/eventLog-"
  telemetryLogFilename: "/home/lvuser/logs/telemetryLog-"
  loopTimeMillis: 100
  loggables:
    - org.usfirst.frc.team449.robot...SomeClass:
        '@id': thing1
        ...
    - org.usfirst.frc.team449.robot...SomeClass2:
        '@id': thing2
        ...
    ...

An event log is mostly just a list of when each command was started and ended. A telemetry log is a list of many properties of the robot's composing objects (e.g. the position and velocity of the front-left drive motor), recorded once every loopTimeMillis milliseconds. Event logs will be saved in /home/lvuser/logs as eventLog-[datetime_of_run].csv, and the telemetry logs work similarly. All Loggable objects must be defined under the robot's logger's loggables or they won't be logged, but these objects can be referenced by their ID later in the map.

Default commands

Some subsystems have a command that they need to be run by by default. For example, the drivetrain may be controlled by driver input by default, but during the middle of a match could be commanded to drive 5 feet forward autonomously. Once this command finishes, control of the drivetrain is automatically given back to the driver.

defaultCommands:
  - subsystem:
      org.usfirst.frc.team449.robot...SomeSubsystem1:
        '@id': subsystem1
        ...
    command:
      org.usfirst.frc.team449.robot...SomeCommand1:
        '@id': command1
        ...
  - subsystem:
      org.usfirst.frc.team449.robot...SomeSubsystem2:
        '@id': subsystem2
        ...
    command:
      org.usfirst.frc.team449.robot...SomeCommand2:
        '@id': command2
        ...
  ...

It's simply a list of subsystem-command pairs, where the command is the default command of the subsystem.

Teleop startup command

Simply the command that runs when teleop starts.

teleopStartupCommand:
  org.usfirst.frc.team449.robot...SomeCommand:
    '@id': teleopStartupCommand
    ...

Buttons

The joystick buttons and what command each will trigger.

buttons:
  - button:
      org.usfirst.frc.team449.robot.oi.buttons.SimpleButton:
        '@id': button1
        joystick:
          org.usfirst.frc.team449.robot.jacksonWrappers.MappedJoystick:
            '@id': driverGamepad
            port: 1
        buttonNumber: 1
    command:
      org.usfirst.frc.team449.robot...SomeCommand1:
        '@id': command1
        ...
    action: WHEN_PRESSED
  - button:
      org.usfirst.frc.team449.robot.oi.buttons.SimpleButton:
        '@id': button2
        joystick:
          org.usfirst.frc.team449.robot.jacksonWrappers.MappedJoystick:
            driverGamepad
        buttonNumber: 2
    command:
      org.usfirst.frc.team449.robot...SomeCommand2:
        '@id': command2
        ...
    action: WHEN_RELEASED
  ...

To define a button, first you need to define the joystick it belongs to. Each joystick is defined by the USB port it belongs to. You can verify the USB port number of a plugged-in joystick by looking at the USB tab of FRC Driver Station. From there, you'll have to determine the button number of the button on Driver Station as well by pressing the button and counting from top to bottom which rectangle lit up. Be careful, as buttons are 1-indexed.

You also get to pick how the command will activate relative to the button: WHEN_PRESSED, WHILE_HELD, WHEN_RELEASED, TOGGLE_WHEN_PRESSED, or CANCEL_WHEN_PRESSED.

Auto startup command

Simply the command that runs when auto starts.

autoStartupCommand:
  org.usfirst.frc.team449.robot...SomeCommand:
    '@id': autoStartupCommand
    ...

Updater

The updater updates any objects which are (i.e. implement) Updatable. These are objects which contain values that change over time, like a joystick throttle or a gyroscope.

updater:
  org.usfirst.frc.team449.robot.other.Updater:
    '@id': updater
    updatables:
      - org.usfirst.frc.team449.robot...SomeClass1: someObject1
      - org.usfirst.frc.team449.robot...SomeClass2: someObject2
      ...

Generally these objects have already been defined earlier in the map, so they'll just be referenced by their IDs here.

Example

See the map for our 2019 robot for an example.