Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-1060, DOCS-1091: Add GitHub Action upload #1782

Merged
4 changes: 2 additions & 2 deletions docs/components/movement-sensor/viam-visual-odometry.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ Therefore, you should not consider returned unit measurements trustworthy: inste
While `viam-visual-odometry` enables you to add movement sensing abilities to your robot without needing specialized hardware, a dedicated [movement sensor](/components/movement-sensor/) will generally provide more accurate readings.
If your robot requires precise awareness of its location and its movement, you should consider using a dedicated movement sensor in addition to the `viam-visual-odometry` module.

The `viam-visual-odometry` module is available [from the Viam Registry](https://app.viam.com/module/viam/monocular-visual-odometry).
See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam Registry on your robot.
The `viam-visual-odometry` module is available [from the Viam registry](https://app.viam.com/module/viam/monocular-visual-odometry).
See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot.

The source code for this module is available on the [`viam-visual-odometry` GitHub repository](https://github.com/viamrobotics/viam-visual-odometry).

Expand Down
2 changes: 1 addition & 1 deletion docs/extend/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ simple_list: true
no_list: true
type: docs
tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"]
description: "Extend Viam with modular resources from the Viam Registry."
description: "Extend Viam with modular resources from the Viam registry."
aliases:
- "/program/extend/"
---
Expand Down
20 changes: 10 additions & 10 deletions docs/extend/modular-resources/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,30 +22,30 @@ For example, you can:
- **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 lifecyle, you can implement your own custom logic by wrapping the generic API.

These custom implementations are called {{< glossary_tooltip term_id="module" text="modular resources" >}}, and are made available for use on a robot through [modules](/extend/modular-resources/key-concepts/#modules).
A module can provide one or more modular resources, and can be added to your robot from the Viam Registry.
A module can provide one or more modular resources, and can be added to your robot from the Viam registry.

## The Viam Registry

The [Viam Registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other.
You can add a module from the Viam Registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.
The [Viam registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other.
You can add a module from the Viam registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.

The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam Registry.
The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam registry.
Once the module has been uploaded to the Registry, you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/).

### Uploading to Viam Registry

After you finish programming your module, you can [upload your module to the Viam Registry](/extend/modular-resources/upload/) to make it available for deployment to robots.
After you finish programming your module, you can [upload your module to the Viam registry](/extend/modular-resources/upload/) to make it available for deployment to robots.
As part of the upload process, you decide whether your module is *public* (visible to all users) or *private* (visible only to other members of your [organization](/manage/fleet/organizations/)).

You can see details about each module in [the Viam Registry](https://app.viam.com/registry) on its module details page.
You can see details about each module in the [Viam registry](https://app.viam.com/registry) on its module details page.
See the [Odrive module](https://app.viam.com/module/viam/odrive) for an example.
Public modules also display the number of times a module has been deployed to a robot.

When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam Registry will track each version that you upload.
When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam registry will track each version that you upload.

### Deploying to a Robot

Once you [upload a module to the Viam Registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/).
Once you [upload a module to the Viam registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/).
Navigate to your robot's **Configuration** tab, click the **+ Create component** button, then start typing the name of the module you would like to deploy.
If you uploaded your module and set its visibility to private, the module will only appear for users within your [organization](/manage/fleet/organizations/).

Expand All @@ -59,9 +59,9 @@ To get started working with modular resources:

- [Create your own module](/extend/modular-resources/create/) implementing at least one modular resource.

- [Upload your module to the Viam Registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization.
- [Upload your module to the Viam registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization.

- Browse [the Viam Registry](https://app.viam.com/registry) to see modules uploaded by other users.
- Browse the [Viam registry](https://app.viam.com/registry) to see modules uploaded by other users.

- [Deploy a module](/extend/modular-resources/configure/) to your robot from the Registry.

Expand Down
36 changes: 18 additions & 18 deletions docs/extend/modular-resources/configure.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,78 +4,78 @@ linkTitle: "Configure"
weight: 30
type: "docs"
tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"]
description: "Add and configure a module from the Viam Registry on your robot."
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 [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).
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:
To add a module 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:

- 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.
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/registry) directly to search available modules.

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

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.
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.

{{<imgproc src="extend/modular-resources/configure/conf-component-from-module.png" resize="400x" declaredimensions=true alt="The components subtab of the config tab showing the camera component configuration pane for the realsense module">}}

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.

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.
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.

### Configure a module from the Viam Registry
### Configure a module 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:
Once you have added a module from the [Viam registry](https://app.viam.com/registry), you can view and configure the 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/) 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/) 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.

{{<imgproc src="extend/modular-resources/configure/conf-module-from-registry.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.
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.
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.
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.
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.
- **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.
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**.
Expand All @@ -84,7 +84,7 @@ If, for example, the module provides a motor component, and the motor is running

### Configure a 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 configured a module from the [Viam registry](https://app.viam.com/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).

The following properties are available for modular resources:

Expand Down
8 changes: 4 additions & 4 deletions docs/extend/modular-resources/create/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ You can extend Viam by creating a custom [module](/extend/modular-resources/key-

A common use case for modular resources is to create a new model that implements an existing Viam API.

Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/extend/modular-resources/upload/) to the Viam Registry, to share it with other Viam users or just to other users in your organization.
Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/extend/modular-resources/upload/) to the Viam registry, to share it with other Viam users or just to other users in your organization.

Alternatively, you can add your module locally to your robot without uploading to the Viam Registry.
Alternatively, you can add your module locally to your robot without uploading to the Viam registry.

## Create a custom module

Expand Down Expand Up @@ -533,6 +533,6 @@ Your executable will be run by `viam-server` as root, so dependencies need to be

## Next steps

Once you have created your custom resource, you can use the [Viam CLI](/manage/cli/) to [upload your custom resource](/extend/modular-resources/upload/) to the Viam Registry, to share it with other Viam users or just to other users in your organization.
Once you have created your custom resource, you can use the [Viam CLI](/manage/cli/) to [upload your custom resource](/extend/modular-resources/upload/) to the Viam registry, to share it with other Viam users or just to other users in your organization.

Alternatively, you can [add your module locally](/extend/modular-resources/configure/) to your robot without uploading to the Viam Registry.
Alternatively, you can [add your module locally](/extend/modular-resources/configure/) to your robot without uploading to the Viam registry.
Loading
Loading