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. You can add and edit env by switching from Builder to JSON mode in the CONFIGURE tab.

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 latest release (Latest) of the version you added.

To change the update strategy for your module, 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.
• 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. This is the default.
• 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.

Set additional environment variables

You can configure additional environment variables for your module, using your choice of variable name and value. For example, you could create a variable MODULE_USER with a string value:

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

To access any system environment variable that viam-server has access to, use the notation ${environment.<ENV-VAR-NAME>} 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}"
      }
    }
  ]
}

Access environment variables from your module

You can access module environment variables from within your module code in the same way you would access any other environment variables. For example, you could use the following Python code to access the VIAM_HOME variable:

import os

viam_home = os.environ.get("VIAM_HOME")

Configure an unlisted module

To configure a module that is uploaded to the Viam Registry but has visibility set to Unlisted, you need to manually add the module to your configuration:

1. Navigate to the module’s page in the Viam Registry, using the link to the module.

2. Find the Unlisted module usage section.

3. Copy the module configuration JSON snippet.

4. In the Viam app, navigate to the CONFIGURE tab of the machine you want to configure.

5. Switch to JSON mode.

6. Paste the copied module configuration into your modules array.

7. Copy the model configuration snippet for the model you want to use, and add it to your components or services array (as appropriate). For example:

   • Example
   • Template

   "components": [
     {
       "name": "sensor-1",
       "api": "rdk:component:sensor",
       "model": "jessamy:hello-world:hello-camera",
       "attributes": {}
     },
     ...
   ],
   "modules": [
     {
       "type": "registry",
       "name": "jessamyhello-world",
       "module_id": "jessamy:hello-world",
       "version": "latest"
     }
   ]
   

   "<components|services>": [
     {
       "name": "<resource-name>",
       "api": "<model-API-namespace>:<component|service>:<model-name>",
       "model": "<module-namespace>:<module-name>:<model-name>",
       "attributes": {}
     }
   ],
   "modules": [
     {
       "type": "registry",
       "name": "<module-namespace><module-name>",
       "module_id": "<module-namespace>:<module-name>",
       "version": "latest"
     }
   ]