Provision Machines Using the Viam Agent

You can use Viam’s software provisioning manager, the Viam Agent, to provision a machine as it first comes online with a pre-defined configuration. This is useful when deploying a fleet of machines directly from the factory to a customer, or when bundling proprietary software on your Viam machine. You can install the Viam Agent on your machines as part of your build process, and then have the Viam Agent perform the rest of the first-time setup for your machine once deployed to a customer, or to the field.

The Viam Agent:

• Automatically connects to a pre-configured WiFi network, or creates its own wireless hotspot if no pre-configured WiFi network is detected.
• Installs viam-server as a static binary, removing the need to perform any library linking or dependency installation during first-time setup. You can also use a custom build of viam-server, if needed.
• Provides automatic updates for viam-server, the agent itself, and any configured subsystems (such as the Agent Provisioning subsystem).
• Allows control of deployed software versions through the Viam app.

Consider a company that sells machines that monitor weather conditions on a maritime craft and provide navigation advice based on those readings. Such a machine might use Viam to interface between a sensor component that takes weather measurements, and the data management service to regularly upload a stream of readings, for example. However, to then parse the readings and provide tailored guidance to a ship’s captain, the company has written their own proprietary application which includes live analytics and speech generation for conveying advice to the captain.

Using the Viam Agent, this company could ship their machines directly to customers and have each machine provision viam-server as it comes online for each user, eliminating factory setup time and allowing for tailored configurations per customer as needed.

The Viam Agent is open source, and available on GitHub.

The example video shows using the Viam mobile application to connect to the Viam Agent on a newly-deployed machine and completing network setup.

Install the Viam Agent

You can install the Viam Agent using either an existing machine’s part ID and API key, or using an existing /etc/viam.json configuration file.

Update the Viam Agent and viam-server

The Viam Agent automatically updates both itself and viam-server as new updates are released. You can also configure update behavior for the Agent and viam-server using the Viam app.

Manage the Viam Agent

The Viam Agent is installed as a systemd service named viam-agent.

• To start the Viam Agent:

  sudo systemctl start viam-agent
  

• To stop the Viam Agent:

  Alert

  When you stop the Viam Agent, the agent will stop viam-server as well.

  sudo systemctl stop viam-agent
  

• To restart the Viam Agent:

  Alert

  When you restart the Viam Agent, the agent will restart viam-server as well.

  sudo systemctl restart viam-agent
  

• To completely uninstall the Viam Agent and viam-server, run the following command:

  sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)"
  

  This command uninstalls Viam Agent, viam-server, the machine configuration file (/etc/viam.json), and the provisioning configuration file (/etc/viam-provisioning.json).

  For more information, see Viam Agent management.

Provision a new machine

With the Viam Agent installed, your machine will either connect to a local WiFi network or will create its own WiFi hotspot, depending on your configuration.

• If you include a viam-server configuration file on your machine, located at /etc/viam.json, which includes a WiFi network and password to connect to, the Viam Agent will connect to the network automatically when in range.
• If you did not include this file, or the configured WiFi network is not available when your machine comes online, the Viam Agent will create its own WiFi hotspot.

This provisioning functionality uses the Viam Agent provisioning subsystem.

Connect to an existing network

If you specify a WiFi network to connect to in your configuration file, the Viam Agent will automatically connect to that network when in range.

You can configure one or more WiFi networks to connect to in the agent_config configuration object in your viam-server configuration file. For example, to configure SSIDs and passwords for two WiFi networks named primaryNet and fallbackNet, you can use the following configuration:

...
"agent_config": {
    "subsystems": {
      "agent-provisioning": {
        ...
        "attributes": {
          ...
          "networks": [
            {
              "type": "wifi",
              "ssid": "primaryNet",
              "psk": "myFirstPassword",
              "priority": 30
            },
            {
              "type": "wifi",
              "ssid": "fallbackNet",
              "psk": "mySecondPassword",
              "priority": 10
            }
          ]
        }
      }
    }
}

You can add this configuration to the /etc/viam.json configuration file you deploy to your machine, or from the CONFIGURE tab in the Viam app for your machine, using Raw JSON mode. The Viam Agent will attempt to connect to the ssid with the highest priority first. If the highest-priority network is not available, it will then attempt to connect to the next-highest priority network, and so on until all configured networks have been tried. If no configured WiFi network could be connected to, the Viam Agent will instead create its own WiFI hotspot, as described in the next section.

Create a WiFi hotspot

If you did not include a viam-server configuration file on your machine, or none of the configured WiFi networks are available when your machine comes online, the Viam Agent will create its own WiFi hotspot that you can connect to in order to complete provisioning.

By default, the hotspot network is named viam-setup-HOSTNAME, where HOSTNAME is replaced with the hostname of your machine. The WiFi password for this network is viamsetup by default.

You can customize these values in the agent_config configuration object in your viam-server configuration file. For example, to set the hotspot password to acme123, you can use the following configuration:

...
"agent_config": {
    "subsystems": {
      "agent-provisioning": {
        ...
        "attributes": {
          "hotspot_password": "acme123"
          ...
        }
      }
    }
}

You can add this configuration to your machine’s configuration in the CONFIGURE tab in the Viam app, using JSON mode, or directly to the /etc/viam.json configuration file you deploy to your machine.

If you did not initially provide a viam-server app configuration in either of these methods, you will be prompted to paste one in when you connect to the WiFi hotspot. This is the part of the machine configuration JSON which contains your machine part secret key and cloud app address, which your machine’s viam-server instance needs to connect to the Viam app.

To copy a machine’s viam-server app configuration:

• Navigate to your machine’s page on the Viam app and select the CONFIGURE tab.
• Select the part status dropdown to the right of your machine’s name on the top of the page:
• Click the copy icon underneath Viam server configuration to copy the viam-server app JSON configuration.
• Paste the viam-server app config into your terminal when prompted.

Use a pre-install script

When you install the Viam Agent, either manually using the commands above or automatically as part of your fleet’s build and deploy process, you can choose to run a pre-install script to perform provisioning steps before deployment to the target machine. For example, you could use the pre-install script to configure and deploy to an SD card or other image file, which you can then use as part of your fleet deployment process. You can also use this method to generate a local tarball containing the configured deployment, which you could then deploy later, or through a different medium (such as automation, or as the basis for further customer-specific customization).

For more information, see Pre-installed provisioning.

Use a provisioning configuration file

When you install the Viam Agent, either manually using the commands above or automatically as part of your fleet’s build and deploy process, you can provide a provisioning configuration file to pre-configure how your machine behaves when it first comes online.

To provision your machine, create a /etc/viam-provisioning.json configuration file, resembling the following:

{
  "manufacturer": "Skywalker",
  "model": "C-3PO",
  "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
  "disable_dns_redirect": true,
  "hotspot_prefix": "skywalker-setup",
  "hotspot_password": "skywalker123"
}

This file configures some basic metadata, specifies a fragment to use to configure the machine, and provides the WiFi network name and password to allow your machine to connect automatically on startup.

Use the Viam mobile app

You can use the Viam mobile application, available for download from the Apple and Google Play app stores, to connect to the Viam Agent on deployed machines.

Once you are logged in using the Viam mobile app, select your organization, then location, then tap Add new smart machine and follow the instructions in the mobile app.

For more information, see Mobile app provisioning.

Add provisioning to your own mobile app

You can write your own mobile application or add provisioning to your existing mobile application using our SDKs which allow you to connect to the Viam Agent and provision your machines. For example, you can fetch local networks available to your deployed machine with getNetworkList(), or assign network credentials for a specific network with setNetworkCredentials().

Currently, provisioning is supported by the Viam Flutter SDK and the TypeScript SDK. If you are not using Flutter or TypeScript and would like to use provisioning, please contact us.