Machine Architecture: Parts

When smart machines communicate with each other, they can share resources and operate collaboratively. This document explains how to establish secure connections between machines.

Machine parts

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 viam-server.

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 part: 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 part 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.

Configuration

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.

The Viam app automatically creates the main part for you when you create a new machine. To add a new sub-part:

1. Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

2. Click the + (Create) icon next to the name of your main part, then click Sub-part from the menu:

   

To rename or delete a sub-part, or to make it the main part, click the … icon to open the Actions menu:

Configure a remote part

To establish a connection between a part of one machine and a part of a second machine, add one as a remote part in the other machine part’s config:

1. 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.

2. Navigate to the CONNECT tab.

3. Click Configure as a remote part in the left-hand menu.

4. Toggle the Include secret switch on, then copy the entire JSON snippet including the name, address, and authentication credentials of the remote part.

   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 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.

5. 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.

6. Navigate to the CONFIGURE tab, click the + (Create) icon next to the machine part’s name in the left side menu.

   

7. Click Remote part.

8. Find the newly-created remote part in the left hand menu. Click it to navigate to its configuration card.

9. Delete the auto-populated JSON from the new remote’s config area and replace it by pasting the remote config you copied in step 4 into the empty field.

   

10. Click Save in the upper right corner of the page to save your config.

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.