Machine Configuration

Before you can program a smart machine, you must configure it.

A machine’s configuration defines the resources (hardware and software services) it has access to, as well as any relevant parameters for those resources. You can configure the following resources:

• Components: Components are the hardware of your machine.
• Services: Services are the software that runs on your machine.
• Processes: Processes automatically run specified scripts when the machine boots.
• Modules: Modules provide modular resources, which are a way to add resource types or models that are not built into Viam.
• Remote parts: Remotes are a way to connect two separate machines so one can access the resources of the other.
• Sub-parts: Sub-parts are a way to connect two computers inside the same machine.
• Fragments: Fragments are a way of sharing and managing identical configuration files (or parts of config files) across multiple machines.
• Frames: Frames hold reference frame information for the relative position of components in space.
• Triggers: Triggers allow you to trigger actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes.
• Network: Networking options allow you to configure the bind address for accepting connections.

To start configuring, go to the Viam app and create a new machine. Open the part status dropdown menu in the top left corner of the page, next to the machine’s name. Click View setup instructions to open the setup instructions. Follow the appropriate instructions for your machine’s architecture.

The setup steps copy your machine’s credentials to your machine. When you turn on your machine, viam-server starts up and uses the provided credentials to fetch its full config from the Viam app. Once the machine has a configuration, it caches it locally and can use the configuration for up to 60 days. Since the configuration is cached locally, your machine does not need to stay connected to the Viam app after it has obtained its configuration file.

If it is online, the machine 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 machine’s configuration.

If your machine will never connect to the internet, you can also create a local configuration file on the machine itself.

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

The CONFIGURE tab

The CONFIGURE tab on the Viam app is the place to configure everything about your machine.

You can switch between Builder, JSON, and Frame mode by clicking on the icon in the upper left-hand corner:

• Builder mode provides a graphical interface for configuring your machine resources.
• JSON mode provides a text editing field where you can write and edit the config manually.
• Frame mode provides a graphical interface for configuring and visualizing the relative position of components in space. For more information, see the Frame System documentation.

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

If you add components in Builder mode and click Save in the top right corner of the screen, you can switch to JSON and see the JSON that has been generated by the builder.

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "my-motor",
      "model": "gpio",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "pins": {
          "a": "13",
          "b": "15"
        },
        "board": "local",
        "max_rpm": 120
      },
      "depends_on": []
    },
    {
      "name": "my_camera",
      "model": "webcam",
      "type": "camera",
      "namespace": "rdk",
      "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": []
}

Components

Components represent the pieces of hardware on your machine that you want to control with Viam. To add a new component, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Component or hit C. Search for and select your desired model.

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

• 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.

• 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 either accept the suggested default name when creating a component or choose a unique name for a component. The name must start with a letter or number and only contain letters, numbers, dashes, and underscores with a max length of 60.

• attributes: Configure component details such as how the component is wired to the machine, its dimensions, and other specifications; attributes vary widely between models. See a component’s documentation 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.

• log_configuration: Specify the log level for a resource. The default log level is "Info". For example:

  "log_configuration": {
      "level": "Debug"
  }
  

For specific information on how to configure each supported component type, see the component’s documentation:

Arm

Base

Board

Camera

Encoder

Gantry

Generic

Gripper

Input Controller

Motor

Movement Sensor

Power Sensor

Sensor

Servo

Some resources have a TEST section on the bottom half of their configuration pane which you can expand and interact with to test out controlling the component. You must be running viam-server and connected to your machine to use this feature.

On the … menu in the upper right corner of each resource you can Duplicate, Delete, and Disable or Enable it.

Services

Services are software packages that make it easier to add complex capabilities such as motion planning or object detection to your machine. To add a new service, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Service or hit S. Search for and select your desired model.

You must configure a service with a name and a type:

• type: specifies which of the Viam services you want to use on your machine, such as the vision service or the motion service.

• 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 accept the suggested default name when creating a service or choose a choose any unique name for a service. The name must start with a letter or number and can only contain letters, numbers, dashes, and underscores with a max length of 60.

• log_configuration: Specify the log level for a resource. The default log level is "Info". For example:

  "log_configuration": {
      "level": "Debug"
  }
  

The other aspects of configuring a service are highly specific to the type of service, review the docs for the service you are interested in:

Data Management

Machine Learning

Motion

Navigation

SLAM

Computer Vision

Generic Service

Frame System

Some resources have a TEST section on the bottom half of their configuration pane which you can expand and interact with to test out controlling the service. You must be running viam-server and connected to your machine to use this feature.

You can disable a service without removing it from the configuration by selecting the … menu in the upper right corner and selecting Disable.

Processes

To automatically run a specified command when the machine boots, configure a process. You can configure any command, for example one that executes a binary or a script, to run as a process.

To add a new process, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Process. Find more information in the processes documentation.

Modules

Modules allow you to add modular resources to your machines which add resource types or models that are not built into Viam. Many models are available in the registry and you are able to add them as components or services.

Local Modules

To add a module that is not in the registry and is local to your machine, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Local module. Follow the instructions in our registry documentation to configure the module.

Remote parts

Configuring a remote part is a way to connect two separate machines so one can access the resources of the other.

To configure a remote part, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Remote part. Find more information in our machine parts documentation.

Sub-parts

Configure a sub-part to connect two computers inside the same machine.

To configure a sub-part, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Sub-part. Find more information in our machine parts documentation.

Fragments

You can use fragments to share similar resource configuration files across multiple machines in your fleet. For example, if you have multiple machines with the same motor hardware, wired the same way, you can create a fragment to configure that motor and share it easily across all of your machines, without needing to individually configure the motor component for each machine.

To use a fragment, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Insert fragment. See Use Fragments to Configure a Fleet for more information on creating and deploying fragments.

Frames

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

Click on the Frame mode to visualize and configure the relative positions of components. Find more information in the frame system documentation.

Triggers

Triggers allow you to trigger actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes. For example, you can configure a trigger to send you a notification when your robot’s sensor collects a new reading.

See Configure a Trigger for more information on triggers.

Network

You can configure your machine’s bind address and heartbeat window.

On your machine’s CONFIGURE tab, click the + button and select Network.

  ... // components {...}, services {...},
  "network": {
    "bind_address": "0.0.0.0:8080",
    "sessions": {
      "heartbeat_window": "30s" // Changes heartbeat window to 30 seconds
    }
  },
  ...

Configuration History

The Viam app keeps a record of each machine’s configuration changes, allowing you to revert to earlier configurations if needed and see who made specific changes.

To see the configuration history for a machine part, click on the History link at the top right corner of the machine part’s card in the Viam app.

To restore to an earlier version of your configuration, click the Restore version button next to the desired configuration.

Troubleshooting

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

• Check the LOGS tab to view log messages and errors from viam-server. You can also access the local log file on your machine if needed.
• Make sure all configured components are saved to your config. If they aren’t, you will see an Unsaved changes note next to the Save button in the top right corner of the page.
• Try restarting viam-server by navigating to the app’s CONFIGURE tab in Builder mode, clicking the … menu on the right side of the machine part’s card, and selecting Restart part. It takes a few minutes for the server to shut down and restart.
• If you need to revert to an earlier configuration, use the Configuration History to restore to an earlier version.
• Make sure the issue is not hardware related. Some things to check are that the machine has adequate power, all wires are properly connected, and no chips or other hardware components are shorted or overheated.
• See Troubleshooting for additional troubleshooting steps.

• 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 use Viam’s cloud features:

• Fleet Management
• Data Management
• Machine Learning

However, if you are configuring a machine that can never connect to the internet, you can create a local configuration file on your machine. A locally-configured machine will not be able to access Viam’s cloud features.

Next steps

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

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