Find a module for your robot

You can extend Viam by adding a module on your robot 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 robot.
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.

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 robot.

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 robot:

• Add a modular component
• Add a modular service

Add a modular component from the Viam registry

To add a modular component from the Viam registry to your robot:

1. Navigate to the Config tab of your robot’s page in the Viam app.

2. Click on the Components subtab and click the Create component button.

3. Browse the list of available component types, and select the specific modular component you’d like to add.

   

   You can also start typing to search for a module by name or to narrow down your search results.

   

4. After selecting the modular component, click the Add module button, enter a name for your modular component, and click Create to add it to your robot’s component configuration.

   

   Be sure the modular component you select supports the platform you intend to use it with, such as linux arm64. You can see which platforms the module supports at bottom of the module information screen before you add it.

When you add a module from the Viam registry, the custom modular component it provides appears under the Components subtab like any other component. You can also find the underlying module listed as Deployed under the Modules subtab.

If the module requires you to configure specific Attributes, click the URL link in the module’s configuration pane to view the specific attribute requirements on the module’s GitHub page.

To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the Modules subtab of the robot’s Config tab. Deleting a module does not delete any configured modular resources it provides.

Add a modular service from the Viam registry

To add a modular service from the Viam registry to your robot:

1. Navigate to the Config tab of your robot’s page in the Viam app.

2. Click on the Services subtab and click the Create service button.

3. Browse the list of available service types and select the specific modular service you’d like to add.

   

   You can also start typing to search for a module by name or to narrow down your search results.

   

4. After selecting the modular service, click the Add module button, enter a name for your modular service, and click Create to add it to your robot’s service configuration.

   

   Be sure the modular service you select supports the platform you intend to use it with, such as linux arm64. You can see which platforms the module supports at bottom of the module information screen before you add it.

When you add a module from the Viam registry, the custom modular service it provides appears under the Services subtab like any other service. You can also find the module itself listed as Deployed under the Modules subtab.

If the module requires you to configure specific Attributes, click the URL link in the module’s configuration pane to view the specific attribute requirements on the module’s GitHub page.

To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the Services tab. Deleting a module does not delete any configured modular resources it provides.

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 robot 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 component or Create 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.

If you prefer to use raw JSON, 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. If the module requires you to configure specific Attributes, click the URL link in the module’s configuration pane 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": {},
      "depends_on": []
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "viam_realsense",
      "module_id": "viam:realsense",
      "version": "0.0.3"
    }
  ]
}

Edit the configuration of a module from the Viam registry

Once you have added a modular resource to your robot, you can view and edit the configuration of the underlying module from the Modules subtab:

1. Navigate to the Config tab of your robot’s page in the Viam app.
2. Click on the Modules subtab. All modules you have added to your robot appear under the Deployed section.

This pane lists the models provided by the module, and any components or services on your robot that are currently using the module. You can also configure how the module updates when a new version is available from the Viam registry, or configure environment variables for your module.

Configure version update management for a registry module

When you add a module to your robot, 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.

If you wish to allow automatic module updates when a new version of the module becomes available in the Viam registry, you can set the Version type for your module in the Modules subtab. Updating to a newer version of a module brings new functionality and bug fixes, but requires restarting the module to apply the update. 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 pane 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 URL link in the upper-right corner of the module configuration pane 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 Config tab on your robot’s page in the Viam app, toggle Raw 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 robot 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 robot 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 robot:

1. Navigate to the Config tab of your robot’s page on the Viam app.

   • If you are adding a modular component, click the Components subtab and click Create component.
   • If you are adding a modular service, click the Services subtab and click Create service.

2. Then, select the local component or local service type from the list.

   

3. On the next screen:

   • Select the type of modular resource provided by your module, such as a camera, from the dropdown menu.
   • 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.
   • Enter a name for this instance of your modular resource. This name must be different from the module name.
   

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

You can also add the module directly, without first adding its modular component or service:

1. Navigate to the Config tab of your robot’s page in the Viam app.

2. Click on the Modules subtab.

3. Scroll to the Add local module section.

4. Enter a Name for this instance of your modular resource.

5. Enter the module’s executable path. This path must be the absolute path to the executable on your robot’s filesystem.

6. Then, click the Add module button, and click Save config.

   

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

Edit the configuration of a local module

Once you have added a modular resource to your robot, you can view and edit the underlying module from the Modules subtab:

1. Navigate to the Config tab of your robot’s page in the Viam app.
2. Click on the Modules subtab. Local modules you have added to your robot appear under the Local section.

The following properties are available for modules:

Add these properties to your module’s configuration:

• Config Builder
• JSON Template

{
  "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 robot, you can add any number of the resources provided by that module to your robot 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.