Calibrate Servo

Fine-tune servo motor positions, limits, and mechanical center points.

Pro Tip

Always leave a 5-10° safety margin from mechanical limits. Servos that hit hard stops generate high current draw and can damage the motor, gears, or connected structure.

Why calibrate?

Servos need calibration because:

• Mechanical tolerances - Each servo is slightly different
• Mounting offsets - Physical installation affects center point
• Safety limits - Prevent damage from over-rotation
• Accurate control - Ensure 90° actually means 90°

Prerequisites

• Servo added to Agent (see Add Actuator)
• Agent running with controller connected
• Physical access to the robot

Step 1: Enter calibration mode

On the Agent:

1. Open ☰ Menu → Settings
2. Go to Hardware → Actuators
3. Select the servo to calibrate
4. Tap [Calibrate]

Step 2: Find mechanical center

First, establish the true center position:

Finding true center

1. Move slider until the physical arm is at its center position
2. For robot arms: usually perpendicular to body
3. For pan/tilt: usually straight ahead
4. For continuous rotation servos: where motor stops

Step 3: Set minimum limit

Find the safe minimum position:

Setting safe minimum

1. Slowly decrease PWM value
2. Watch for mechanical limits (collision, strain)
3. Stop before hitting hard limits
4. Leave ~5° margin for safety

Step 4: Set maximum limit

Find the safe maximum position:

Step 5: Verify range

Test the full range of motion:

Step 6: Set angle mapping

Map PWM values to logical angles:

Common angle mappings

Calibration summary

After calibration:

Calibrating multiple servos

Sequential calibration

Calibrate each servo individually for precision:

1. Start with base/root joints
2. Move outward to end effectors
3. Lock calibrated joints during later calibration

Calibration order for robot arm

Trim adjustment

For minor adjustments after initial calibration:

1. Open actuator settings
2. Tap [Trim]
3. Adjust the center offset

Troubleshooting calibration

Servo won't move during calibration

1. Power issue - Check power supply
2. Connection - Verify controller connection
3. Pin conflict - Check no other software uses the pin

Servo moves erratically

1. Power supply - Use dedicated servo power
2. Ground loop - Common ground between controller and servo power
3. PWM frequency - Standard servos need 50Hz

Center doesn't match physical center

1. Servo horn offset - Remove and reattach horn at center
2. Gear slippage - Check for worn splines
3. Use trim - For minor misalignment

Range seems limited

1. PWM limits - Some servos need 400-2600µs
2. Mechanical binding - Check for obstructions
3. Servo specification - Some servos are <180°

Calibration data storage

Calibration is saved in:

~/.local/share/OctoMY™/OctoMY Agent/<personality>/hardware.json

Example calibration data:

{
  "actuators": [
    {
      "name": "Right Arm Shoulder",
      "type": "servo",
      "pin": 3,
      "calibration": {
        "minPwm": 600,
        "maxPwm": 2400,
        "centerPwm": 1500,
        "minAngle": 0,
        "maxAngle": 180,
        "trim": 3,
        "inverted": false
      }
    }
  ]
}

Backup and restore

Export calibration

# Copy calibration to backup
cp ~/.local/share/OctoMY™/OctoMY\ Agent/MyRobot/hardware.json \
   ~/octomy-calibration-backup.json

Restore calibration

# Restore from backup
cp ~/octomy-calibration-backup.json \
   ~/.local/share/OctoMY™/OctoMY\ Agent/MyRobot/hardware.json

Transfer to another robot

Same model robots can share calibration:

# On source robot
scp hardware.json user@target:~/

# On target robot
cp ~/hardware.json ~/.local/share/OctoMY™/OctoMY\ Agent/NewRobot/