You can use the Viam web app to control your machines, or the Viam SDKs to develop frontend and backend applications. But if you want to explore what's happening behind the scenes, let's use Viam's gRPC API to control a rover.

Prerequisites

• Sign up for a free Viam account, and then sign in to the Viam app.
• Set up a rover, such as Yahboom or SCUTTLE or Viam rover
• Sign up for a free Postman account, and then sign in. If you're using the web version of Postman, also download and install the Postman desktop agent.

What You'll Learn

• Authorize the Viam gRPC API
• Invoke API methods available for your machine's resources
• Use variables in Postman to store data

What You'll Need

• A free Viam Account
• A machine running on Viam
• A free Postman Account

What You'll Build

• A working Postman collection to control and interact with your Viam machine

Watch the Video

Follow along with the step-by-step video.

Fork the collection

In Postman, fork the following collection to your own workspace.

1. Select the collection in the sidebar.
2. Select the overflow menu (...), and Fork the collection.
3. Enter a label for your fork, and select a workspace to save it to.
4. Select Fork Collection.

Postman creates your fork in the selected workspace. You can now update this version of the collection as you wish. If you optionally chose to watch the collection, you can pull changes to your own collection when the main collection is updated.

For each folder and request, review the companion documentation in the context bar to the right.

Find your Viam credentials

1. To find the API key and API key ID, go to the Viam app, select the machine you wish to connect to, and under the Connect tab, select a code sample language. Toggle Include API key, and then copy and paste the API key ID and API key to update your Postman variables
2. To find the machine address, go to the Viam app, select the machine you wish to connect to, and under the Status dropdown, copy the Remote address to update your Postman variable.
3. Input your credentials for api_key, api_key_id, and machine_url as Postman variables and Save your changes.

In the next section, let's learn about generating access tokens.

Authorization

To authorize subsequent calls to the Viam server running on your smart machine, generate access tokens in Postman.

1. Invoke the AuthService / Authenticate method to generate an access token. Under the Messages tab, notice you are using your api_key and api_key_id to authorize the call to the app_url. Under the Scripts tab, notice code that saved the access token as a variable app_access_token for you to re-use in subsequent requests.
2. Invoke the ExternalAuthService / AuthenticateTo method to generate an access token. Under the Scripts tab, notice code that saved the access token as a variable machine_access_token.
3. For subsequent calls to Viam gRPC services, you can include the machine_access_token variable under the Authorization tab expressed with double curly braces like {{machine_access_token}} using the Bearer token authorization type in order to make calls to your machine_url.

Check out the documentation for more details about each request in the context bar on the right side of Postman.

Get resource names

1. Invoke the RobotService / ResourceName method to get a list of resources associated with your machine. Notice you are using your machine_access_token to authorize the call to your machine_url.
2. In the server response, find the base component, and make a note of the component's name. We will need it for the next step.

Spin a Viam rover

1. Open the BaseService / Spin request. Once again, you are using your machine_access_token to authorize the call to your machine_url. This time, additional information is required. Under the Messages tab of your request, update the name property to the name of your own base component retrieved in the previous step.
2. Invoke the method to spin your rover.

From here, you can continue updating the payload, exploring other hardware Components, software Services, and experiment with other cloud capabilities, such as machine learning.

This tutorial was a hands-on introduction to the Viam gRPC API. Browse other methods available using server reflection, or see some of them documented in the Viam gRPC API collection as a reference. Read more about how Viam uses gRPC and WebRTC for system architecture.

In most cases, you won't be developing applications or controlling them using the raw gRPC APIs. Instead, check out these resources:

• The Viam SDK libraries for development
• The Viam web app for ad hoc controls

Once you learn the fundamentals of working with your machine, you can start adding more intelligence and capabilities, such as the following.

• Viam Data Management: Collect data from different parts of a robot, IoT device, or any other machine
• Viam Fleet management: Organize, manage, and control any number of machines alone or in collaboration with others
• Viam Registry: Add and share a modular resource on your robot