From cf4f764763693d30f53fdf9680bf8ac705bca3c5 Mon Sep 17 00:00:00 2001 From: JessamyT Date: Wed, 1 Nov 2023 17:12:23 -0700 Subject: [PATCH 1/5] DOCS-1270: Improve generic --- docs/components/generic/_index.md | 6 ++++-- docs/modular-resources/_index.md | 10 ++++++---- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md index 1a639ced8e..538200079e 100644 --- a/docs/components/generic/_index.md +++ b/docs/components/generic/_index.md @@ -14,6 +14,8 @@ no_list: true The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >}} is for custom components that are incompatible with any of the other component APIs. +For example, if you have an LED display, it does not make sense to implement it as an arm, camera, or any other existing component subtype because an LED display does not have joints or capture images. + There are no built-in generic component models (other than `fake`). Use generic for a [modular resource](/modular-resources/) model that represents a unique type of hardware. @@ -23,13 +25,13 @@ The generic component API only supports the `DoCommand` method. If you use the generic subtype, your module needs to define any and all component functionality and pass it through `DoCommand`. Whenever possible, it is best to use an [existing component API](/components/) instead of generic so that you do not have to replicate code. -If you want to use most of an existing API but need just a few other functions, try using the `DoCommand` endpoint and extra parameters to add custom functionality to an existing subtype. +If you want to use most of an existing API but need just a few other functions, try using the `DoCommand` endpoint and extra parameters to add custom functionality to an [existing subtype](/components/), instead of using generic. {{% /alert %}} ## Supported Models -To use your generic component with Viam, check whether one of the following [modular resources](#modular-resources) supports your component. +Before creating a new generic component, check whether one of the following [modular resources](#modular-resources) supports your component. {{< readfile "/static/include/create-your-own-mr.md" >}} diff --git a/docs/modular-resources/_index.md b/docs/modular-resources/_index.md index 42c63bcd62..039a5a8fa1 100644 --- a/docs/modular-resources/_index.md +++ b/docs/modular-resources/_index.md @@ -59,18 +59,20 @@ If none of the existing modular resources in the Viam registry support your use - **Implement a custom component**: You can write a driver for an unsupported {{< glossary_tooltip term_id="component" text="component" >}} by implementing the corresponding component API. -- **Implement a custom service**: You can implement your own algorithm or {{< glossary_tooltip term_id="model" text="model" >}} against a corresponding service API or use custom algorithm or data models when working with services such as [SLAM](/services/slam/), [vision](/services/vision/), or [motion planning](/services/motion/). - -- **Implement fully custom logic**: If your robot runs specialty or proprietary logic, and you want to use Viam to manage and control that logic, such as when managing a software development lifecycle, you can implement your own custom logic by wrapping the [generic API](/components/generic/). +- **Implement a custom service**: You can implement your own algorithm or {{< glossary_tooltip term_id="model" text="model" >}} against a corresponding service API or use custom algorithms or data models when working with services such as [SLAM](/services/slam/), [vision](/services/vision/), or [motion planning](/services/motion/). To create a new modular resource: -1. [Code a new resource model](/modular-resources/create/) by implementing all methods for the component's or service's [standardized APIs](/program/apis/). +1. [Code a new resource model](/modular-resources/create/) by implementing all methods for the component's or service's [standardized API](/program/apis/). 1. Package your modular resource or modular resources as a {{< glossary_tooltip term_id="module" text="module" >}} and [upload the module to the Viam registry](/modular-resources/upload/) to make it available for deployment to robots. You can upload _private_ modules for your [organization](/manage/fleet/organizations/) or _public_ modules. 1. Once you have uploaded your module to the registry, you can [deploy and configure the module](/modular-resources/configure/) from [the Viam app](https://app.viam.com/). You can test your added resource using the [**Control** tab](/manage/fleet/#remote-control) and [program](/program/) it with Viam's Go or Python SDKs. +### Unique cases + +If your hardware won't work with any of the standard component APIs, you can use the [generic API](/components/generic/). + Some use cases may require you to define a new API, or to deploy custom components using a server on a remote part. For more information, see [Advanced Modular Resources](/modular-resources/advanced/). From c70d5e7edaa2ef33bae111762c8983625c8ce259 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 3 Nov 2023 16:09:17 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: andf-viam <132301587+andf-viam@users.noreply.github.com> --- docs/components/generic/_index.md | 8 ++++---- docs/modular-resources/_index.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md index 538200079e..2db3eb8e20 100644 --- a/docs/components/generic/_index.md +++ b/docs/components/generic/_index.md @@ -12,12 +12,12 @@ no_list: true # SMEs: --- -The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >}} is for custom components that are incompatible with any of the other component APIs. +The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >}} enables you to add support for unique types of hardware that do not already have an [appropriate API](/program/apis/#component-apis) defined for them. -For example, if you have an LED display, it does not make sense to implement it as an arm, camera, or any other existing component subtype because an LED display does not have joints or capture images. +For example, when using an [arm component](/components/arm), it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. +But if you want to use an LED display, you need very different functionality that isn't currently exposed in any API. -There are no built-in generic component models (other than `fake`). -Use generic for a [modular resource](/modular-resources/) model that represents a unique type of hardware. +Instead, you can use the generic component API to add support for your unique type of hardware, like LED displays, to your smart machine. {{% alert title="Important" color="note" %}} diff --git a/docs/modular-resources/_index.md b/docs/modular-resources/_index.md index 039a5a8fa1..58b15815ea 100644 --- a/docs/modular-resources/_index.md +++ b/docs/modular-resources/_index.md @@ -71,7 +71,7 @@ To create a new modular resource: ### Unique cases -If your hardware won't work with any of the standard component APIs, you can use the [generic API](/components/generic/). +If you are using unique hardware that does not already have an [appropriate API](/program/apis/#component-apis) defined to support it, you can use the [generic API](/components/generic/) to add support for that unique hardware type to your smart machine. Some use cases may require you to define a new API, or to deploy custom components using a server on a remote part. For more information, see [Advanced Modular Resources](/modular-resources/advanced/). From 73d661c2bc2eca50d24ee3f0bf5c30de0ae26578 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 3 Nov 2023 16:13:23 +0100 Subject: [PATCH 3/5] Update docs/components/generic/_index.md --- docs/components/generic/_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md index d6d7335a9e..4fdaa659f9 100644 --- a/docs/components/generic/_index.md +++ b/docs/components/generic/_index.md @@ -16,7 +16,6 @@ The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >} For example, when using an [arm component](/components/arm), it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. But if you want to use an LED display, you need very different functionality that isn't currently exposed in any API. - Instead, you can use the generic component API to add support for your unique type of hardware, like LED displays, to your smart machine. There are no built-in generic component models (other than `fake`). From 7defafc3f306e2c102e28cdbe83ff46dd7108082 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 3 Nov 2023 19:39:58 +0100 Subject: [PATCH 4/5] Update _index.md --- docs/components/generic/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md index 4fdaa659f9..799f71e6fd 100644 --- a/docs/components/generic/_index.md +++ b/docs/components/generic/_index.md @@ -14,7 +14,7 @@ no_list: true The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >}} enables you to add support for unique types of hardware that do not already have an [appropriate API](/program/apis/#component-apis) defined for them. -For example, when using an [arm component](/components/arm), it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. +For example, when using an [arm component](/components/arm)/, it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. But if you want to use an LED display, you need very different functionality that isn't currently exposed in any API. Instead, you can use the generic component API to add support for your unique type of hardware, like LED displays, to your smart machine. From ef050a6e968d163b45b403814804b37109e29c95 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 3 Nov 2023 20:32:46 +0100 Subject: [PATCH 5/5] Update _index.md --- docs/components/generic/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/generic/_index.md b/docs/components/generic/_index.md index 799f71e6fd..355a88086b 100644 --- a/docs/components/generic/_index.md +++ b/docs/components/generic/_index.md @@ -14,7 +14,7 @@ no_list: true The _generic_ component {{< glossary_tooltip term_id="subtype" text="subtype" >}} enables you to add support for unique types of hardware that do not already have an [appropriate API](/program/apis/#component-apis) defined for them. -For example, when using an [arm component](/components/arm)/, it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. +For example, when using an [arm component](/components/arm/), it makes sense to use the [arm API](/components/arm/#api), which provides specific functionality an arm component needs, such as moving to position or stopping movement. But if you want to use an LED display, you need very different functionality that isn't currently exposed in any API. Instead, you can use the generic component API to add support for your unique type of hardware, like LED displays, to your smart machine.