Edit

Modular Resources

The Viam Registry hosts modules that provide modular resources. A modular resource is a model of a components or services that you can use on your machines.

In this page

Modular resources in the registry

API

Model

Description

Configuration

When you add components and services from your machine’s CONFIGURE tab, you can select available modular resources from the Viam registry. When you add a modular resource from the registry, the module that provides it is automatically added at the same time. To add a modular resource from a local module, you must add the module first.

You configure the module and the modular resources it provides separately.

Modular resource configuration

The modular resource card allows you to configure attributes for the resource.

Config Builder
JSON

The following image shows an example of a configured modular resource, specifically an ultrasonic sensor component. This modular component is made available by the ultrasonic module. See module configuration.

A configured modular resource example in the Viam app builder UI.

JSON Example
JSON Template

{
  "name": "sensor-1",
  "model": "viam:ultrasonic:sensor",
  "type": "sensor",
  "namespace": "rdk",
  "attributes": {
    "trigger_pin": "13",
    "echo_interrupt_pin": "15",
    "board": "board-1",
    "timeout_ms": 500
  },
  "depends_on": []
}

{
  "name": "<your-model-instance-name>",
  "model": "<namespace>:<repo-name>:<name>",
  "type": "<your-resource-subtype>",
  "namespace": "<your-module-namespace>",
  "attributes": {
    "<relevant attributes--see module Readme>"
  },
  "depends_on": []
}

The following properties are available for modular resources:

Name	Type	Required?	Description
`attributes`	object	Sometimes Required	Any configuration attributes for your model Check the module’s GitHub Readme for information about available configuration attributes for a resource.
`name`	string	Required	What you want to name this instance of your modular resource.
`namespace`	string	Required	The namespace of the API (the first part of the API namespace triplet). This will be `rdk` unless the module implements a custom, non-standard API. See Valid API identifiers.
`type`	string	Required	The subtype of the API (the third part of the API namespace triplet). See Valid API identifiers.
`model`	string	Required	The full model namespace triplet of the modular resource’s model.
`depends_on`	array	Optional	The `name` of components you want to confirm are available on your machine alongside your modular resource. Often a board. Unnecessary if you coded implicit dependencies.

The following image shows an example of a configured module in a machine’s config. This ultrasonic sensor in the previous section is provided by the ultrasonic module shown here.

A configured module example in the Viam app builder UI.

Examples:

  "modules": [
    {
      "type": "registry",
      "name": "viam_ultrasonic",
      "module_id": "viam:ultrasonic",
      "version": "0.0.2"
    },
    {
      "type": "registry",
      "name": "viam_tflite_cpu",
      "module_id": "viam:tflite_cpu",
      "version": "latest"
    },
    {
      "type": "registry",
      "name": "viam_raspberry-pi",
      "module_id": "viam:raspberry-pi",
      "version": "1.1.0"
    },
  ]

The config of both a module and a corresponding modular resource resembles the following:

JSON Template
JSON Example

{
  "components": [
    {
      "name": "<your-model-instance-name>",
      "model": "<module-namespace>:<repo-name>:<name>",
      "type": "<your-resource-subtype>",
      "namespace": "<model-API-namespace>",
      "attributes": {},
      "depends_on": []
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "<module-namespace>_<module-name>",
      "module_id": "<module-namespace>:<module-name>",
      "version": "<module-version>",
      "env": {
        "MY_VAR": "<some-value>",
        "PATH": "<example-folder>:${environment.PATH}"
      }
    }
  ]
}

The following is an example configuration for the Intel Realsense module. The configuration adds viam:camera:realsense as a modular resource from the module viam:realsense. The model is configured as a component with the name myRealsenseCamera1.

{
  "components": [
    {
      "name": "myRealsenseCamera1",
      "model": "viam:camera:realsense",
      "type": "camera",
      "namespace": "rdk",
      "attributes": {
        "sensors": ["color", "depth"]
      },
      "depends_on": []
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "viam_realsense",
      "module_id": "viam:realsense",
      "version": "0.0.3"
    }
  ]
}

The following properties are configurable for each module:

Name	Type	Required?	Description
`version`	string	Required	You can specify: a specific version (X.Y.Z) of the module to use to pin the module version to the newest release, so your machine automatically updates to the latest version of the module that is available or to the latest patch release of a configured minor (X.Y._) or major (X._) version. For more information, see Module versioning.
`type`	string	Required	`registry` or `local`, depending on whether the module is in the Viam registry or is only available locally on your computer.
`module_id`	string	Required	The module author’s organization namespace or UUID, then a colon, then the name of the module. Identical to the first two pieces of the model namespace triplet. `<module namespace>:<module name>`.
`name`	string	Required	A name for this instance of the module.
`env`	object	Optional	Environment variables available to the module. For example `{ "API_KEY": "${environment.API_KEY}" }`. Some modules require that you set environment variables as part of configuration. Check the module’s readme for more information. See environments variables.

Module versioning

You can configure how each module on your machine updates itself when a newer version becomes available from the Viam registry. By default, a newly-added module is set to pin to the specific patch release (Patch (X.Y.Z)) of the version you added, meaning that the module will never automatically update itself.

To allow automatic module updates when a new version of the module becomes available in the Viam registry, set the Pinned version type for your module in its module card on the CONFIGURE tab.

The following update options are available:

Patch (X.Y.Z): Do not update to any other version. This is the default.
Minor (X.Y.*): Only update to newer patch releases of the same minor release branch. The module will automatically restart and update itself whenever new updates within the same minor release are available in the Viam registry. For example, use this option to permit a module with version 1.2.3 to update to version 1.2.4 or 1.2.5 but not 1.3.0 or 2.0.0.
Major (X.*): Only update to newer minor releases of the same major release branch. The module will automatically restart and update itself whenever new updates within the same major release are available in the Viam registry. For example, use this option to permit a module with version 1.2.3 to update to version 1.2.4 or 1.3.0 but not 2.0.0 or 3.0.0.
Latest: Always update to the latest version of this module available from the Viam registry as soon as a new version becomes available.

When using the Patch (X.Y.Z) version type, you may select any patch version of the module from the Version dropdown menu, including past versions if desired.

The current deployed version of your module and the latest version of that module available from the Viam registry are shown on this module card for your reference.

Caution

For any version type other than Patch (X.Y.Z), the module will upgrade as soon as an update that matches that specified version type is available, which will restart the module. If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.

Environment variables

Each module has access to the following default environment variables:

Name	Description
`VIAM_HOME`	The root of the `viam-server` configuration. Default: `$HOME/.viam`
`VIAM_MODULE_ROOT`	The root of the module install directory. The module process uses this directory as its current working directory (`cwd`). This variable is useful for file navigation that is relative to the root of the module. If you are using a local module, you must set this value manually if your module requires it. Example: `/opt/my-module/verxxxx-my-module/`
`VIAM_MODULE_DATA`	A persistent folder location a module can use to store data across reboots and versions. This location is a good place to store python virtual environments. Example: `$VIAM_HOME/module-data/cloud-machine-id/my-module-name/`
`VIAM_MODULE_ID`	The module ID of the module. Example: `viam:realsense`

You can also set additional environment variables.

Example: string value

Set the environment variable MODULE_USER:

{
  "modules": [
    {
      ...
      "env": {
        "MODULE_USER": "my-username"
      }
    }
  ]
}

Use the notation ${environment.<ENV-VAR-NAME>} to access any system environment variable that viam-server has access to, where <ENV-VAR-NAME> represents a system environment variable, like PATH, USER, or PWD. For example, you can use ${environment.HOME} to access the HOME environment variable for the user running viam-server.

Example: system variable

To set the path to a program or library on a machine, you can set a system variable:

{
  "modules": [
    {
      ...
      "env": {
        "PATH": "/home/username/bin:${environment.PATH}"
      }
    }
  ]
}

How modules run

Modules run alongside viam-server as separate processes, communicating with viam-server over UNIX sockets. When a module initializes, it registers its model or models and associated APIs with viam-server, making the new model available for use. viam-server manages the dependencies, start-up, reconfiguration, data management, and shutdown behavior of your modular resource.

Next steps

You can write modules in a variety of programming languages, such as, Go, Python, C++, Rust, while implementing the respective component APIs or service APIs.

To see modular resources in actions, follow one of these tutorials:

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!