Configure a Robot
Before you can program a robot, you must configure it.
A robot’s configuration tells the code running the robot what resources (hardware components and software services) it has access to, as well as any relevant parameters for those resources.
To start configuring, go to the Viam app, create a new robot and follow the steps on your new robot’s Setup tab.
The setup steps copy your robots credentials to your robot and store them at
{
"cloud": {
"app_address": "https://app.viam.com:123",
"id": "123456ab-a1b2-12a3-a123-1a2b345cdefg6",
"secret": "LOCATION SECRET FROM THE VIAM APP"
}
}
Location secret
By default, the sample code does not include your robot location secret. We strongly recommend that you add your location secret as an environment variable and import this variable into your development environment as needed.
To show your robot’s location secret in the sample code, toggle Include secret on the Code sample tab. You can also see your location secret on the locations page.
Caution
Do not share your location secret, part secret, or robot address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your robot, or to the computer running your robot.
When you turn on your robot, viam-server
starts up and, by default, it uses the credentials in its local
Tip
You can also store your config file in a custom location if desired. See Run viam-server
for more information.
After you have completed the setup steps and successfully connected to your robot, go to the Config tab to start adding to the configuration.
Info
Your robot does not need to stay connected to the Viam app after it has obtained its configuration file. The configuration is cached locally. If your robot will never connect to the internet, you can also create a local configuration file on the robot itself.
The Config tab
The Config tab on the Viam app is the place to configure everything about your robot.
You can use the mode selector to switch between Builder and Raw JSON:
- Builder mode provides a graphical interface for configuring your robot resources.
- Raw JSON mode provides a text editing field where you can write and edit the config manually.
Regardless of the mode you choose, Viam stores the configuration file in JSON (JavaScript Object Notation).
Simultaneous config edits
If you edit a config while someone else edits the same config, the person who saves last will overwrite any prior changes that aren’t reflected in the new config.
Before editing a config, we recommend you refresh the page to ensure you have all the latest changes.
If you add components in Builder mode and click Save Config at the bottom of the screen, you can switch to Raw JSON and see the JSON that has been generated by the builder.
The Config tab has subtabs for each section of your robot’s config:
- Components: Components are the hardware of your robot.
- Services: Services are the software that runs on your robot.
- Modules: Modules provide modular resources, which are a way to add resource types or models that are not built into Viam.
- Remotes: Remotes are a way to connect two separate robots so one can access the resources of the other.
- Processes: Processes automatically run specified scripts when the robot boots.
- Fragments: Fragments are a way of sharing and managing identical configuration files (or parts of config files) across multiple robots.
- Auth/Network: The auth and network section allows you to configure robot-level API keys and set a bind address for
viam-server
. - Frames: Frames hold reference frame information for the relative position of components in space.
Tip
Simple robots often use only a few components (and perhaps services). Depending on your robot, you may not need to configure any modules, remotes, processes, fragments or frames.
Components
Components represent the pieces of hardware on your robot that you want to control with Viam.
You must configure each component with a type, a model, a name, attributes, and dependencies:
type
: The broad component category, such asmotor
,arm
orcamera
. Components of a given type have a common API.model
: Indicates the more specific category of hardware. Components of the same model are supported using the same low-level code.name
: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can choose any unique name for a component.attributes
: A struct to define things like how the component is wired to the robot, its dimensions, and other specifications; attributes vary widely between models. See the component documentation for a given component type and model for more details.Tip
Some optional attributes have default values. If you omit these attributes from your config, or if you include them but leave their values empty,
viam-server
will apply these default values at runtime, even though they are not reflected in the configuration file.depends_on
: Any components that a given component relies upon, and that must be initialized on boot before this component is initialized. Many built-in components have convenient implicit dependencies, in which casedepends_on
can be left blank. For example, agpio
motor depends on theboard
to which it is wired, but it has a dedicatedboard
attribute andviam-server
will automatically initialize that board before it looks for the motor.
If you are configuring several similar components, you can use the Duplicate component button in the upper-right of a component’s configuration pane to create a new identical component beneath your existing one. Be sure to edit the duplicated component to change any parameters that are unique to the new component, such as its name and pins.
To delete a component, click the trash can icon in the upper-right of the component configuration pane.
For specific information on how to configure each supported component type, see the components documentation.
Tip
When you configure a component on the Config tab, it will also appear on the Control tab which gives you an interface to test and interact with it. Meanwhile the Code sample tab will also update to include code for some basic interaction with that component using the Viam SDKs.
Services
Services are built-in software packages that make it easier to add complex capabilities such as motion planning or object detection to your robot.
For services, the type
specifies which of the Viam services you want to use on your robot, such as the vision service or the motion service.
The name
serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource.
You can choose any unique name for a service.
The other aspects of configuring a service are highly specific to the type of service. See the services documentation for more information.
Modules
Modular resources are a way to add resource types or models that are not built into Viam.
To add a modular resource as a component or service of your robot, configure a module per the modular resource documentation.
Remotes
Configuring a remote is a way to connect two separate robots so one can access the resources of the other. Find more information in our remotes documentation.
Processes
To automatically run a specified script when the robot boots, configure a process.
Start by giving the process a Name (id
in raw JSON) (an identifier of your choice) and clicking Create Process.
Then fill in the following fields:
- Executable (
name
): The command you want to execute when your robot connects to the server. - Arguments (
args
): Optional arguments to follow the command. - Working Directory (
cwd
): Where you want the process to execute. An optional setting that defaults to the directory whereviam-server
executes.
You can also toggle whether you want errors and other messages to be logged, and whether to execute the command just once or keep running the process indefinitely.
In raw JSON, these options are represented by log
(bool) and one_shot
(bool), respectively.
Fragments
Fragments are a way of sharing and managing identical resource configuration files across multiple robots. For example, if you have multiple robots with the same hardware, wired the same way, you can create and share a fragment and add it to any number of robots. When changes are made to the fragment, those changes are automatically carried to all robots that include the fragment in their config.
Create a fragment
To create your own private fragment, go to app.viam.com/fragments or click on Fragments in the left navigation bar on the FLEET page.
- Enter a name for your new fragment and click Add fragment.
- Add the JSON configuration in the config field.
- Click SAVE FRAGMENT.
Add a fragment to a robot
You can add a fragment to a robot’s config and also add other configuration outside the fragment. For example, if you have multiple identical rovers but one has an arm attached, you can add the rover configuration fragment (including the motors and base components), and then configure the arm on just that one rover.
To add a fragment to a robot:
- Go to the Fragments subtab of your robot’s Config tab on the Viam app.
- Look through the list of available fragments and click Add next to any fragments you want to add to your robot.
- Click Save Config at the bottom of the screen.
The components and services included in the fragment appear inside a read-only fragment section in the Components and Services subtabs.
In the Raw JSON
configuration, you will see the fragment ID in the fragments
section:
{
"components": [],
"fragments": ["3e8e0e1c-f515-4eac-8307-b6c9de7cfb84"]
}
For an example of adding a fragment to a robot, see the Viam Rover fragment tutorial.
Modify the config of a robot that uses a fragment
When you modify a fragment, those changes are pushed to all robots that use that fragment. If you need to modify the config of just one robot that uses a fragment you can do the following:
- Go to the Fragments subtab of the Config tab.
- Click Remove next to the fragment.
- Select and copy the contents of the fragment in the box on the right side of the Fragments subtab.
- Toggle to Raw JSON mode.
- Paste the raw fragment contents into the Raw JSON config field.
- Click Save config.
- Now, you can edit the config either in Raw JSON mode or in Builder mode.
Auth/network
The auth section allows you to configure robot-level API keys for connecting over LAN.
The network section allows you to set the address viam-server
binds to for accepting connections.
By default, viam-server
binds to 0.0.0.0:8080
when managed by the Viam app or when authentication and TLS are enabled.
Frame system
The frame system holds reference frame information for the relative position of components in space.
Configure a frame for a given component on its panel on the Components tab, then switch to the Frame System tab to visualize the relative positions. Find more information in the frame system documentation.
Troubleshooting
If you run into issues, here are some things to try:
- Check the Logs tab to view log messages and errors from
viam-server
. You can also access the local log file on your robot if needed. - Make sure all configured components are actually saved to your config. If they aren’t, you will see an Unsaved Changes note next to the Save Config button at the bottom of the config screen.
- Try restarting
viam-server
by clicking Restart in the upper right corner of the app. It takes a few minutes for the server to shut down and restart. - Make sure the issue is not hardware related. Some things to check are that the robot has adequate power, all wires are properly connected, and no chips or other hardware components are shorted or overheated.
- See Troubleshooting for additional troubleshooting steps.
You can also ask questions in the Community Discord and we will be happy to help.
Local Setup
Configuring viam-server
with the Viam app allows you to make use of the cloud features of Viam:
However, if you are configuring a robot that can never connect to the internet, you can create a local configuration file on your robot. A locally-configured robot will not be able to access Viam’s cloud features.
Next Steps
After configuring your robot, you can use the Viam SDKs to program and control your robot.
If you want to try configuring a robot but don’t have any hardware on hand, try the Build a Mock Robot tutorial.
Have questions, or want to meet other people working on robots? Join our Community Discord.
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!