Skip to content

Commit

Permalink
Align add vs configure
Browse files Browse the repository at this point in the history
  • Loading branch information
JessamyT committed Oct 27, 2023
1 parent b5e0d51 commit 6c01ccd
Showing 1 changed file with 58 additions and 53 deletions.
111 changes: 58 additions & 53 deletions docs/modular-resources/configure.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -49,17 +51,17 @@ To add a modular [component](/components/) from the Viam registry to your robot:

{{<imgproc src="modular-resources/configure/add-component-by-name.png" resize="400x" declaredimensions=true alt="The add a component modal showing results for the intel realsense module when searching by the name 'realsense'">}}

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.

{{<imgproc src="modular-resources/configure/add-component-screen.png" resize="400x" declaredimensions=true alt="The add a component modal showing the intel realsense module pane, with the 'Add module' button shown">}}

Be sure the modular component you select supports the [platform](/manage/cli/#using-the---platform-argument) you intend to use it with, such as `linux arm64`.
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.
Expand All @@ -78,66 +80,29 @@ To add a modular [service](/services/) from the Viam registry to your robot:

{{<imgproc src="modular-resources/configure/add-service-by-name.png" resize="400x" declaredimensions=true alt="The add a component modal showing results for the mlmodelservice triton module when searching by the name 'triton'">}}

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.

{{<imgproc src="modular-resources/configure/add-service-screen.png" resize="400x" declaredimensions=true alt="The add a component modal showing the mlmodelservice triton module pane, with the 'Add module' button shown">}}

Be sure the modular service you select supports the [platform](/manage/cli/#using-the---platform-argument) you intend to use it with, such as `linux arm64`.
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.

{{<imgproc src="modular-resources/configure/deployed-module-with-component.png" resize="1000x" declaredimensions=true alt="The module subtab of the config tab showing the realsense custom module configuration pane includes the update management section showing version update management options version type, set to Patch (X.Y.Z) and version set to 0.0.3">}}

### 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:

<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
Expand Down Expand Up @@ -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.

{{<imgproc src="modular-resources/configure/deployed-module-with-component.png" resize="1000x" declaredimensions=true alt="The module subtab of the config tab showing the realsense custom module configuration pane includes the update management section showing version update management options version type, set to Patch (X.Y.Z) and version set to 0.0.3">}}

### 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_.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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).

Expand Down

0 comments on commit 6c01ccd

Please sign in to comment.