Find a Module for your Machine

You can extend Viam by adding a module on your machine that provides one or more modular resources (components or services):

1. Add a module, either one from the registry or a local module. This makes the modular resource available to the machine.
2. Then add the modular resource itself.

When you add a modular resource from the registry, the underlying 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 can search the available modular resources from the Viam Registry here:

You can see details about each module in the Viam registry on its dedicated module page. You can integrate modules into any Viam-powered machine.

Add a modular resource from the Viam registry

The Viam registry is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam’s capabilities on your machine.

A module provides one or more modular resources (either a component or service).

Follow the instructions below depending on the type of modular resource you would like to add to your machine:

Add additional modular resources from a registry module

Once you have added a module from the Viam registry, you can add any number of the modular resources it provides to your machine by adding new components or services configured with your modular resource’s model.

Follow the same steps as when you added the first modular resource, clicking Create and Component or Service as applicable. You will be prompted to click Add module again while configuring the resource, though no duplicate module will be added to the modules section of the configuration.

Edit the configuration of a module from the Viam registry

Edit modular resources

You can edit the configuration of the modular resource or resources you have added from your module in the card matching the name you gave the resource when adding it on the CONFIGURE tab.

If you prefer to use JSON, the following properties are available for all modular resources:

All standard properties for configuration, such as attributes and depends_on, are also supported for modular resources. The attributes available vary depending on your implementation. If the module requires you to configure specific Attributes, click the Registry link in the module’s configuration card to view the specific attribute requirements on the module’s GitHub page.

{
  "components": [
    {
      "name": "<your-model-instance-name>",
      "model": "<namespace>:<repo-name>:<name>",
      "type": "<your-resource-subtype>",
      "namespace": "<your-module-namespace>",
      "attributes": {},
      "depends_on": []
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "<module-name>",
      "module_id": "<module-namespace>:<module-name>",
      "version": "<module-version>"
    }
  ]
}

{
  "components": [
    {
      "name": "my-realsense",
      "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"
    }
  ]
}

Edit the module

You can also view and edit the configuration of a modular resource’s underlying module from the CONFIGURE tab:

1. Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

2. Scroll to the card with the name of the module, as indicated by its page in the registry.

   This is the Registry module card, which lists the deployed version of the module and the latest version available. Here you can configure how a module updates.

   

   You can also use JSON mode to configure environment variables for your module.

Configure version update management for a registry module

When you add a module to your machine, you can also configure how that module 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.

Use environment variables with a registry module

Some modules require that you set specific environment variables as part of configuration. You can click the Homepage link in the upper-right corner of the module configuration card to view any specific requirements on the module’s GitHub page.

Module environment variables can be either:

• Static string values, or
• References to a system environment variable.

For example, if your module requires a MODULE_USER environment variable, you can add it with the following configuration:

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

Or if you are using a module that requires access to an additional program or library on your machine, you can create a PATH environment variable for that module:

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

This configures a module environment variable PATH that uses your system’s PATH (which you can view by running echo $PATH) as a base, and adds one additional filesystem path: /home/username/bin.

The notation ${environment.<ENV-VAR-NAME>} can be used 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.

To configure a modular resource with an environment variable, navigate to the CONFIGURE tab on your machine’s page in the Viam app, select JSON mode, and add the following env configuration to the modules section:

{
  "modules": [
    {
      "type": "registry",
      "name": "<module-name>",
      "module_id": "<module-namespace>:<module-name>",
      "version": "<module-version>",
      "env": {
        "MY_VAR": "<some-value>",
        "PATH": "<example-folder>:${environment.PATH}"
      }
    }
  ]
}

{
  "modules": [
    {
      "type": "registry",
      "name": "my-module",
      "module_id": "my-namespace:my-module",
      "version": "1.0.0",
      "env": {
        "PATH": "/home/username/bin:${environment.PATH}",
        "MY_USER": "username"
      }
    }
  ]
}

To delete an environment variable configuration, delete the env section from your smart machine’s configuration.

Default environment variables

When a module is instantiated, it has access to the following default environment variables:

Local modules

If you wish to add a module to your machine without uploading it to the Viam registry, you can add your module as a local module.

You can add your own custom modules as local modules, or you can add pre-built modules written by other Viam users.

Prepare a local module

First determine the module you wish to add as a local module:

• If you are adding your own custom module, be sure that you have followed the steps to create your own module to code and compile your module and generate an executable.
• If you are using a pre-built module, make sure you have installed the module and determined the filename of the module’s executable.

Then, ensure that viam-server is able to find and run the executable:

• Ensure that the module executable is saved to a location on the filesystem of your machine that viam-server can access. For example, if you are running viam-server on an Raspberry Pi, you must save the module executable on the Pi’s filesystem.

• Ensure that this file is executable (runnable) with the following command:

  sudo chmod a+rx <path-to-your-module-executable>
  

See the instructions to compile your module into an executable for more information.

Add a local module

To add a local module on your machine, first add its module, then the component or service it implements:

1. Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

2. Click the + (Create) icon next to your machine part in the left-hand menu and select Local module, then Local module.

3. Enter a Name for this instance of your module.

4. Enter the module’s Executable path. This path must be the absolute path on your machine’s filesystem to either:

   • the module’s executable file, such as run.sh or a compiled binary.
   • a packaged tarball of your module, ending in .tar.gz or .tgz. If you are providing a tarball file in this field, be sure that your packaged tarball contains your module’s meta.json file within it.

5. Then, click the Create button, and click Save in the upper right corner to save your config.

   

   This example shows the configuration for adding a CSI camera as a local module.

6. Still on your machine’s CONFIGURE tab, click the + (Create) icon next to your machine part in the left-hand menu.

7. Select Local module, then select Local component or Local service.

8. Select the type of modular resource provided by your module, such as a camera, from the dropdown menu.

9. Enter the model namespace triplet of your modular resource’s model. If you are adding a pre-built modular resource, the model triplet should be provided for you in the module’s documentation.

10. Enter a name for this instance of your modular resource. This name must be different from the module name.

    

11. Click Create to create the modular resource provided by the local module.

Once you’ve added your local module using steps 1-5, you can repeat steps 6-11 to add as many additional instances of your modular resource as you need.

Edit the configuration of a local module

Once you have added a modular resource to your machine, you can view and edit the underlying module.

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Local modules you have added to your machine are identifiable by name. Locate a module’s card in the part-resource hierarchy and click on it to expand.

The following properties are available for modules:

• Config Builder
• JSON Template

To edit the raw JSON instead of using the config builder UI, click {} JSON in the upper left corner of the CONFIGURE tab.

{
  "modules": [
    {
      "name": "<your-module-name>",
      "executable_path": "<path-on-your-filesystem-to/your-module-directory>/<your_executable.sh>",
      "type": "local"
    }
  ]
}

Add a local modular resource

Once you have added a local module to your machine, you can add any number of the resources provided by that module to your machine by adding new components or services that use your modular resource’s model.

The following properties are available for modular resources:

All standard properties for configuration, such as attributes and depends_on, are also supported for modular resources. The attributes available vary depending on your implementation.

{
  "components": [
    {
      "namespace": "<your-module-namespace>",
      "type": "<your-resource-subtype>",
      "model": "<namespace>:<repo-name>:<name>",
      "name": "<your-model-instance-name>",
      "attributes": {},
      "depends_on": []
    }
  ],
  "modules": [ ... ] // < INSERT YOUR MODULE CONFIGURATION >
}

{
  "components": [
    {
      "type": "board",
      "name": "main-board",
      "model": "pi"
    },
    {
      "type": "base",
      "name": "my-custom-base-1",
      "model": "acme:demo:mybase",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": ["main-board"]
    }
  ],
  "modules": [
    {
      "name": "my-custom-base",
      "executable_path": "/home/my_username/my_base/run.sh"
    }
  ]
}

Next steps

Now that you’ve configured a modular resource, test it with the CONTROL tab and program it with the Viam SDKs.

You can also check out these tutorials that configure and use modular resources:

Plant Watering Robot

Create a plant watering robot with a Raspberry Pi.

AI Companion Robot

Harness AI and use ChatGPT to add life to your Viam rover and turn it into a companion robot.