Create a module

If your physical or virtual hardware is not already supported by an existing module, you can create a new module to add support for it. You can keep the module private or share it with your organization or the public. You can use built-in tools to manage versioning and deployment to machines as you iterate on your module.

This page provides instructions for creating and uploading 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.

Write your module

Generate stub files

The easiest way to generate the files for your module is to use the Viam CLI:

1. Install the Viam CLI and authenticate to Viam, from the same machine that you intend to upload your module from.

   Install the Viam CLI and authenticate

   • macOS
   • Linux aarch64
   • Linux x86_64
   • Windows
   • Source

   To download the Viam CLI on a macOS computer, install brew and run the following commands:

   brew tap viamrobotics/brews
   brew install viam
   

   To download the Viam CLI on a Linux computer with the aarch64 architecture, run the following commands:

   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
   

   To download the Viam CLI on a Linux computer with the amd64 (Intel x86_64) architecture, run the following commands:

   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
   

   You can also install the Viam CLI using brew on Linux amd64 (Intel x86_64):

   brew tap viamrobotics/brews
   brew install viam
   

   Download the binary and run it directly to use the Viam CLI on a Windows computer.

   If you have Go installed, you can build the Viam CLI directly from source using the go install command:

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

   To confirm viam is installed and ready to use, issue the viam command from your terminal. If you see help instructions, everything is correctly installed. If you do not see help instructions, add your local go/bin/* directory to your PATH variable. If you use bash as your shell, you can use the following command:

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

   For more information see install the Viam CLI.

   Authenticate your CLI session with Viam using one of the following options:

   • Personal access token
   • API key

   viam login
   

   This will open a new browser window with a prompt to start the authentication process. If a browser window does not open, the CLI will present a URL for you to manually open in your browser. Follow the instructions to complete the authentication process.

   Use your organization, location, or machine part API key and corresponding API key ID in the following command:

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

2. Run the module generate command in your terminal. If you are writing your module using Python, you must have Python version 3.11 or newer installed on your computer for this command to work:

   viam module generate
   

3. Follow the prompts.

   Click for more details about each prompt

   Prompt	Description
   Module name	The module name describes the module or the family of devices it supports. It is generally the same as the name of the GitHub repo where you will put your module code.
   Language	The language for the module.
   Visibility	Choose Private to share only with your organization, or Public to share publicly with all organizations. If you are testing, choose Private.
   Namespace/Organization ID	In the Viam app, navigate to your organization settings through the menu in upper right corner of the page. Find the Public namespace (or create one if you haven’t already) and copy that string. If you use the organization ID, you must still create a public namespace first.
   Resource to add to the module (API)	The component API your module will implement. See How to design your module for more information.
   Model name	Name your component model based on what it supports, for example, if it supports a model of ultrasonic sensor called “XYZ Sensor 1234” you could call your model xyz_1234 or similar. Must be all-lowercase and use only alphanumeric characters (a-z and 0-9), hyphens (-), and underscores (_).
   Enable cloud build	If you select Yes (recommended) and push the generated files (including the .github folder) and create a release of the format vX.X.X, the module will build and upload to the Viam registry and be available for all Viam-supported architectures without you needing to build for each architecture. Yes also makes it easier to upload using PyInstaller by creating a build entrypoint script. You can select No if you will always build the module yourself before uploading it.
   Register module	Select Yes unless you are creating a local-only module for testing purposes and do not intend to upload it. Registering a module makes its name and metadata appear in the Viam app registry page; uploading the actual code that powers the module is a separate step. If you decline to register the module at this point, you can run viam module create to register it later.

The generator will create a folder containing stub files for your modular sensor component. In the next section, you’ll customize some of the generated files to support your sensor.

Creating multiple models within one module

If you have multiple modular components that are related to or even dependent upon each other, you can opt to put them all into one module. Note that each model can implement only one API. For an example of how this is done, see Create a Hello World module.

Implement the component API

Edit the generated files to add your logic:

import asyncio
from typing import Any, ClassVar, Final, Mapping, Optional, Sequence

from typing_extensions import Self
from viam.components.sensor import Sensor
from viam.module.module import Module
from viam.proto.app.robot import ComponentConfig
from viam.proto.common import ResourceName
from viam.resource.base import ResourceBase
from viam.resource.easy_resource import EasyResource
from viam.resource.types import Model, ModelFamily
from viam.utils import SensorReading, struct_to_dict

import openmeteo_requests
import requests_cache
from retry_requests import retry


class meteo_PM(Sensor, EasyResource):
    MODEL: ClassVar[Model] = Model(
      ModelFamily("jessamy", "weather"), "meteo_PM")

    @classmethod
    def new(
        cls, config: ComponentConfig, dependencies: Mapping[
          ResourceName, ResourceBase]
    ) -> Self:
        """This method creates a new instance of this Sensor component.
        The default implementation sets the name from the `config` parameter
        and then calls `reconfigure`.
        """
        return super().new(config, dependencies)

    @classmethod
    def validate_config(cls, config: ComponentConfig) -> Sequence[str]:
        """This method allows you to validate the configuration object
        received from the machine, as well as to return any
        dependencies based on that `config`.
        """
        fields = config.attributes.fields
        # Check that configured fields are floats
        if "latitude" in fields:
            if not fields["latitude"].HasField("number_value"):
                raise Exception("Latitude must be a float.")

        if "longitude" in fields:
            if not fields["longitude"].HasField("number_value"):
                raise Exception("Longitude must be a float.")
        return []

    def reconfigure(
        self, config: ComponentConfig, dependencies: Mapping[
          ResourceName, ResourceBase]
    ):
        """This method allows you to dynamically update your service
        when it receives a new `config` object.
        """
        attrs = struct_to_dict(config.attributes)

        self.latitude = float(attrs.get("latitude", 45))
        self.logger.debug("Using latitude: " + str(self.latitude))

        self.longitude = float(attrs.get("longitude", -121))
        self.logger.debug("Using longitude: " + str(self.longitude))
        return super().reconfigure(config, dependencies)

    async def get_readings(
        self,
        *,
        extra: Optional[Mapping[str, Any]] = None,
        timeout: Optional[float] = None,
        **kwargs
    ) -> Mapping[str, SensorReading]:
        # Set up the Open-Meteo API client with cache and retry on error
        cache_session = requests_cache.CachedSession(
          '.cache', expire_after=3600)
        retry_session = retry(cache_session, retries=5, backoff_factor=0.2)
        openmeteo = openmeteo_requests.Client(session=retry_session)

        # The order of variables in hourly or daily is
        # important to assign them correctly below
        url = "https://air-quality-api.open-meteo.com/v1/air-quality"
        params = {
            "latitude": self.latitude,
            "longitude": self.longitude,
            "current": ["pm10", "pm2_5"],
            "timezone": "America/Los_Angeles"
        }
        responses = openmeteo.weather_api(url, params=params)

        # Process location
        response = responses[0]

        # Current values. The order of variables needs
        # to be the same as requested.
        current = response.Current()
        current_pm10 = current.Variables(0).Value()
        current_pm2_5 = current.Variables(1).Value()

        self.logger.info(current_pm2_5)

        # Return a dictionary of the readings
        return {
            "pm2_5": current_pm2_5,
            "pm10": current_pm10
        }


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

# Within some method, log information:
self.logger.debug("debug info")
self.logger.info("info")
self.logger.warn("warning info")
self.logger.error("error info")
self.logger.exception("error info", exc_info=True)
self.logger.critical("critical info")

# In your import block, import the logging package:
from viam.logging import getLogger

# Before your first class or function, define the LOGGER variable:
LOGGER = getLogger(__name__)

# in some method, log information
LOGGER.debug("debug info")
LOGGER.info("info info")
LOGGER.warn("warn info")
LOGGER.error("error info")
LOGGER.exception("error info", exc_info=True)
LOGGER.critical("critical info")

package hello_world

import (
  "context"
  "errors"
  "os"
  "reflect"

  "go.viam.com/rdk/components/camera"
  "go.viam.com/rdk/logging"
  "go.viam.com/rdk/pointcloud"
  "go.viam.com/rdk/resource"
  "go.viam.com/utils/rpc"
)

var (
  HelloCamera      = resource.NewModel("jessamy", "hello-world", "hello-camera")
  errUnimplemented = errors.New("unimplemented")
)

func init() {
  resource.RegisterComponent(camera.API, HelloCamera,
    resource.Registration[camera.Camera, *Config]{
      Constructor: newHelloWorldHelloCamera,
    },
  )
}

type Config struct {
  ImagePath    string `json:"image_path"`
  ExampleValue string `json:"example_value"`
}

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

type helloWorldHelloCamera struct {
  resource.AlwaysRebuild // Resource rebuilds instead of reconfiguring

  name resource.Name

  logger logging.Logger
  cfg    *Config

  exampleValue string

  cancelCtx  context.Context
  cancelFunc func()
}

func newHelloWorldHelloCamera(ctx context.Context, deps resource.Dependencies, rawConf resource.Config, logger logging.Logger) (camera.Camera, error) {
  conf, err := resource.NativeConfig[*Config](rawConf)
  if err != nil {
    return nil, err
  }

  cancelCtx, cancelFunc := context.WithCancel(context.Background())

  s := &helloWorldHelloCamera{
    name:       rawConf.ResourceName(),
    logger:     logger,
    cfg:        conf,
    cancelCtx:  cancelCtx,
    cancelFunc: cancelFunc,
}

  s.exampleValue = s.cfg.ExampleValue
  if s.exampleValue == "" {
    s.exampleValue = "default value"
    s.logger.Debug("setting default exampleValue: %s", s.exampleValue)
  }

 return s, nil
}

func (s *helloWorldHelloCamera) Name() resource.Name {
  return s.name
}

func (s *helloWorldHelloCamera) Image(ctx context.Context, mimeType string, extra map[string]interface{}) ([]byte, camera.ImageMetadata, error) {
  imagePath := s.cfg.ImagePath
  imgFile, err := os.Open(imagePath)
  if err != nil {
    return nil, camera.ImageMetadata{}, errors.New("Error opening image.")
  }
  defer imgFile.Close()
  imgByte, err := os.ReadFile(imagePath)
  s.logger.Info("The s.exampleValue is: " + s.exampleValue)
  return imgByte, camera.ImageMetadata{}, nil
}

func (s *helloWorldHelloCamera) NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, name resource.Name, logger logging.Logger) (camera.Camera, error) {
  return nil, errors.New("not implemented")
}

func (s *helloWorldHelloCamera) Images(ctx context.Context) ([]camera.NamedImage, resource.ResponseMetadata, error) {
  return []camera.NamedImage{}, resource.ResponseMetadata{}, errors.New("not implemented")
}

func (s *helloWorldHelloCamera) NextPointCloud(ctx context.Context) (pointcloud.PointCloud, error) {
  return nil, errors.New("not implemented")
}

func (s *helloWorldHelloCamera) Properties(ctx context.Context) (camera.Properties, error) {
  return camera.Properties{}, errors.New("not implemented")
}

func (s *helloWorldHelloCamera) DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error) {
  return map[string]interface{}{}, errors.New("not implemented")
}

func (s *helloWorldHelloCamera) Close(context.Context) error {
  s.cancelFunc()
  return nil
}

fn (c *component) someFunction(ctx context.Context, a int) {
  // Log with severity info:
  c.logger.CInfof(ctx, "performing some function with a=%v", a)
  // Log with severity debug (using value wrapping):
  c.logger.CDebugw(ctx, "performing some function", "a" ,a)
  // Log with severity warn:
  c.logger.CWarnw(ctx, "encountered warning for component", "name", c.Name())
  // Log with severity error without a parameter:
  c.logger.CError(ctx, "encountered an error")
}

Test your module locally

It’s a good idea to test your module locally before uploading it to the Viam Registry. You’ll configure it through the Viam app, but the configured module will consist of local files.

1

Prepare to run your module

• Python: Hot reloading (recommended)
• Python: venv
• Go

If you enabled cloud build, use these steps.

1. Create a reload.sh script in your module directory. You’ll use this for local testing and can delete it before you upload your module. Paste the following contents into it and save the file:

   #!/usr/bin/env bash
   
    # bash safe mode. look at `set --help` to see what these are doing
    set -euxo pipefail
   
    cd $(dirname $0)
    MODULE_DIR=$(dirname $0)
    VIRTUAL_ENV=$MODULE_DIR/venv
    PYTHON=$VIRTUAL_ENV/bin/python
    ./setup.sh
   
    # Be sure to use `exec` so that termination signals reach the python process,
    # or handle forwarding termination signals manually
    exec $PYTHON src/main.py $@
   

2. Make your reload script executable by running the following command in your module directory:

   chmod 755 reload.sh
   

3. Create a virtual Python environment with the necessary packages by running the setup file from within the module directory:

   sh setup.sh
   

4. Edit your meta.json, replacing the "entrypoint", "build", and "path" fields as follows:

     "entrypoint": "reload.sh",
     "first_run": "",
     "build": {
       "build": "rm -f module.tar.gz && tar czf module.tar.gz requirements.txt src/*.py src/models/*.py meta.json setup.sh reload.sh",
       "setup": "./setup.sh",
       "path": "module.tar.gz",
       "arch": [
         "linux/amd64",
         "linux/arm64"
       ]
     }
   

Create a virtual Python environment with the necessary packages by running the setup file from within the module directory:

sh setup.sh

This environment is where the local module will run. viam-server does not need to run inside this environment.

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

make setup
viam module build local

2

Configure your local module on a machine

• Python: Hot reloading (recommended)
• Python: venv
• Go

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

viam module reload <insert relevant named args>

Reload example commands

For example, to run on your development machine:

viam module reload --local

Or to run on a different machine (such as a single-board computer), specify the part ID of the remote machine:

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

For more information, run the command with the -h flag or see the CLI 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 in the Viam app 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/jessamy/ 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 in your machine’s CONFIGURE tab in the Viam app. In upper right corner of the module’s card, click the … menu, then click Restart.

When you run viam module reload, the module will be added to your device automatically.

On your machine’s CONFIGURE tab in the Viam app, click the + (create) icon in the left-hand menu. Select Local module, then Local module.

Enter the absolute path to the run.sh script, for example /home/jessamy/my-module/run.sh on Linux, or /Users/jessamy/my-python-sensor-module/run.sh on macOS. For modules configured this way, viam-server uses this path instead of the entrypoint field in your meta.json file.

Click Create.

On your machine’s CONFIGURE tab in the Viam app, click the + (create) icon in the left-hand menu. Select Local module, then Local module.

Enter the absolute path to the /bin/<module-name> executable, for example /home/jessamy/my-go-module/bin/mymodule on Linux, or /Users/jessamy/my-go-module/bin/mymodule on macOS. For modules configured this way, viam-server uses this path instead of the entrypoint field in your meta.json file.

Click Create.

3

Configure the model provided by your module

Click the + button again, this time selecting Local module and then Local component.

Select or enter the model namespace triplet, for example jessamy:weather:meteo-PM. 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 my-cool-component. Click Create.

Configure any required attributes using proper JSON syntax.

4

Test the component

Click the TEST bar at the bottom of your modular component configuration, and check whether it works as expected. For example, if you created a sensor component, check whether readings are displayed.

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:

• Python: PyInstaller (recommended)
• Python: venv
• Go

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

viam module reload <insert relevant named args>

Since you are using run.sh instead of a built executable, you do not need to rebuild anything as you iterate. Just save your code changes, then restart the module in your machine’s CONFIGURE tab in the Viam app: In 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 Viam app. In upper right corner of the module’s card, click … menu, then click Restart.

See Using the build subcommand for advanced build options.

Upload your module

Once you are done testing locally, you can upload your module to the Viam Registry and make it available either to all machines in your organization, or to the general public.

# `meteo_PM` modular component

This module implements the [Viam sensor API](https://docs.viam.com/dev/reference/apis/components/sensor/) in a `jessamy:weather:meteo_PM` model.
With this model, you can gather [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api) PM2.5 and PM10 air quality data from anywhere in the world, at the coordinates you specify.

Navigate to the **CONFIGURE** tab of your machine's page in the [Viam app](https://app.viam.com/).
Click the **+** button, select **Component or service**, then select the `sensor / weather:meteo_PM` model provided by the [`weather` module](https://app.viam.com/module/jessamy/weather).
Click **Add module**, enter a name for your sensor, and click **Create**.

## Configure your `meteo_PM` sensor

On the new component panel, copy and paste the following attribute template into your sensor's **Attributes** box:

```json
{
  "latitude": <float>,
  "longitude": <float>
}
```

### Attributes

The following attributes are available for `rdk:sensor:jessamy:weather:meteo_PM` sensors:

| Name        | Type  | Inclusion | Description                            |
| ----------- | ----- | --------- | -------------------------------------- |
| `latitude`  | float | Optional  | Latitude at which to get the readings  |
| `longitude` | float | Optional  | Longitude at which to get the readings |

### Example Configuration

```json
{
  "latitude": -40.6,
  "longitude": 93.125
}
```

 "entrypoint": "dist/main",
 "first_run": "",
 "build": {
   "build": "./build.sh",
   "setup": "./setup.sh",
   "path": "dist/archive.tar.gz",
   "arch": [
     "linux/amd64",
     "linux/arm64"
   ]
 }

sh setup.sh
sh build.sh

viam module upload --version 1.0.0 --platform any dist/archive.tar.gz

viam module upload --version 1.0.0 --platform <platform> .

Use your uploaded module

Now that your module is in the registry, you can test the registry version of your module on one machine, and then add it to more machines. Configure it just as you would configure any other component or service in the registry:

1. Go to your machine’s CONFIGURE tab in the Viam app.

2. Click the + button, select Component or service, and search for and select your model.

3. Click Add module, enter a name for your resource, and click Create.

4. Configure any required attributes.

5. Save your configuration.

You can delete the local module; it is no longer needed.