viam-server

The viam-server executable runs on a computer and manages hardware, software, and data for a machine. viam-server is built from the open-source Robot Development Kit (RDK). If you are working with microcontrollers, viam-micro-server is a lightweight version of viam-server which can run on resource-limited embedded systems that cannot run the fully-featured viam-server.

To use Viam with a machine, you create a configuration specifying which hardware and software the machine consists of. viam-server then manages and runs the drivers for the configured resources.

Overall, viam-server manages:

• Communication
• Dependency management
• Start-up
• Reconfiguration
• Logging
• Shutdown

Communication

viam-server handles all gRPC and WebRTC communication for connecting machines to the cloud or for connecting to other parts of your machine.

Dependency management

viam-server handles dependency management between resources.

Start-up

viam-server ensures that any configured modules, built-in resources and modular resources, and processes are loaded on startup.

After start-up, viam-server manages:

• the configured processes,
• the connections to hardware,
• the running services, and
• the modules that provide the modular resources.

Reconfiguration

When you or your collaborators change the configuration of a machine in the Viam app, viam-server automatically synchronizes the configuration to your machine and updates the running resources within 15 seconds. This means you can add, modify, and remove a modular resource instance from a running machine.

Reconfiguration of individual resources happens concurrently if there are no configured dependencies for any resources. If there are configured dependencies, resources are reconfigured in groups.

You can see configuration changes made by yourself or by your collaborators by selecting History on the right side of your machine part’s card on the CONFIGURE tab. You can also revert to an earlier configuration from the History tab.

Maintenance window

There are a few updates that may make your machine temporarily unavailable:

• viam-agent updating viam-server
• configuration updates

To avoid performing these updates until your machine is ready for maintenance, you can define a maintenance window. A maintenance window consists of one or multiple conditions that determine if maintenance is currently allowed. To configure a maintenance window, you need to create a sensor that returns true when your maintenance conditions are met and false otherwise.

// components: [ ... ],
// services: [ ... ],
maintenance : {
   "sensor_name" : string,
   "maintenance_allowed_key" : string
}

Logging

Log messages appear under the LOGS tab for a machine.

The default log level for viam-server and any running resources is "Info".

You can set log levels for individual components or other resources by adding the log_configuration option to the resources’ JSON configuration:

"log_configuration": {
    "level": "Debug"
},
"attributes": { ... }

Alternatively, you can configure logs for all machine resources, inside your machine config. To specify the log level for a specific resource, add the log field to your machine config:

For example:

"log": [
     {
       "pattern": "rdk.resource_manager",
       "level": "info",
     },{
       "pattern": "rdk.resource_manager.*",
       "level": "debug",
     }
  ]

Patterns are processed from top to bottom. If multiple patterns apply, the last pattern to be processed will apply. If log configurations are applied at a resource level using the log_configuration field, these take precedence over log levels applied in the log field of the machine configuration.

Debugging

You can enable debug level logs in two ways:

• Start viam-server with the -debug option.

• Add "debug": true to the machine’s configuration:

  {
    "debug": true,
    "components": [{ ... }]
  }
  

Enabling debug level logs will take precedence over all logging configuration set using the log field on a machine or the log_configuration field on a resource.

Shutdown

During machine shutdown, viam-server handles modular resource instances similarly to built-in resource instances - it signals them for shutdown in topological (dependency) order.

Next steps

APIs

Access and control your machine or fleet with the SDKs' client libraries for the resource and robot APIs.

Viam Registry

Add additional models of components and services or ML models from the Viam Registry, or extend Viam by creating new modular resources.

Installation

To use Viam, install and run viam-server on the computer that will run your machine and is connected to your hardware.