From 494d0cddc3c8712871743ec045ea3b3135fae7f8 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Fri, 8 Sep 2023 16:37:18 -0400 Subject: [PATCH 01/13] DOCS-1060, DOCS-1091: Add GitHub Action upload --- .../extend/modular-resources/upload/_index.md | 73 ++++++++++++++++++- 1 file changed, 70 insertions(+), 3 deletions(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index e885205da0..00abece994 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -14,13 +14,13 @@ This feature is in beta, and may not be suitable for production use. Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam Registry. -With the CLI, you can register your module with the Viam Registry to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). +With the CLI, you can register your module with [the Viam Registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). For more information, see the [`viam module` command](/manage/cli/#module). ## Upload a custom module -To upload your custom module to the Viam Registry, either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: +To upload your custom module to [the Viam Registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: 1. First, [install the Viam CLI](/manage/cli/#install) and [authenticate](/manage/cli/#authenticate) to Viam, from the same machine that you intend to upload your module from. @@ -179,7 +179,17 @@ For more information, see the [`viam module` command](/manage/cli/#module) ## Update an existing module -You can also use the [Viam CLI](/manage/cli/) to update an existing custom module in the Viam Registry. +You can update an existing module in [the Viam Registry](https://app.viam.com/registry) in one of two ways: + +- [Upload a newer version of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/). +- [Upload a newer version of your module automatically](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. + +Updating your module manually is appropriate for smaller projects, especially those with only one contributor. +Updating your module automatically using CI is better suited for larger, ongoing projects, especially those with multiple contributors. + +### Update an existing module using the Viam CLI + +To update an existing module in [the Viam Registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/): 1. Edit your custom module with the changes you'd like to make. @@ -231,3 +241,60 @@ You can also use the [Viam CLI](/manage/cli/) to update an existing custom modul When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam Registry. For more information, see the [`viam module` command](/manage/cli/#module) + +### Update an existing module using a Github action + +To update an existing module in [the Viam Registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). + +1. Edit your custom module with the changes you'd like to make. + +1. Navigate to the **Actions** tab of the GitHub repository you are using for your module code. + If you have already created GitHub actions for this repository, click the **New workflow** button to create a new one. + If you have not yet created any GitHub actions, click the **Set up a workflow yourself** link. + See the [GitHub actions documentation](https://docs.github.com/en/actions/creating-actions) for more information. + +1. Paste the following action template YAML into the edit window. + + ```yaml {class="line-numbers linkable-line-numbers"} + on: + push: + release: + types: [released] + + jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: build + run: echo "your build command goes here" && false # <-- replace this with the command that builds your module's tar.gz + - uses: viamrobotics/upload-module@main + # if: github.event_name == 'release' # <-- once the action is working, uncomment this so you only upload on release + with: + module-path: module.tar.gz + org-id: your-org-id-uuid # <-- replace with your org ID. not required for public modules + platform: linux/amd64 # <-- replace with your target architecture, or your module will not deploy + version: ${{ github.event_name == 'release' && github.ref_name || format('0.0.0-{0}.{1}', github.ref_name, github.run_number) }} # <-- see 'Versioning' section below for explanation + key-id: ${{ secrets.viam_key_id }} + key-value: ${{ secrets.viam_key_value }} + ``` + +1. Edit the copied code to include the configuration specific to your module. + Each item marked with a `<--` comment requires that you edit the configuration values accordingly. + + Set `run` to the command you use to build and package your module. + When ready to test the action, uncomment `if: github.event_name == 'release'` to enable the action to trigger a run when you [issue a release](https://docs.github.com/en/repositories/releasing-projects-on-github). + + For guidance on configuring the other parameters, see the documentation for each: + - [`org-id`](#using-the---org-id-and---public-namespace-arguments) - Not required if your module is public. + - [`platform`](/manage/cli/#using-the---platform-argument) - You can only upload one platform at a time. + - [`version`](/manage/cli/#using-the---version-argument) + - [`key-id` and `key-value`](/manage/cli/#create-an-organization-api-key) - You will set these values in the next step. + +1. Next, follow the instructions to [Create an organization API key](/manage/cli/#create-an-organization-api-key), which the action will use to authenticate its run. + Provide the `key-id` and `key-value` generated in the YAML configuration above. + +1. Push a commit to your module or [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github). + Your module should upload to [the Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. + +For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module). From 32d4cfed72475f49b80111416c520afde984db41 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Fri, 8 Sep 2023 16:42:17 -0400 Subject: [PATCH 02/13] more link, title updates --- docs/extend/modular-resources/_index.md | 4 ++-- docs/extend/modular-resources/configure.md | 8 ++++---- docs/extend/modular-resources/key-concepts.md | 6 +++--- docs/extend/modular-resources/upload/_index.md | 12 ++++++------ docs/viam/_index.md | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 97e28d9249..93cb1c0b3c 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -37,7 +37,7 @@ Once the module has been uploaded to the Registry, you can [deploy the module](/ 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. @@ -61,7 +61,7 @@ To get started working with modular resources: - [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. diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 4ead43ea07..1d76af6ed8 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -16,7 +16,7 @@ See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concep ## 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: @@ -27,7 +27,7 @@ To add a module from the Viam Registry to your robot: - 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. + - [Browse the Viam Registry](https://app.viam.com/registry) directly to search available modules. {{}} @@ -44,7 +44,7 @@ To delete a module added from the Viam Registry, click the trash can icon in the ### 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) 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. @@ -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: diff --git a/docs/extend/modular-resources/key-concepts.md b/docs/extend/modular-resources/key-concepts.md index 375b4c162f..efe61f4128 100644 --- a/docs/extend/modular-resources/key-concepts.md +++ b/docs/extend/modular-resources/key-concepts.md @@ -47,7 +47,7 @@ See [Naming your model](/extend/modular-resources/key-concepts/#naming-your-mode 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 available for download from [the Viam Registry](https://app.viam.com/module), and are written by either Viam or community users. +- Provided in custom modules available for download from the [Viam Registry](https://app.viam.com/module), and are written by either Viam or community users. ### Built-in models @@ -90,7 +90,7 @@ If you are [creating a custom module](/extend/modular-resources/create/) and [up In addition, you should chose a name for the `family` of your model based on the whether your module implements a single model, or multiple models: - If your module provides a single model, the `family` should match the `subtype` of whichever API your model implements. - For example, the Intel Realsense module `realsense`, available from [the Viam Registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows: + For example, the Intel Realsense module `realsense`, available from the [Viam Registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows: ```json {class="line-numbers linkable-line-numbers"} { @@ -100,7 +100,7 @@ In addition, you should chose a name for the `family` of your model based on the ``` - If your module provides multiple models, the `family` should describe the common functionality provided across all the models of that module. - For example, the ODrive module `odrive`, available from [the Viam Registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows: + For example, the ODrive module `odrive`, available from the [Viam Registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows: ```json {class="line-numbers linkable-line-numbers"} { diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index 00abece994..2298c084a5 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -14,13 +14,13 @@ This feature is in beta, and may not be suitable for production use. Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam Registry. -With the CLI, you can register your module with [the Viam Registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). +With the CLI, you can register your module with the [Viam Registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). For more information, see the [`viam module` command](/manage/cli/#module). ## Upload a custom module -To upload your custom module to [the Viam Registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: +To upload your custom module to the [Viam Registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: 1. First, [install the Viam CLI](/manage/cli/#install) and [authenticate](/manage/cli/#authenticate) to Viam, from the same machine that you intend to upload your module from. @@ -179,7 +179,7 @@ For more information, see the [`viam module` command](/manage/cli/#module) ## Update an existing module -You can update an existing module in [the Viam Registry](https://app.viam.com/registry) in one of two ways: +You can update an existing module in the [Viam Registry](https://app.viam.com/registry) in one of two ways: - [Upload a newer version of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/). - [Upload a newer version of your module automatically](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. @@ -189,7 +189,7 @@ Updating your module automatically using CI is better suited for larger, ongoing ### Update an existing module using the Viam CLI -To update an existing module in [the Viam Registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/): +To update an existing module in the [Viam Registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/): 1. Edit your custom module with the changes you'd like to make. @@ -244,7 +244,7 @@ For more information, see the [`viam module` command](/manage/cli/#module) ### Update an existing module using a Github action -To update an existing module in [the Viam Registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). +To update an existing module in the [Viam Registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). 1. Edit your custom module with the changes you'd like to make. @@ -295,6 +295,6 @@ To update an existing module in [the Viam Registry](https://app.viam.com/registr Provide the `key-id` and `key-value` generated in the YAML configuration above. 1. Push a commit to your module or [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github). - Your module should upload to [the Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. + Your module should upload to the [Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module). diff --git a/docs/viam/_index.md b/docs/viam/_index.md index 230059ffd1..aae6bcfb8d 100644 --- a/docs/viam/_index.md +++ b/docs/viam/_index.md @@ -29,7 +29,7 @@ You will not need to write a single line of code to integrate them, and swapping You can make use of computer vision, motion planning, SLAM, data management, machine learning, and more by configuring Viam's built-in {{< glossary_tooltip term_id="service" text="services">}}. - **Architecture**: You can build simple robots or multi-part robots that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API. -- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from [the Viam Registry](/extend/modular-resources/). +- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from the [Viam Registry](/extend/modular-resources/). Join the [**Viam community**](https://discord.gg/viam) to collaborate during planning and beyond. From be605d738df1cacd1b408eba4d3145a9adb0b7c9 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Fri, 8 Sep 2023 16:44:45 -0400 Subject: [PATCH 03/13] last fixes --- docs/extend/modular-resources/configure.md | 2 +- docs/extend/modular-resources/key-concepts.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 1d76af6ed8..c4ffda010f 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -44,7 +44,7 @@ To delete a module added from the Viam Registry, click the trash can icon in the ### Configure a module from the Viam Registry -Once you have added a module from the [Viam Registry](https://app.viam.com/registry) +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. diff --git a/docs/extend/modular-resources/key-concepts.md b/docs/extend/modular-resources/key-concepts.md index efe61f4128..febf0d06cb 100644 --- a/docs/extend/modular-resources/key-concepts.md +++ b/docs/extend/modular-resources/key-concepts.md @@ -47,7 +47,7 @@ See [Naming your model](/extend/modular-resources/key-concepts/#naming-your-mode 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 available for download from the [Viam Registry](https://app.viam.com/module), and are written by either Viam or community users. +- Provided in custom modules available for download from the [Viam Registry](https://app.viam.com/registry), and are written by either Viam or community users. ### Built-in models From 6837fc0819253334b4f0605e13a312b8ec46e639 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Fri, 8 Sep 2023 16:47:58 -0400 Subject: [PATCH 04/13] remove beta alert? --- docs/extend/modular-resources/upload/_index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index 2298c084a5..39abcc337c 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -8,10 +8,6 @@ description: "Use the Viam CLI to upload a custom module to the Viam Registry." no_list: true --- -{{% alert title="Beta Notice" color="note" %}} -This feature is in beta, and may not be suitable for production use. -{{% /alert %}} - Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam Registry. With the CLI, you can register your module with the [Viam Registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). From 8d8bfad0b5a0dfa55ba436f6450215f6bc35315e Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Fri, 8 Sep 2023 16:54:52 -0400 Subject: [PATCH 05/13] fix link --- docs/extend/modular-resources/upload/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index 39abcc337c..d43998c1c9 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -282,7 +282,7 @@ To update an existing module in the [Viam Registry](https://app.viam.com/registr When ready to test the action, uncomment `if: github.event_name == 'release'` to enable the action to trigger a run when you [issue a release](https://docs.github.com/en/repositories/releasing-projects-on-github). For guidance on configuring the other parameters, see the documentation for each: - - [`org-id`](#using-the---org-id-and---public-namespace-arguments) - Not required if your module is public. + - [`org-id`](/manage/cli/#using-the---org-id-and---public-namespace-arguments) - Not required if your module is public. - [`platform`](/manage/cli/#using-the---platform-argument) - You can only upload one platform at a time. - [`version`](/manage/cli/#using-the---version-argument) - [`key-id` and `key-value`](/manage/cli/#create-an-organization-api-key) - You will set these values in the next step. From 7c67a56164d36605642b1e7b6e205e70cee4f8f0 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Mon, 11 Sep 2023 11:24:18 -0400 Subject: [PATCH 06/13] apply abes feedback, add DOCS-1056 links --- docs/extend/modular-resources/upload/_index.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index d43998c1c9..b03c30e712 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -177,8 +177,8 @@ For more information, see the [`viam module` command](/manage/cli/#module) You can update an existing module in the [Viam Registry](https://app.viam.com/registry) in one of two ways: -- [Upload a newer version of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/). -- [Upload a newer version of your module automatically](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. +- [Upload new versions of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/). +- [Automatically upload new versions of your module on release](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. Updating your module manually is appropriate for smaller projects, especially those with only one contributor. Updating your module automatically using CI is better suited for larger, ongoing projects, especially those with multiple contributors. @@ -284,13 +284,19 @@ To update an existing module in the [Viam Registry](https://app.viam.com/registr For guidance on configuring the other parameters, see the documentation for each: - [`org-id`](/manage/cli/#using-the---org-id-and---public-namespace-arguments) - Not required if your module is public. - [`platform`](/manage/cli/#using-the---platform-argument) - You can only upload one platform at a time. - - [`version`](/manage/cli/#using-the---version-argument) + - [`version`](https://github.com/viamrobotics/upload-module/blob/main/README.md#versioning) - Also see [Using the --version argument](/manage/cli/#using-the---version-argument) for more details on the types of versioning supported. - [`key-id` and `key-value`](/manage/cli/#create-an-organization-api-key) - You will set these values in the next step. -1. Next, follow the instructions to [Create an organization API key](/manage/cli/#create-an-organization-api-key), which the action will use to authenticate its run. +1. Follow the instructions to [Create an organization API key](/manage/cli/#create-an-organization-api-key), which the action will use to authenticate its run. Provide the `key-id` and `key-value` generated in the YAML configuration above. 1. Push a commit to your module or [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github). - Your module should upload to the [Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. + The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the `run` step you defined earlier. + Once complete, your module should upload to the [Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. -For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module). +For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module), or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs: + +- [Python with virtualenv](https://github.com/viam-labs/python-example-module) +- [Python with docker](https://github.com/viamrobotics/python-container-module) +- [Golang](https://github.com/viam-labs/wifi-sensor) +- [C++](https://github.com/viamrobotics/module-example-cpp) From fe7a3f63e5e4c88c36626e08b039979765bfa734 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Mon, 11 Sep 2023 11:32:10 -0400 Subject: [PATCH 07/13] lowercase registry per someone said --- .../movement-sensor/viam-visual-odometry.md | 4 +- docs/extend/_index.md | 2 +- docs/extend/modular-resources/_index.md | 24 +++++------ docs/extend/modular-resources/configure.md | 38 ++++++++--------- .../extend/modular-resources/create/_index.md | 8 ++-- docs/extend/modular-resources/key-concepts.md | 12 +++--- .../extend/modular-resources/upload/_index.md | 42 +++++++++---------- docs/manage/CLI.md | 22 +++++----- docs/manage/fleet/organizations.md | 2 +- docs/viam/_index.md | 10 ++--- 10 files changed, 82 insertions(+), 82 deletions(-) diff --git a/docs/components/movement-sensor/viam-visual-odometry.md b/docs/components/movement-sensor/viam-visual-odometry.md index 13295a7a29..7e9af1c94e 100644 --- a/docs/components/movement-sensor/viam-visual-odometry.md +++ b/docs/components/movement-sensor/viam-visual-odometry.md @@ -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). diff --git a/docs/extend/_index.md b/docs/extend/_index.md index d5c618c8ab..c597873ead 100644 --- a/docs/extend/_index.md +++ b/docs/extend/_index.md @@ -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/" --- diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 93cb1c0b3c..1a76fde06f 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -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 -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 +### 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/). @@ -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. diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index c4ffda010f..04afaf9d6d 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -4,21 +4,21 @@ 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 +## Add a module 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. +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. @@ -26,56 +26,56 @@ To add a module from the Viam Registry 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/registry) 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. {{}} 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. {{}} 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](https://app.viam.com/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. {{}} #### 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**. @@ -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](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). +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: diff --git a/docs/extend/modular-resources/create/_index.md b/docs/extend/modular-resources/create/_index.md index cebdbf2d43..21c314a38a 100644 --- a/docs/extend/modular-resources/create/_index.md +++ b/docs/extend/modular-resources/create/_index.md @@ -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 @@ -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. diff --git a/docs/extend/modular-resources/key-concepts.md b/docs/extend/modular-resources/key-concepts.md index febf0d06cb..c7e3911486 100644 --- a/docs/extend/modular-resources/key-concepts.md +++ b/docs/extend/modular-resources/key-concepts.md @@ -19,7 +19,7 @@ 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](/extend/modular-resources/upload/) or can [add existing modules from the Registry](/extend/modular-resources/configure/). +You can [upload your own modules to the Viam registry](/extend/modular-resources/upload/) or can [add existing modules from the Registry](/extend/modular-resources/configure/). See [Creating a custom module](/extend/modular-resources/create/) for more information. @@ -47,7 +47,7 @@ See [Naming your model](/extend/modular-resources/key-concepts/#naming-your-mode 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 available for download from the [Viam Registry](https://app.viam.com/registry), and are written by either Viam or community users. +- Provided in custom modules available for download from the [Viam registry](https://app.viam.com/registry), and are written by either Viam or community users. ### Built-in models @@ -61,7 +61,7 @@ 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. +The [Viam registry](https://app.viam.com/registry) makes available both Viam-provided and community-written modules for download and use on your robot. These models run outside `viam-server` as a separate process. #### Valid APIs to implement in your model @@ -80,7 +80,7 @@ When implementing a custom model of an existing [service](/services/), valid [AP #### Naming your model -If you are [creating a custom module](/extend/modular-resources/create/) and [uploading that module](/extend/modular-resources/upload/) to the Viam Registry, ensure your model name meets the following requirements: +If you are [creating a custom module](/extend/modular-resources/create/) and [uploading that module](/extend/modular-resources/upload/) to the Viam registry, ensure your model name meets the following requirements: - The namespace of your model **must** match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization). For example, if your organization uses the `acme` namespace, your models must all begin with `acme`, like `acme:demo:mybase`. @@ -90,7 +90,7 @@ If you are [creating a custom module](/extend/modular-resources/create/) and [up In addition, you should chose a name for the `family` of your model based on the whether your module implements a single model, or multiple models: - If your module provides a single model, the `family` should match the `subtype` of whichever API your model implements. - For example, the Intel Realsense module `realsense`, available from the [Viam Registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows: + For example, the Intel Realsense module `realsense`, available from the [Viam registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows: ```json {class="line-numbers linkable-line-numbers"} { @@ -100,7 +100,7 @@ In addition, you should chose a name for the `family` of your model based on the ``` - If your module provides multiple models, the `family` should describe the common functionality provided across all the models of that module. - For example, the ODrive module `odrive`, available from the [Viam Registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows: + For example, the ODrive module `odrive`, available from the [Viam registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows: ```json {class="line-numbers linkable-line-numbers"} { diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index b03c30e712..c6934ed786 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -1,22 +1,22 @@ --- -title: "Upload your own modules to the Viam Registry" +title: "Upload your own modules to the Viam registry" linkTitle: "Upload" weight: 20 type: "docs" tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"] -description: "Use the Viam CLI to upload a custom module to the Viam Registry." +description: "Use the Viam CLI to upload a custom module to the Viam registry." no_list: true --- -Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam Registry. +Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam registry. -With the CLI, you can register your module with the [Viam Registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). +With the CLI, you can register your module with the [Viam registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/). For more information, see the [`viam module` command](/manage/cli/#module). ## Upload a custom module -To upload your custom module to the [Viam Registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: +To upload your custom module to the [Viam registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below: 1. First, [install the Viam CLI](/manage/cli/#install) and [authenticate](/manage/cli/#authenticate) to Viam, from the same machine that you intend to upload your module from. @@ -109,16 +109,16 @@ To upload your custom module to the [Viam Registry](https://app.viam.com/registr See [The `meta.json` file](/manage/cli/#the-metajson-file) for more information. -1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam Registry. +1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam registry. Run this command from within the same directory as your `meta.json` file: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module update ``` - On a successful update, the command will return a link to the updated module in the Viam Registry. + On a successful update, the command will return a link to the updated module in the Viam registry. -1. Package your custom module to get it ready to upload to the Viam Registry. +1. Package your custom module to get it ready to upload to the Viam registry. Currently, the Registry only supports `tar.gz` or `tar.xz` format. Use the command below specific for the language of your module: @@ -139,7 +139,7 @@ To upload your custom module to the [Viam Registry](https://app.viam.com/registr Where `run.sh` is your [entrypoint file](/extend/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/extend/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. -1. Run `viam module upload` to upload the updated custom module to the Viam Registry: +1. Run `viam module upload` to upload the updated custom module to the Viam registry: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module upload --version --platform module.tar.gz @@ -163,19 +163,19 @@ To upload your custom module to the [Viam Registry](https://app.viam.com/registr Use the *same version number* when running multiple `upload` commands of the same module code if only the `platform` support differs. {{% /alert %}} - For example, the following command uploads the compressed `module.tar.gz` archive to the Viam Registry when run in the same directory as the corresponding `meta.json` file: + For example, the following command uploads the compressed `module.tar.gz` archive to the Viam registry when run in the same directory as the corresponding `meta.json` file: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module upload --version 1.0.0 --platform darwin/arm64 module.tar.gz ``` - When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam Registry. + When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry. For more information, see the [`viam module` command](/manage/cli/#module) ## Update an existing module -You can update an existing module in the [Viam Registry](https://app.viam.com/registry) in one of two ways: +You can update an existing module in the [Viam registry](https://app.viam.com/registry) in one of two ways: - [Upload new versions of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/). - [Automatically upload new versions of your module on release](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. @@ -185,23 +185,23 @@ Updating your module automatically using CI is better suited for larger, ongoing ### Update an existing module using the Viam CLI -To update an existing module in the [Viam Registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/): +To update an existing module in the [Viam registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/): 1. Edit your custom module with the changes you'd like to make. 1. Update your custom module's `meta.json` file with the changes, if any. For example, if you have altered your model's name, or adjusted the endpoint name, you'll need to update `meta.json` with these changes. -1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam Registry. +1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam registry. Run this command from within the same directory as your `meta.json` file: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module update ``` - On a successful update, the command will return a link to the updated module in the Viam Registry. + On a successful update, the command will return a link to the updated module in the Viam registry. -1. Package your custom module to get it ready to upload to the Viam Registry. +1. Package your custom module to get it ready to upload to the Viam registry. Currently, the Registry only supports `tar.gz` or `tar.xz` format. Use the command below specific for the language of your module: @@ -222,25 +222,25 @@ To update an existing module in the [Viam Registry](https://app.viam.com/registr Where `run.sh` is your [entrypoint file](/extend/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/extend/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. -1. Run `viam module upload` to upload the updated custom module to the Viam Registry: +1. Run `viam module upload` to upload the updated custom module to the Viam registry: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module upload --version --platform ``` - For example, the following command uploads the compressed `my-module.tar.gz` archive to the Viam Registry when run in the same directory, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`: + For example, the following command uploads the compressed `my-module.tar.gz` archive to the Viam registry when run in the same directory, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`: ``` sh {id="terminal-prompt" class="command-line" data-prompt="$"} viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz ``` - When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam Registry. + When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry. For more information, see the [`viam module` command](/manage/cli/#module) ### Update an existing module using a Github action -To update an existing module in the [Viam Registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). +To update an existing module in the [Viam registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). 1. Edit your custom module with the changes you'd like to make. @@ -292,7 +292,7 @@ To update an existing module in the [Viam Registry](https://app.viam.com/registr 1. Push a commit to your module or [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github). The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the `run` step you defined earlier. - Once complete, your module should upload to the [Viam Registry](https://app.viam.com/registry) with the appropriate version automatically. + Once complete, your module should upload to the [Viam registry](https://app.viam.com/registry) with the appropriate version automatically. For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module), or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs: diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index a19dcf4ffd..196ad5553d 100644 --- a/docs/manage/CLI.md +++ b/docs/manage/CLI.md @@ -15,7 +15,7 @@ The CLI lets you: * Retrieve [organization](/manage/fleet/organizations/) and location information * Manage [robot fleet](/manage/fleet/) data and logs * Control robots by issuing component and service commands -* Upload and manage [modular resources](/extend/modular-resources/) in the Viam Registry +* Upload and manage [modular resources](/extend/modular-resources/) in the Viam registry For example, this CLI command moves a servo to the 75 degree position: @@ -304,8 +304,8 @@ This includes: * Creating a new custom modular resource * Updating an existing module with new changes -* Uploading a new module to the Viam Registry -* Updating an existing module in the Viam Registry +* Uploading a new module to the Viam registry +* Updating an existing module in the Viam registry ```sh {class="command-line" data-prompt="$"} viam module create --name [--org-id | --public-namespace ] @@ -325,7 +325,7 @@ viam module create --name 'my-module' --org-id 'abc' # update an existing module: viam module update -# upload a new or updated custom module to the Viam Registry: +# upload a new or updated custom module to the Viam registry: viam module upload --version "1.0.0" --platform "darwin/arm64" packaged-module.tar.gz ``` @@ -337,7 +337,7 @@ See [Upload a custom module](/extend/modular-resources/upload/#upload-a-custom-m | ----------- | ----------- | ----------- | | `create` | generate new metadata for a custom module on your local filesystem | - | | `update` | update an existing custom module on your local filesystem with recent changes to the [`meta.json` file](#the-metajson-file) | - | -| `upload` | validate and upload a new or existing custom module on your local filesystem to the Viam Registry. See [Upload validation](#upload-validation) for more information | +| `upload` | validate and upload a new or existing custom module on your local filesystem to the Viam registry. See [Upload validation](#upload-validation) for more information | | `--help` | return help | - | ##### Named arguments @@ -356,10 +356,10 @@ See [Upload a custom module](/extend/modular-resources/upload/#upload-a-custom-m All of the `module` commands accept either the `--org-id` or `--public-namespace` argument. -* Use the `--public-namespace` argument to supply the [namespace](/manage/fleet/organizations/#create-a-namespace-for-your-organization) of your organization, suitable for uploading your module to the Viam Registry and sharing with other users. +* Use the `--public-namespace` argument to supply the [namespace](/manage/fleet/organizations/#create-a-namespace-for-your-organization) of your organization, suitable for uploading your module to the Viam registry and sharing with other users. * Use the `--org-id` to provide your organization ID instead, suitable for sharing your module privately within your organization. -You may use either argument for the `viam module create` command, but must use `--public-namespace` for the `update` and `upload` commands when uploading as a public module (`visibility: "public"`) to the Viam Registry. +You may use either argument for the `viam module create` command, but must use `--public-namespace` for the `update` and `upload` commands when uploading as a public module (`visibility: "public"`) to the Viam registry. ##### Using the `--platform` argument @@ -379,7 +379,7 @@ Use the *same version number* when running multiple `upload` commands of the sam The `--version` argument accepts a valid [semver 2.0](https://semver.org/) version (example: `1.0.0`). You set an initial version for your custom module with your first `viam module upload` command for that module, and can later increment the version with subsequent `viam module upload` commands. -Once your module is uploaded, users can select which version of your module to use on their robot from your module's page on the Viam Registry. +Once your module is uploaded, users can select which version of your module to use on their robot from your module's page on the Viam registry. Users can choose to pin to a specific patch version, permit upgrades within major release families or only within minor releases, or permit continuous updates. When you `update` a module configuration and then `upload` it, the `entrypoint` for that module defined in the [`meta.json` file](#the-metajson-file) is associated with the specific `--version` for that `upload`. @@ -387,7 +387,7 @@ Therefore, you are able to change the `entrypoint` file from version to version, ##### Upload validation -When you `upload` a module, the command validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam Registry. +When you `upload` a module, the command validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam registry. The following criteria are checked for every `upload`: * The packaged module must exist on the filesystem at the path provided to the `upload` command. @@ -397,9 +397,9 @@ The following criteria are checked for every `upload`: ##### The `meta.json` file -When uploading a custom module, the Viam Registry tracks your module's metadata in a `meta.json` file. +When uploading a custom module, the Viam registry tracks your module's metadata in a `meta.json` file. This file is created for you when you run the `viam module create` command, with the `module_id` field pre-populated based on the `--name` you provided to `create`. -If you later make changes to this file, you can register those changes with the Viam Registry by using the `viam module update` command. +If you later make changes to this file, you can register those changes with the Viam registry by using the `viam module update` command. The `meta.json` file includes the following configuration options: diff --git a/docs/manage/fleet/organizations.md b/docs/manage/fleet/organizations.md index f16937de0e..2743c2ec5d 100644 --- a/docs/manage/fleet/organizations.md +++ b/docs/manage/fleet/organizations.md @@ -48,7 +48,7 @@ In the members section of the page enter their email address, select a role, and ### Create a namespace for your organization -When uploading [custom modules](/extend/modular-resources/) to the Viam Registry, you must set a namespace for your organization to associate your module with. +When uploading [custom modules](/extend/modular-resources/) to the Viam registry, you must set a namespace for your organization to associate your module with. To create a new namespace for your organization, click on the Org's **Settings** in the top right of the navigation bar, then click the **Set a public namespace** button. Enter a name for your namespace, and then click **Set namespace**. diff --git a/docs/viam/_index.md b/docs/viam/_index.md index aae6bcfb8d..3b8ae38623 100644 --- a/docs/viam/_index.md +++ b/docs/viam/_index.md @@ -29,7 +29,7 @@ You will not need to write a single line of code to integrate them, and swapping You can make use of computer vision, motion planning, SLAM, data management, machine learning, and more by configuring Viam's built-in {{< glossary_tooltip term_id="service" text="services">}}. - **Architecture**: You can build simple robots or multi-part robots that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API. -- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from the [Viam Registry](/extend/modular-resources/). +- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from the [Viam registry](/extend/modular-resources/). Join the [**Viam community**](https://discord.gg/viam) to collaborate during planning and beyond. @@ -134,11 +134,11 @@ With it you can: ## Extensibility -You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam Registry](https://app.viam.com/registry) to your robot. +You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam registry](https://app.viam.com/registry) to your robot. -The Viam 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. -You can also [upload your own module to the Viam Registry](/extend/modular-resources/upload/). +The Viam 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. +You can also [upload your own module to the Viam registry](/extend/modular-resources/upload/). See [Modular resources](/extend/modular-resources/) for more information. From 643e3a6724633b8e454b8edea2759cf22a966b57 Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Mon, 11 Sep 2023 11:39:56 -0400 Subject: [PATCH 08/13] add mention from CLI reference docs --- docs/manage/CLI.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index 196ad5553d..597a8cbacd 100644 --- a/docs/manage/CLI.md +++ b/docs/manage/CLI.md @@ -331,6 +331,9 @@ viam module upload --version "1.0.0" --platform "darwin/arm64" packaged-module.t See [Upload a custom module](/extend/modular-resources/upload/#upload-a-custom-module) and [Update an existing module](/extend/modular-resources/upload/#update-an-existing-module) for a detailed walkthrough of the `viam module` commands. +If you update and release your module as part of a continuous integration (CI) workflow, you can also +[automatically upload new versions of your module on release](/extend/modular-resources/upload/#update-an-existing-module-using-a-github-action) using a GitHub Action. + #### Command options | command option | description | positional arguments From b1b431a054e439bee72b50a90a82cb1e21ac4cdc Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Mon, 11 Sep 2023 11:54:21 -0400 Subject: [PATCH 09/13] restore title case in headings --- docs/extend/modular-resources/_index.md | 4 ++-- docs/extend/modular-resources/configure.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 1a76fde06f..bbb60e6a2c 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -24,7 +24,7 @@ For example, you can: 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. -## 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. @@ -32,7 +32,7 @@ You can add a module from the Viam registry directly from your robot's **Configu 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 +### 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. 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/)). diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 04afaf9d6d..8d9d92b397 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -14,7 +14,7 @@ You can [add a module from the Viam registry](#add-a-module-from-the-viam-regist 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 +## Add a module 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. From d089c0c1a816885415525fd4ee620f67267113bf Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Mon, 11 Sep 2023 17:08:48 -0400 Subject: [PATCH 10/13] Update docs/extend/modular-resources/upload/_index.md Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- docs/extend/modular-resources/upload/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index c6934ed786..7609ad8d3e 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -294,7 +294,7 @@ To update an existing module in the [Viam registry](https://app.viam.com/registr The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the `run` step you defined earlier. Once complete, your module should upload to the [Viam registry](https://app.viam.com/registry) with the appropriate version automatically. -For more details, see the [`upload-module` Github action documentation](https://github.com/viamrobotics/upload-module), or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs: +For more details, see the [`upload-module` GitHub action documentation](https://github.com/viamrobotics/upload-module), or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs: - [Python with virtualenv](https://github.com/viam-labs/python-example-module) - [Python with docker](https://github.com/viamrobotics/python-container-module) From f3f4d0e4837bba33d5359d1a8f6129f3642d9fd8 Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Mon, 11 Sep 2023 17:08:56 -0400 Subject: [PATCH 11/13] Update docs/extend/modular-resources/upload/_index.md Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- docs/extend/modular-resources/upload/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index 7609ad8d3e..dccd5f593f 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -240,7 +240,7 @@ For more information, see the [`viam module` command](/manage/cli/#module) ### Update an existing module using a Github action -To update an existing module in the [Viam registry](https://app.viam.com/registry) using CI, use the [`upload-module` Github action](https://github.com/viamrobotics/upload-module). +To update an existing module in the [Viam registry](https://app.viam.com/registry) using CI, use the [`upload-module` GitHub action](https://github.com/viamrobotics/upload-module). 1. Edit your custom module with the changes you'd like to make. From d39ca660bb439af4c6be946da232ea1de21c0e2b Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Mon, 11 Sep 2023 17:09:03 -0400 Subject: [PATCH 12/13] Update docs/extend/modular-resources/upload/_index.md Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- docs/extend/modular-resources/upload/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md index dccd5f593f..f1b5f461f2 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -238,7 +238,7 @@ To update an existing module in the [Viam registry](https://app.viam.com/registr For more information, see the [`viam module` command](/manage/cli/#module) -### Update an existing module using a Github action +### Update an existing module using a GitHub action To update an existing module in the [Viam registry](https://app.viam.com/registry) using CI, use the [`upload-module` GitHub action](https://github.com/viamrobotics/upload-module). From d392353b3548f3f917763e63c3ba3b7fd4c7291e Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Mon, 11 Sep 2023 17:24:20 -0400 Subject: [PATCH 13/13] Lowercase registry again --- docs/extend/modular-resources/configure.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 95b60a14fd..1d7a73dc4d 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -9,13 +9,13 @@ no_list: true --- 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). +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). See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concepts/) for more information. -## Add a module from the Viam Registry +## Add a module 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. +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. A module provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} (either a [component](/components/) or [service](/services/)). @@ -26,7 +26,7 @@ Follow the instructions below depending on the type of modular resource you woul ### Add a modular component from the Viam registry -To add a modular [component](/components/) from the Viam Registry to your robot: +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. @@ -47,12 +47,12 @@ You can also find [the module itself](#configure-a-module-from-the-viam-registry 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. +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. ### Add a modular service from the Viam registry -To add a modular [service](/services/) from the Viam Registry to your robot: +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. @@ -68,15 +68,15 @@ To add a modular [service](/services/) from the Viam Registry 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. +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. +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 +## 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: @@ -84,7 +84,7 @@ Once you have added a modular resource to your robot, you can view and configure 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. +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. {{}} @@ -118,7 +118,7 @@ If, for example, the module provides a motor component, and the motor is running ### 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](/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: