Part 1: Prerequisites and setup

Part 1 of 5 | ⏱️ 15-20 minutes

In this tutorial series, you’ll learn how to create a custom module to add support for hardware that isn’t already supported by existing registry modules.

What you’ll do in this part

• Install and authenticate the Viam CLI
• Set up a test machine (optional but recommended)
• Verify your development environment (Python 3.11+ or Go 1.20+)
• Write a test script to verify hardware connectivity
• Understand the module architecture

What you’ll build

Throughout this tutorial series, you’ll create a hello-world module that demonstrates two common module capabilities:

1. Camera model: Returns an image from a configured file path
2. Sensor model: Returns a random number reading

This example shows how to implement multiple resources within a single module.

Prerequisites

Before you begin, make sure you have the following:

1. Install and authenticate the Viam CLI

The Viam CLI is required to generate module code and upload modules to the registry.

Install the Viam CLI on your development machine:

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

For more information see install the Viam CLI.

Verify installation:

viam version

You should see output like: viam version 0.x.x

Authenticate to Viam:

viam login

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

2. Set up a machine for testing

While you can develop a module without a machine, you’ll need one to test your module.

Add a new machine on Viam. On the machine’s page, follow the setup instructions to install viam-server on the computer you’re using for your project. Wait until your machine has successfully connected to Viam.

Already have a machine? Great! You’ll configure it in Part 4.

3. Development environment

Your module can be written in Python or Go. Choose your preferred language and verify your environment:

python3 --version

go version

Write a test script

Before writing a module, it’s helpful to write a simple test script to verify you can control your hardware.

For the example module, this script opens an image file and prints 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)

python3 test.py

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)
}

go run test.go

Understanding module architecture

A module is essentially a packaged wrapper around your hardware control code. The module:

1. Registers with viam-server when it starts
2. Validates user configuration when they add your component
3. Implements standard Viam API methods (like GetImages for cameras)
4. Communicates with your hardware using your control code

In Part 2, you’ll choose which Viam API best matches your hardware’s capabilities.

What you’ve accomplished

Environment ready:

• Viam CLI installed and authenticated
• Machine set up for testing (optional)
• Development environment verified (Python 3.11+ or Go 1.20+)
• Test script working

Understanding:

• What modules are and why you’d create one
• Basic module architecture

Next steps

Now that your environment is ready, continue to Part 2: Choose an API and generate code to select the right API for your hardware and generate your module structure.

Tutorial navigation:

• Current: Part 1: Prerequisites and setup
• Next: Part 2: Choose an API and generate code →
• All parts: Module creation tutorial