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:
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 machine that provides access to GPIO pins.
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 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 machine.
Component
A resource that represents a physical component in a machine which a computer controls; for example, a servo, a camera, or an arm.
Each component is typed by a proto API, such as the component proto definitions.
For more information, see Components.
Fragment
A reusable configuration block that you can share across multiple machines. For example, if you are deploying a specific mobile machine 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 machines that allows you to organize machines and manage access to your fleet.
For more information, see Manage Locations and Sub-Locations.
Machine
A smart machine is an organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks.
For more information, see Machines.
Machine Config
The complete configuration of a single machine part.
For more information, see Configuration.
Model
A particular implementation of a resource subtype that implements its API.
Models allow you to control hardware or software of a similar category, such as motors, with a consistent set of methods as an interface, even if the underlying implementation differs.
For example, some models of DC motors communicate using GPIO, while other DC motors use serial protocols like the SPI bus.
Regardless, you can power any motor model that implements the rdk:component:motor API with the SetPower() method.
Models are either included with viam-server, provided in custom modules available for download from the Viam registry, or installed as local modules.
All models are uniquely namespaced as colon-delimited-triplets.
Built-in model names have the form rdk:builtin:name.
Modular resource model names have the form namespace:repo-name:name.
See Naming your model for more information.
Model Namespace Triplet
Models are uniquely namespaced as colon-delimited-triplets.
Modular resource model names have the form namespace:repo-name:name.
Built-in model names have the form rdk:builtin:name.
See Naming your model for more information.
Modular Resource
A modular resource is a custom model of a component or service that implements the standardized API methods for that resource.
Modular resources are provided by modules, and are not built into the RDK.
A modular resource runs in the module process.
This differs from built-in resources, which run as part of viam-server.
For more information see the Modular Resource Documentation.
Module
A module provides one or more modular resources, which add resource types or models that are not built into Viam.
Modules run alongside viam-server as separate process, communicating with viam-server over UNIX sockets.
You can create your own module or add existing modules from the Viam registry.
For more information see the modular resource documentation.
MQL
MQL is the MongoDB query language, similar to SQL but specific to the MongoDB document model.
You can use MQL to query tabular data that you have synced to the Viam app using the data management service.
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
Smart 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.
For more information, see Machine Architecture: Parts.
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 instances of programs, invoked by commands running binaries or scripts 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.
Find more information in Configure a Process to Run on Your Machine.
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 part
A machine part which is controlled by another machine part.
For more information, see Machine Architecture: Parts.
Resource
Resources are individual, addressable elements of a machine.
Parts can operate multiple types of resources:
- physical components
- software services
- modular resources provided by modules
- processes
Each part has local resources and can also have resources from another remote machine part. The capabilities of each resource are exposed through the part’s API.
Each resource on your machine implements either one of the existing Viam APIs, or a custom interface.
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 Interact with Resources with Viam’s Client SDKs.
Service
Services are built-in software packages for complex capabilities such as Simultaneous Localization And Mapping (SLAM), computer vision, motion planning, and data collection.
Each service is typed by a proto API, such as the service proto definitions.
For more information, see Services.
SLAM
SLAM (Simultaneous Localization and Mapping) algorithms use data from a machine’s sensors, like LiDARs, cameras, and movement sensors, to generate a map of the environment and determine the machine’s position within it.
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.
SQL
SQL (structured query language) is the widely-used, industry-standard query language popular with relational databases.
You can use SQL to query tabular data that you have synced to the Viam app using the data management service.
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 machine 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 Agent
The Viam Agent is a provisioning application for deploying and managing viam-server across a fleet of machines.
You can use the Viam Agent to provision a machine as it first comes online with a pre-defined configuration, including WiFi networks or additional build or provision steps.
See Provision Machines for more information.
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.
View setup instructions
Before configuring a machine part, you must follow the correct setup instructions for your machine’s architecture. You can view the setup instructions by navigating to the CONFIGURE tab and finding your machine’s card. If it hasn’t been set up, an alert will be present directing you to Set up your machine part. Click View setup instructions to open the setup instructions.
After setting up the part, you can view the setup instructions again by navigating to the CONFIGURE tab, finding the machine part’s card, clicking the … menu in the upper right corner and selecting View setup instructions.
You can also view the setup instructions by opening the part status dropdown menu in the top left corner of the page (next to your machine’s name) and selecting View setup instructions in the appropriate part’s box. Or, you can find the machine part in the left-hand nested configuration menu of the CONFIGURE tab, select the … menu, and select View setup instructions.
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.