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":"ab0cd0efghijkl0m12no3pqrstuvw0xyza4bcd567891abcd"}}
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 another location.
To start viam-server
with a config file in a different location, run the following command:
sudo viam-server -config <path-to-config>.json
viam-server -config <path-to-config>.json
After you have completed the setup steps and successfully connected to your robot, go to the Config tab to start adding to the configuration.
Note
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 you cannot connect your robot to the internet at all, you can also store the 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).
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: Modular resources 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 name, a model, a type, attributes, and dependencies:
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.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.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.
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.
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 check for any errors or other info from
viam-server
.You can also view logs locally by running the following command on the robot:
sudo journalctl --unit=viam-server
cat $(brew --prefix)/var/log/viam.log
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.
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:
A locally configured robot, will not be able to access Viam’s cloud features. If you are configuring a robot that can never connect to the internet, you can manually create a local full raw JSON config file on your robot.
You can write the contents of this config file manually, or you can use the Viam app’s config builder (without connecting your robot to it).
Once you finish configuring your robot in the Builder mode, switch to Raw JSON and copy the entire raw JSON into your config file.
Save the file at
Then start viam-server
:
sudo viam-server
viam-server
If you have stored your config file at a location different from the default location (
sudo viam-server -config <path-to-config>.json
viam-server -config <path-to-config>.json
To run viam-server
as a system service, see Start automatically on boot.
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 there is anything we could be doing better, please create an issue.
We're sorry about that. If you'd like to talk to us for help, please join the Community Discord. To ensure we know what's wrong with this page, you can also open an issue.