Configure a module on your robot

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

You can add a module from the Viam registry, or you can add a local module.

See Key Concepts of Modular Resource APIs for more information.

Add a module 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.

   

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

   

   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.

Configure a module from the Viam registry

Once you have added a modular resource to your robot, you can view and configure the module itself 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, any components or services on your robot that are currently using the module, and allows you to configure how the module updates when a new version is available from the Viam registry.

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 drop down 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.

Create a new modular resource 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 resources’ 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. 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": "<model-namespace>:<model-family>:<model-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"
    }
  ]
}

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 modular resource 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 drop down 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.

Configure a local module

Once you have added a modular resource to your robot, you can view and configure the module itself 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"
    }
  ]
}

Configure a 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 resources’ 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": "<model-namespace>:<model-family>:<model-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.