From f4035b4a3ecd07371642715e836e3e84af02ddaf Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 23 Oct 2024 14:03:13 +0200 Subject: [PATCH] DOCS-3049: Update viam-server page slightly --- docs/appendix/contributing.md | 2 +- docs/appendix/glossary/model.md | 2 +- docs/appendix/glossary/rdk.md | 4 ++-- docs/architecture/viam-micro-server.md | 2 +- docs/architecture/{rdk.md => viam-server.md} | 10 ++++------ docs/installation/viam-micro-server-dev.md | 2 +- docs/installation/viam-server-setup.md | 2 +- docs/registry/modular-resources.md | 6 +++--- .../tutorials/projects/integrating-viam-with-openai.md | 2 +- static/include/components/apis/generated/camera.md | 3 +++ 10 files changed, 18 insertions(+), 17 deletions(-) rename docs/architecture/{rdk.md => viam-server.md} (80%) diff --git a/docs/appendix/contributing.md b/docs/appendix/contributing.md index c7e777c792..669d5d4129 100644 --- a/docs/appendix/contributing.md +++ b/docs/appendix/contributing.md @@ -62,7 +62,7 @@ The docs use the [Diátaxis Framework](https://diataxis.fr/) as the basis of t - **Explanation (conceptual)**: An understanding-oriented piece of content. This content provides background knowledge on a topic and tends to be referenced in how-to guides and tutorials. - For example the [`viam-server` page](/architecture/rdk/) or the [Registry page](/registry/). + For example the [`viam-server` page](/architecture/viam-server/) or the [Registry page](/registry/). It’s useful to have a real or imagined "Why?" question to serve as a prompt. {{< expand "Click to view template" >}} diff --git a/docs/appendix/glossary/model.md b/docs/appendix/glossary/model.md index 09568efbae..0265a5ed5e 100644 --- a/docs/appendix/glossary/model.md +++ b/docs/appendix/glossary/model.md @@ -12,7 +12,7 @@ Models allow you to control hardware or software of a similar category, such as For example, some _models_ of DC motors communicate using [GPIO](/components/board/), 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`](/architecture/rdk/) or provided through {{< glossary_tooltip term_id="module" text="modules" >}}. +Models are either included with [`viam-server`](/architecture/viam-server/) or provided through {{< glossary_tooltip term_id="module" text="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`. diff --git a/docs/appendix/glossary/rdk.md b/docs/appendix/glossary/rdk.md index ea63583c14..a4b9c9bf95 100644 --- a/docs/appendix/glossary/rdk.md +++ b/docs/appendix/glossary/rdk.md @@ -1,8 +1,8 @@ --- title: RDK (Robot Development Kit) id: rdk -full_link: /architecture/rdk/ +full_link: /architecture/viam-server/ short_description: The official Viam-developed codebase that provides all functionality of an SDK and more. --- -Viam’s Robot Development Kit (RDK) is the [open-source](https://github.com/viamrobotics/rdk), on-machine portion of the Viam platform, that provides [`viam-server`](/architecture/rdk/) and the Go SDK. +Viam’s Robot Development Kit (RDK) is the [open-source](https://github.com/viamrobotics/rdk), on-machine portion of the Viam platform, that provides [`viam-server`](/architecture/viam-server/) and the Go SDK. diff --git a/docs/architecture/viam-micro-server.md b/docs/architecture/viam-micro-server.md index ac8fa9a085..42cad1d5ae 100644 --- a/docs/architecture/viam-micro-server.md +++ b/docs/architecture/viam-micro-server.md @@ -11,7 +11,7 @@ date: "2024-09-03" # SMEs: Nicolas M., Gautham V., Andrew M. --- -`viam-micro-server` is the lightweight version of [`viam-server`](/architecture/rdk/) which can run on resource-limited embedded systems (ESP32) that cannot run the fully-featured `viam-server`. +`viam-micro-server` is the lightweight version of [`viam-server`](/architecture/viam-server/) which can run on resource-limited embedded systems (ESP32) that cannot run the fully-featured `viam-server`. `viam-micro-server` is built from the [micro-RDK](https://github.com/viamrobotics/micro-rdk/tree/main). ## Hardware requirements diff --git a/docs/architecture/rdk.md b/docs/architecture/viam-server.md similarity index 80% rename from docs/architecture/rdk.md rename to docs/architecture/viam-server.md index b137d922f1..cf72e7b60f 100644 --- a/docs/architecture/rdk.md +++ b/docs/architecture/viam-server.md @@ -9,15 +9,14 @@ aliases: - "/product-overviews/rdk" - "/build/program/rdk" - /internals/rdk/ + - /architecture/rdk/ --- -At the core of Viam is the open-source `viam-server` executable which runs on a computer and manages hardware, software, and data for a machine. +The open-source `viam-server` executable runs on a computer and manages hardware, software, and data for a machine. If you are working with microcontrollers, [`viam-micro-server`](/architecture/viam-micro-server/) is a lightweight version of `viam-server` which can run on resource-limited embedded systems that cannot run the fully-featured `viam-server`. To use Viam with a machine, you create a configuration specifying which hardware and software the machine consists of. -Viam has many built-in {{< glossary_tooltip term_id="component" text="components" >}} and {{< glossary_tooltip term_id="service" text="services" >}} that run within `viam-server`. -The components and services are configurable building blocks you can put together to make your machine. -`viam-server` then manages and runs the drivers for the configured hardware components and software services. +`viam-server` manages and runs the drivers for the configured {{< glossary_tooltip term_id="resource" text="resources" >}}. Overall, _viam-server_ manages: @@ -34,8 +33,7 @@ Overall, _viam-server_ manages: ## Dependency management -Modular resources may depend on other built-in resources or other modular resources, and vice versa. -The Viam RDK handles dependency management. +`viam-server` handles dependency management between resources. ## Start-up diff --git a/docs/installation/viam-micro-server-dev.md b/docs/installation/viam-micro-server-dev.md index b9dafa8b1d..dc3505dfd8 100644 --- a/docs/installation/viam-micro-server-dev.md +++ b/docs/installation/viam-micro-server-dev.md @@ -18,7 +18,7 @@ aliases: - /installation/viam-micro-server-dev/ --- -`viam-micro-server` is the lightweight version of [`viam-server`](/architecture/rdk/) which can run on resource-limited embedded systems (ESP32) that cannot run the fully-featured `viam-server`. +`viam-micro-server` is the lightweight version of [`viam-server`](/architecture/viam-server/) which can run on resource-limited embedded systems (ESP32) that cannot run the fully-featured `viam-server`. This page provides instructions for configuring a development environment for working with `viam-micro-server`, outlines the steps for performing various development tasks, and provides troubleshooting and development tips to help organize and streamline work. diff --git a/docs/installation/viam-server-setup.md b/docs/installation/viam-server-setup.md index cdad8ead2d..a555949fb3 100644 --- a/docs/installation/viam-server-setup.md +++ b/docs/installation/viam-server-setup.md @@ -25,7 +25,7 @@ aliases: To use Viam, you need to install either the `viam-server` binary or `viam-micro-server`. -[`viam-server`](/architecture/rdk/) is the binary built from the [Robot Development Kit](https://github.com/viamrobotics/rdk) that contains and manages communications between all Viam's built-in hardware drivers ({{< glossary_tooltip term_id="component" text="components" >}}) and software {{< glossary_tooltip term_id="service" text="services" >}}, connects your machine to the cloud, manages machine configuration, and manages dependencies including {{< glossary_tooltip term_id="module" text="modules" >}}. +[`viam-server`](/architecture/viam-server/) is the binary built from the [Robot Development Kit](https://github.com/viamrobotics/rdk) that contains and manages communications between all Viam's built-in hardware drivers ({{< glossary_tooltip term_id="component" text="components" >}}) and software {{< glossary_tooltip term_id="service" text="services" >}}, connects your machine to the cloud, manages machine configuration, and manages dependencies including {{< glossary_tooltip term_id="module" text="modules" >}}. `viam-micro-server` is a lightweight version of `viam-server` which can run on resource-limited embedded systems that cannot run the fully-featured `viam-server`. To install `viam-micro-server`, see [`viam-micro-server` Installation Guide](/installation/viam-micro-server-setup/) instead. diff --git a/docs/registry/modular-resources.md b/docs/registry/modular-resources.md index c57c48a6c7..00b85a9b2d 100644 --- a/docs/registry/modular-resources.md +++ b/docs/registry/modular-resources.md @@ -111,7 +111,7 @@ The following properties are available for modular resources: | `namespace` | string | **Required** | The namespace of the API (the first part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). This will be `rdk` unless the module implements a [custom, non-standard API](/registry/advanced/). See [Valid API identifiers](/how-tos/create-module/#valid-api-identifiers). | | `type` | string | **Required** | The {{< glossary_tooltip term_id="subtype" text="subtype">}} of the API (the third part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid API identifiers](/how-tos/create-module/#valid-api-identifiers). | | `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's {{< glossary_tooltip term_id="model" text="model" >}}. | -| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your machine alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/architecture/rdk/#dependency-management). | +| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your machine alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/architecture/viam-server/#dependency-management). | ### Module configuration @@ -319,9 +319,9 @@ To set the path to a program or library on a machine, you can set a system varia ## How modules run -Modules run alongside [`viam-server`](/architecture/rdk/) as separate processes, communicating with `viam-server` over UNIX sockets. +Modules run alongside [`viam-server`](/architecture/viam-server/) as separate processes, communicating with `viam-server` over UNIX sockets. When a module initializes, it registers its {{< glossary_tooltip term_id="model" text="model or models" >}} and associated [APIs](/appendix/apis/) with `viam-server`, making the new model available for use. -`viam-server` manages the [dependencies](/architecture/rdk/#dependency-management), [start-up](/architecture/rdk/#start-up), [reconfiguration](/architecture/rdk/#reconfiguration), [data management](/services/data/#configuration), and [shutdown](/architecture/rdk/#shutdown) behavior of your modular resource. +`viam-server` manages the [dependencies](/architecture/viam-server/#dependency-management), [start-up](/architecture/viam-server/#start-up), [reconfiguration](/architecture/viam-server/#reconfiguration), [data management](/services/data/#configuration), and [shutdown](/architecture/viam-server/#shutdown) behavior of your modular resource. ## Next steps diff --git a/docs/tutorials/projects/integrating-viam-with-openai.md b/docs/tutorials/projects/integrating-viam-with-openai.md index ac8726cb13..cb0f9df89b 100644 --- a/docs/tutorials/projects/integrating-viam-with-openai.md +++ b/docs/tutorials/projects/integrating-viam-with-openai.md @@ -133,7 +133,7 @@ You can also attach your speaker to the top of your rover with [double-sided foa The [git repository](https://github.com/viam-labs/tutorial-openai-integration) for this tutorial contains code that integrates with: -- [viam-server](/architecture/rdk/) +- [viam-server](/architecture/viam-server/) - [Google text/speech tools](https://gtts.readthedocs.io/en/latest/) - [OpenAI](https://openai.com/api/) diff --git a/static/include/components/apis/generated/camera.md b/static/include/components/apis/generated/camera.md index a1a1f89d5a..7dec5e0320 100644 --- a/static/include/components/apis/generated/camera.md +++ b/static/include/components/apis/generated/camera.md @@ -41,6 +41,8 @@ For example: ```python {class="line-numbers linkable-line-numbers"} from viam.media.utils.pil import pil_to_viam_image, viam_to_pil_image +my_camera = Camera.from_robot(robot=machine, name="my_camera") + # Get the ViamImage from your camera. frame = await my_camera.get_image() @@ -207,6 +209,7 @@ The consumer of this call should decode the bytes into the format suggested by t import numpy as np import open3d as o3d +my_camera = Camera.from_robot(robot=machine, name="my_camera") data, _ = await my_camera.get_point_cloud() # write the point cloud into a temporary file