From 9f99313a66407a1592746e9073c3b96ebcab87e8 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Thu, 14 Mar 2024 11:34:39 -0700 Subject: [PATCH] DOCS-1447: Add info to components and services landing pages (#2641) --- docs/appendix/glossary/machine.md | 2 +- docs/components/_index.md | 15 +++++++++++++-- docs/components/base/_index.md | 2 +- docs/services.md | 19 ++++++++++++++++++- 4 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/appendix/glossary/machine.md b/docs/appendix/glossary/machine.md index 7799b173fd..2fdce91cc2 100644 --- a/docs/appendix/glossary/machine.md +++ b/docs/appendix/glossary/machine.md @@ -2,7 +2,7 @@ title: Machine id: machine full_link: /fleet/machines/ -short_description: An organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks. +short_description: An organizational concept, consisting of a computer and the components and services it controls, or sometimes multiple computers working closely together. --- A smart machine is an organizational concept, consisting of either one _{{< glossary_tooltip term_id="part" text="part" >}}_, or multiple _parts_ working closely together to complete tasks. diff --git a/docs/components/_index.md b/docs/components/_index.md index f7cb58901a..bb6a0066c0 100644 --- a/docs/components/_index.md +++ b/docs/components/_index.md @@ -9,9 +9,20 @@ aliases: - "/components/" --- -A _component_ represents a physical piece of electrical or electromechanical hardware in a machine. +Viam provides support for a wide variety of hardware. +A _component_ represents a physical piece of hardware in your {{< glossary_tooltip term_id="machine" text="machine" >}}, and the software that directly supports that hardware. + +{{< imgproc src="/viam/machine-components.png" alt="Diagram with various components and services on a smart machine. This machine employs the vision, navigation, and data capture services, which run within viam-server on the machine's single board computer." resize="1000x" style="max-width:650px" class="aligncenter" >}} +
+ +Viam groups categories of hardware together, with a [standardized API](/build/program/apis/#component-apis) for all _{{< glossary_tooltip term_id="model" text="models" >}}_ in each grouping. +For example, [`xarm7`](/components/arm/xarm7/) and [`ur5e`](/components/arm/ur5e/) are different arm models, which provide software support for xArm7 arms and UR5e arms, respectively. +Though the hardware is different, you use the same Viam SDK commands to control both models, for example [`MoveToPosition`](/components/arm/#movetoposition). + +You need to [configure](/build/#step-2-configure) a component to represent each piece of hardware your machine controls. +Configuration is the process of editing the file that indicates to `viam-server` what hardware is available to it, how to communicate with that hardware, and how the pieces of hardware relate to each other (for example, which board a motor is connected to). Viam provides built-in support for the following component types. -You can also add support for additional component types using {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}. +You can also add support for additional component types using [{{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}](/registry/). If you are connecting components to a microcontroller instead of a 64-bit single-board computer, find component configuration information in the [micro-RDK documentation](/build/micro-rdk/). diff --git a/docs/components/base/_index.md b/docs/components/base/_index.md index 092b4d7a13..13a117fe2a 100644 --- a/docs/components/base/_index.md +++ b/docs/components/base/_index.md @@ -4,7 +4,7 @@ linkTitle: "Base" weight: 10 type: "docs" no_list: true -description: "The moving platform that the other parts of a mobile robot attach to." +description: "A moving platform that the other parts of a mobile robot attach to." tags: ["base", "components"] icon: true images: ["/icons/components/base.svg"] diff --git a/docs/services.md b/docs/services.md index 160f065fd5..caa3934bf6 100644 --- a/docs/services.md +++ b/docs/services.md @@ -11,8 +11,25 @@ aliases: Services are built-in software packages that make it easier to add complex capabilities such as motion planning or object detection to your machine. +In the following diagram, the machine is comprised of various hardware components including a GPS and a camera, and software (`viam-server`) running on a single-board computer. +Some of that software is the low-level code that communicates directly with the hardware [components](/components/), while some pieces of that software (the _services_) add higher-level functionality. +In this case, the vision service is configured to run computer vision models on output from the camera component. +The navigation service can take the raw output from the GPS component output and determine geographical location, and the data service captures data from any or all of the components, for example storing images from the camera. + +{{< imgproc src="/viam/machine-components.png" alt="Machine components" resize="1000x" style="max-width:650px" class="aligncenter" >}} +
+ +Many built-in services run locally within `viam-server`, but you can think of them as discrete building blocks that you can mix and match however you want; you can run your machine using none, some, or all of them, depending on your use case. +To use a given service, add it to your machine's configuration. + +[Configuring](/build/#step-2-configure) services on your machine indicates to `viam-server` which software packages you want to use with your machine, and how to integrate that software with your [components](/components/) and other services. +Services take many forms, so their configuration and usage varies widely. +For example, when you [configure data capture](/data/capture/), you indicate which types of data you want to capture, from which components. +When you configure the [frame system](/mobility/frame-system/), you indicate how the components relate to each other spatially. +Find more information in the documentation for each service below. + Viam provides built-in support for the following service types. -You can also add support for additional service types using {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}. +You can also add support for additional service types using [{{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}](/registry/). {{< cards >}} {{% card link="/data/" %}}