Create a release

Define the schemas

Releases are defined by the config schemas they contain. Each schema sets the file path where the Miru Agent writes its config instance on the device, and a release can only be deployed to devices running the operating system its file paths target.The getting-started repository has a folder for each operating system:

linux/ writes config instances to /srv/miru/configs/
windows/ writes config instances to C:\ProgramData\Miru\configs\

Each folder contains two sets of schemas:

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, select the tab for the operating system of the device you’ll deploy to and choose one of its schema sets to create your release with. If you don’t currently use a schema, we recommend starting with an empty schema and gradually adding constraints as needed.

Linux
Windows

Empty Schemas

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

@miru(config_type="mobility",instance_filepath="/srv/miru/configs/mobility.json")
{
	...
}

@miru(config_type="planning",instance_filepath="/srv/miru/configs/planning.json")
{
	...
}

Strict Schemas

@miru(config_type="communication",instance_filepath="/srv/miru/configs/communication.json")
{
	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
	}
}

@miru(config_type="mobility",instance_filepath="/srv/miru/configs/mobility.json")
{
	max_linear_speed_mps: number & >=0.1 & <=5.0 | *1.2
	max_angular_speed_radps: number & >=0.1 & <=3.0 | *1.0
	obstacle_avoidance_enabled: bool | *true
	navigation_mode: "conservative" | "balanced" | "aggressive" | *"balanced"

	telemetry: {
		upload_interval_sec: int & >=10 & <=300 | *60
		heartbeat_interval_sec: int & >=1 & <=60 | *10
	}
}

@miru(config_type="planning",instance_filepath="/srv/miru/configs/planning.json")
{
	planning_frequency_hz: number & >=1.0 & <=100.0 | *20.0
	control_frequency_hz: number & >=10.0 & <=200.0 | *50.0
	planning_timeout_s: number & >=0.1 & <=5.0 | *1.0

	path_following: {
		lookahead_distance_m: number & >=0.1 & <=2.0 | *0.3
		lookahead_time_s: number & >=0.1 & <=2.0 | *0.5
		path_tolerance_m: number & >=0.01 & <=0.5 | *0.05
		goal_tolerance_m: number & >=0.01 & <=0.5 | *0.1
		heading_tolerance_rad: number & >=0.01 & <=0.5 | *0.05
		min_lookahead_distance_m: number & >=0.05 & <=1.0 | *0.1
		max_lookahead_distance_m: number & >=0.2 & <=5.0 | *0.5
	}

	trajectory: {
		max_path_velocity_mps: number & >=0.2 & <=5.0 | *1.5
		min_path_velocity_mps: number & >=0.05 & <=0.5 | *0.1
		path_acceleration_mps2: number & >=0.1 & <=3.0 | *1.0
		path_deceleration_mps2: number & >=0.1 & <=4.0 | *1.2
		max_centripetal_acceleration_mps2: number & >=0.1 & <=2.0 | *0.5
		path_jerk_mps3: number & >=0.1 & <=5.0 | *0.5
	}

	local_planner: {
		min_samples: int & >=5 & <=100 | *10
		max_samples: int & >=10 & <=500 | *50
		sampling_time_s: number & >=0.1 & <=2.0 | *0.8
		resolution_m: number & >=0.01 & <=0.5 | *0.05
		horizon_m: number & >=0.5 & <=10.0 | *2.0
	}

	global_planner: {
		grid_resolution_m: number & >=0.01 & <=0.5 | *0.1
		inflation_radius_m: number & >=0.1 & <=2.0 | *0.5
		cost_scaling_factor: number & >=0.1 & <=10.0 | *2.0
		lethal_cost_value: int & >=100 & <=255 | *253
		neutral_cost_value: int & >=0 & <=100 | *50
	}

	obstacle_avoidance: {
		min_obstacle_distance_m: number & >=0.1 & <=1.0 | *0.5
		max_obstacle_distance_m: number & >=0.5 & <=5.0 | *2.0
		obstacle_inflation_m: number & >=0.05 & <=1.0 | *0.2
		dynamic_obstacle_velocity_threshold_mps: number & >=0.05 & <=2.0 | *0.2
	}

	smoothing: {
		curve_weight: number & >=0.0 & <=1.0 | *0.3
		smooth_weight: number & >=0.0 & <=1.0 | *0.3
		tolerance: number & >=0.0001 & <=0.1 | *0.01
		max_iterations: int & >=5 & <=1000 | *10
	}

	recovery: {
		enable_backoff: bool | *true
		backoff_distance_m: number & >=0.1 & <=2.0 | *0.3
		enable_rotation_in_place: bool | *true
		max_rotation_angle_rad: number & >=0.1 & <=6.28318 | *1.57
		clear_costmap_before_recovery: bool | *true
	}
}

Windows file paths escape each backslash (\\), because CUE treats a backslash in a double-quoted string as the start of an escape sequence.Empty Schemas

@miru(config_type="communication",instance_filepath="C:\\ProgramData\\Miru\\configs\\communication.json")
{
	...
}

@miru(config_type="mobility",instance_filepath="C:\\ProgramData\\Miru\\configs\\mobility.json")
{
	...
}

@miru(config_type="planning",instance_filepath="C:\\ProgramData\\Miru\\configs\\planning.json")
{
	...
}

Strict Schemas

@miru(config_type="communication",instance_filepath="C:\\ProgramData\\Miru\\configs\\communication.json")
{
	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
	}
}

@miru(config_type="mobility",instance_filepath="C:\\ProgramData\\Miru\\configs\\mobility.json")
{
	max_linear_speed_mps: number & >=0.1 & <=5.0 | *1.2
	max_angular_speed_radps: number & >=0.1 & <=3.0 | *1.0
	obstacle_avoidance_enabled: bool | *true
	navigation_mode: "conservative" | "balanced" | "aggressive" | *"balanced"

	telemetry: {
		upload_interval_sec: int & >=10 & <=300 | *60
		heartbeat_interval_sec: int & >=1 & <=60 | *10
	}
}

@miru(config_type="planning",instance_filepath="C:\\ProgramData\\Miru\\configs\\planning.json")
{
	planning_frequency_hz: number & >=1.0 & <=100.0 | *20.0
	control_frequency_hz: number & >=10.0 & <=200.0 | *50.0
	planning_timeout_s: number & >=0.1 & <=5.0 | *1.0

	path_following: {
		lookahead_distance_m: number & >=0.1 & <=2.0 | *0.3
		lookahead_time_s: number & >=0.1 & <=2.0 | *0.5
		path_tolerance_m: number & >=0.01 & <=0.5 | *0.05
		goal_tolerance_m: number & >=0.01 & <=0.5 | *0.1
		heading_tolerance_rad: number & >=0.01 & <=0.5 | *0.05
		min_lookahead_distance_m: number & >=0.05 & <=1.0 | *0.1
		max_lookahead_distance_m: number & >=0.2 & <=5.0 | *0.5
	}

	trajectory: {
		max_path_velocity_mps: number & >=0.2 & <=5.0 | *1.5
		min_path_velocity_mps: number & >=0.05 & <=0.5 | *0.1
		path_acceleration_mps2: number & >=0.1 & <=3.0 | *1.0
		path_deceleration_mps2: number & >=0.1 & <=4.0 | *1.2
		max_centripetal_acceleration_mps2: number & >=0.1 & <=2.0 | *0.5
		path_jerk_mps3: number & >=0.1 & <=5.0 | *0.5
	}

	local_planner: {
		min_samples: int & >=5 & <=100 | *10
		max_samples: int & >=10 & <=500 | *50
		sampling_time_s: number & >=0.1 & <=2.0 | *0.8
		resolution_m: number & >=0.01 & <=0.5 | *0.05
		horizon_m: number & >=0.5 & <=10.0 | *2.0
	}

	global_planner: {
		grid_resolution_m: number & >=0.01 & <=0.5 | *0.1
		inflation_radius_m: number & >=0.1 & <=2.0 | *0.5
		cost_scaling_factor: number & >=0.1 & <=10.0 | *2.0
		lethal_cost_value: int & >=100 & <=255 | *253
		neutral_cost_value: int & >=0 & <=100 | *50
	}

	obstacle_avoidance: {
		min_obstacle_distance_m: number & >=0.1 & <=1.0 | *0.5
		max_obstacle_distance_m: number & >=0.5 & <=5.0 | *2.0
		obstacle_inflation_m: number & >=0.05 & <=1.0 | *0.2
		dynamic_obstacle_velocity_threshold_mps: number & >=0.05 & <=2.0 | *0.2
	}

	smoothing: {
		curve_weight: number & >=0.0 & <=1.0 | *0.3
		smooth_weight: number & >=0.0 & <=1.0 | *0.3
		tolerance: number & >=0.0001 & <=0.1 | *0.01
		max_iterations: int & >=5 & <=1000 | *10
	}

	recovery: {
		enable_backoff: bool | *true
		backoff_distance_m: number & >=0.1 & <=2.0 | *0.3
		enable_rotation_in_place: bool | *true
		max_rotation_angle_rad: number & >=0.1 & <=6.28318 | *1.57
		clear_costmap_before_recovery: bool | *true
	}
}

Schema annotations

Each of the above schemas carries the following annotations:

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}"

@miru(config_type="{config-type-slug}")

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

The instance file path is the absolute file system path where config instances for this schema are written on the device.This annotation is optional and defaults to /srv/miru/configs/{config-type-slug}.{instance-format}. The default is a Linux path, so schemas for Windows devices must set an explicit path such as C:\ProgramData\Miru\configs\mobility.json.To share the same schema amongst multiple config instances, declare instance slots instead.

Linux
Windows

x-miru-instance-filepath: "/srv/miru/configs/mobility.json"

@miru(instance_filepath="/srv/miru/configs/mobility.json")

instance_filepath: "/srv/miru/configs/mobility.json"

The Miru Agent ships with out-of-the-box access to /srv/miru. Any local account can read configs deployed to /srv/miru.

To deploy configs to a custom directory, visit File system access.

/srv/miru/configs/mobility.json
/home/myapp/configs/communication.yaml

Quote Windows paths in single quotes in YAML, and escape each backslash as \\ in CUE.

x-miru-instance-filepath: 'C:\ProgramData\Miru\configs\mobility.json'

@miru(instance_filepath="C:\\ProgramData\\Miru\\configs\\mobility.json")

instance_filepath: 'C:\ProgramData\Miru\configs\mobility.json'

The Miru Agent ships with out-of-the-box access to %ProgramData%\Miru\configs. Only Local System, Administrators, the agent, and members of the local Miru Agent Users group can read configs deployed to %ProgramData%\Miru\configs.

To deploy configs to a custom directory, visit File system access.

C:\ProgramData\Miru\configs\mobility.json
C:\ProgramData\MyApp\configs\communication.yaml

Miru supports more annotations, such as instance slots and instance formats. However, this tutorial only covers the two annotations above.For the full list and their syntax in each schema language, visit the annotations documentation.

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.

The CLI runs on your development machine, not on the device. The CLI is not yet available for Windows, so if your device runs Windows, install the CLI on a macOS or Linux machine to create the release.

InstallThe 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

LoginTo log in, run the login command.

miru login

The CLI prints a verification URL and a short code, then opens the URL in your default browser. Confirm that the code in the browser matches the code in the terminal.

$ miru login

Visit https://app.mirurobotics.com/oauth/device?user_code=XXXX-XXXX

Confirm this code is shown in your browser: XXXX-XXXX

◐ Waiting for authentication...
Successfully authenticated as Benjamin
  Type         User
  User Type    Admin
  Auth Source  Token stored by miru login
  Workspace    Acme Robotics

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 the schema set you chose for your device’s operating system.

Linux
Windows

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

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

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

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

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

$ miru release create \
  --version v1.0.0 \
  --schemas ./{os}/cue/{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 define releases documentation.

Welcome

Fleet

Config Management

Data Uploads

Developers

Administration

Create a release

Define the schemas

Schema annotations

Set up the CLI

Create a release

​Define the schemas

​Schema annotations

​Set up the CLI

​Create a release

Define the schemas

Schema annotations

Set up the CLI

Create a release