Part 2: Choose an API and generate code

Part 2 of 5 | ⏱️ 15 minutes

What you’ll do in this part

• Understand how modules map hardware to Viam APIs
• Choose the right API for your hardware
• Generate module code using the Viam CLI
• Understand the generated file structure

Choose an API

A module wraps your hardware driver in a standardized Viam API. This means:

• Your hardware works seamlessly with all Viam SDKs
• You can use Viam services (vision, data capture, etc.)
• Configuration is consistent across all components

How to choose

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.

Hardware-to-API mapping guide

Decision process

Step 1: Identify your hardware’s primary function

Step 2: Check if an existing API provides the methods you need

• Full API reference
• Each API has specific methods designed for that type of hardware

Step 3: For multiple functions, create multiple models

• Each model implements one API
• One module can contain many models
• You’ll learn how to do this in Part 5

Example: The hello-world module

Hardware capabilities:

1. Returns an image from a file path
2. Returns a random number

API mapping:

1. Image retrieval → Camera API (GetImages method)
2. Number reading → Sensor API (GetReadings method)

Result: Two models in one module

Generate module code

Use the Viam CLI to generate template files for your module. You can work on your module either on the device running viam-server or on another computer.

Run the generator

Run the module generate command in your terminal:

viam module generate

The CLI will prompt you for several configuration options:

Example command

For the hello-world module, you can skip the interactive prompts by providing all options on the command line:

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

Understand the generated files

The generator creates a directory containing stub files for your modular component. Here’s what you need to know about each file:

hello-world/
└── src/
|   ├── models/
|   |   └── hello_camera.py
|   └── main.py
└── README.md
└── <org-id>_hello-world_hello-camera.md
└── build.sh
└── meta.json
└── requirements.txt
└── run.sh
└── setup.sh

hello-world/
└── cmd/
|   ├── cli/
|   |   └── main.go
|   └── module/
|       └── main.go
└── Makefile
└── README.md
└── <org-id>_hello-world_hello-camera.md
└── go.mod
└── module.go
└── meta.json

💡 Getting started tip: Focus on the main model file (hello_camera.py or module.go). Everything else can wait until you need it.

What you’ve accomplished

✅ API selected:

• Understand how hardware maps to Viam APIs
• Chosen the right API for your hardware (Camera for the example)

✅ Module generated:

• Created module structure with CLI
• Understand what each file does
• Know which files to edit first

✅ Ready to code:

• Have a working module scaffold
• Ready to implement API methods

Next steps

Now that you have your module structure, continue to Part 3: Implement your module to write the code that makes your hardware work.

Tutorial navigation:

• Previous: ← Part 1: Prerequisites and setup
• Current: Part 2: Choose an API and generate code
• Next: Part 3: Implement your module →
• All parts: Module creation tutorial