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:

Model
Description

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

API
Model
Description

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:

  1. Create a module with one or more modular resources by implementing all methods for the component’s or service’s standardized API.
  2. 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.
  3. 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 with acme, like acme:repo-name:mybase.
  • Your model triplet must be all-lowercase.
  • Your model triplet may only use alphanumeric (a-z and 0-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 the rand:yahboom:gripper model use the repository name yahboom. The models implement the rdk:component:arm and the rdk: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 API viam-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:

When implementing a custom model of an existing service, valid APIs always have the following parameters:

Tutorials creating modules