Provision devices using viam-agent

Create a fragment

If you do not yet have a fragment, follow the steps to Create a fragment and make a note of the fragment ID.

Create the defaults file

If you would like to use a captive web portal, skip this and the next step.

Create a defaults file called viam-defaults.json to configure the provisioning experience for the users setting up their machines. You will later pass this file to a script, so you can save it anywhere. The script will save the file is at /etc/viam-defaults.json on the machine.

You must at least specify a fragment_id.

{
  "network_configuration": {
    "manufacturer": "<NAME>",
    "model": "<NAME>",
    "fragment_id": "<ID>",
    "hotspot_interface": "<INTERFACE>",
    "hotspot_prefix": "<PREFIX>",
    "disable_captive_portal_redirect": false,
    "hotspot_password": "<PASSWORD>",
    "disable_bt_provisioning": false,
    "disable_wifi_provisioning": false,
    "bluetooth_trust_all": false,
    "turn_on_hotspot_if_wifi_has_no_internet": false,
    "offline_before_starting_hotspot_minutes": 2,
    "user_idle_minutes": 5,
    "retry_connection_timeout_minutes": 10
  }
}

{
  "network_configuration": {
    "manufacturer": "Skywalker",
    "model": "C-3PO",
    "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
    "hotspot_interface": "wlan0",
    "hotspot_prefix": "skywalker-setup",
    "disable_captive_portal_redirect": false,
    "hotspot_password": "skywalker123",
    "disable_bt_provisioning": false,
    "disable_wifi_provisioning": false,
    "bluetooth_trust_all": false,
    "turn_on_hotspot_if_wifi_has_no_internet": false,
    "offline_before_starting_hotspot_minutes": 4,
    "user_idle_minutes": 3,
    "retry_connection_timeout_minutes": 15
  }
}

Configure Networks

If a machine connects to a network during setup and you know in advance which WiFi a machine will connect to, this step allows you to add credentials for it.

If you do not know the network in advance, skip this step. In this case the end user will have to provide network details later in the process.

If you know in advance that the machine should be able to connect to multiple networks, we recommend that you add WiFi settings in the operating system (for example, directly in NetworkManager). If that is not possible, you can add networks with the additional_networks field. viam-agent will then 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:

{
  "network_configuration": {
    "manufacturer": "Skywalker",
    "model": "C-3PO",
    "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
    "hotspot_interface": "wlan0",
    "hotspot_prefix": "skywalker-setup",
    "disable_captive_portal_redirect": false,
    "hotspot_password": "skywalker123",
    "disable_bt_provisioning": false,
    "disable_wifi_provisioning": false,
    "turn_on_hotspot_if_wifi_has_no_internet": true,
    "offline_before_starting_hotspot_minutes": 4,
    "user_idle_minutes": 3,
    "retry_connection_timeout_minutes": 15
  },
  "additional_networks": {
    "testNet1": {
      "priority": 30,
      "psk": "myFirstPassword",
      "ssid": "fallbackNetOne",
      "type": "wifi"
    },
    "testNet2": {
      "priority": 10,
      "psk": "mySecondPassword",
      "ssid": "fallbackNetTwo",
      "type": "wifi"
    }
  }
}

Create a machine in advance

If you are using a mobile app for provisioning, skip this step.

If you provision devices using a captive web portal, you can create a machine in advance. You can either provide its machine cloud credentials to the preinstall script you will run in the next steps, or provide them using the captive web portal.

You can get the machine cloud credentials by clicking the copy icon next to Machine cloud credentials in the part status dropdown to the right of your machine’s name on the top of the page. Paste the machine cloud credentials into a file on your hard drive called viam.json. You will pass the file to the preinstall script later, so you can store it anywhere. The script will save the file is at /etc/viam.json on the machine.

import asyncio
import requests

from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient
from viam.app.app_client import APIKeyAuthorization

# TODO: Replace "<API-KEY>" (including brackets) with your API key
API_KEY = "<API-KEY>"
# TODO: Replace "<API-KEY-ID>" (including brackets) with your API key ID
API_KEY_ID = "<API-KEY-ID>"
# The id of the location to create the machine in
LOCATION_ID = ""
# The name for the machine to create
MACHINE_NAME = ""


async def connect() -> ViamClient:
    dial_options = DialOptions(
      credentials=Credentials(
        type="api-key",
        payload=API_KEY,
      ),
      auth_entity=API_KEY_ID
    )
    return await ViamClient.create_from_dial_options(dial_options)


async def main():
    async with await connect() as viam_client:
        cloud = viam_client.app_client
        new_machine_id = await cloud.new_machine(
            name=MACHINE_NAME, location_id=LOCATION_ID)
        print("Machine created: " + new_machine_id)
        list_of_parts = await cloud.get_machine_parts(
            machine_id=new_machine_id)
        print("Part id: " + list_of_parts[0].id)

        org_list = await cloud.list_organizations()
        print(org_list[0].id)

        auth = APIKeyAuthorization(
            role="owner",
            resource_type="robot",
            resource_id=new_machine_id
        )
        api_key, api_key_id = await cloud.create_key(
            org_list[0].id, [auth], "test_provisioning_key")
        print(api_key, api_key_id)

        headers = {
            'key_id': api_key_id,
            'key': api_key
        }
        params = {
            "client": 'true',
            "id": list_of_parts[0].id
        }
        res = requests.get(
            'https://app.viam.com/api/json1/config',
            params=params,
            headers=headers,
            timeout=10
        )
        print(res.text)

        with open("viam.json", "w") as text_file:
            text_file.write(res.text)


if __name__ == '__main__':
    asyncio.run(main())

Flash an operating system to the SD card of the single-board computer

Mount the SD card

Still using the computer used for flashing the SD card, eject and reinsert the card to make sure it’s mounted with the newly written operating system.

Download the preinstall script

Run the following commands to download the preinstall script and make the script executable:

wget https://storage.googleapis.com/packages.viam.com/apps/viam-agent/preinstall.sh
chmod 755 preinstall.sh

curl -O https://storage.googleapis.com/packages.viam.com/apps/viam-agent/preinstall.sh
chmod 755 preinstall.sh

Run the preinstall script

Run the preinstall script. It will attempt to auto-detect a mounted root filesystem (or for Raspberry Pi, bootfs) and also automatically determine the architecture.

sudo ./preinstall.sh

Follow the instructions. If you created a viam-defaults.json file or a viam.json file, specify their locations when prompted.

Using a Raspberry Pi?

Important: Required customization

You must customize at least the hostname when prompted by the Raspberry Pi Imager.

When you customize the hostname or other settings, the Raspberry Pi Imager creates firstrun.sh which is required to set up provisioning.

If you do not customize anything, firstrun.sh is not present on the device and the preinstall.sh script fails.

For Raspberry Pis, the script will automatically perform the required next steps, it will:

• create a tarball
• update firstrun.sh.
• extract the tarball to the mounted root filesystem

sudo ./preinstall.sh
Found Raspberry Pi bootfs mounted at /Volumes/bootfs
A Raspberry Pi boot partition has been found mounted at /Volumes/bootfs
This script will modify firstrun.sh on that partition to install Viam agent.
Continue pre-install? (y/n): y
Path to custom viam-agent binary (leave empty to download default):
Path to custom viam-defaults.json (leave empty to skip):
Path to custom viam.json (leave empty to skip)
Creating tarball for install.
a opt
a opt/viam
a opt/viam/cache
a opt/viam/bin
a opt/viam/bin/viam-agent
a opt/viam/bin/agent-provisioning
a opt/viam/cache/viam-agent-provisioning-factory-aarch64
a opt/viam/cache/viam-agent-factory-aarch64
a etc
a usr
a usr/local
a usr/local/lib
a usr/local/lib/systemd
a usr/local/lib/systemd/system
a usr/local/lib/systemd/system/viam-agent.service
a usr/local/lib/systemd/system/multi-user.target.wants
a usr/local/lib/systemd/system/multi-user.target.wants/viam-agent.service
Install complete! You can eject/unmount and boot the image now.

sudo ./preinstall.sh --aarch64

sudo ./preinstall.sh --x86_64

sudo tar -xJvpf $TARBALL -C <PATH_TO_ROOT_FS>

sudo ./preinstall.sh /path/to/rootfs

Set up more devices

Unless you provided a machine cloud credentials file (viam.json) to the machine, you can clone SD cards to speed up the provisioning process.