Extend Viam with Models from the Viam Registry
The Viam registry is the central place where you can browse:
ML models
Viam provides the ability to train, upload, and deploy machine learning models within the platform. See Machine Learning for more information.
The Viam registry hosts trained ML models that users have made public, which you can use to deploy classifiers or detectors for your use case onto your robot instead of training your own. You can also upload your own model to the registry.
You can search the available ML models from the Viam registry here:
To use an existing model from the registry, deploy the ML model to your robot and use a Vision service to make detections or classifications on-machine.
Modular resources
Viam provides built-in support for a variety of resources:
- Various types of hardware components.
- High-level functionality exposed as services.
If the model of component or service you want to use for your project is not built-in to viam-server
and available for configuration by default, you can use a model from a module.
To configure a modular resource on your robot, add new models that others have created from the Viam registry or create your own.
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.
Be aware that unlike natively supported models, modular resources are not documented on the Viam Documentation. Documentation for each modular resource is available on its GitHub page, which is linked from the models’ page on the registry or by clicking on the model name in the above search.
Use modules
To use a modular resource from the registry, add it from your machine’s CONFIGURE tab in the Viam app, using the Create component button.
After adding a module to your machine, you can choose to configure it for automatic version updates from the Viam registry, or update your module manually. By default, newly added modules will remain at the version they were when you installed them, and will not update automatically.
Once you have added and configured the module you would like to use in the Viam app, you can test your added resource using the CONTROL tab and program it using standardized APIs.
viam-server
manages the dependencies, start-up, reconfiguration, data management, and shutdown behavior of your modular resource.
Tutorials using modules
Create your own modules
If none of the existing modular resources in the Viam registry support your use case, you can create your own modules with your own modular resources:
Implement a custom component: Write a driver for an unsupported component by implementing the corresponding component API.
Implement a custom service: Implement your own algorithm or model against a corresponding service API or use custom algorithms or data models when working with services such as SLAM, vision, or motion planning.
You can write modules in a variety of programming languages, such as, Go, Python, C++, Rust, while implementing the same APIs. To create a new module:
- Create a module with one or more modular resources by implementing all methods for the component’s or service’s standardized API.
- Upload the module to the Viam registry to make it available for deployment to machines or add it as a local module. You can upload private modules for your organization or public modules.
- Once you have uploaded your module to the registry, deploy and configure the module from the Viam app. Then, you can test your added resource using the CONTROL tab and program it with Viam’s Go or Python SDKs.
Naming your model: namespace:repo-name:name
If you are creating a custom module and want to upload that module to the Viam registry, ensure your model name meets the following requirements:
- The namespace of your model must match the namespace of your organization.
For example, if your organization uses the
acme
namespace, your models must all begin withacme
, likeacme:repo-name:mybase
. - Your model triplet must be all-lowercase.
- Your model triplet may only use alphanumeric (
a-z
and0-9
), hyphen (-
), and underscore (_
) characters.
For the middle segment of your model triplet repo-name
, use the name of the Git repository where you store your module’s code.
Ideally, your repo-name
should describe the common functionality provided across the model or models of that module.
For example:
The
rand:yahboom:arm
model and therand:yahboom:gripper
model use the repository name yahboom. The models implement therdk:component:arm
and therdk:component:gripper
API to support the Yahboom DOFBOT arm and gripper, respectively:{ "api": "rdk:component:arm", "model": "rand:yahboom:arm" }, { "api": "rdk:component:gripper", "model": "rand:yahboom:gripper" }
The
viam-labs:audioout:pygame
model uses the repository name audioout. It implements the custom APIviam-labs:service:audioout
:{ "api": "viam-labs:service:audioout", "model": "viam-labs:audioout:pygame" }
The viam
namespace is reserved for models provided by Viam.
Valid APIs to implement in your model
When implementing a custom model of an existing component, valid APIs always have the following parameters:
namespace
:rdk
type
:component
subtype
: any one of these component proto files, for examplemotor
When implementing a custom model of an existing service, valid APIs always have the following parameters:
namespace
:rdk
type
:service
subtype
: any one of these service proto files, for examplenavigation
Tutorials creating modules
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!