Complete end-user setup for a machine

If you have a machine with Viam pre-installed on it, this guide will show you how to complete your device setup using either the Viam mobile app or the captive portal.

Whether you need to use the Viam mobile app or the captive portal, depends on how provisioning was set up on your machine.

Prerequisites

  • Physical hardware constituting a machine
  • A WiFi-enabled computer, or mobile device (if using the Viam mobile app)

Set up your machine using the Viam mobile app

1

Install the Viam mobile app

You can find the mobile app on the App Store and on Google Play.

apple store icon google play store icon
2

Create a machine

Open the Viam mobile app and sign in. Then, select an organization and location for your machine. Create a new machine or click on an existing machine that has not yet been set up and follow the instructions.

3

Turn on your machine and follow the app instructions

Turn on the smart machine you are attempting to connect to.

Follow the instructions and connect to the Bluetooth hotspot your machine has created. You may need to wait a short time for your machine to boot and turn on Bluetooth.

By default, the name will begin with viam-setup-.

4

Provide the network information for the machine

In the mobile app, follow the instructions to provide the network information for the machine.

The machine will now disable Bluetooth and attempt to connect using the provided network information. If the machine cannot establish a connection using the provided network information, the machine enable the hotspot again and prompt you to re-enter the network information until a connection is successfully established.

5

Wait for machine to complete setup

If the machine can successfully connect to the network it will now complete its setup and become live.

Any features that require internet access will not function if the connected WiFi network is not connected to the internet.

Set up your machine using the captive portal

1

Turn on the smart machine

Turn on the smart machine you are attempting to set up.

2

Connect to your machine’s WiFi hotspot

On a laptop or mobile device, open your WiFi settings and connect to the WiFi hotspot your machine has created. You may need to wait a short time for your machine to boot and create its WiFi hotspot. Select the machine’s WiFi hotspot and enter the password. By default, the name will begin with viam-setup- and the password is viamsetup.

Once you are connected to your machine’s WiFi hotspot you will be redirected to a captive portal. If you are using a laptop or are not redirected, try opening http://viam.setup/ in a browser.

3

Follow the captive portal’s instructions to provide network information

In the captive web portal, follow the instructions to provide the network information for the machine.

4

If prompted, provide a machine cloud credentials configuration

Depending on how the machine was set up so far, the captive portal may also require you to paste machine cloud credentials. This is the JSON object which contains your machine part secret key and cloud app address, which your machine needs to connect to Viam.

Log into Viam, and use an existing machine or create a new machine.

To copy your machine cloud credentials:

  • Navigate to your machine’s page.

  • Select the part status dropdown to the right of your machine’s name on the top of the page.

    Machine part info dropdown

  • Click the copy icon next to Machine cloud credentials.

  • Paste the credentials when prompted.

5

Wait for machine to complete setup

The machine will now disable the hotspot network and attempt to connect using the provided network information. If the machine cannot establish a connection using the provided network information, the machine will create the hotspot again and prompt you to re-enter the network information until a connection is successfully established.

If the machine can successfully connect to the network it will now complete its setup and become live.

Any features that require internet access will not function if the connected WiFi network is not connected to the internet.

Troubleshooting

Bluetooth connection issues

If you’re having trouble with Bluetooth provisioning:

  1. Check Bluetooth permissions: Ensure the app used for provisioning has Bluetooth permissions enabled on your device.

  2. Verify Bluetooth is enabled: Make sure Bluetooth is turned on in your mobile device settings.

  3. Restart Bluetooth: Try turning Bluetooth off and on again on your mobile device.

  4. Remove and re-add: If you’ve already connected to the machine over Bluetooth, remove or forget the device from your mobile device’s settings, and re-add it.

If you can open a terminal on the machine:

  1. Check if Bluetooth is available:

    bluetoothctl list

  2. Restart Bluetooth service:

    sudo systemctl restart bluetooth

  3. Configuration check: If you set up provisioning, verify that disable_bt_provisioning is set to false in your configuration.

WiFi connection issues

If you cannot connect to your machine’s temporary WiFi hotspot, confirm you are using the correct password. The default password, unless changed by the manufacturer, is viamsetup,

If your machine cannot connect to your permanent office or home WiFi network:

  1. Check network credentials: Verify that the WiFi network name (SSID) and password are correct.

  2. Check network compatibility: Ensure your WiFi network is compatible with your machine’s WiFi band frequency (2.4ghz vs 5ghz).

  3. Try a different network: If possible, try connecting to a different WiFi network to isolate the issue.

Next Steps

The machine is now usable.

If the machine needs to be able to connect to more than one WiFi network, you can add additional networks in the viam-agent network configuration. You can also override other configuration details in the viam-agent configuration.

Previous

Provision devices