Overview
A calibration is a result a device reports to Miru after calibrating one of its components, such as the pose of a robot arm or the intrinsics of a RealSense D435. Miru allows on-device applications to report calibrations using the endpoint in the Device API. When a calibration is reported, the agent saves it on the device and immediately returns a200 response, regardless of whether the device is online or offline. Once a device is online, the agent uploads the calibration to Miru.
Prerequisites
To follow this guide, you must have a device installed with a Miru Agent v0.12.0 or later. To provision a device, see the Provision a device guide.Components
A component is a kind of hardware that devices report calibrations for, such as an arm, a camera, or a Robotiq 2F-85. A calibration names its component with a slug, such askuka-arm, realsense-d435, or robotiq-2f-85.
When a calibration is reported, Miru checks if its component exists and creates it if it doesn’t.
Roles
Oftentimes devices have multiple units of the same component, such as multiple arms. Roles distinguish components that are identical except for their purpose in the overall system. For example, a device with two arms might distinguish them asleft and right.
Aspects
Separately, some components have multiple calibrations. An aspect distinguishes parts of a unit that are calibrated separately. For example, a camera might report bothintrinsics and extrinsics. These calibrations belong to the same unit, but are used for different purposes within the unit itself.
Both aspects and roles are optional. A device with one arm, calibrated one way, reports only the component.
Each device keeps a separate history for a given component, role, and aspect. Miru creates a role or aspect the first time a calibration reports it.
Send a calibration
Calibrations are sent to the Miru Agent via the endpoint in the Device API. We recommend using the official Python Device SDK to report calibrations. You can also generate your own client using the Device API’s OpenAPI specification, located in the Device API Changelog. The following parameters are required.Required parameters
enum
required
The file format of
content.data: json, yaml, jsonc, xml or text.string
required
The calibration result, usually the full text of the calibration file. At most 1 MiB.
File formatting
The Miru dashboard shows thecontent.data string exactly as it was uploaded. Pretty-print that string in the request, including indentation and line breaks, the way you want it to appear.
Optional parameters
In addition to the required parameters, you can also set the following optional parameters:string
The serial number of the calibrated unit. At most 255 characters.Example:
SN-1234Response
The agent saves the calibration on the device, then responds with200 OK, a new report ID and the time it received the calibration:
200.
The agent holds up to 1,000 calibrations that haven’t uploaded yet. When it’s holding 1,000, it saves nothing and responds with 507 Insufficient Storage and the error code calibration_buffer_full. Retry once the device is back online and the agent has uploaded some of them. A calibration that still hasn’t uploaded 90 days after its reported_at is dropped.