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.

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

If you only want to apply configuration updates under certain conditions, you can create a sensor with your conditions. The sensor must return a true value when it is safe to update and a false value otherwise.

Add the following configuration to your machine’s JSON configuration:

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

Logging

Log messages written appear under the LOGS tab for the machine running the module.

Debugging

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

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": [{ ... }]
  }
  

To enable debug level logs for specific resources you can add the log_configuration option to the resources’ JSON configuration:

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

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.