Local Configuration File

The viam-server binary uses a JSON-formatted configuration file to define all resources (hardware components and software services) it has access to, as well as any relevant parameters for those resources.

When you install viam-server from the Viam app, you configure your machine directly in the app, and the app will automatically sync your configuration to your machine.

However, if your machine will never connect to the internet, you will need to create your own local configuration file, using one of these options:

For information on the individual configuration options available, see Configuration.

Build a local configuration file in the Viam app

If your machine will never connect to the internet, and you want to create a local configuration file manually, you can still use the Viam app to build the configuration file even without connecting your machine to it. Follow the steps below to build and then download your configuration file:

  1. Navigate to the Viam app and select the CONFIGURE tab.
  2. Use Builder mode to add components and services, configure attributes, and map pin assignments.
  3. Then, switch to JSON mode to be shown the equivalent JSON configuration to the settings you made in Builder mode.
  4. Download the JSON configuration to the board or computer you intend to run viam-server on. In Builder mode, you can select the … (Actions) menu to the right of your main part’s name in the left-hand panel and click the View debug configuration option to view the full configuration file in plaintext for easy copying.

If you later need to make changes to your machine’s configuration:

  1. Make your edits under the CONFIGURE tab in Builder mode
  2. Select the View debug configuration option from the … (Actions) menu to the right of your main part’s name in the left-hand panel to view your full configuration in JSON format.
  3. Download the code to your machine, overwriting your local configuration file with the new one. If it is currently running, viam-server will detect the updated configuration and apply it automatically – there is no need to restart viam-server to apply changes.

Build a local configuration file manually

If your machine will never connect to the internet, you can create a local configuration file yourself without using the Viam app. A locally-configured machine will not be able to access Viam’s cloud features. For most users, we recommend using the Viam app to create the configuration file as it is less error-prone.

If you followed the instructions to install viam-server, the installation process provides an example configuration file in the following location:

  • Linux: /etc/viam.json
  • macOS: /opt/homebrew/etc/viam.json

You can also use the example configuration file below to base your machine’s configuration on.

Example JSON configuration file

If you want to create your own JSON configuration file without using the Viam app, you can start with the following example file. This file contains some basic example component and service configurations, as well as an example of a process:

{
  "network": {
    "fqdn": "something-unique",
    "bind_address": ":8080"
  },
  "components": [
    {
      "name": "arm1",
      "model": "fake",
      "type": "arm",
      "namespace": "rdk",
      "attributes": {
        "arm-model": "xArm6"
      }
    },
    {
      "name": "audio_input1",
      "type": "audio_input",
      "model": "fake"
    },
    {
      "name": "base1",
      "type": "base",
      "model": "fake"
    },
    {
      "name": "board1",
      "model": "fake",
      "type": "board",
      "namespace": "rdk",
      "attributes": {
        "analogs": [
          {
            "name": "analog1",
            "pin": "0"
          }
        ],
        "digital_interrupts": [
          {
            "name": "di1",
            "pin": "14"
          }
        ]
      }
    },
    {
      "name": "camera1",
      "type": "camera",
      "model": "fake"
    },
    {
      "name": "encoder1",
      "model": "fake",
      "type": "encoder",
      "namespace": "rdk",
      "attributes": {
        "update_rate_msec": 200
      }
    },
    {
      "name": "gantry1",
      "type": "gantry",
      "model": "fake"
    },
    {
      "name": "generic1",
      "type": "generic",
      "model": "fake"
    },
    {
      "name": "gripper1",
      "type": "gripper",
      "model": "fake"
    },
    {
      "name": "input_controller1",
      "type": "input_controller",
      "model": "fake"
    },
    {
      "name": "motor1",
      "model": "fake",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "encoder": "encoder1",
        "pins": {
          "a": "1",
          "b": "2",
          "pwm": "3"
        },
        "ticks_per_rotation": 100
      },
      "depends_on": ["board1", "encoder1"]
    },
    {
      "name": "movement_sensor1",
      "type": "movement_sensor",
      "model": "fake"
    },

    {
      "name": "sensor1",
      "type": "sensor",
      "model": "fake"
    },
    {
      "name": "servo1",
      "type": "servo",
      "model": "fake"
    }
  ],
  "processes": [
    {
      "id": "1",
      "name": "echo",
      "args": ["hello", "world"],
      "one_shot": true
    },
    {
      "id": "2",
      "name": "bash",
      "args": [
        "-c",
        "trap \"exit 0\" SIGINT; while true; do echo hey; sleep 2; done"
      ],
      "log": true
    }
  ],
  "services": [
    {
      "name": "navigation1",
      "type": "navigation",
      "attributes": {
        "store": {
          "type": "memory"
        },
        "movement_sensor": "movement_sensor1",
        "base": "base1"
      }
    },
    {
      "name": "slam1",
      "type": "slam",
      "model": "fake"
    },
    {
      "name": "dm",
      "type": "data_manager",
      "model": "builtin"
    }
  ]
}

For more information on the individual configuration options available, see Configuration.