diff --git a/docs/modular-resources/_index.md b/docs/modular-resources/_index.md index 8d7f430303..42c63bcd62 100644 --- a/docs/modular-resources/_index.md +++ b/docs/modular-resources/_index.md @@ -27,13 +27,13 @@ Viam provides built-in support for a variety of {{< glossary_tooltip term_id="re - Various types of hardware {{< glossary_tooltip term_id="component" text="components" >}}. - High-level functionality exposed as {{< glossary_tooltip term_id="service" text="services" >}}. -If the {{< glossary_tooltip term_id="component" text="component" >}} or {{< glossary_tooltip term_id="service" text="service" >}} you want to use for your project is not natively supported, you can [use _modular resources_ from the Viam Registry](#the-viam-registry) or [create your own modular resources](#create-your-own-modular-resources). +If the component or service you want to use for your project is not natively supported, you can use _modular resources_ from the [Viam Registry](#the-viam-registry) or [create your own modular resources](#create-your-own-modular-resources). You configure and manage modular resources the same way as built-in resources and use the same [standardized APIs](/program/apis/). ## The Viam Registry -The [Viam registry](https://app.viam.com/registry) is the central place where you can browse modular resources that add capabilities to your smart machine beyond what is built-in to `viam-server`. -You can see details about each module in the [Viam registry](https://app.viam.com/registry) on its module details page. +The [Viam registry](https://app.viam.com/registry) is the central place where you can browse modular resources that add capabilities to your smart machine beyond what is built into `viam-server`. +You can see details about each module in the Viam registry on its module details page. You can search the available modular resources from the Viam Registry here: @@ -51,11 +51,11 @@ You can search the available modular resources from the Viam Registry here: -To use a modular resource from the registry, add it from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **Create component** button. +To use a modular resource from the registry, add it from your robot's **Config** tab in [the Viam app](https://app.viam.com/), using the **Create component** button. -## Create Your Own Modular Resources +## Create your own modular resources -If none of the existing modular resources in the Viam registry support your use case, you can also create your own modular resources: +If none of the existing modular resources in the Viam registry support your use case, you can create your own modular resources: - **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. @@ -65,13 +65,13 @@ If none of the existing modular resources in the Viam registry support your use To create a new modular resource: -1. [Code a new resource model](/modular-resources/create/) by implementing all methods for the component's or services'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 APIs](/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. + 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. -Some use cases may require you to extend the standardized API definitions or deploy custom components using a server on a remote part. +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/). ## Related tutorials diff --git a/docs/modular-resources/advanced/custom-components-remotes.md b/docs/modular-resources/advanced/custom-components-remotes.md index b2749c39ba..c2ce8d316b 100644 --- a/docs/modular-resources/advanced/custom-components-remotes.md +++ b/docs/modular-resources/advanced/custom-components-remotes.md @@ -18,7 +18,7 @@ However, if you are unable to use [modular resources](/modular-resources/) becau Once you have coded your custom component and configured the remote servers, you can control and monitor your component with the Viam SDKs, like any other component. To show how to create a custom resource, the following example creates an arm as a custom component and registers the new arm model with a Viam SDK. -Then you can control it as part of your robot with the same [API methods](/components/arm/#api) available for [arm models built-in to the RDK](/components/arm/#supported-models). +Then you can control it as part of your robot with the same [API methods](/components/arm/#api) available for [arm models built into the RDK](/components/arm/#supported-models). ## Instructions diff --git a/docs/modular-resources/configure.md b/docs/modular-resources/configure.md index 530eddb70a..8f828d2908 100644 --- a/docs/modular-resources/configure.md +++ b/docs/modular-resources/configure.md @@ -12,19 +12,22 @@ tags: "components", "services", ] -description: "Add and configure a module from the Viam registry on your robot." +description: "Add a modular resource to your robot by configuring it." no_list: true aliases: - "/program/extend/modular-resources/configure/" --- -You can extend Viam by adding a module on your robot that provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} ([components](/components/) or [services](/services/)). +To use a [modular resource](/modular-resources/) on your robot, you need to: -You can [add a module from the Viam registry](#add-a-module-from-the-viam-registry), or you can [add a local module](#local-modules). +1. Add a {{< glossary_tooltip term_id="module" text="module" >}}, either one [from the registry](#add-a-modular-resource-from-the-viam-registry) or a [local module](#local-modules). + This makes the modular resource available to the robot. +1. Then add the modular resource itself. -See [Key Concepts of Modular Resource APIs](/modular-resources/key-concepts/) for more information. +When you add a modular resource from the registry, the underlying module that provides it is automatically added at the same time. +To add a modular resource from a local module, you must add the module first. -## Add a module from the Viam registry +## Add a modular resource from the Viam registry The [Viam registry](https://app.viam.com/registry) is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam's capabilities on your robot. @@ -49,7 +52,7 @@ To add a modular [component](/components/) from the Viam registry to your robot: {{}} -1. After selecting the modular component, click the **Add module** button, enter a name for your modular component, and click **Create** to add it to your robot. +1. After selecting the modular component, click the **Add module** button, enter a name for your modular component, and click **Create** to add it to your robot's component configuration. {{}} @@ -57,9 +60,9 @@ To add a modular [component](/components/) from the Viam registry to your robot: You can see which platforms the module supports at bottom of the module information screen before you add it. When you add a module from the Viam registry, the custom modular component it provides appears under the **Components** subtab like any other component. -You can also find [the module itself](#configure-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab. +You can also find [the underlying module](#edit-the-configuration-of-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab. -If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#configure-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page. +If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#edit-the-configuration-of-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page. To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the **Modules** subtab of the robot's **Config** tab. Deleting a module _does not_ delete any configured modular resources it provides. @@ -78,7 +81,7 @@ To add a modular [service](/services/) from the Viam registry to your robot: {{}} -1. After selecting the modular service, click the **Add module** button, enter a name for your modular service, and click **Create** to add it to your robot. +1. After selecting the modular service, click the **Add module** button, enter a name for your modular service, and click **Create** to add it to your robot's service configuration. {{}} @@ -86,58 +89,21 @@ To add a modular [service](/services/) from the Viam registry to your robot: You can see which platforms the module supports at bottom of the module information screen before you add it. When you add a module from the Viam registry, the custom modular service it provides appears under the **Services** subtab like any other service. -You can also find [the module itself](#configure-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab. +You can also find [the module itself](#edit-the-configuration-of-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab. -If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#configure-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page. +If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#edit-the-configuration-of-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page. To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the **Services** tab. Deleting a module _does not_ delete any configured modular resources it provides. -## Configure a module from the Viam registry +### Add additional modular resources from a registry module -Once you have added a modular resource to your robot, you can view and configure the module itself from the **Modules** subtab: +Once you have [added a module](#add-a-modular-resource-from-the-viam-registry) from the Viam registry, you can add any number of the modular resources it provides to your robot by adding new components or services configured with your modular resource's [model](/modular-resources/key-concepts/#models). -1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -1. Click on the **Modules** subtab. - All modules you have added to your robot appear under the **Deployed** section. - -This pane lists the models provided by the module, any [components](/components/) or [services](/services/) on your robot that are currently using the module, and allows you to configure [how the module updates](#configure-version-update-management-for-a-registry-module) when a new version is available from the Viam registry. - -{{}} - -### Configure version update management for a registry module - -When you add a module to your robot, you can also configure how that module updates itself when a newer version becomes available from the Viam registry. -By default, a newly-added module is set to pin to the specific patch release (**Patch (X.Y.Z)**) of the version you added, meaning that the module will _never automatically update itself_. - -If you wish to allow automatic module updates when a new version of the module becomes available in the Viam registry, you can set the **Version type** for your module in the **Modules** subtab. -Updating to a newer version of a module brings new functionality and bug fixes, but requires restarting the module to apply the update. -The following update options are available: - -- **Patch (X.Y.Z)**: Do not update to any other version. - This is the default. -- **Minor (X.Y.\*)**: Only update to newer patch releases of the same minor release branch. - The module will automatically restart and update itself whenever new updates within the same minor release are available in the Viam registry. - For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.2.5` but not `1.3.0` or `2.0.0`. -- **Major (X.\*)**: Only update to newer minor releases of the same major release branch. - The module will automatically restart and update itself whenever new updates within the same major release are available in the Viam registry. - For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.3.0` but not `2.0.0` or `3.0.0`. -- **Latest**: Always update to the latest version of this module available from the Viam registry as soon as a new version becomes available. +Follow the same steps as when you added the first modular resource, clicking **Create component** or **Create service** as applicable. +You will be prompted to click **Add module** again while configuring the resource, though no duplicate module will be added to the `modules` section of the configuration. -When using the **Patch (X.Y.Z)** version type, you may select any patch version of the module from the **Version** drop down menu, including past versions if desired. - -The current deployed version of your module and the latest version of that module available from the Viam registry are shown on this pane for your reference. - -{{% alert title="Caution" color="caution" %}} -For any version type other than **Patch (X.Y.Z)**, the module will upgrade as soon as an update that matches that specified version type is available, which will **restart the module**. -If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades. -{{% /alert %}} - -### Create a new modular resource from a registry module - -Once you have [added a module](#add-a-module-from-the-viam-registry) from the Viam registry, you can add any number of the modular resources it provides to your robot by adding new components or services configured with your modular resources' [model](/modular-resources/key-concepts/#models). - -The following properties are available for modular resources: +If you prefer to use raw JSON, the following properties are available for modular resources: | Name | Type | Inclusion | Description | @@ -211,6 +177,46 @@ The custom model is configured as a component with the name "my-realsense". {{% /tab %}} {{% /tabs %}} +## Edit the configuration of a module from the Viam registry + +Once you have added a modular resource to your robot, you can view and edit the configuration of the underlying module from the **Modules** subtab: + +1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). +1. Click on the **Modules** subtab. + All modules you have added to your robot appear under the **Deployed** section. + +This pane lists the models provided by the module, any [components](/components/) or [services](/services/) on your robot that are currently using the module, and allows you to configure [how the module updates](#configure-version-update-management-for-a-registry-module) when a new version is available from the Viam registry. + +{{}} + +### Configure version update management for a registry module + +When you add a module to your robot, you can also configure how that module updates itself when a newer version becomes available from the Viam registry. +By default, a newly-added module is set to pin to the specific patch release (**Patch (X.Y.Z)**) of the version you added, meaning that the module will _never automatically update itself_. + +If you wish to allow automatic module updates when a new version of the module becomes available in the Viam registry, you can set the **Version type** for your module in the **Modules** subtab. +Updating to a newer version of a module brings new functionality and bug fixes, but requires restarting the module to apply the update. +The following update options are available: + +- **Patch (X.Y.Z)**: Do not update to any other version. + This is the default. +- **Minor (X.Y.\*)**: Only update to newer patch releases of the same minor release branch. + The module will automatically restart and update itself whenever new updates within the same minor release are available in the Viam registry. + For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.2.5` but not `1.3.0` or `2.0.0`. +- **Major (X.\*)**: Only update to newer minor releases of the same major release branch. + The module will automatically restart and update itself whenever new updates within the same major release are available in the Viam registry. + For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.3.0` but not `2.0.0` or `3.0.0`. +- **Latest**: Always update to the latest version of this module available from the Viam registry as soon as a new version becomes available. + +When using the **Patch (X.Y.Z)** version type, you may select any patch version of the module from the **Version** drop down menu, including past versions if desired. + +The current deployed version of your module and the latest version of that module available from the Viam registry are shown on this pane for your reference. + +{{% alert title="Caution" color="caution" %}} +For any version type other than **Patch (X.Y.Z)**, the module will upgrade as soon as an update that matches that specified version type is available, which will **restart the module**. +If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades. +{{% /alert %}} + ## Local modules If you wish to add a module to your robot without uploading it to the Viam registry, you can add your module as a _local module_. @@ -275,9 +281,9 @@ You can also add the module directly, without first adding its modular component This example shows the configuration for adding a [CSI camera](/modular-resources/examples/csi/) as a local module. -## Configure a local module +### Edit the configuration of a local module -Once you have added a modular resource to your robot, you can view and configure the module itself from the **Modules** subtab: +Once you have added a modular resource to your robot, you can view and edit the underlying module from the **Modules** subtab: 1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). 1. Click on the **Modules** subtab. @@ -317,9 +323,9 @@ Add these properties to your module's configuration: {{% /tab %}} {{% /tabs %}} -### Configure a modular resource +### Add a local modular resource -Once you have added a local module to your robot, you can add any number of the {{< glossary_tooltip term_id="resource" text="resources" >}} provided by that module to your robot by adding new components or services that use your modular resources' [model](/modular-resources/key-concepts/#models). +Once you have added a local module to your robot, you can add any number of the {{< glossary_tooltip term_id="resource" text="resources" >}} provided by that module to your robot by adding new components or services that use your modular resource's [model](/modular-resources/key-concepts/#models). The following properties are available for modular resources: diff --git a/docs/modular-resources/create/_index.md b/docs/modular-resources/create/_index.md index 0ce3f0f0d6..d226f685ad 100644 --- a/docs/modular-resources/create/_index.md +++ b/docs/modular-resources/create/_index.md @@ -18,7 +18,7 @@ aliases: - "/extend/modular-resources/create/" --- -You can extend Viam by creating a custom {{< glossary_tooltip term_id="module" text="module" >}} that provides one or more modular {{< glossary_tooltip term_id="resource" text="resource" >}} {{< glossary_tooltip term_id="model" text="models" >}} and can be added to any smart machine running on Viam. +You can extend Viam by creating a custom {{< glossary_tooltip term_id="module" text="module" >}} that provides one or more modular {{< glossary_tooltip term_id="resource" text="resource" >}} {{< glossary_tooltip term_id="model" text="models" >}}. A common use case for modular resources is to create a new [model](/modular-resources/key-concepts/#models) that implements an existing Viam [API](/program/apis/). @@ -70,7 +70,7 @@ For more information see [Naming your model](/modular-resources/key-concepts/#na The Go code for the custom model (mybase.go) and module entry point file (main.go) is adapted from the full demo modules available on the [Viam GitHub](https://github.com/viamrobotics/rdk/blob/main/examples/customresources). -{{% alert title="Naming module models" color="tip" %}} +{{% alert title="Tip" color="tip" %}} Name your model with all lowercase letters for optimal performance with Viam's SDKs. For example, `mybase` or `my-cool-sensor`. diff --git a/docs/modular-resources/key-concepts.md b/docs/modular-resources/key-concepts.md index 8b0442fe45..e213f457ad 100644 --- a/docs/modular-resources/key-concepts.md +++ b/docs/modular-resources/key-concepts.md @@ -26,7 +26,7 @@ Viam's [Robot Development Kit (RDK)](/internals/rdk/) provides built-in support However, if you want to work with a new hardware component that is not already supported by Viam, or want to introduce a new software service or service model to support additional functionality on your smart machine, you can extend Viam by adding a _modular resource_ to your smart machine. Modular resources are defined in _modules_, which are easy to create and add to your robot. -A module can provide one or more modular resource models. +A module can provide one or more modular resource models, and can be added to any smart machine running on Viam. ## Modules @@ -36,24 +36,21 @@ A module provides definitions for one or more pairs of [APIs](#valid-apis-to-imp When the module initializes, it registers those pairs on your robot, making the functionality defined by that pair available for use. -You can [upload your own modules to the Viam registry](/modular-resources/upload/) or can [add existing modules from the Registry](/modular-resources/configure/). - -See [Creating a custom module](/modular-resources/create/) for more information. - ## Resources A resource is a [component](/components/) or [service](/services/). Each component or service is typed by a proto API, such as the [component proto definitions](https://github.com/viamrobotics/api/tree/main/proto/viam/component). -Any resource on your robot needs to implement either one of these [existing Viam APIs](#valid-apis-to-implement-in-your-model), or a custom interface. +Any resource on your robot needs to implement either one of the [existing Viam APIs](#valid-apis-to-implement-in-your-model), or a [custom interface](/modular-resources/advanced/#new-api-subtypes). -A _modular resource_ is a resource that is provided by a [module](#modules), and not built-in to the RDK. -A modular resource runs in the module process. This differs from built-in resources, which run as part of `viam-server`. +A _modular resource_ is a resource that is provided by a [module](#modules), and 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`. ## Models A _model_ describes a specific implementation of a [resource](#resources) that implements (speaks) its [API](/program/apis/). -Models allow you to control different instances of a resource with a consistent interface, even if the underlying implementation differs. +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 DC motors communicate using [GPIO](/components/board/), while other DC motors use serial protocols like the [SPI bus](/components/board/#spis). Regardless, you can power any motor model that implements the `rdk:component:motor` API with the `SetPower()` method. @@ -67,6 +64,7 @@ Models are either: - Built into the RDK, and included when you [install `viam-server`](/installation/) or when you use one of the [Viam SDKs](/program/apis/). - Provided in [custom modules](#modules) available for download from the [Viam registry](https://app.viam.com/registry), and are written by either Viam or community users. + Custom modules can also be [local](/modular-resources/configure/#local-modules). ### Built-in models @@ -81,21 +79,22 @@ For example: ### Custom models The [Viam registry](https://app.viam.com/registry) makes available both Viam-provided and community-written modules for download and use on your robot. +You can also run modules [locally](/modular-resources/configure/#local-modules). These models run outside `viam-server` as a separate process. #### Valid APIs to implement in your model -When implementing a custom [model](#models) of an existing [component](/components/), valid [APIs](/program/apis/) are always: +When implementing a custom [model](#models) of an existing [component](/components/), valid [APIs](/program/apis/) always have the following parameters: - `namespace`: `rdk` - `type`: `component` -- `subtype`: any one of [these component proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/component). +- `subtype`: any one of [these component proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/component), for example `motor` -When implementing a custom [model](#models) of an existing [service](/services/), valid [APIs](/program/apis/) are always +When implementing a custom [model](#models) of an existing [service](/services/), valid [APIs](/program/apis/) always have the following parameters: - `namespace`: `rdk` - `type`: `service` -- `subtype`: any one of [these service proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/service). +- `subtype`: any one of [these service proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/service), for example `navigation` #### Naming your model: namespace:repo-name:name @@ -116,7 +115,7 @@ For example: - The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout) It implements the custom API `viam-labs:service:audioout`. -A model with the `viam` namespace is always Viam-provided. +The `viam` namespace is reserved for models provided by Viam. ## Management diff --git a/layouts/shortcodes/modular-resources.html b/layouts/shortcodes/modular-resources.html index f962d9e29e..9733be548a 100644 --- a/layouts/shortcodes/modular-resources.html +++ b/layouts/shortcodes/modular-resources.html @@ -1,4 +1,4 @@ -

Search for additional {{.Get "type" }} models that you can add from the Viam Registry: +

Search for additional {{.Get "type" }} models that you can add from the Viam Registry:

For configuration information, click on the model name: