Complete 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.
In this page
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
2. 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.
3. Follow the instructions in the app
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.
Once you are connected to your machine’s WiFi hotspot return to the Viam mobile app.
4. 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.
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.
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
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, 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.
3. 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.
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’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.
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.
Note that any features that require internet access will not function if the connected WiFi network is not connected to the internet.
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.
For information on how to use your machine’s controls, see:
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
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!