diff --git a/assets/extend/modular-resources/configure/add-component-by-category.png b/assets/extend/modular-resources/configure/add-component-by-category.png new file mode 100644 index 0000000000..a9282047da Binary files /dev/null and b/assets/extend/modular-resources/configure/add-component-by-category.png differ diff --git a/assets/extend/modular-resources/configure/add-component-by-name.png b/assets/extend/modular-resources/configure/add-component-by-name.png new file mode 100644 index 0000000000..47b2360ab0 Binary files /dev/null and b/assets/extend/modular-resources/configure/add-component-by-name.png differ diff --git a/assets/extend/modular-resources/configure/add-component-screen.png b/assets/extend/modular-resources/configure/add-component-screen.png new file mode 100644 index 0000000000..2ce641cf4a Binary files /dev/null and b/assets/extend/modular-resources/configure/add-component-screen.png differ diff --git a/assets/extend/modular-resources/configure/add-module-from-registry.png b/assets/extend/modular-resources/configure/add-module-from-registry.png deleted file mode 100644 index 3792481cd8..0000000000 Binary files a/assets/extend/modular-resources/configure/add-module-from-registry.png and /dev/null differ diff --git a/assets/extend/modular-resources/configure/add-service-by-category.png b/assets/extend/modular-resources/configure/add-service-by-category.png new file mode 100644 index 0000000000..f009bac6f9 Binary files /dev/null and b/assets/extend/modular-resources/configure/add-service-by-category.png differ diff --git a/assets/extend/modular-resources/configure/add-service-by-name.png b/assets/extend/modular-resources/configure/add-service-by-name.png new file mode 100644 index 0000000000..e28bae9ca4 Binary files /dev/null and b/assets/extend/modular-resources/configure/add-service-by-name.png differ diff --git a/assets/extend/modular-resources/configure/add-service-screen.png b/assets/extend/modular-resources/configure/add-service-screen.png new file mode 100644 index 0000000000..4689402b9e Binary files /dev/null and b/assets/extend/modular-resources/configure/add-service-screen.png differ diff --git a/assets/extend/modular-resources/configure/conf-component-from-module.png b/assets/extend/modular-resources/configure/conf-component-from-module.png deleted file mode 100644 index 44990a5a82..0000000000 Binary files a/assets/extend/modular-resources/configure/conf-component-from-module.png and /dev/null differ diff --git a/assets/extend/modular-resources/configure/conf-module-from-registry.png b/assets/extend/modular-resources/configure/conf-module-from-registry.png deleted file mode 100644 index ebd4753672..0000000000 Binary files a/assets/extend/modular-resources/configure/conf-module-from-registry.png and /dev/null differ diff --git a/assets/extend/modular-resources/configure/deployed-module-with-component.png b/assets/extend/modular-resources/configure/deployed-module-with-component.png new file mode 100644 index 0000000000..e0f108d8bd Binary files /dev/null and b/assets/extend/modular-resources/configure/deployed-module-with-component.png differ diff --git a/assets/extend/modular-resources/configure/deployed-module-with-service.png b/assets/extend/modular-resources/configure/deployed-module-with-service.png new file mode 100644 index 0000000000..3b5abd8b8c Binary files /dev/null and b/assets/extend/modular-resources/configure/deployed-module-with-service.png differ diff --git a/docs/extend/custom-components-remotes.md b/docs/extend/custom-components-remotes.md index 70bcbd8332..8aea4324f5 100644 --- a/docs/extend/custom-components-remotes.md +++ b/docs/extend/custom-components-remotes.md @@ -12,10 +12,10 @@ description: "Implement custom components and register them on a server configur --- {{% alert title="Caution" color="caution" %}} -{{< glossary_tooltip term_id="module" text="Modular resources" >}} are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. +[Modular resources](/extend/modular-resources/key-concepts/) are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. {{% /alert %}} -If a type or model of [component](/components/) you are working with is not built-in to the [Viam RDK](/internals/rdk/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. +If a type or model of [component](/components/) you are working with is not [built-in to the Viam RDK](/internals/rdk/), or [available from the Viam Registry as a module](/extend/modular-resources/key-concepts/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. 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. diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 4ead43ea07..7a6bcec36e 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -8,53 +8,87 @@ description: "Add and configure a module from the Viam Registry on your robot." no_list: true --- -You can extend Viam by adding a module on your robot to make one or more modular resources available for configuration. +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/)). You can [add a module from the Viam Registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). -A *module* makes one or more *modular resources* available for configuration. See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concepts/) for more information. ## Add a module from the Viam Registry -The Viam 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. +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. -To add a module from the Viam Registry to your robot: +A module provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} (either a [component](/components/) or [service](/services/)). + +Follow the instructions below depending on the type of modular resource you would like to add to your robot: + +- [Add a modular component](#add-a-modular-component-from-the-viam-registry) +- [Add a modular service](#add-a-modular-service-from-the-viam-registry) + +### Add a modular component from the Viam registry + +To add a modular [component](/components/) from the Viam Registry to your robot: 1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). 1. Click on the **Components** subtab and click the **Create component** button. -1. Enter the name of the module you would like to add to your robot. - To find the name of a module you're interested in, you can: +1. Browse the list of available component types, and select the specific modular component you'd like to add. + + {{}} + + You can also start typing to search for a module by name or to narrow down your search results. - - Start typing to search for modules by name. - Modules available from the Viam Registry will be listed under the `From Registry` section of the search results. - - [Browse the Viam Registry](https://app.viam.com/modules) directly to search available modules. + {{}} - {{}} +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 entering the name of the module that you would like to add to your robot, select the matching module in the search results and click the **Add module** button. + {{}} 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. -{{}} - -If the module requires you to configure specific **Atrributes**, click the **URL** link in the module's configuration pane to view the specific documentation 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](#configure-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 **Components** tab. +Deleting a module *does not* delete any configured modular resources it provides. -### Configure a module from the Viam Registry +### Add a modular service from the Viam registry -Once you have added a module from the Viam Registry, you can view and configure the module from the **Modules** subtab: +To add a modular [service](/services/) from the Viam Registry to your robot: + +1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). +1. Click on the **Services** subtab and click the **Create service** button. +1. Browse the list of available service types and select the specific modular service you'd like to add. + + {{}} + + You can also start typing to search for a module by name or to narrow down your search results. + + {{}} + +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. + + {{}} + +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. + +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. + +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 + +Once you have added a modular resource to your robot, you can view and configure the module itself 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/) on your robot that are currently using those models, 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. +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 +### 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*. @@ -82,9 +116,9 @@ For any version type other than **Patch (X.Y.Z)**, the module will upgrade as so If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades. {{% /alert %}} -### Configure a modular resource from a Registry module +### Create a new modular resource from a Registry module -Once you have configured a module from the Viam Registry, you can add any number of the resources that the module makes available to your robot by adding new components or services configured with your modular resources' [model](/extend/modular-resources/key-concepts/#models). +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](/extend/modular-resources/key-concepts/#models). The following properties are available for modular resources: @@ -98,6 +132,7 @@ The following properties are available for modular resources: All standard properties for configuration, such as `attributes` and `depends_on`, are also supported for modular resources. The `attributes` available vary depending on your implementation. +If the module requires you to configure specific **Attributes**, click the **URL** link in the module's configuration pane to view the specific attribute requirements on the module's GitHub page. {{< tabs >}} {{% tab name="JSON Template" %}} @@ -106,47 +141,51 @@ The `attributes` available vary depending on your implementation. { "components": [ { - "namespace": "", - "type": "", - "model": "::", "name": "", - "depends_on": [], + "model": "::", + "type": "", + "namespace": "", + "attributes": {}, + "depends_on": [] } ], - "modules": [ ... ] // < INSERT YOUR MODULE CONFIGURATION > + "modules": [ + { + "type": "registry", + "name": "", + "module_id": ":", + "version": "" + } + ] } ``` {{% /tab %}} {{% tab name="JSON Example" %}} -The following is an example configuration for a base modular resource implementation. -The configuration adds `acme:demo:mybase` as a modular resource from the module `my_base`. -The custom model is configured as a component with the name "my-custom-base-1". -You can send commands to the base according to the Viam [base API](/components/base/#api): +The following is an example configuration for for the [Intel Realsense module](https://app.viam.com/module/viam/realsense). +The configuration adds `viam:camera:realsense` as a modular resource from the module `viam:realsense`. +The custom model is configured as a component with the name "my-realsense". ```json {class="line-numbers linkable-line-numbers"} { "components": [ - { - "type": "board", - "name": "main-board", - "model": "pi" - }, - { - "type": "base", - "name": "my-custom-base-1", - "model": "acme:demo:mybase", - "namespace": "rdk", - "attributes": {}, - "depends_on": [ "main-board" ] - } - ], - "modules": [ - { - "name": "my-custom-base", - "executable_path": "/home/my_username/my_base/run.sh" - } + { + "name": "my-realsense", + "model": "viam:camera:realsense", + "type": "camera", + "namespace": "rdk", + "attributes": {}, + "depends_on": [] + } + ], + "modules": [ + { + "type": "registry", + "name": "viam_realsense", + "module_id": "viam:realsense", + "version": "0.0.3" + } ] } ``` @@ -240,7 +279,8 @@ The `attributes` available vary depending on your implementation. "type": "", "model": "::", "name": "", - "depends_on": [], + "attributes": {}, + "depends_on": [] } ], "modules": [ ... ] // < INSERT YOUR MODULE CONFIGURATION >