Viam Simple Module Example

This example goes through how to create custom modular resources using Viam's Python SDK, and how to connect it to a machine.

This is a limited document. For a more in-depth understanding of modules, see the documentation.

Note

You can auto-generate the stub files for your module using the Viam CLI. Install the CLI and authenticate, then run viam module generate and follow the prompts.

Purpose

Modular resources allow you to define custom components and services, and add them to your robot. Viam ships with many component models, but you're not limited to only using those models -- you can add support for other models of hardware and software using modules.

For more information, see the documentation. For a more complex example, take a look at the complex module example, which contains multiple new APIs and custom resource models.

For a fully fleshed-out example of a Python module that uses Github CI to upload to the Viam Registry, take a look at python-example-module. For an example that uses Docker to manage dependencies, take a look at python-container-module. For a list of example modules in different Viam SDKs, take a look here.

Project structure

The definition of the new resources are in the main file of the src directory.

The run.sh script is the entrypoint for a module and calls the main.py file. The main.py file contains the definition of a new sensor model and code to register it.

It also has the optional validator and reconfiguration functions. The validator function can raise errors that are triggered because of the configuration. It also returns a sequence of strings representing the implicit dependencies of the resource. The reconfiguration function reconfigures the resource based on the new configuration passed in.

When called, the program creates and starts the module. Read further to learn how to connect this module to your robot.

Outside the src directory, there is a client.py file. You can use this file to test the module once you have connected to your robot and configured the module. You will have to update the credentials and robot address in that file.

Configuring and using the module

These steps assume that you have a robot available at app.viam.com.

The run.sh script is the entrypoint for this module. To connect this module with your robot, you must add this module's entrypoint to the robot's config. For example, the entrypoint file may be at /home/viam-python-sdk/examples/simple_module/run.sh and you must add this file path to your configuration. See the documentation for more details.

Once the module has been added to your robot, add a new component that uses the MySensor model. See the documentation for more details.

Models are uniquely namespaced as colon-delimited-triplets in the form namespace:family:name, and are named according to the Viam API that your model implements. A model with the viam namespace is always Viam-provided. Read more about making custom namespaces here.

An example configuration for a Sensor component could look like this:

{
  "components": [
    {
      "name": "sensor1",
      "type": "sensor",
      "model": "viam:sensor:mysensor",
      "attributes": {
        "multiplier": 2
      },
      "depends_on": []
    }
  ],
  "modules": [
    {
      "name": "my-module",
      "executable_path": "/home/viam-python-sdk/examples/simple_module/run.sh"
    }
  ]
}

After the robot has started and connected to the module, you can use the provided client.py to connect to your robot and make calls to your custom, modular resources.