Edit

Complete end-user setup for a machine

If you have received 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.

Unless you have been told to use the captive portal, we recommend you use the Viam mobile app.

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

Install the Viam mobile app

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

Create a machine

Open the Viam mobile app and sign in. Then, select an organization and location for your machine. If you have already created a machine, select it. If you have not yet created a machine, click on Add new smart machine and give your machine a name.

Turn on your machine and follow the app instructions

Turn on the smart machine you are attempting to connect to. Then leave the app and navigate to your mobile device’s 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.

Your machine’s WiFi hotspot name will begin with viam-setup-. Unless you have been given other instructions, the WiFi password for this hotspot network is viamsetup.

Return to the Viam mobile app once connected

You may need to wait a short time for your machine to boot and start its provisioning services.

Provide the network information for the machine

In the mobile app, you will be prompted to provide the network information for the machine.

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.

Wait for machine to complete setup

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

Note that 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

Turn on the smart machine

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

Connect to your machine’s WiFi hotspot

On a laptop or mobile device, navigate to 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. Your machine’s WiFi hotspot name will begin with viam-setup-. Unless you have been given other instructions, the WiFi password for this hotspot network is viamsetup.

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

Follow the captive portal’s instructions to provide network information

In the captive web portal, you will then be prompted to provide the network information for the machine.

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’s viam-server instance needs to connect to the Viam app.

Navigate to the Viam app and create a new machine.

To copy your machine cloud credentials:

Navigate to your machine’s page on the Viam app.
Select the part status dropdown to the right of your machine’s name on the top of the page.
Click the copy icon next to Machine cloud credentials.
Paste the credentials when prompted.

Wait for machine to complete setup

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

Note that 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 a custom Flutter app

The Flutter Provisioning package shows an example for Bluetooth provisioning.

When developing your own application, if you support both Bluetooth and WiFi Hotspot provisioning, make the app choose the best available method. We recommend using Bluetooth by default for a smoother setup experience.

App Development Considerations

When developing mobile apps with Bluetooth provisioning, ensure your app requests appropriate Bluetooth permissions.

Troubleshooting

Bluetooth connection issues

If you’re having trouble with Bluetooth provisioning:

Verify the device supports Bluetooth Low Energy (BLE)
Check Bluetooth permissions: Ensure the Viam mobile app has Bluetooth permissions enabled on your device.
Verify Bluetooth is enabled: Make sure Bluetooth is turned on in your mobile device settings.
Check device compatibility: Ensure your mobile device supports Bluetooth Low Energy (BLE).
Restart Bluetooth: Try turning Bluetooth off and on again on your mobile device.

If you can open a terminal on the machine:

Check if Bluetooth is available:
```
bluetoothctl list
```
Verify Bluetooth service status:
```
sudo systemctl status bluetooth
```

WiFi connection issues

If your machine cannot connect to your WiFi network:

Check network credentials: Verify that the WiFi network name (SSID) and password are correct.
Check network compatibility: Ensure your WiFi network is compatible with your machine’s WiFi adapter.
Check signal strength: Make sure your machine is within range of your WiFi router.
Try a different network: If possible, try connecting to a different WiFi network to isolate the issue.

Next Steps

You can now use your machine.

If your 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.

To control your machine, you can navigate to its CONTROL tab in the Viam app.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!