Edit

Add Custom Components as Remote Parts of Your Machine

Running modular resources on the board directly connected to your components is the preferred way of managing and controlling custom components.

However, if you are unable to use modular resources because you need to host viam-server on a non-Linux system or have an issue with compilation, you can use a Viam SDK to code a custom resource implementation, host it on a server, and add it as a remote part of your machine.

Once you have coded your custom component and configured the remote servers, you can control and monitor your component with the Viam SDKs, like any other component.

To show how to create a custom resource, the following example creates an arm as a custom component and registers the new arm model with a Viam SDK. Then you can control it as part of your machine with the same API methods available for arm models built into the RDK.

Instructions

To add a custom resource as a remote part:

Go
Python

Code a new model of a built-in resource type. You can do this by creating a new interface that implements required methods. The new model must implement any functions of the built-in resource type marked as required in its RDK API definition.
Register the custom component on a new gRPC server instance and start the server.
Add the server as a remote part of your machine.
(Optional) Configure a process to launch this remote server to ensure the remote server is always running alongside the rest of your machine.

Each remote server can host one or many custom components.

Tip

For more detailed instructions, see the full example in the Python SDK documentation.

Code a new model of a built-in resource type. You can do this by subclassing a built in resource type like sensor or arm. The new model must implement any methods of the built-in resource type marked as required in its RDK API definition.
Register the custom component on a new gRPC server instance and start the server. You can do this with the viam.rpc library by creating a new rpc.server.Server instance.
Add the server as a remote part of your machine.
(Optional) Configure a process to launch this remote server to ensure the remote server is always running alongside the rest of your machine.

Each remote server can host one or many custom components.

Important

You must define all methods belonging to a built-in resource type when defining a new model. Otherwise, the class will not instantiate.

If you are using the Python SDK, raise an NotImplementedError() in the body of functions you do not want to implement or put pass.
If you are using the Go SDK, return errUnimplemented.
Additionally, return any values designated in the function’s return signature, typed correctly.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.

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!