Create a Hello World module

This guide will walk you through creating a modular camera component that responds to API calls by returning a configured image. This guide also includes optional steps to create a modular sensor that returns random numbers, to demonstrate how you can include two modular resources within one module. By the end of this guide, you will be able to create your own modular resources and package them into modules so you can use them on your machines.

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>

Create a test script

The point of creating a module is to add functionality to your machine. For the purposes of this guide, you’re going to make a module that does two things: It opens an image file from a configured path on your machine, and it returns a random number.

1. Find an image you’d like to display when your program runs. We used this image of a computer with “hello world” on the screen. Save the image to your computer.

2. Create a test script on your computer and copy the following code into it:

   • Python
   • Go

   # test.py opens an image and prints a random number
   from PIL import Image
   import random
   
   # TODO: Replace path with path to where you saved your photo
   photo = Image.open("/Users/jessamyt/Downloads/hello-world.jpg")
   
   photo.show()
   
   number = random.random()
   
   print("Hello, World! The latest random number is ", number, ".")
   

   // test.go opens an image and prints a random number
   package main
   
   import (
     "os"
     "os/exec"
     "fmt"
     "math/rand"
   )
   
   func main() {
   
     // TODO: Replace path string with path to where you saved your photo
     imagePath := "/Users/jessamyt/Downloads/hello-world.jpg"
     file, err := os.Open(imagePath)
     if err != nil {
       fmt.Println("Error opening image:", err)
       return
     }
     defer file.Close()
   
     // "open" works on macOS.
     // For Linux, replace "open" with "xdg-open".
     err = exec.Command("open", imagePath).Start()
     if err != nil {
       fmt.Println("Error opening image viewer:", err)
     }
   
     number := rand.Float64()
     fmt.Println("Hello, World! The latest random number is ", number, ".")
   }
   

3. Replace the path in the script above with the path to where you saved your photo. Save the script.

4. Run the test script in your terminal:

   • Python
   • Go

   It’s best practice to use a virtual environment for running Python scripts. You’ll also need to install the dependency Pillow in the virtual environment before running the test script.

   python3 -m venv .venv
   source .venv/bin/activate
   pip install Pillow
   python3 test.py
   

   The image you saved should open on your screen, and a random number should print to your terminal.

   In later steps, the module generator will create a new virtual environment with required dependencies, so you can deactivate the one you just ran the test script in:

   deactivate
   

   go run test.go
   

   The image you saved should open on your screen, and a random number should print to your terminal.

Choose an API to implement

Now it’s time to decide which Viam APIs make sense for your module. 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. None of the camera API methods return a number though.

Look at the sensor API, which includes the GetReadings method. You can return a number with that, but the sensor API can’t return an image.

Your module can contain multiple modular resources, so let’s make two modular resources: a camera to return the image, and a sensor to return a random number.

Generate stub files

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

Generate the camera files

The CLI module generator generates the files for one modular resource at a time. First let’s generate the camera component files, and we’ll add the sensor code later.

1. Run the module generate command in your terminal:

   viam module generate
   

2. Follow the prompts, selecting the following options:

   • Module name: hello-world
   • Language: Your choice
   • Visibility: 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 and copy that string. In the example snippets below, the namespace is jessamy.
   • Resource to add to the module (API): Camera Component. We will add the sensor later.
   • Model name: hello-camera
   • Enable cloud build: No
   • Register module: Yes

3. Hit your Enter key and the generator will generate a folder called hello-world containing stub files for your modular camera component.

Generate the sensor code

Implement the API methods

Edit the stub files to add the logic from your test script in a way that works with the camera and sensor APIs:

Test your module

With the implementation written, it’s time to test your module locally:

2. Make sure your machine’s instance of viam-server is live and connected to the Viam app.

3. In the Viam app, navigate to your machine’s CONFIGURE page.

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

6. Now add the modular camera resource provided by the module:

   Click +, click Local module, then click Local component.

   For the model namespace triplet, select or enter <namespace>:hello-world:hello-camera, replacing <namespace> with the organization namespace you used when generating the stub files. For example, jessamy:hello-world:hello-camera.

   For type, enter camera.

   For name, you can use the automatic camera-1.

7. Configure the image path attribute by pasting the following in place of the {} brackets:

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

   Replace the path with the path to your image, for example "/Users/jessamyt/Downloads/hello-world.jpg".

8. Save the config, then click the TEST section of the camera’s configuration card.

   

   You should see your image displayed. If not, check the LOGS tab for errors.

Package and upload the module

You now have a working local module. To make it available to deploy on more machines, you can package it and upload it to the Viam Registry.

The hello world module you created is for learning purposes, not to provide any meaningful utility, so we recommend making it available only to machines within your organization instead of making it publicly available.

To package (for Python) and upload your module and make it available to configure on machines in your organization:

viam module upload --version 1.0.0 --platform any .

Now, if you look at the Viam Registry page while logged into your account, you’ll be able to find your private module listed. Because the module is now in the registry, you can configure the hello-sensor and hello-camera on your machines just as you would configure other components and services; there’s no more need for local module configuration. The local module configuration is primarily for testing purposes.

For more information about uploading modules, see Update and manage modules you created.

Next steps

For more module creation information, see the Integrate other hardware guide.

To update or delete a module, see Update and manage modules.