Creating Schemas

​

Configs

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

Every config has a history of config schemas and a history of concrete configs deployed to robots. Below are the config schemas for the Mobility config.

​

Config Schemas

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

Config schemas live in a git repository (preferably in the same repository as the code consuming the config to minimize versioning errors between code and configurations).

As an example, let’s say our application has the following directory structure.

src/...
configs/
├── mobility.yaml
└── ...
schemas/
├── mobility.schema.yaml
└── ...

mobility.schema.yaml specifies the possible values for the mobility.yaml concrete config. On the other hand, mobility.yaml defines actual concrete config values.

$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

However, concrete configs defined in a git repository are for development use only. In production, concrete configs 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.yaml supplies concrete config values via the local file system for quick iteration. mobility.yaml is never uploaded to the cloud or deployed to production robots.

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

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

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

In production, the SDK retrieves the concrete config from the Miru agent running on the robot. The agent is a lightweight systemd service that provides the SDK with the concrete configs over a unix socket.

Below is a code snippet of the SDK in production.

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

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

More will be said about the Miru agent in coming sections. For now, the key takeaway is that the development workflow leverages the local file system for consuming concrete configs via the Miru SDK.

​

Pushing a Schema

Once ready to deploy new configurations to production, config schemas are uploaded to the cloud using the Miru CLI.

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

The CLI collects some git information to help version and track config schemas when viewing them in the Miru dashboard. Miru does not have access to your git repository. The git information is extracted from the 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, config schemas are available in the dashboard.