Quickstart

Use KineCal to collect kinematic calibration data, identify a calibrated robot model, and use that model for downstream robot control.

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.
A calibration kit and its socket_offset_mm.
Robot STL mesh files referenced correctly by the robot URDF.

If you built the calibration kit yourself, measure socket_offset_mm before running identification. See Make Your Kit for the hardware setup and socket-offset measurement.

Step 2: Check the Robot Files

Before running calibration, confirm that the robot mesh files exist in the repository and that the URDF <mesh> paths point to those local files for both visual and collision geometry.

For more detail, see Calibration and Identification - KineCal.

Step 3: Run KineCal Data Collection

From the repository root, activate the Python environment and run KineCal:

bash
cd <root folder of your repository>
source venv/bin/activate
python3 -m robot.run kinecal <YOUR_ROBOT_IP>

Example:

bash
python3 -m robot.run kinecal 192.168.1.231

Run this command once for each workspace region you want to calibrate. At the end of each run, the terminal prints the dataset folder path. Save each dataset path because you will pass it to identification.

Example dataset path:

text
/home/robot1234/controlbox/apps/reforge-interface/src/robot/data/kinecal/datacol/20260625_1742

Before recording each data point, make sure the end-effector is fully engaged with the sphere and the sphere is centered in the socket. Incorrect contact can negatively affect calibration.

If your robot has a flange button and you want to record poses with it instead of the keyboard, edit src/scripts/dev/kinecal/config.toml:

toml
# recording_method = "keyboard"
recording_method = "flange_button"

Step 4: Run Cloud Identification

After collecting a workspace dataset, run model identification with your Reforge API token, robot ID, and dataset folder:

bash
cd <path-to-reforge-interface>

python3 -m robot.run identify \
  <REFORGE_API_TOKEN> \
  <ROBOT_ID> \
  <DATA_FOLDER>

Use the KineCal dataset folder printed by the data-collection command. Run the command once per dataset you want to identify.

When identification finishes, results are extracted under:

text
src/robot/models/kinecal/<timestamp-results-id>/

The output includes a calibrated URDF and a performance report. If identification fails, check the report first; common issues include an incorrect dataset folder path or calibration data that was recorded with poor socket contact.

Step 5: Use the Calibrated Model

Use the calibrated kinematic model directly as a calibrated URDF or through the Reforge control module. The control page will contain the downstream controller example when that workflow is filled in.

For the full calibration workflow, see Calibration and Identification - KineCal. For controller usage, see KineCal Control.