Modular resource and module configuration details

This page contains reference material. For quick instructions on configuring a module on your machine, see Configure hardware on your machine.

Modular resource configuration details

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.

• JSON Example
• JSON Template

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

{
  "name": "<your-model-instance-name>",
  "model": "<namespace>:<module-name>:<model-name>",
  "api": "<model-API-namespace>:<component|service>:<model-name>",
  "attributes": {
    "<relevant attributes--see module Readme>"
  },
  "depends_on": []
}

The following properties are available for modular resources:

Module configuration details

• Config Builder
• JSON

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.

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>:<module-name>:<model-name>",
      "api": "<model-API-namespace>:<component|service>:<model-name>",
      "attributes": {}
    }
  ],
  "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",
      "api": "rdk:component:camera",
      "attributes": {
        "sensors": ["color", "depth"]
      },
      "depends_on": []
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "viam_realsense",
      "module_id": "viam:realsense",
      "version": "0.0.11"
    }
  ]
}

The following properties are configurable for each module:

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 (latest): Always update to the latest version of this module available from the Viam Registry as soon as a new version becomes available.
• Latest with prerelease (latest-with-prerelease): Always update to the latest release or prerelease version of this module available from the Viam Registry as soon as the 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.

Environment variables

Each module has access to the following default environment variables. Not all of these variables are automatically available on local modules; you can manually set variables your module requires if necessary.

You can also set additional environment variables.

{
  "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.

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