Manage Machines
A machine is an organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks. The machine represents the configuration and entry point for one or more computers (and the components they control) coupled into one logical grouping of parts that work together to complete tasks. A machine usually reflects a physical device, from a camera collecting images, to a wheeled rover, or an articulated arm on a factory floor. A machine always has a main part that receives client requests, and any number of other parts.
Add a new machine
Add a new machine in the Viam app by clicking + Add machine, providing a name in the New machine field and clicking Add machine again.
Click the name of a machine to go to that machine’s page, where you’ll find a variety of tools for working with your machine.
Navigating the machine page
Next to the machine name, there is an indicator of the machine’s status.
Click on the status dropdown to open a menu with information about each part of your machine.
Once you connect to the viam-server
instance on a part, this display includes its OS, Host, viam-server
version, IP addresses, and what time it was last online or remote address (if live):
Set up a new machine
To connect to the viam-server
instance on a part, follow the setup instructions.
Open the part status dropdown menu in the top left corner of the page, next to the machine’s name.
Click View setup instructions to open the setup instructions.
Select your system’s architecture and select the version of the RDK to use. Then, follow the instructions on the page to connect and set up your machine.
Tip
If your machine is controlled by a microcontroller, install the viam-micro-server instead of full viam-server
.
More in-depth information on installing viam-server
can be found in our Installation Guide.
Once all parts of your machine are set up and connected to the app, the part status display at the top left corner of the page turns green. Now, you can manage your machine with one of four tabs: CONFIGURE, CONTROL, LOGS, and CONNECT:
CONFIGURE
The configuration of a machine describes the resources that it has access to. When a machine part that is managed with the Viam app first comes online, it requests its configuration from the Viam app. Once the machine has a configuration, it caches it locally and can use the configuration for up to 60 days. The machine checks for new configurations every 15 seconds and changes its configuration automatically when a new configuration is available.
After connecting your machine, go to the CONFIGURE tab, and start adding components, services, and other resources.
The Viam app keeps a record of your configuration changes, allowing you to revert to earlier configurations if needed. To see the history of the configuration of a machine part, click on History on the right side of its card on the CONFIGURE tab.
For more information, see the configuration documentation.
Tip
If you are managing a large fleet, you can use fragments when configuring your fleet.
CONTROL
Once you have configured components and services for your machine, you can visually test and remotely operate them from the CONTROL tab in the Viam app or the Viam mobile app.
You can also switch between different machine parts by selecting the part from the Machine part dropdown menu.
For more information, see Control machines.
LOGS
To make debugging issues with your machines easier, each machine automatically sends its logs to the cloud. You can access your logs from the LOGS tab in the Viam app and filter your logs for specific keywords or log levels:
You can click on the part names in the left-hand menu to switch logs between parts. You can also change your timestamp format to ISO or Local depending on your preference.
To view logs in the Viam mobile app:
- Select an organization clicking on the menu icon in the top left corner and tapping an organization.
- Tap the Locations tab and tap on a location and then on a machine.
- Click the menu button marked “…” in the upper right corner.
- Click View Logs.
CONNECT
Code sample
To start programming your machine, go to the CONNECT tab and select the Code sample page. This has boilerplate code snippets you can copy and paste into your SDK code to connect to your machine.
API key and API key ID
By default, the sample code does not include your machine API key and API key ID. We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.
To show your machine’s API key and API key ID in the sample code, toggle Include API key on the CONNECT tab’s Code sample page.
Caution
Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
For more information on the SDKs, see Program your Machine with Viam’s SDKs.
Configure as remote part
On the CONNECT tab, there is also a page called Configure as remote part. This page has instructions for how to configure a part of your machine as a remote part of another machine.
API keys
Your machine and the Viam app communicate securely using WebRTC with unique secrets. The API keys page of the CONNECT tab allows you to access, generate, and delete your API keys, which grant access to organizations, locations, and machines.
Copy an API key or API key ID by clicking on the clipboard icon. Click Show details and Access settings to go to your organization settings page, where you can modify the access your API keys provide.
Caution
Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
Delete a machine
To delete a machine, click on the … menu in the top right hand corner of its page, select Delete machine, and confirm that you’re sure.
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!