Modular resource and module configuration

This page contains detailed information on configuring modules and modular resources. For an introduction to configuring a module on your machine, see Configure registry modules instead.

Modular resource configuration details

In the Viam web UI, when you add a modular resource, it adds two cards to the UI: a module card and a resource card. The modular resource card allows you to configure attributes for the resource.

If you switch to {} JSON mode, you can also configure the attributes in JSON.

• Config Builder
• JSON

The resource card shows all configuration attributes for the resource. For example:

• 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

In the Viam web UI, when you add a modular resource, it adds two cards to the UI: a module card and a resource card. The module card allows you to configure attributes for the module.

If you switch to {} JSON mode, you can also configure the attributes in JSON.

• Config Builder
• JSON

The module card shows all configuration attributes for the module. For example:

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",
      "disabled": true
    },
    {
      "type": "registry",
      "name": "viam_raspberry-pi",
      "module_id": "viam:raspberry-pi",
      "version": "1.1.0"
    },
    {
      "type": "local",
      "name": "local-module-1",
      "executable_path": "/Users/jessamy/myFolderOfCode/my-control-logic/run.sh"
    }
  ]

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 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 patch and 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.

If a module appears in both a fragment and the part configuration, or in multiple fragments, Viam imports the newest of the configured versions.

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 (public_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. 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": "hello-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-name>",
       "module_id": "<module-namespace>:<module-name>",
       "version": "latest"
     }
   ]
   

Module meta.json configuration

Each module must have a meta.json file that defines the module’s properties. This file includes information about the module’s ID, visibility, models, and other features.

Example meta.json file:

{
  "module_id": "your-namespace:your-module",
  "visibility": "public",
  "url": "https://github.com/your-org/your-repo",
  "description": "Your module description",
  "models": [
    {
      "api": "rdk:component:base",
      "model": "your-namespace:your-module:your-model"
    }
  ],
  "entrypoint": "run.sh",
  "first_run": "setup.sh",
  "applications": [
    {
      "name": "your-app-name",
      "type": "single_machine",
      "entrypoint": "dist/index.html",
      "fragmentIds": [],
      "logoPath": "static/logo.png",
      "customizations": {
        "machinePicker": {
          "heading": "Air monitoring dashboard",
          "subheading": "Sign in and select your devices to view your air quality metrics in a dashboard."
        }
      }
    }
  ]
}

For modules that include Viam applications, you can add the applications field. The applications field is an array of application objects with the following properties:

For more information about Viam applications, see the Viam applications documentation.