(4) Map

Overview

Robot code requires many constants (port numbers, PID values, field distances, etc.). For organizational purposes, 449 code stores all changeable parameters in a format that preserves the module structure.

All changeable parameters in robot code are to be held in a JSON configuration file named cfg.json. Changeable parameters include port numbers, PID values, field distances, and more. The robot code accesses the configuration file at runtime.

Explanation

When code is deployed, two artifacts are sent over to the RoboRIO: FRCUserProgram.jar and cfg.json.

When FRCUserProgram.jar is run, the modules' map classes parse the configuration file in their constructors to assign values to their fields. The modules' map classes expect the configuration file structure to follow the module structure and the module map classes' field structure as shown in examples below. If the configuration file is not in the format expected by the map's parser, FRCUserProgram.jar will crash.

Example 1

Module Structure:

 └── robot                     
   ├── mechanism (map = MechanismMap.java)
   │   ├── arm (map = ArmMap.java)
   │   └── leg (map = LegMap.java)
   ├── drive (map = DriveMap.java)
   │   └── bipedal (map = BipedalMap.java)
   └── oi (map = OIMap.java)

JSON Configuration File (cfg.json):

{
    "MechanismMap": {
        "ArmMap": {},
        "LegMap": {}
    },
    "DriveMap": {
        "BipedalMap": {}
    },
    "OIMap": {}
}

Example 2

This shows the top level structure of the map and its components, however the map is obviously incomplete without the actual constants to be stored. A real map holds its constants in "components" blocks. Below is an example of a configuration file with example values and one of the module map classes.

Map File (ArmMap.java):

public class ArmMap extends MechanismMap {
    public int armConstant1;
    public int armConstant2;

    public ArmMap(JSONObject json) {
        super(json);
    }
}

JSON Configuration File (cfg.json):

{
    "components": {},
    "MechanismMap": {
        "ArmMap": {
            "components": {
                "armConstant1": 1,
                "armConstant2": 2
            }
        },
        "LegMap": { ... }
        },
        "components": {}
    },
    "DriveMap": { ... },
    "OIMap": { ... }
}

Example 3

The previous example shows how to add numbers and strings to the configuration file. One can also add more complex objects with static local inner classes in the map files as shown below. Note that the objects read into the static local inner classes do not contain "components" objects.

Map File (ArmMap.java):

public class ArmMap extends MechanismMap {
    public int armConstant1;
    public int armConstant2;

    public Motor motor1;
    public Motor motor2;
    public Motor motor3;

    public ArmMap(JSONObject json) {
        super(json);
    }

    public static class Motor() {
        public int motorPort;
        public boolean inverted;
        public Motor(JSONObject json, String path, Class enclosing) {
            super(json, path, enclosing);
        }
    }
}

JSON Configuration File (cfg.json)

{
    "components": {},
    "MechanismMap": {
        "ArmMap": {
            "components": {
                "armConstant1": 1,
                "armConstant2": 2
                "motor1": {
                    "motorPort": 1,
                    "inverted": false
                }
                "motor2": {
                    "motorPort": 2,
                    "inverted": false
                }
                "motor3": {
                    "motorPort": 3,
                    "inverted": false
                }
            }
        },
        "LegMap": { ... }
        },
        "components": {}
    },
    "DriveMap": { ... },
    "OIMap": { ... }
    }
}