Quickstart

Use KineCal to collect kinematic calibration data, identify a calibrated robot model, and use that model for downstream robot control. Check the video of KineCal working on 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.
A calibration kit and its socket_offset_mm.
Robot STL mesh files referenced correctly by the robot URDF if you use semi-automated collection.

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

If you plan to use semi-automated collection, 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. Manual collection skips collision planning and does not require the mesh files.

For more detail, see Calibration and Identification - KineCal.

Step 3: Run KineCal Data Collection

Choose either the semi-automated or manual collection workflow for each workspace region you want to calibrate.

Semi-automated collection

The semi-automated workflow plans the ideal robot poses for each socket to maximize data quality. It then plans the motion to each pose slightly above the socket, then transitions the robot to teaching/hand-guided mode for the user to move the robot to make contact with the socket.

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

Manual collection

Use full-manual collection when you need to move the robot yourself in teaching/hand-guided mode. The SDK will not change robot modes, plan trajectories, or command robot motion.

bash
python3 -m robot.run kinecal <YOUR_ROBOT_IP> --manual

Before continuing, put the robot in teaching/hand-guided mode. For each socket, fully seat the sphere and capture the current pose with Enter or the flange button. Manual collection always starts with socket 1 active. Press s to switch between sockets at any time and d to finish the collection invocation. KineCal recommends at least 30 total samples per socket. If either socket has fewer samples, KineCal warns and asks you to press d again, but it does not prevent completion.

Resume or append to a collection

Every accepted sample is checkpointed. If collection is interrupted, continue using the existing dataset folder instead of starting over:

bash
# Resume an interrupted semi-automated collection
python3 -m robot.run kinecal <YOUR_ROBOT_IP> \
  --data-folder <EXISTING_DATASET_FOLDER>

# Continue with manual collection or append more manual samples
python3 -m robot.run kinecal <YOUR_ROBOT_IP> \
  --manual \
  --data-folder <EXISTING_DATASET_FOLDER>

An incomplete semi-automated collection resumes only its missing samples. Manual collection may follow either an incomplete or completed semi-automated collection, and manual samples accumulate across invocations. Once manual collection starts in a dataset, that dataset cannot return to semi-automated collection. A completed semi-automated collection also cannot be run again in semi-automated mode.

After collection

Run your chosen collection workflow once for each workspace region you want to calibrate. At the end of each run, the terminal prints the dataset folder path. Without --data-folder, KineCal creates a new timestamped folder. With --data-folder, it continues the selected folder. Save each completed dataset path because you will pass it to identification. Identification rejects an in-progress dataset until collection finishes successfully.

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/robot/config/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.