Joint Tracker Quickstart

Use Joint Tracker to identify joint-level dynamics and compute a compensated joint command before sending the command to the robot.

Step 1: Setup the SDK

Go over the First Steps from Get Started to generate your API token and robot ID and install the Reforge Robotics SDK.

You will need:

• The robot IP address.
• The Reforge API token.
• The Reforge robot ID.
• The robot SDK token, if the robot manufacturer requires one.
• The local PC IP address, if the robot SDK requires an explicit local address.

Step 2: Calibrate and Identify the Joint Tracker Model

From the repository root, run calibration with automatic cloud identification:

bash
python3 -m robot.run calibrate \
  <ROBOT_IP> \
  --type joint_tracker \
  --local_ip <LOCAL_IP> \
  --sdk_token <ROBOT_SDK_TOKEN> \
  --robot_id <REFORGE_ROBOT_ID> \
  --freq 250 \
  --identify <REFORGE_API_TOKEN>

The CLI name for the Joint Tracker calibration workflow is joint_tracker. The --identify argument is required for this workflow to generate the controller models using the Reforge Cloud API.

Calibration data is stored under src/robot/data/ and downloads the identified joint-controller model bundle into src/robot/models/current/joint_tracker.

For a full description of the safety setup, calibration command, and identification output, see Calibration and Identification.

Step 3: Use the Joint Tracker During Control

Load the model from src/robot/models/current/joint_tracker, compensate the desired joint trajectory, and send the compensated command to the robot SDK:

python
import numpy as np
import robot_sdk  # Replace with the SDK package for the robot you are using.
from reforge_core.control.joint_tracker import JointTrackerInterface

sample_time_s = 0.004
model_directory = "src/robot/models/current/joint_tracker"
num_joints = 6

initializing_JTC = JointTrackerInterface(
    sample_time=sample_time_s,
    num_joints=num_joints,
    model_directory=model_directory,
    num_axes=6,
)

# `desired_trajectory_rad` is the desired joint position command [N, num_joints].
desired_trajectory_rad = np.asarray(robot_sdk.get_planned_joint_trajectory())
time_vector_s = list(np.arange(desired_trajectory_rad.shape[0]) * sample_time_s)

JTC_offline_mode = initializing_JTC.process_trajectory(
    command=desired_trajectory_rad,
    time_vector=time_vector_s,
)

robot_sdk.send_joint_trajectory(
    positions=JTC_offline_mode.positions,
    velocities=JTC_offline_mode.velocities,
    accelerations=JTC_offline_mode.accelerations,
    sample_time=sample_time_s,
)

This quickstart shows the full known-trajectory path. For controller inputs and appendable planner streams, see Control.