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):
- Add a module, either one from the registry or a local module. This makes the modular resource available to the robot.
- 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 from the Viam registry
To add a modular component from the Viam registry to your robot:
Navigate to the Config tab of your robot’s page in the Viam app.
Click on the Components subtab and click the Create component button.
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.
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:
Navigate to the Config tab of your robot’s page in the Viam app.
Click on the Services subtab and click the Create service button.
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.
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:
Name | Type | Inclusion | Description |
---|---|---|---|
namespace | string | Required | The namespace of the API (the first part of the API namespace triplet). See Valid APIs to implement in your model |
type | string | Required | The subtype of the API (the third part of the API namespace triplet). See Valid APIs to implement in your model. |
name | string | Required | What you want to name this instance of your modular resource. |
model | string | Required | The full model namespace triplet of the modular resource’s model. |
depends_on | array | Optional | The name of components you want to confirm are available on your robot alongside your modular resource. Often a board. Unnecessary if you coded implicit dependencies. |
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>"
}
]
}
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 custom model is configured as a component with the name “my-realsense”.
{
"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:
- Navigate to the Config tab of your robot’s page in the Viam app.
- 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 version1.2.4
or1.2.5
but not1.3.0
or2.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 version1.2.4
or1.3.0
but not2.0.0
or3.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.
Caution
For any version type other than Patch (X.Y.Z), the module will upgrade as soon as an update that matches that specified version type is available, which will restart the module. If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.
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:
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:
Name | Description |
---|---|
VIAM_HOME | The root of the viam-server configuration.Default: $HOME/.viam |
VIAM_MODULE_ROOT | The root of the module install directory. Useful for file navigation that is relative to the root of the module. If you are using a local module, you must set this value manually if your module requires it. Example: $VIAM_HOME/packages/.data/modules/verxxxx-my-module/ |
VIAM_MODULE_DATA | A persistent folder location a module can use to store data across reboots and versions. This location is a good place to store python virtual environments. Example: $VIAM_HOME/module-data/cloud-robot-id/my-module-name/ |
VIAM_MODULE_ID | The module ID of the module. Example: viam:realsense |
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 runningviam-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:
Navigate to the Config tab of your robot’s page on the Viam app.
Then, select the
local component
orlocal service
type from the list.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.
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:
Navigate to the Config tab of your robot’s page in the Viam app.
Click on the Modules subtab.
Scroll to the Add local module section.
Enter a Name for this instance of your modular resource.
Enter the module’s executable path. This path must be the absolute path to the executable on your robot’s filesystem.
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:
- Navigate to the Config tab of your robot’s page in the Viam app.
- 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:
Name | Type | Inclusion | Description |
---|---|---|---|
name | string | Required | Name of the module you are registering. |
executable_path | string | Required | The absolute path to the executable on your robot’s filesystem. |
type | string | Required | Either registry or local . |
Add these properties to your module’s configuration:

{
"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:
Name | Type | Inclusion | Description |
---|---|---|---|
namespace | string | Required | The namespace of the API (the first part of the API namespace triplet). See Valid APIs to implement in your model. |
type | string | Required | The subtype of the API (the third part of the API namespace triplet). See Valid APIs to implement in your model. |
name | string | Required | A custom name for this instance of your modular resource. |
model | string | Required | The full model namespace triplet of the modular resource’s model. |
depends_on | array | Optional | The name of components you want to confirm are available on your robot alongside your modular resource. Often a board. Unnecessary if you coded implicit dependencies. |
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 >
}
The following is an example configuration for a base modular resource implementation.
The configuration adds acme:demo:mybase
as a modular resource from the module my_base
.
The custom model is configured as a component with the name “my-custom-base-1”.
You can send commands to the base according to the Viam base API:
{
"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:
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!