Support additional hardware and software

If your physical or virtual hardware is not supported by an existing registry module, you can create a new module to add support for it.

This page provides instructions for creating a module in Python or Go. For C++ module examples, see the C++ examples directory on GitHub. If you want to create a module for use with a microcontroller, see Modules for ESP32.

Example module: With each step of this guide, you have instructions for creating a module which does two things:

1. Gets an image from a configured path on your machine
2. Returns a random number

Prerequisites

brew tap viamrobotics/brews
brew install viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

brew tap viamrobotics/brews
brew install viam

go install go.viam.com/rdk/cli/viam@latest

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

viam login

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

Preparation

While not required, we recommend starting by writing a test script to check that you can connect to and control your hardware from your computer, perhaps using the manufacturer’s API or other low-level code.

Example module: For the example module, the test script will open an image in the same directory and print a random number.

import random
from PIL import Image

# Open an image
img = Image.open("example.png")
img.show()

# Return a random number
random_number = random.random()
print(random_number)

package main

import (
  "fmt"
  "math/rand"
  "os"
)

func main() {
  // Open an image
  imgFile, err := os.Open("example.png")
  if err != nil {
    fmt.Printf("Error opening image file: %v\n", err)
    return
  }
  defer imgFile.Close()
  imgByte, err := os.ReadFile("example.png")
  fmt.Printf("Image file type: %T\n", imgByte)
  if err != nil {
    fmt.Printf("Error reading image file: %v\n", err)
    return
  }

  // Return a random number
  number := rand.Float64()
  fmt.Printf("Random number: %f\n", number)
}

Choose an API

You can think of a module as a packaged wrapper around a script. The module takes the functionality of the script and maps it to a standardized API for use within the Viam ecosystem.

Review the available component APIs and choose the one whose methods map most closely to the functionality you need.

If you need a method that is not in your chosen API, you can use the flexible DoCommand (which is built into all component APIs) to create custom commands. See Run control logic for more information.

Example module: To choose the Viam APIs that make sense for your module, think about the functionality you want to implement. You need a way to return an image and you need a way to return a number.

If you look at the camera API, you can see the GetImage method, which returns an image. That will work for the image.

The camera API also has a few other methods. You do not need to fully implement all the methods of an API. For example, this camera does not use point cloud data, so for methods like GetPointCloud it will return an “unimplemented” error.

The sensor API includes the GetReadings method. You can return the random number with that.

Note that the camera API can’t return a number and the sensor API can’t return an image. Each model can implement only one API, but your module can contain multiple modular resources. Therefore it is best to make two modular resources: a camera to return the image and a sensor to return a random number.

Write your module

Generate stub files

Use the Viam CLI to generate template files for your module:

viam module generate

viam module generate --language python --model-name hello-camera \
  --name hello-world --resource-subtype=camera --public false \
  --enable-cloud true

viam module generate --language go --model-name hello-camera \
  --name hello-world --resource-subtype=camera --public false \
  --enable-cloud true

hello-world/
└── src/
|   ├── models/
|   |   └── hello_camera.py
|   └── main.py
└── README.md
└── build.sh
└── meta.json
└── requirements.txt
└── run.sh
└── setup.sh

hello-world/
└── cmd/
|   ├── cli/
|   |   └── main.go
|   └── module/
|       └── main.go
└── Makefile
└── README.md
└── go.mod
└── module.go
└── meta.json

Creating multiple models within one module

Some of the code you generated for your first modular resource is shared across the module no matter how many modular resource models it supports. Some of the code you generated is resource-specific.

If you have multiple modular resources that are related, you can put them all into the same module.

For convenience, we recommend running the module generator again from within the first module’s directory, generating an unregistered module, and copying the resource-specific code from it.

Example module: Change directory into the first module’s directory:

cd hello-world

Run the following command from within the first module’s directory to generate temporary code you can copy from. Do not register this module.

viam module generate --language python --model-name hello-sensor \
  --name hello-world --resource-subtype=sensor --public false \
  --enable-cloud true

import asyncio

from viam.module.module import Module
try:
    from models.hello_camera import HelloCamera
    from models.hello_sensor import HelloSensor
except ModuleNotFoundError:  # when running as local module with run.sh
    from .models.hello_camera import HelloCamera
    from .models.hello_sensor import HelloSensor

if __name__ == '__main__':
    asyncio.run(Module.run_from_registry())

{
  "$schema": "https://dl.viam.dev/module.schema.json",
  "module_id": "exampleorg:hello-world",
  "visibility": "private",
  "url": "",
  "description": "Example camera and sensor components: hello-camera and hello-sensor",
  "models": [
    {
      "api": "rdk:component:camera",
      "model": "exampleorg:hello-world:hello-camera",
      "short_description": "A camera that returns an image.",
      "markdown_link": "README.md#model-exampleorghello-worldhello-camera"
    },
    {
      "api": "rdk:component:sensor",
      "model": "exampleorg:hello-world:hello-sensor",
      "short_description": "A sensor that returns a random number.",
      "markdown_link": "README.md#model-exampleorghello-worldhello-sensor"
    }
  ],
  "applications": null,
  "markdown_link": "README.md",
  "entrypoint": "./run.sh",
  "first_run": "",
  "build": {
    "build": "./build.sh",
    "setup": "./setup.sh",
    "path": "dist/archive.tar.gz",
    "arch": ["linux/amd64", "linux/arm64", "darwin/arm64", "windows/amd64"]
  }
}

viam module generate --language go --model-name hello-sensor \
  --name hello-world --resource-subtype=sensor --public false \
  --enable-cloud true

package main

import (
    "helloworld"
    "go.viam.com/rdk/module"
    "go.viam.com/rdk/resource"
    camera "go.viam.com/rdk/components/camera"
    sensor "go.viam.com/rdk/components/sensor"
)

func main() {
    // ModularMain can take multiple APIModel arguments, if your module implements multiple models.
    module.ModularMain(
      resource.APIModel{ camera.API, helloworld.HelloCamera},
      resource.APIModel{ sensor.API, helloworld.HelloSensor},
    )
}

{
  "$schema": "https://dl.viam.dev/module.schema.json",
  "module_id": "exampleorg:hello-world",
  "visibility": "private",
  "url": "",
  "description": "Example camera and sensor components: hello-camera and hello-sensor",
  "models": [
    {
      "api": "rdk:component:camera",
      "model": "exampleorg:hello-world:hello-camera",
      "short_description": "A camera that returns an image.",
      "markdown_link": "README.md#model-exampleorghello-worldhello-camera"
    },
    {
      "api": "rdk:component:sensor",
      "model": "exampleorg:hello-world:hello-sensor",
      "short_description": "A sensor that returns a random number.",
      "markdown_link": "README.md#model-exampleorghello-worldhello-sensor"
    }
  ],
  "applications": null,
  "markdown_link": "README.md",
  "entrypoint": "bin/hello-world",
  "first_run": "",
  "build": {
    "build": "make module.tar.gz",
    "setup": "make setup",
    "path": "module.tar.gz",
    "arch": ["linux/amd64", "linux/arm64", "darwin/arm64", "windows/amd64"]
  }
}

You can now delete the temporary hello-world/hello-world directory and all its contents.

Implement the components

At this point you have a template for your module.

If you want to see example modules, check out the Viam Registry. Many modules have a linked GitHub repo, where you can see the module’s code. When logged in, you can also download the module’s source code to inspect it.

Example module: You can view complete example code in the hello-world-module repository on GitHub.

Set up model configuration options

Many resource models have configuration options that allow you to specify options such as:

• A file path from which to access data
• A pin to which a device is wired
• An optional signal frequency to override a default value
• The name of another resource you wish to use in the model

Model configuration happens in two steps:

{
  "image_path": "/path/to/file"
}

    @classmethod
    def validate_config(
        cls, config: ComponentConfig
    ) -> Tuple[Sequence[str], Sequence[str]]:
        # Check that a path to get an image was configured
        fields = config.attributes.fields
        if "image_path" not in fields:
            raise Exception("Missing image_path attribute.")
        elif not fields["image_path"].HasField("string_value"):
            raise Exception("image_path must be a string.")

        return [], []

func (cfg *Config) Validate(path string) ([]string, []string, error) {
    var deps []string
    if cfg.ImagePath == "" {
        return nil, nil, resource.NewConfigValidationFieldRequiredError(path, "image_path")
    }
    if reflect.TypeOf(cfg.ImagePath).Kind() != reflect.String {
        return nil, nil, errors.New("image_path must be a string.")
    }
    imagePath = cfg.ImagePath
    return deps, []string{}, nil
}

"reflect"

Implement API methods

Depending on the component API you are implementing, you can implement different API methods.

    async def get_images(
        self,
        *,
        filter_source_names: Optional[Sequence[str]] = None,
        extra: Optional[Dict[str, Any]] = None,
        timeout: Optional[float] = None,
        **kwargs
    ) -> Tuple[Sequence[NamedImage], ResponseMetadata]:
        img = Image.open(self.image_path)
        vi_img = pil_to_viam_image(img, CameraMimeType.JPEG)
        named = NamedImage("default", vi_img.data, vi_img.mime_type)
        metadata = ResponseMetadata()
        return [named], metadata

from viam.media.utils.pil import pil_to_viam_image
from viam.media.video import CameraMimeType
from PIL import Image

Pillow

    async def get_readings(
        self,
        *,
        extra: Optional[Mapping[str, Any]] = None,
        timeout: Optional[float] = None,
        **kwargs
    ) -> Mapping[str, SensorReading]:
        number = random.random()
        return {
            "random_number": number
        }

import random

import asyncio
from viam.module.module import Module
try:
    from models.hello_camera import HelloCamera
except ModuleNotFoundError:
    # when running as local module with run.sh
    from .models.hello_camera import HelloCamera

if __name__ == '__main__':
    asyncio.run(Module.run_from_registry())

func (s *helloWorldHelloCamera) Images(ctx context.Context, filterSourceNames []string, extra map[string]interface{}) ([]camera.NamedImage, resource.ResponseMetadata, error) {
    var responseMetadataRetVal resource.ResponseMetadata

    imgFile, err := os.Open(imagePath)
    if err != nil {
        return nil, responseMetadataRetVal, errors.New("Error opening image.")
    }
    defer imgFile.Close()

    imgByte, err := os.ReadFile(imagePath)
    if err != nil {
        return nil, responseMetadataRetVal, err
    }

    named, err := camera.NamedImageFromBytes(imgByte, "default", "image/png")
    if err != nil {
        return nil, responseMetadataRetVal, err
    }

    return []camera.NamedImage{named}, responseMetadataRetVal, nil
}

"os"

func (s *helloWorldHelloSensor) Readings(ctx context.Context, extra map[string]interface{}) (map[string]interface{}, error) {
    number := rand.Float64()
    return map[string]interface{}{
        "random_number": number,
    }, nil
}

"math/rand"

Test your module locally

You can test your module locally before uploading it to the registry. You can configure it in the web UI using the local files on your machine.

Add module to machine

To get your module onto your machine, hot reloading builds and packages it and then uses the shell service to copy it to the machine for testing. If you are using a Python virtual environment (venv), make sure your module files are on the same device where viam-server is running, and add the module manually instead.

• Hot reloading (recommended)
• Manual (required for Python venv)

Run the following command to build the module and add it to your machine:

• Same device
• Other device

viam module reload-local --cloud-config /path/to/viam.json

viam module reload --part-id 123abc45-1234-432c-aabc-z1y111x23a00

For more information, see the viam module documentation.

Reload troubleshooting

• Error: Could not connect to machine part: context deadline exceeded; context deadline exceeded; mDNS query failed to find a candidate

  Try specifying the --part-id, which you can find by clicking the Live indicator on your machine’s page and clicking Part ID.

• Error: Rpc error: code = Unknown desc = stat /root/.viam/packages-local: no such file or directory

  Try specifying the --home directory, for example /Users/yourname/ on macOS.

• Error: Error while refreshing token, logging out. Please log in again

  Run viam login to reauthenticate the CLI.

Try using a different command

If you are still having problems with the reload command, you can use a different, slower method of rebuilding and then restarting the module. Run the following command to rebuild your module:

viam module build local

Then restart it on your machine’s CONFIGURE tab. In the upper-right corner of the module’s card, click the … menu, then click Restart.

Refresh

You may need to refresh your machine page for your module to show up.

Navigate to your machine’s CONFIGURE page.

• Python
• Go

Click the + button, select Local module, then again select Local module.

Enter the path to the automatically-generated run.sh script. Click Create. For local modules, viam-server uses this path to start the module.

Example module: For the hello-world module, the path should resemble /home/yourname/hello-world/run.sh on Linux, or /Users/yourname/hello-world/run.sh on macOS.

Save the config.

From within the module directory, compile your module with the module build command into a single executable:

viam module build local

Click the + button, select Local module, then again select Local module.

Enter the path to the /bin/<module-name> executable. For local modules, viam-server uses this path to start the module.

Example module: For the hello-world module, the path should resemble /home/yourname/hello-world/bin/hello-world.

Click Create.

Save the config.

Add local model

1

Configure the model provided by your module

On your machine’s CONFIGURE page, click +, click Local module, then click Local component or Local service.

Select or enter the model namespace triplet, for example exampleorg:hello-world:hello-camera. You can find the triplet in the model field of your meta.json file.

Select the Type corresponding to the API you implemented.

Enter a Name such as camera-1. Click Create.

2

Configure attributes

When you add a new component or service, a panel appears for it on the CONFIGURE tab. If your model has required or optional attributes, configure them in the configuration field by adding them inside the {} object.

Example module: For the camera model, add the image_path attribute by replacing {} with:

{
  "image_path": "<replace with the path to your image>"
}

3

Save the config and wait a few seconds for it to apply.

Then click the TEST section of the camera’s configuration card. If there are errors you will see them on the configuration panel and on the LOGS tab.

4

Test the component

Click the TEST bar at the bottom of your modular component configuration, and check whether it works as expected.

Example module: For the camera model, the test panel should show the image:

If you also implemented the sensor model, add and test it the same way.

5

Iterate

If your component works, you’re almost ready to share your module by uploading it to the registry. If not, you have some debugging to do.

Each time you make changes to your local module code, you need to update its instance on your machine:

• Hot reloading (recommended)
• Manual (required for Python venv)

Run the reload command again to rebuild and restart your module:

• Same device
• Other device

viam module reload-local --cloud-config /path/to/viam.json

viam module reload --part-id 123abc45-1234-432c-aabc-z1y111x23a00

• Python
• Go

As you iterate, save the code changes, then restart the module in your machine’s CONFIGURE tab: In the upper-right corner of the module’s card, click … menu, then click Restart.

Run the following command to rebuild your module:

viam module build local

Then restart it in your machine’s CONFIGURE tab. In the upper-right corner of the module’s card, click … menu, then click Restart.

Next steps

Once you have thoroughly tested your module, continue to package and deploy it.