Glossary

API Namespace Triplet

Every Viam resource subtype exposes an application programming interface (API) to describe how you can interact with that resource.

These APIs are organized by colon-delimited-triplet identifiers, in the form of namespace:type:subtype.

The namespace for built-in Viam resources is rdk, while the type is component or service. subtype refers to a specific component or service, like a camera or vision.

One subtype can have various models, custom or built-in, but they all must conform to the subtype’s API definition. This requirement ensures that when a resource of that model is deployed, you can interface with it using the same client API methods you would when programming resources of the same subtype with a different model.

For example:

  • The API of the built-in component camera is rdk:component:camera, which exposes methods such as GetImage().
  • The API of the built-in service vision is rdk:service:vision, which exposes methods such as GetDetectionsFromCamera().

Attribute

A configuration parameter of a resource.

Base

A physical, mobile platform that the other parts of a mobile robot attach to. For example, a wheeled rover, boat, or flying drone.

For more information see Base Component.

Board

A board is the signal wire hub of a smart machine that provides access to GPIO pins, SPI or I2C.

Examples of boards include Jetson, Raspberry Pi, Numato, or Arduino.

For more information see Board Component.

Client Application

Client applications run business logic to operate your smart machine.

You can run a client application on the same part that runs viam-server, or on a separate device. Client applications typically use an SDK to talk to their smart machine.

Component

A resource that represents a physical component in a robot which a computer controls; for example, a servo, a camera, or an arm.

For more information, see Components.

Fragment

A reusable configuration block that you can share across multiple smart machines. For example, if you are deploying a specific mobile robot that is always physically connected the same way, you can create a fragment to make managing your fleet easy.

For more information, see Fragments.

Frame

A frame represents a coordinate system that describes the position and orientation of an object. See also frame system.

The location of a frame is described in relation to its parent frame using rigid transformations rather than in absolute terms.

Frame System

The frame system holds reference frame information for the relative position of components in space.

Gantry

A mechanical system that only uses linear motion to carry out a task; for example, the scaffolding of a 3D printer, which moves the print head around on motorized linear rails.

gRPC

An open source, cross-platform, high performance Remote Procedure Call (RPC) framework initially developed at Google in 2015. With gRPC, a client application can communicate directly with a server application on a different machine. This framework can run in any environment and efficiently connect distributed applications and services.

For more information see grpc.io.

Location

A location is a virtual grouping of smart machines that allows you to organize smart machines and manage access to your fleet.

For more information, see Manage Locations and Sub-Locations.

Model

A particular implementation of a resource subtype.

For example: ur5e is a model of arm, implementing the resource API of the arm subtype of component, which, in turn, is a type of resource.

Model Namespace Triplet

Models are uniquely namespaced as colon-delimited-triplets in the form of namespace:family:name.

For example:

  • The rdk:builtin:gpio model implements the rdk:component:motor API to support GPIO-controlled DC motors.
  • The rdk:builtin:DMC4000 model implements the rdk:component:motor API to support DMC4000 motor controllers.

Module

A module provides one or more modular resources, which add resource types (components and services) or models that are not built into Viam.

You can extend the capabilities of Viam on your robot by creating your own module or adding an existing module from the Viam registry.

For more information see the modular resource documentation.

Organization

An organization is the highest level grouping in the Viam platform, which generally represents a company, or other institution. Every location is grouped into an organization. You can also have organizations for departments or other entities, or for personal use.

For more information, see Manage Organizations.

Part

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

For more information, see Robot Architecture: Parts, Sub-Parts and Remotes.

Pin Number

A pin number is the physical index of a pin on a board.

This number is distinct from the GPIO number assigned to general purpose input/output (GPIO) pins. For example, pin number “11” on a NVIDIA Jetson Nano is GPIO “50”, and pin number “11” on a Raspberry Pi 4 is GPIO “17”. When Viam documentation refers to pin number, it will always mean the pin’s physical index and not GPIO number.

Pin numbers are found on a board’s pinout diagram and data sheet.

Process

Processes are binaries or scripts that run on a part.

You can use processes to create a new local instance of viam-server to implement drivers for custom components, or to run a client application, for example. They provide an OS-specific process managed by viam-server to either run once or indefinitely. For example, you could use a process to run a camera server.

For information on how to configure a process, see Configure a Robot.

Protocol Buffers (Protobuf)

A free and open-source, language-neutral, cross-platform data format for serializing structured data.

Protocol Buffers are useful in developing programs that communicate with each other over a network or for storing data.

RDK (Robot Development Kit)

The RDK is the official Viam-developed codebase that provides all functionality of an SDK and more.

Remote

A robot part which is controlled by another robot part.

For more information, see Robot Architecture: Parts, Sub-Parts and Remotes.

Resource

Resources are individual, addressable elements of a robot.

Parts can operate multiple types of resources:

Each part has local resources and can also have resources from another remote robot part. The capabilities of each resource are exposed through the part’s API.

Robot

An organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks.

For more information, see Robots.

Robot Config

The complete configuration of a single robot part.

For more information, see Configuration.

SDK (Software Development Kit)

Viam provides software development kits (SDKs) to help you write client applications and create support for custom component types.

The SDKs wrap the viam-server gRPC Viam Robot API and streamline connection, authentication, and encryption.

For more information, see Program your Robot with Viam’s SDKs.

Service

Services are built-in software packages for complex capabilities such as SLAM, computer vision, motion planning, and data collection.

For more information, see Services.

SLAM

Simultaneous Localization and Mapping (SLAM) is an algorithm that allows your robot to create a map of its surroundings and find its location within that map.

For more information, see SLAM.

Smart Machine

A machine or device that lives in the real world and has some ability to perceive the world (with a sensor, for example) and perform actions like operating a motor. The machine might also interact with other systems, with the cloud, or with users.

Subtype

A category within a type of resource. Resource models belonging to a subtype share the same API. Models implement that subtype’s API protocol with different drivers.

For example, an arm is a subtype of the component resource type, while the ur5e is a model of the arm subtype’s API.

The Vision Service is a subtype of the service resource type.

A subtype is designated by its api-namespace-triplet.

Type

In the RDK architecture’s namespace triplet for resource APIs, type refers to the distinction between component or service.

However, the meaning of “type” can be context dependent across the Viam platform.

For example, when configuring a robot in the Viam app, "type" is used in the JSON to indicate a particular implementation of a component or service, which is formally designated as the subtype.

Viam Robot API

The specification for communication with resources.

  • The SDKs implement the Viam Robot API server-side.
  • The SDKs use the Viam Robot API to act as clients.

Currently, the Viam Robot API is defined in a collection of Protocol Buffer files.

All SDKs written by Viam use gRPC but the Viam Robot API itself does not mandate gRPC as the transport mechanism.

Web sockets

A computer communications protocol that provides full-duplex communication channels over a single Transmission Control Protocol (TCP) connection.

WebRTC

An open source project which provides applications with real-time communication (RTC) using application programming interfaces (API) allowing powerful voice and video integration.

For more information see webrtc.org.