Provision machines using viam-agent

You can use Viam’s software provisioning manager (agent-provisioning), 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.

The provisioning subsystem is a feature of viam-agent, which you can install as part of your manufacturing process. agent-provisioning will then perform the rest of the first-time setup for your machine once an end user sets up the machine.

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 regularly capture and upload a stream of sensor readings, for example. To parse the readings and provide tailored guidance to a ship’s captain, the company writes their own proprietary application which includes live analytics and speech generation for conveying advice to the captain.

Using agent-provisioning, this company can ship their machines directly to customers with viam-agent installed. When a customer sets up their machine, the provisioning subsystem installs viam-server. By having the end customer set up the machine, the company:

• eliminates per-device setup and individualization at the factory
• allows for tailored configurations per customer as needed
• allows customer to provide their own WiFi credentials

For a guide on how to configure provisioning for your machine, see:

Setup for provisioning

Install and configure viam-agent for provisioning one or many machines.

End user experience

End users receive a machine, and use either a captive web portal or mobile app to complete the machine setup.

One option is to use the Viam mobile app. The Viam mobile app allows end users to create a new machine in the app, and agent-provisioning will then install viam-server and run it with a provided configuration.

To add your branding, you can build your own mobile app and use the Flutter SDK or the TypeScript SDK to connect to viam-agent and provision your machines.

If you are not using Flutter or TypeScript and would like to use provisioning, please contact us.

For an end-user guide to setting up their machine, see:

This is the general process for provisioning depending on whether you are using a captive web portal or a mobile app:

Configuration

When you install viam-agent, you may optionally provide a provisioning configuration file to customize the experience at /etc/viam-provisioning.json with the following format:

{
  "manufacturer": "<NAME>",
  "model": "<NAME>",
  "fragment_id": "<ID>",
  "hotspot_prefix": "<PREFIX>",
  "disable_dns_redirect": true,
  "hotspot_password": "<PASSWORD>",
  "roaming_mode": false,
  "offline_timeout": "0m00s",
  "user_timeout": "0m00s",
  "fallback_timeout": "0m00s"
}

{
  "manufacturer": "Skywalker",
  "model": "C-3PO",
  "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
  "hotspot_prefix": "skywalker-setup",
  "disable_dns_redirect": true,
  "hotspot_password": "skywalker123",
  "roaming_mode": false,
  "offline_timeout": "3m30s",
  "user_timeout": "2m30s",
  "fallback_timeout": "15m"
}

Attributes

Networks

During the provisioning process, a machine connects to a network to install viam-server. If an end user uses an app to provision the machine, they will generally provide network details through that app.

If you know in advance which other networks a machine should be able to connect to, we recomment that you add WiFi settings in the operating system (for example, directly in NetworkManager).

However, if you want to add additional networks to the provisioning configuration you can add them to the networks field value.

If roaming_mode is enabled, agent-provisioning will try to connect to each specified network in order of priority from highest to lowest.

The following configuration defines the connection information and credentials for two WiFi networks named fallbackNetOne and fallbackNetTwo:

{
  "manufacturer": "Skywalker",
  "model": "C-3PO",
  "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
  "hotspot_prefix": "skywalker-setup",
  "disable_dns_redirect": true,
  "hotspot_password": "skywalker123",
  "roaming_mode": false,
  "offline_timeout": "3m30s",
  "user_timeout": "2m30s",
  "fallback_timeout": "15m",
  "roaming_mode": true,
  "networks": [
    {
      "type": "wifi",
      "ssid": "otherNetworkOne",
      "psk": "myFirstPassword",
      "priority": 30
    },
    {
      "type": "wifi",
      "ssid": "otherNetworkTwo",
      "psk": "mySecondPassword",
      "priority": 10
    }
  ]
}