From 6c01ccd39d1d4cfcccb969818bab40aac40cac69 Mon Sep 17 00:00:00 2001 From: JessamyT Date: Fri, 27 Oct 2023 16:48:00 -0700 Subject: [PATCH] Align add vs configure --- docs/modular-resources/configure.md | 111 +++++++++++++++------------- 1 file changed, 58 insertions(+), 53 deletions(-) diff --git a/docs/modular-resources/configure.md b/docs/modular-resources/configure.md index ed198b94b1..848ade061d 100644 --- a/docs/modular-resources/configure.md +++ b/docs/modular-resources/configure.md @@ -20,11 +20,13 @@ aliases: To use a [modular resource](/modular-resources/) on your robot, you need to: -1. Configure a {{< glossary_tooltip term_id="module" text="module" >}}, either one [from the registry](#add-a-module-from-the-viam-registry) or 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 configure the modular resource itself. +1. Then add the modular resource itself. -## Add a module from the Viam registry +These two steps automatically happen at the same time when you add a modular resource from the 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 +51,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 config. {{}} @@ -57,9 +59,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 +80,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 config. {{}} @@ -86,58 +88,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 - -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/) 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 %}} +### Add additional modular resources from a registry module -### Configure a modular resource from a registry module +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). -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). +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 config. -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 +176,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,7 +280,7 @@ 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 local module configuration Once you have added a modular resource to your robot, you can view and configure the module itself from the **Modules** subtab: @@ -317,7 +322,7 @@ Add these properties to your module's configuration: {{% /tab %}} {{% /tabs %}} -### Configure a local 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 resource's [model](/modular-resources/key-concepts/#models).