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 multiple computers within the same machine, use one as the main part and connect each additional part to it as a sub-part. Any given part can only be a sub-part of one main part.

  Click for an example.

  Imagine you have a system of five cameras in different places along an assembly line, each attached to its own single-board computer, and you want to run an object detector on the streams from all of them. You have one main computer with greater compute power set up as the main part. You set up each of the single-board computers as a sub-part. This allows the main part to access all the camera streams and run object detection on all of them.
  
  You could also set this up with each single-board computer being a remote part instead of a sub-part, but it is slightly easier to configure sub-parts because you do not need to add the address of each part to your machine's config. Additionally, configuring a discrete system of parts as one multi-part machine helps keep your fleet more clearly organized in the Viam app.
  
  

• Remote part: To connect multiple computers that are parts of different machines in the same or different organizations, add one machine part as a remote part of the other machine or machines. A part can be a remote part of any number of other parts.

  Click for an example.

  If you have one camera connected to a computer in a warehouse that many machines should be able to share, you can configure the camera as a remote part of each machine that needs it.

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.

When a part starts up, it attempts to connect to any remotes and sub-parts. If it cannot connect to them, the part will still successfully start up.

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