Creating Schemas

​

Config Types

Applications have various configurations serving different purposes. Below are some config types for a fictional robot. Each config type is responsible for a particular aspect of the robot’s behavior.

Every config type has a history of config schemas as well as a history of config instances deployed to robots. Below are the config schemas for the Mobility config type.

​

Config Schemas

Miru requires the use of config schemas. These schemas validate config instances before deployment, preventing runtime application errors.

Config schemas live in a git repository for streamlined development and versioning with git.

As an example, say an application has the following directory structure.

src/...
instances/
├── mobility.instance.yaml
└── ...
schemas/
├── mobility.schema.yaml
└── ...

mobility.schema.yaml specifies the possible values for the mobility.instance.yaml config instance.

$schema: "https://json-schema.org/draft/2020-12/schema"
title: Mobility
type: object
properties:
  max_linear_speed_mps:
    type: number
    minimum: 0.1
    maximum: 5.0
    default: 1.2
  max_angular_speed_radps:
    type: number
    minimum: 0.1
    maximum: 3.0
    default: 1.0
  obstacle_avoidance_enabled:
    type: boolean
    default: true
  navigation_mode:
    type: string
    enum: [conservative, balanced, aggressive]
    default: balanced
  telemetry:
    type: object
    properties:
      upload_interval_sec:
        type: integer
        minimum: 10
        maximum: 300
        default: 60
      heartbeat_interval_sec:
        type: integer
        minimum: 1
        maximum: 60
        default: 10
    required:
      - upload_interval_sec
      - heartbeat_interval_sec
required:
  - max_linear_speed_mps
  - max_angular_speed_radps
  - obstacle_avoidance_enabled
  - navigation_mode
  - telemetry

​

Miru SDK

Config instances defined in a git repository are for development use only. In production, config instances are defined in the cloud and retrieved from the Miru Agent running on the robot (more on this later).

In development, quickly defining and editing configurations is essential. mobility.instance.yaml supplies config instance values via the local file system for quick iteration. mobility.instance.yaml is never uploaded to the cloud or deployed to production robots.

Miru provides an SDK to support both development and production scenarios. Below is a code snippet of the SDK in development.

// instantiate the config instance from the file system
auto config_instance = miru::configs::ConfigInstance::from_file(
    "/path/to/instances/mobility.instance.yaml",
    "/path/to/schemas/mobility.schema.yaml"
);

// retrieve a parameter from the config instance
std::string config_type_slug = "mobility";
std::string parameter_name = config_type_slug + "." + "an_integer";
auto parameter = miru::query::get_param(config_instance, parameter_name);
int value = parameter.as_int();

In production, the SDK retrieves config instances from the Miru agent running on the robot. The agent is a lightweight systemd service that serves config instances to the SDK over a Unix socket.

Below is a code snippet of the SDK in production.

// instantiate the config instance from the agent
auto config_instance = miru::configs::ConfigInstance::from_agent(
    "/path/to/schemas/mobility.schema.yaml"
);

// retrieve a parameter from the config instance
std::string config_type_slug = "mobility";
std::string parameter_name = config_type_slug + "." + "an_integer";
auto parameter = miru::query::get_param(config_instance, parameter_name);
int value = parameter.as_int();

More will be said about the Miru agent in the coming sections. The key takeaway is that the development workflow leverages the local file system to consume config instances, while the production workflow leverages the Miru agent.

​

Pushing a Schema

When ready to deploy new config instances to production, config schemas are uploaded to Miru using the Miru CLI.

miru schema push ./path/to/schemas/mobility.schema.yaml

The CLI collects some git information to aid versioning and tracking config schemas from the Miru dashboard. Miru does not have access to your git repository; git information is extracted from the local git repository where the CLI is run.

📦 Attempting to push 1 config schemas...

🏁 Successfully pushed schema for mobility config
    commit: a8340d496013f4e33bb5d59fbebf057a80c44dbf
    branch: main
    origin: https://github.com/miruml/getting-started.git
    git file path: schemas/mobility.schema.yaml


✅ Successfully uploaded 1 config schemas

After executing miru schema push, the config schemas are available in the dashboard.