Architecture: Parts, Sub-Parts, and Remotes
When smart machines communicate with each other, they can share resources and operate collaboratively. This document explains how to establish secure connections between machines.
Machines are organized into parts, where each part represents a computer (a single-board computer, desktop, laptop, or other computer) running
viam-server, the hardware components attached to it, and any services or other resources running on it.
Every smart machine has a main part which is automatically created when you create the machine.
Multi-part machines also have one or more sub-parts representing additional computers running
There are two ways to link machine parts:
Sub-part: If you have two computers within the same machine, use one as the main part and connect the other to it as a sub-part.
Remote: To connect two computers that are parts of different machines, add one machine part as a remote part of the other machine.
Connections between machines are established using the best network path available.
When you configure a remote or a sub-part, the main machine part can access all the components and services configured on the remote machine part as though they were entities of the main machine part. This is a one-way connection: the main machine part can access the resources of the remote machine part, but the remote machine cannot access the resources of the machine part remoting into it.
Configure a sub-part
You can make a multi-part machine by first configuring one part which is the “main” part, and then configuring one or more sub-parts. The main part will be able to access the resources of its sub-parts. Sub-parts will not have access to the resources of the main part.
Use the parts dropdown menu in the top banner of your machine’s page on the Viam app to add a new sub-part:
To delete a sub-part or make it the main part, use the buttons in the top right of the Config tab.
Configure a remote
To establish a connection between a part of one machine and a part of a second machine, configure a
remote on the first machine’s part.
Go to the Viam app machine page of the smart machine part to which you wish to establish the remote connection. This is the machine part whose resources will be accessible to the other machine part.
Click the Code sample tab.
On the Language toggle, select Remotes, then click Copy.
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 secret on the Code sample tab. You can also see your API key and API key ID on your machine’s Security tab.
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.
Go to the Viam app machine page of the machine part from which you want to establish a remote connection. This is the machine part that will be able to access the resources of the other machine part.
Click the Config tab, click the Remotes subtab, and select JSON mode.
Click Create Remote.
Paste the remote config you copied in step 4 into the empty field.
Click Save Config in the bottom left of the screen.
Using remote parts and sub-parts with the Viam SDKs
Once your sub-part or remote part is configured, you can access all the components and services configured on the sub-part or remote machine part as though they were resources of your main machine part. The only difference is that the names of the components have the remote machine part name prepended to them. For example, instead of calling
servo = Servo.from_robot(robot=robot, name='my_servo')
you need to call
servo = Servo.from_robot(robot=robot, name='my-sub-part-name:my_servo')
servo = Servo.from_robot(robot=robot, name='my-other-robot-main:my_servo')
For an example that controls a motor that is a component of a sub-part, see the 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: