Viam Architecture

This page provides an overview of how a machine is structured, including on-device and cloud communications:

• viam-server and viam-micro-server
• Components, services and modules
• Communication flow and security
• How data flows in Viam
• Basic machine example
• Structure of more complex machines

viam-server and viam-micro-server

viam-server is the open-source executable binary that runs on your machine’s SBC or other computer.

viam-server does the following locally:

• Runs drivers for your hardware
• Runs motion planning and vision services
• Runs modules
• Manages local connections between all these resources
• Captures and stores data

When viam-server can connect to the cloud, it also:

• Automatically pulls configuration updates you make in the Viam app
• Gets new versions of software packages
• Uploads and syncs image and sensor data
• Handles requests from client code you write with SDKs
• Allows you to remotely monitor and control your machine from the Viam app

viam-server can use the internet, wide area networks (WAN) or local networks (LAN) to establish peer-to-peer connections between two machines, or to a client application.

viam-micro-server is the lightweight version of viam-server that you can run on ESP32 microcontrollers. It supports a limited set of resources and can connect with the cloud as well as with devices running viam-server.

Components, services, modules

A component represents a physical piece of hardware in your machine, and the software that directly supports that hardware.

A service is a software package that adds complex capabilities such as motion planning or object detection to your machine.

Viam has many built-in components and services that run within viam-server.

A modular resource is a custom component or service, not built into viam-server but rather provided by a module that you or another user have created. A module runs as a process managed by viam-server on your machine, communicating over UNIX sockets, and viam-server manages its lifecycle.

Communication

Viam uses peer-to-peer communication, where all machines running viam-server or viam-micro-server (the version of viam-server for microcontrollers) communicate directly with each other as well as with the cloud. This peer-to-peer connectivity is enabled by sending gRPC commands over WebRTC connections.

On startup, viam-server establishes a WebRTC connection with the Viam app. viam-server pulls its configuration from the app, caches it locally, and initializes all components and services based on that configuration.

If sub-parts or remote parts are configured, communications are established between the viam-server instances on each of them.

If you have client code running on a separate computer, that code sends API requests to viam-server using gRPC over WebRTC. If a WebRTC connection cannot be established, the request is sent directly over gRPC. When a built-in service communicates with a component, for example when the vision service requests an image from a camera, viam-server handles that request as well.

When you control your machine or view its camera streams or sensor outputs from the Viam app CONTROL tab, those connections happen over WebRTC. The Viam app uses the same API endpoints as your SDK client code (in fact, it uses the Viam TypeScript SDK), with viam-server handling requests.

For more details, see Machine-to-Machine Communication.

Security

TLS certificates automatically provided by the Viam app ensure that all communication is authenticated and encrypted.

Viam uses API keys with role-based access control (RBAC) to control access to machines from client code.

Data management flow

Data is captured and synced to the Viam cloud as follows:

1. Data collected by your resources, such as sensors and cameras, is first stored locally in a specified directory (defaults to ~/.viam/capture). You control what data to capture, how often to capture it, and where to store it using the configuration in the Viam app.

   • You can also sync data from other sources by putting it into folders you specify.
     
     

2. viam-server syncs data to the cloud at your specified interval, and deletes the data from the local directory.

3. You can view your data from the Viam app or query it using Viam SDKs, MQL, or SQL.

If a device has intermittent internet connectivity, data is stored locally until the machine can reconnect to the cloud.

For more information, see Data Management.

Basic machine example

Imagine you have a simple device consisting of a temperature sensor connected to the GPIO pins of a single-board computer (SBC). You want to capture sensor data at regular intervals, and sync it to the cloud. Here is how this works in Viam:

• You configure your machine in the Viam app with a sensor component and the data management service.
• viam-server runs on the SBC, managing all communications between hardware and the cloud using gRPC over WebRTC. On startup, viam-server uses credentials stored locally to establish a connection with the Viam app and fetches its configuration.
• Sensor data is cached in a local folder, then synced to the cloud at a configurable interval.
• You can use the tools in the Viam app to remotely view sensor data as well as to change your machine’s configuration, to view logs, and more.

Now imagine you want to run code to turn on a fan when the temperature sensor reads over 100 degrees Fahrenheit:

• Configure the fan motor as a motor component and wire the fan motor relay to the same board as the sensor.

• Write your script using one of the Viam SDKs, for example the Viam Python SDK, using the sensor API and motor API.

• You then run this code either locally on the SBC, or on a separate server. See Run code for more options. Your code connects to the machine, authenticating with API keys, and uses the sensor API to get readings and the motor API to turn the motor on and off.

  

Now, imagine you want to change to a different model of temperature sensor from a different brand:

• You power down your device, disconnect the old sensor from your SBC and connect the new one.
• You update your configuration in the Viam app to indicate what model you are using, and how it’s connected (imagine this one uses USB instead of GPIO pins).
• You turn your device back on, and viam-server automatically fetches the config updates.
• You do not need to change your SDK code, because the API is the same for all models of sensor.

Complex machines with multiple parts

In Viam, a part is an organizational concept consisting of one instance of viam-server (or viam-micro-server) running on a SBC or other computer, and all the hardware and software that the viam-server instance controls.

Many simple machines consist of only one part: just one computer running viam-server with configured components and services. If you have a more complex situation with multiple computers and associated hardware working together, you have two options for organization:

• One complex machine consisting of multiple parts, working together.
• Multiple individual machines (each made up of one or more parts), linked by a remote connection.

These two options are very similar: in both cases, the parts communicate with each other securely and directly using gRPC/WebRTC. Any given part can be a remote part of multiple machines, whereas a part can only be a sub-part of one machine. In other words, remote connections allow sharing of resources across multiple machines, whereas main parts and sub-parts are a way to hierarchically organize one machine.

Connecting parts (either as main part and sub-part, or as part and remote part) means that you can write SDK code that establishes a connection with the main part and controls all parts in a coordinated way. This streamlines authentication because you do not need to provide multiple sets of API keys as you would if you were using separate API clients. However, in some high-bandwidth cases it is better to establish a direct connection from an API client to a part, because connections to remotes and to sub-parts use the main part’s bandwidth.

See Parts, Sub-parts and Remotes for more details.

Next steps

This page has provided an overview of the architecture of just one machine. For information on organizing a fleet of many machines, see Cloud Organization Hierarchy.

For more details on the architecture of a single machine, see the following:

Parts, Sub-parts, Remotes

Connect multiple machine parts to each other as sub-parts or remotes.

Machine-to-Machine Communication

Explanation of how a machine and its parts interact at the communication layer.

viam-server

viam-server is the open-source, on-machine portion of the Viam platform.

viam-micro-server

Set up the Espressif ESP32 for development with `viam-micro-server`.