Configure a Robot

Before you can program a robot, you must configure it.

A robot’s configuration tells the code running the robot what resources (hardware components and software services) it has access to, as well as any relevant parameters for those resources.

To start configuring, go to the Viam app, create a new robot and follow the steps on your new robot’s Setup tab.

The setup steps copy your robots credentials to your robot and store them at /etc/viam.json. The credentials look like this:

{"cloud":{"app_address":"https://app.viam.com:123","id":"123456ab-a1b2-12a3-a123-1a2b345cdefg6",
"secret":"ab0cd0efghijkl0m12no3pqrstuvw0xyza4bcd567891abcd"}}

When you turn on your robot, viam-server starts up and, by default, it uses the credentials in its local /etc/viam.json to fetch its full config from the Viam app. Once the robot has a configuration, it caches it locally and can use the configuration for up to 60 days. The robot checks for new configurations every 15 seconds and changes its configuration automatically when a new configuration is available. All communication happens securely over HTTPS using secret tokens that are in a robot’s configuration.

sudo viam-server -config <path-to-config>.json

viam-server -config <path-to-config>.json

After you have completed the setup steps and successfully connected to your robot, go to the Config tab to start adding to the configuration.

The CONFIG tab

The Config tab on the Viam app is the place to configure everything about your robot.

You can use the mode selector to switch between Builder and Raw JSON:

• Builder mode provides a graphical interface for configuring your robot resources.
• Raw JSON mode provides a text editing field where you can write and edit the config manually.

Regardless of the mode you choose, Viam stores the configuration file in JSON (JavaScript Object Notation).

If you add components in Builder mode and click Save Config at the bottom of the screen, you can switch to Raw JSON and see the JSON that has been generated by the builder.

{
  "components": [
    {
      "name": "local",
      "type": "board",
      "model": "pi",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "my-motor",
      "type": "motor",
      "model": "gpio",
      "attributes": {
        "pins": {
          "a": "13",
          "b": "15"
        },
        "board": "local",
        "max_rpm": 120
      },
      "depends_on": [],
    },
    {
      "name": "my_camera",
      "type": "camera",
      "model": "webcam",
      "attributes": {
        "video_path": "video0"
      }
    }
  ],
  "services": [
    {
      "name": "detector",
      "type": "vision",
      "attributes": {
        "register_models": [
          {
            "parameters": {
              "segment_size_px": 200,
              "hue_tolerance_pct": 0.05,
              "detect_color": "#19FFD9"
            },
            "type": "color_detector",
            "name": "green_detector"
          }
        ]
      }
    }
  ],
  "modules": []
}

The Config tab has subtabs for each section of your robot’s config:

• Components: Components are the hardware of your robot.
• Services: Services are the software that runs on your robot.
• Modules: Modular resources are a way to add resource types or models that are not built into Viam.
• Remotes: Remotes are a way to connect two separate robots so one can access the resources of the other.
• Processes: Processes automatically run specified scripts when the robot boots.
• Fragments: Fragments are a way of sharing and managing identical configuration files (or parts of config files) across multiple robots.
• Auth/Network: The auth and network section allows you to configure robot-level API keys and set a bind address for viam-server.
• Frames: Frames hold reference frame information for the relative position of components in space.

Components

Components represent the pieces of hardware on your robot that you want to control with Viam.

You must configure each component with a name, a model, a type, attributes, and dependencies:

• name: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can choose any unique name for a component.

• type: The broad component category, such as motor, arm or camera. Components of a given type have a common API.

• model: Indicates the more specific category of hardware. Components of the same model are supported using the same low-level code.

• attributes: A struct to define things like how the component is wired to the robot, its dimensions, and other specifications; attributes vary widely between models. See the component documentation for a given component type and model for more details.

• depends_on: Any components that a given component relies upon, and that must be initialized on boot before this component is initialized. Many built-in components have convenient implicit dependencies, in which case depends_on can be left blank. For example, a gpio motor depends on the board to which it is wired, but it has a dedicated board attribute and viam-server will automatically initialize that board before it looks for the motor.

For specific information on how to configure each supported component type, see the components documentation.

Services

Services are built-in software packages that make it easier to add complex capabilities such as motion planning or object detection to your robot.

For services, the type specifies which of the Viam services you want to use on your robot, such as the Vision Service or the Motion Service.

The name serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can choose any unique name for a service.

The other aspects of configuring a service are highly specific to the type of service. See the services documentation for more information.

Modules

Modular resources are a way to add resource types or models that are not built into Viam.

To add a modular resource as a component or service of your robot, configure a module per the modular resource documentation.

Remotes

Configuring a remote is a way to connect two separate robots so one can access the resources of the other. Find more information in our remotes documentation.

Processes

To automatically run a specified script when the robot boots, configure a process.

Start by giving the process a Name (id in raw JSON) (an identifier of your choice) and clicking Create Process.

Then fill in the following fields:

• Executable (name): The command you want to execute when your robot connects to the server.
• Arguments (args): Optional arguments to follow the command.
• Working Directory (cwd): Where you want the process to execute. An optional setting that defaults to the directory where viam-server executes.

You can also toggle whether you want errors and other messages to be logged, and whether to execute the command just once or keep running the process indefinitely. In raw JSON, these options are represented by log (bool) and one_shot (bool), respectively.

"processes": [
    {
      "id": "run-my-code",
      "log": true,
      "name": "python3",
      "args": [
        "my_cool_script.py"
      ],
      "cwd": "/home/myName/project/"
    }
  ]

Fragments

Fragments are a way of sharing and managing identical resource configuration files across multiple robots. For example, if you have multiple robots with the same hardware, wired the same way, you can create and share a fragment and add it to any number of robots. When changes are made to the fragment, those changes are automatically carried to all robots that include the fragment in their config.

Create a fragment

To create your own private fragment, go to app.viam.com/fragments or click on Fragments in the left navigation bar on the FLEET page.

1. Enter a name for your new fragment and click Add fragment.
2. Add the JSON configuration in the config field.
3. Click SAVE FRAGMENT.

Add a fragment to a robot

You can add a fragment to a robot’s config and also add other configuration outside the fragment. For example, if you have multiple identical rovers but one has an arm attached, you can add the rover configuration fragment (including the motors and base components), and then configure the arm on just that one rover.

To add a fragment to a robot:

• Go to the Fragments subtab of your robot’s Config tab on the Viam app.
• Look through the list of available fragments and click Add next to any fragments you want to add to your robot.
• Click Save Config at the bottom of the screen.

The components and services included in the fragment appear inside a read-only fragment section in the Components and Services subtabs.

In the Raw JSON configuration, you will see the fragment ID in the fragments section:

{
  "components": [ ],
  "fragments": [
    "3e8e0e1c-f515-4eac-8307-b6c9de7cfb84"
  ]
}

For an example of adding a fragment to a robot, see the Viam Rover fragment tutorial.

Auth/network

The auth section allows you to configure robot-level API keys for connecting over LAN.

The network section allows you to set the address viam-server binds to for accepting connections. By default, viam-server binds to 0.0.0.0:8080 when managed by the Viam app or when authentication and TLS are enabled.

Frame system

The frame system holds reference frame information for the relative position of components in space.

Configure a frame for a given component on its panel on the Components tab, then switch to the Frame System tab to visualize the relative positions. Find more information in the frame system documentation.

Troubleshooting

If you run into issues, here are some things to try:

• Check the Logs tab to check for any errors or other info from viam-server.

• You can also view logs locally by running the following command on the robot:

  • Linux
  • macOS

  sudo journalctl --unit=viam-server
  

  cat $(brew --prefix)/var/log/viam.log
  

• Make sure all configured components are actually saved to your config. If they aren’t, you will see an Unsaved Changes note next to the Save Config button at the bottom of the config screen.

• Try restarting viam-server by clicking Restart in the upper right corner of the app. It takes a few minutes for the server to shut down and restart.

• Make sure the issue is not hardware related. Some things to check are that the robot has adequate power, all wires are properly connected, and no chips or other hardware components are shorted or overheated.

• You can also ask questions in the Community Discord and we will be happy to help.

Local Setup

Configuring viam-server with the Viam app allows you to make use of the cloud features of Viam:

• Fleet Management
• Data Management
• Machine Learning

A locally configured robot, will not be able to access Viam’s cloud features. If you are configuring a robot that can never connect to the internet, you can manually create a local full raw JSON config file on your robot.

You can write the contents of this config file manually, or you can use the Viam app’s config builder (without connecting your robot to it). Once you finish configuring your robot in the Builder mode, switch to Raw JSON and copy the entire raw JSON into your config file. Save the file at /etc/viam.json or another location.

Then start viam-server:

sudo viam-server

viam-server

If you have stored your config file at a location different from the default location (/etc/viam.json), pass in the path to the config:

sudo viam-server -config <path-to-config>.json

viam-server -config <path-to-config>.json

To run viam-server as a system service, see Start automatically on boot.

Next Steps

After configuring your robot, you can use the Viam SDKs to program and control your robot.

If you want to try configuring a robot but don’t have any hardware on hand, try the Build a Mock Robot tutorial.