Create a release

To keep things simple, we’ve provided a getting-started repository that contains everything you need to create a release. Follow along with us by cloning the repository.

git clone https://github.com/mirurobotics/getting-started.git

Define the schemas

Releases are defined by the config schemas they contain. The getting-started repository contains two sets of schemas for each of the supported schema languages:

Empty schemas - regard all config instances as valid
Strict schemas - constrain the valid fields, types, and values for instances of the config type they belong to

For this tutorial, choose one of these schema sets to create your release with. If you’re unfamiliar with schema languages, we recommend starting with JSON Schema. If you don’t currently use a schema, we recommend starting with an empty schema and gradually adding constraints as needed.

JSON Schema
CUE

Empty Schemas

x-miru-config-type: "communication"
x-miru-instance-filepath: "/srv/miru/configs/communication.yaml"
$schema: "http://json-schema.org/draft/2020-12/schema"

Strict Schemas

x-miru-config-type: "communication"
x-miru-instance-filepath: "/srv/miru/configs/communication.yaml"
$schema: "http://json-schema.org/draft/2020-12/schema"
type: object
required:
    - control_loop_rate_hz
    - watchdog_timeout_ms
    - network
    - logging
    - error_handling
properties:
    control_loop_rate_hz:
    type: integer
    description: Control loop frequency in Hertz
    minimum: 1
    maximum: 1000  
    default: 50
    watchdog_timeout_ms:
    type: integer
    description: Watchdog timeout duration in milliseconds
    minimum: 100   
    maximum: 5000  
    default: 500
    network:
    type: object
    required:
        - max_latency_ms
        - connection_timeout_ms
        - reconnect_attempts
        - reconnect_interval_ms
        - heartbeat_interval_ms
    properties:
        max_latency_ms:
        type: integer
        description: Maximum acceptable network latency in milliseconds
        minimum: 10    
        maximum: 1000  
        default: 100
        connection_timeout_ms:
        type: integer
        description: Connection timeout duration in milliseconds
        minimum: 100    
        maximum: 10000  
        default: 2000
        reconnect_attempts:
        type: integer
        description: Number of reconnection attempts
        minimum: 1
        maximum: 10    
        default: 3
        reconnect_interval_ms:
        type: integer
        description: Interval between reconnection attempts in milliseconds
        minimum: 100    
        maximum: 5000   
        default: 1000
        heartbeat_interval_ms:
        type: integer
        description: Interval between heartbeat messages in milliseconds
        minimum: 50     
        maximum: 1000   
        default: 250
    logging:
    type: object
    required:
        - enable_packet_logging
        - log_level
        - max_log_size_mb
        - retain_logs_days
    properties:
        enable_packet_logging:
        type: boolean
        description: Enable or disable packet logging
        default: true
        log_level:
        type: string
        description: Logging level
        enum: ["debug", "info", "warn", "error"]
        default: "info"
        max_log_size_mb:
        type: integer
        description: Maximum log file size in megabytes
        minimum: 1
        maximum: 1024  
        default: 100
        retain_logs_days:
        type: integer
        description: Number of days to retain log files
        minimum: 1
        maximum: 90    
        default: 30
    error_handling:
    type: object
    required:
        - max_consecutive_failures
        - failure_timeout_ms
        - enable_auto_recovery
    properties:
        max_consecutive_failures:
        type: integer
        description: Maximum number of consecutive failures allowed
        minimum: 1
        maximum: 20    
        default: 5
        failure_timeout_ms:
        type: integer
        description: Timeout duration for failure handling in milliseconds
        minimum: 100    
        maximum: 30000  
        default: 5000
        enable_auto_recovery:
        type: boolean
        description: Enable or disable automatic recovery from failures
        default: true

Empty Schemas

@miru(config_type="communication",instance_filepath="/srv/miru/configs/communication.yaml")
{
	...
}

Strict Schemas

@miru(config_type="communication",instance_filepath="/srv/miru/configs/communication.yaml")
{
	control_loop_rate_hz: int & >=1 & <=1000 | *50
	watchdog_timeout_ms: int & >=100 & <=5000 | *500

	network: {
		max_latency_ms: int & >=10 & <=1000 | *100
		connection_timeout_ms: int & >=100 & <=10000 | *2000
		reconnect_attempts: int & >=1 & <=10 | *3
		reconnect_interval_ms: int & >=100 & <=5000 | *1000
		heartbeat_interval_ms: int & >=50 & <=1000 | *250
	}

	logging: {
		enable_packet_logging: bool | *true
		log_level: "debug" | "info" | "warn" | "error" | *"info"
		max_log_size_mb: int & >=1 & <=1024 | *100
		retain_logs_days: int & >=1 & <=90 | *30
	}

	error_handling: {
		max_consecutive_failures: int & >=1 & <=20 | *5
		failure_timeout_ms: int & >=100 & <=30000 | *5000
		enable_auto_recovery: bool | *true
	}
}

Schema annotations

Each of the above schema examples are annotated with the x-miru-config-type and x-miru-instance-filepath fields. These annotations are crucial metadata that Miru uses to process the schema and deploy config instances to the correct location on the device.

config type

required

The config type is a required annotation that identifies the config type to which a schema belongs. Below is the syntax for annotating a schema with a config type slug.

x-miru-config-type: "{config-type-slug}"

If the provided config type slug does not yet exist, it is automatically created. To edit a config type after creation, visit the config types documentation.Examples: mobility, communication, perception

instance file path

The instance file path is the absolute file system path where config instances for this schema are written on the device.

The Miru Agent ships with out-of-the-box access to /srv/miru. To deploy configurations to a custom directory, please visit the File Permissions page.

Instance file paths control the type of file that config instances are deployed as. Currently, JSON (.json) and YAML (.yaml, .yml) are supported.This annotation is optional and defaults to /srv/miru/configs/{config-type-slug}.json.

x-miru-instance-filepath: "/srv/miru/configs/{config-type-slug}.json"

Examples:

/srv/miru/configs/mobility.json
/home/myapp/configs/communication.yaml
/var/lib/myapp/configs/safety.yaml

Set up the CLI

Next, we’ll install the CLI—the primary method of creating releases in Miru. Creating releases via the CLI is a deliberate design choice. We believe a release’s schemas should live in a Git repository. This allows them to be versioned alongside the code that uses them and encourages better software development practices. While this tutorial covers creating releases on your local machine, the CLI can also be used to create releases in a CI pipeline. Install The CLI is only available on macOS and Linux. Windows is not supported.

macOS
Linux

Install via Homebrew.

brew install mirurobotics/cli/miru

If you are not seeing the latest CLI version, refresh Homebrew with brew update.

The CLI is distributed to Linux as a Debian package. Other package formats are not yet supported.We recommend using apt to install the CLI. However, you can manually install the Debian package by downloading it from GitHub and installing it with dpkg.

APT
Manual

Set up

Set up Miru’s apt repository.

# ensure the appropriate dependencies are installed
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# add Miru's signing key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://packages.mirurobotics.com/apt/miru.gpg -o /tmp/miru.gpg.armor
sudo gpg --dearmor -o /etc/apt/keyrings/miru-archive-keyring.gpg /tmp/miru.gpg.armor
rm /tmp/miru.gpg.armor
sudo chmod a+r /etc/apt/keyrings/miru-archive-keyring.gpg

# add the repository to your sources list
sudo tee /etc/apt/sources.list.d/miru.sources > /dev/null <<EOF
Types: deb
URIs: https://packages.mirurobotics.com/apt
Suites: stable
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/miru-archive-keyring.gpg
EOF

Install

After configuring the apt repository, install the CLI.

sudo apt-get update
sudo apt-get install miru-cli

Install a specific version with sudo apt-get install miru-cli=<version> (e.g. 0.9.1, 0.10.0, etc.).

Download

All Miru CLI releases are available as Debian packages on GitHub. You can find the latest release here.To download the CLI, drop down the Assets section for the desired release. The assets ending with the .deb extension are the Debian packages for the Miru CLI.

Find the architecture that matches your target machine’s architecture and download the package.For example, if your robot is an x86_64 machine, you’ll want to download the miru-cli_<version>_amd64.deb package. If your robot is an aarch64 machine, you’ll want to download the miru-cli_<version>_arm64.deb package.

Install

After downloading the package, install it using dpkg.

sudo dpkg -i <...>.deb

Login To log in, run the login command.

miru login

Retrieve your authentication token from the Secrets page.

You must be an user to retrieve an authentication token.

Paste the token into the CLI.

Please retrieve your authentication token from the following URL:
🔗 https://app.mirurobotics.com/settings/cli-token

🔑 Paste your authentication token: **********

Validating authentication token...
✅ Successfully logged in as Benjamin

Create a release

With the CLI setup, we are ready to create a release in Miru. Navigate to the root of the getting-started repository and create the release with a schema set of your choice.

JSON Schema
CUE

miru release create \
  --version "v1.0.0" \
  --schemas ./jsonschema/empty-schemas/

miru release create \
  --version "v1.0.0" \
  --schemas ./cue/empty-schemas/

Upon a successful creation, you’ll see a confirmation message similar to the following:

$ miru release create \
  --version v1.0.0 \
  --schemas ./{schema-language}/{schema-type}/

◐ Creating release v1.0.0

  ✓ Pushed git commit (new)
    1c7f7a8 · mirurobotics/getting-started

  ◐ Pushing schemas
    ✓ Mobility · SCH-D5nFP (new)
    ✓ Planning · SCH-37QAr (new)
    ✓ Communication · SCH-9WfCx (new)

✓ Created release v1.0.0

Git metadata is pulled from the local Git repository that the schemas are defined in.

To view the release in Miru, navigate to the releases page and click into the release.

Then select the overview tab at the top of the page to view the release’s details.

For a more comprehensive guide on creating releases, visit the create releases documentation. For a concise reference of the CLI command, visit the CLI Reference.

Getting started

Learn

Developers

Administration

Create a release

Define the schemas

Schema annotations

Set up the CLI

Create a release

Getting started

Learn

Developers

Administration

Documentation Index

​Define the schemas

​Schema annotations

​Set up the CLI

​Create a release

Define the schemas

Schema annotations

Set up the CLI

Create a release