Overview

This page defines the key terminology used in Miru and should be used as a quick reference. To quickly understand how Miru works we recommend you read through the core concepts and refer back to this page as needed.

Concrete Config

A concrete config is a particular instantiation of parameters used to alter the behavior of your code.

You’re probably storing concrete configs as JSON or YAML files (or potentially in a database somewhere), which your application parses into a structured format for consumption. The following YAML file defines a concrete config for controlling a robot’s motion.

max_linear_speed_mps: 1.2
max_angular_speed_radps: 1.0
obstacle_avoidance_enabled: true
navigation_mode: balanced
telemetry:
  upload_interval_sec: 60
  heartbeat_interval_sec: 10

Config Schema

A config schema defines the constraints on a concrete config.

Miru uses JSON Schema, a popular open-source configuration language for defining the valid fields, types, and values in a JSON or YAML file. Here is an example of a config schema written in JSON Schema.

$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 only supports JSON Schema, which is widely used and has code generation for many languages. However, support for other configuration languages is coming soon. Here are some popular ones.

Config

A config represents the parameters responsible for configuring a particular aspect of your application through time.

For instance, your application may have a Mobility config that controls the motion of your robot. The Mobility config goes through many iterations—parameters are added or deprecated (creating new config schemas for the config) and given different values (creating new concrete configs for the config).

The Mobility config is not a particular instantiation of parameters or a particular specification of constraints. Instead, it is the parameters responsible for configuring the motion of your robot at any point in your application’s lifecycle.

Client

A client is the machine to which concrete configs are deployed. This could be an NVIDIA Jetson, Raspberry Pi, industrial PC, or any other machine running your application.

Tag Types & Tags

A tag type is a group of related tags, while a tag is an instantiation of a tag type. Examples illustrate this best.

A hardware tag type could be used to group clients based on their hardware:

  • Raspberry Pi 4 Model B
  • NVIDIA Jetson Orin Nano
  • NVIDIA Jetson Orin AGX

An environment tag type could group clients based on their stage of development:

  • Dev
  • QA
  • Beta
  • Stable

An accelerometer tag type could define a tag for each accelerometer:

  • Accelerometer 1
  • Accelerometer 2
  • Accelerometer 3
  • Accelerometer 4

A client’s accelerometer tag would reflect the specific accelerometer in use by the client, which may change as accelerometers are replaced or upgraded.

As the name suggests, clients can be “tagged” with a particular tag.

Metadata

Metadata is data stored about a particular tag.

Maybe robots support certain features based on their hardware. This information can be stored as metadata for each tag in the hardware tag type.

For example, let’s say robots running the NVIDIA Jetson Orin Nano can support the jump and spin features but not the backflip feature. This information can be stored as metadata for the NVIDIA Jetson Orin Nano tag.

Metadata Schema

A metadata schema defines the constraints on the metadata.

Metadata schemas are written in a configuration language like JSON Schema. The following JSON Schema is a plausible metadata schema for the robot_id metadata we showed above.

Miru requires every tag type to have a metadata schema describing what constitutes valid metadata for any tag of that tag type. For instance, the hardware tag type may have the following metadata schema to specify the features (jump, spin, backflip) supported by a given hardware.

Any tags of the hardware tag type can only store metadata that adheres to the hardware metadata schema.

Metadata schemas look eerily similar to config schemas but serve a different purpose. A metadata schema does not describe or enforce any constraints on the concrete configs that are deployed to clients. Metadata schemas only describe what constitutes valid metadata, effectively structuring the metadata stored for clients and tags.

Override

An override references tag metadata that “overrides” the default configuration values of the config schema. Here is a hardware override example.

The default values in the config schema are shown on the left. On the right is the hardware override, which references the supports_jump, supports_spin, and supports_backflip fields in the metadata schema for the hardware tag type.

Overrides are completely named and defined by you. An override does not need to specify all the fields in a config schema, only a subset of the config schema fields. However, it cannot specify fields not present in the config schema.

Overrides can only be evaluated given a particular tag. For instance, the features.jump, features.spin, and features.backflip fields in the hardware override reference the supports_jump, supports_spin, and supports_backflip fields in the metadata schema for the hardware tag type.

Given the NVIDIA Jetson Orin Nano tag, the hardware override would use

  • features.jump: true
  • features.spin: true
  • features.backflip: false

since the NVIDIA Jetson Orin Nano tag has

  • supports_jump: true
  • supports_spin: true
  • supports_backflip: false

This would override the default values in the config schema, changing features.spin from false to true.

Overrides are hierarchically evaluated to determine a concrete config for a client. The client’s tags determine the specific values referenced by overrides.

Combining tags with overrides provides a flexible method to evaluate configuration data unique to each client that’s formatted according to a given config schema.