This page is a complete reference for every key in every configuration file used by a raccoon/libstp project. Configuration is split across several YAML files that are assembled by raccoon’s include-aware loader at build time. All paths are relative to the project root.

File layout and include graph

raccoon.project.yml
  ├── config/robot.yml         (robot: key)
  ├── config/missions.yml      (missions: key)
  ├── config/hardware.yml      (definitions: key)
  │   ├── config/motors.yml    (!include-merge)
  │   └── config/servos.yml    (!include-merge)
  └── config/connection.yml    (connection: key)

raccoon.project.yml is the root file. It uses !include to delegate each top-level section to the files listed above. config/hardware.yml in turn uses !include-merge for motors and servos, which means all motor and servo entries are promoted to the same level as the sensor definitions.

raccoon.project.yml

The root project descriptor. Only a handful of keys live here directly; the rest are delegated.

config/robot.yml

Top-level robot configuration. Maps directly to the generated Robot class in src/hardware/robot.py.

shutdown_in

Number of seconds after program start after which GenericRobot will automatically shut down the running mission sequence. Prevents the robot from running indefinitely if something goes wrong. Set to 0 to disable.

drive

Container for the drive subsystem. All motion steps read their kinematics and velocity control from here.

drive.kinematics

Specifies the kinematic model that maps chassis velocities to per-wheel commands.

The type value is case-insensitive. DifferentialKinematics is instantiated as DifferentialKinematics(left_motor, right_motor, wheelbase, wheel_radius) and MecanumKinematics as MecanumKinematics(front_left_motor, front_right_motor, back_left_motor, back_right_motor, wheelbase, track_width, wheel_radius).

Example — differential drive:

drive:
  kinematics:
    type: differential
    wheel_radius: 0.03
    wheelbase: 0.16
    left_motor: left_motor
    right_motor: right_motor

drive.vel_config

Per-axis chassis velocity control configuration. Each axis has a PID controller and a feedforward term that together compute the motor command voltage.

The three axes are:

• vx — forward/backward linear velocity (m/s)
• vy — lateral (strafe) velocity (m/s); only relevant for mecanum
• wz — angular (yaw) velocity (rad/s)

Each axis block has the same structure:

vel_config:
  vx:
    pid:
      kp: 0.0
      ki: 0.0
      kd: 0.0
    ff:
      kS: 0.0
      kV: 1.0
      kA: 0.0
  vy:
    pid: { kp: 0.0, ki: 0.0, kd: 0.0 }
    ff:  { kS: 0.0, kV: 1.0, kA: 0.0 }
  wz:
    pid: { kp: 0.0, ki: 0.0, kd: 0.0 }
    ff:  { kS: 0.0, kV: 1.0, kA: 0.0 }

pid sub-keys (maps to PidGains):

ff sub-keys (maps to Feedforward):

The vel_config is translated into a ChassisVelocityControlConfig struct at code-generation time.

odometry

Selects the odometry model used to estimate the robot’s pose (position + heading) during autonomous motion.

Can be specified in two forms:

Short form (type name only):

odometry: FusedOdometry

Long form with configuration:

odometry:
  type: FusedOdometry
  config:
    bemf_trust: 1.0

Supported type values (case-insensitive): FusedOdometry, fused, ImuOdometry, imu.

When type is FusedOdometry, the optional config sub-block maps to FusedOdometryConfig:

motion_pid

Unified configuration for the position/heading PID controllers used by all drive-based motion steps (Drive, Turn, DriveAngle, etc.). Required.

This entire block maps to the UnifiedMotionPidConfig C++ struct.

Distance PID (motion_pid.distance)

Controls convergence toward a position target (linear or 2-D).

Heading PID (motion_pid.heading)

Controls convergence toward an angular target.

Same sub-keys as distance (kp, ki, kd, integral_max, integral_deadband, derivative_lpf_alpha, output_min, output_max).

Scaffold defaults: kp: 3.0, all others matching the distance block.

Velocity feedforward

Convergence tolerances

Linear saturation handling

When the drive command saturates the actuators, the controller de-rates its output to prevent integral windup.

Heading-specific saturation handling

Motion profile constraints

These three sub-blocks are populated automatically by raccoon calibrate characterize_drive and should not be edited manually. They are commented out in the scaffold until characterization is run.

motion_pid:
  linear:
    max_velocity: 0.0   # m/s
    acceleration: 0.0   # m/s²
    deceleration: 0.0   # m/s²
  lateral:
    max_velocity: 0.0
    acceleration: 0.0
    deceleration: 0.0
  angular:
    max_velocity: 0.0   # rad/s
    acceleration: 0.0   # rad/s²
    deceleration: 0.0   # rad/s²

Each sub-block maps to AxisConstraints:

When all three values in a block are 0.0 the profiler for that axis is disabled and the PID controller drives directly without trapezoidal profiling.

physical

Geometric description of the robot body. Used to compute sensor positions relative to the robot center and to populate _wheel_positions in the generated Robot class for collision and pose reasoning.

Sensor entry sub-keys:

config/hardware.yml

Defines all hardware objects. Every key (other than _motors and _servos) maps to one attribute on the generated Defs class. Keys must be valid Python identifiers.

hardware.yml also contains the lines:

_motors: !include-merge 'motors.yml'
_servos: !include-merge 'servos.yml'

These merge all motor and servo definitions from the separate files directly into the definitions namespace.

Required entry: button

Every project must define a hardware entry named button of type DigitalSensor. The calibration and wait-for-light steps use button as the confirmation input. The code generator will reject a project that lacks this entry.

button:
  type: DigitalSensor
  port: 10

Built-in entry: imu

An IMU entry named imu is always generated, even if not listed in hardware.yml. If an imu key is present, any extra parameters in it are forwarded to the Imu() constructor. If absent, imu = Imu() is emitted with no arguments.

imu:
  type: IMU

Hardware type: DigitalSensor

Maps to libstp.hal.DigitalSensor.

Hardware type: AnalogSensor

Maps to libstp.hal.AnalogSensor.

All AnalogSensor instances are also collected into the Defs.analog_sensors list, which is used by the analog-channel calibration steps.

Hardware type: IRSensor

Maps to libstp.sensor_ir.IRSensor (subclass of AnalogSensor).

Hardware type: SensorGroup

Maps to libstp.step.motion.sensor_group.SensorGroup. Binds a pair of IR sensors together with shared defaults for threshold, speed, and line-follow PID. At least one of left or right is required.

Example:

front:
  type: SensorGroup
  left: front_left_ir_sensor
  right: front_right_ir_sensor
  threshold: 0.6
  follow_kp: 0.6

config/motors.yml

Defines drive and auxiliary motor objects. All entries are merged into the definitions namespace by hardware.yml. Each key must be a valid Python identifier and must match the name referenced in drive.kinematics.

Motor entry

Maps to libstp.hal.Motor.

calibration sub-keys

The ff and pid sub-keys within calibration are nested mappings. The code generator uses docstring introspection to detect that MotorCalibration accepts ff and pid as nested Feedforward and PidGains objects respectively, so the YAML nesting is preserved correctly.

Minimal scaffold entry:

left_motor:
  type: Motor
  port: 0
  inverted: false
  calibration:
    ticks_to_rad: 0.00002
    vel_lpf_alpha: 1.0

After motor calibration:

left_motor:
  type: Motor
  port: 0
  inverted: false
  calibration:
    ticks_to_rad: 0.00436
    vel_lpf_alpha: 0.8
    bemf_scale: 0.000312
    bemf_offset: -0.0041
    ticks_per_revolution: 1440.0
    ff:
      kS: 0.042
      kV: 0.981
      kA: 0.003
    pid:
      kp: 0.12
      ki: 0.0
      kd: 0.0

config/servos.yml

Defines servo hardware objects with optional named positions. All entries are merged into the definitions namespace by hardware.yml.

Servo entry

Maps to libstp.hal.Servo wrapped in libstp.step.servo.preset.ServoPreset when positions is specified.

The port is the only argument passed to the underlying Servo constructor. The positions and offset keys are consumed by ServoPreset at the wrapper level and are not forwarded to the hardware object.

Example:

arm_servo:
  type: Servo
  port: 0
  offset: 0
  positions:
    up: 30
    down: 160

claw_servo:
  type: Servo
  port: 1
  positions:
    open: 30
    closed: 135

Generated code (simplified):

class Defs:
    arm_servo = ServoPreset(Servo(0), positions={'up': 30, 'down': 160}, offset=0)
    claw_servo = ServoPreset(Servo(1), positions={'open': 30, 'closed': 135})

Usage in a mission:

seq([
    Defs.arm_servo.up(),
    Defs.claw_servo.open(),
    Defs.claw_servo.closed(speed=120),   # eased motion at 120 deg/s
])

config/missions.yml

An ordered YAML list of missions to run. The code generator uses this to produce the missions, setup_mission, and shutdown_mission attributes on the Robot class.

Entry formats

Normal mission (runs in sequence with others):

- MyMission

Typed mission (dict with a single key):

- SetupMission: setup
- AnotherMission: normal
- TeardownMission: shutdown

The value is one of three strings:

If a bare string entry (without a type key) is used, it is treated as normal.

Each mission class name is converted to snake_case to derive the source filename. DriveToBoxMission → src/missions/drive_to_box_mission.py.

The scaffold generates:

- SetupMission: setup

config/connection.yml

Controls how raccoon connects to the robot over the network and copies files via SSH/SFTP.

Calibration-populated keys summary

Several keys are written back to config files automatically by raccoon calibration commands. These should not be edited by hand unless you know the exact values.