Controller files and motor profiles

Result: prepare a complete configuration for your arm. The controller file selects ports, motors and workflow; a profile sets one motor’s control parameters. These files do not replace encoder calibration or saved travel limits.

Create local files

For named-pose replay, start with the example:

cp tools/poses/replay.example.json tools/poses/controller.local.json
cp host/arm-control/profile.example.json tools/poses/motor-1.local.json

Copy-Item tools/poses/replay.example.json tools/poses/controller.local.json
Copy-Item host/arm-control/profile.example.json tools/poses/motor-1.local.json

Edit the local copies. The example controller.local.json contains only motor 1. Add all recorded IDs for an arm. Create separate motor-2.local.json, motor-3.local.json and other profiles, each reviewed for its joint.

The six-motor structure below illustrates the format, not universally safe settings. Replace /dev/ttyUSB0 with the actual port, such as COM3 on Windows. A terminal’s SERVO_PORT variable is not automatically substituted into JSON.

{
  "followerPort": "/dev/ttyUSB0",
  "baudRate": 1000000,
  "maxAgeMs": 100,
  "acceleration": 1000,
  "rampTimeMs": 50,
  "profiles": {
    "1": "motor-1.local.json",
    "2": "motor-2.local.json",
    "3": "motor-3.local.json",
    "4": "motor-4.local.json",
    "5": "motor-5.local.json",
    "6": "motor-6.local.json"
  },
  "replay": {
    "speed": 500,
    "holdMs": 1000,
    "repeat": 1,
    "moveTimeoutMs": 30000,
    "toleranceCounts": 10
  }
}

Save this JSON as tools/poses/controller.local.json, with motor-1.local.json through motor-6.local.json beside it. For different IDs, update profile keys, pose recordings and connected devices consistently.

Profile settings

The complete source example is:

{
  "kpQ8": 256,
  "kdQ8": 32,
  "kiQ8": 0,
  "integralLimit": 0,
  "effortLimit": 100,
  "velocityLimit": 500,
  "velocityFilterQ8": 64,
  "gravitySlewEffortPerS": 1000,
  "velocityFeedforward": {
    "positiveGainQ8": 0,
    "negativeGainQ8": 0,
    "effortLimit": 0
  }
}

Shared acceleration and rampTimeMs belong to the controller file. A motor profile can override them with accelerationLimit and rampTimeMs. See the configuration register for ranges and relationships.

Paths and IDs

• Profile paths and gravityModel are relative to the controller file, not the working directory.
• A tuning plan’s config path is relative to the plan file.
• Named poses provide motor IDs; that replay does not require joints.
• Tuning and profile application require joints: [{"followerId": 1}, …] covering every controlled motor.
• Live teleoperation and session replay require leaderId, followerId and mapping.

Check paths when moving an example between directories. An omitted joints array is intentional in the named-pose replay example.

Applying settings

Profiles are written to Extension RAM and must be reapplied after reset. EEPROM calibration and travel limits are separate. Replay applies its configuration automatically. A changed profile briefly disables that motor; fresh startup can release all configured motors.

The supplied host/arm-control/profiles/so101/ and so102/ settings come from particular upright arms with empty grippers. The SO-101 profile retains unresolved M1 oscillation and slower M2 excursions; the fast SO-102 profile still needs hardware validation. They are not universal first-run defaults.

Check: valid JSON, existing relative files, one profile per motor and settings reviewed for the mechanism. Then perform replay preview. A valid file does not establish safe hardware behavior.

Documentation home · Source revision: a995f77. Extension 9.0.