From 593007b6155d04b82c8db2d230d712d3d0e01577 Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Mon, 11 Sep 2023 17:31:35 -0400 Subject: [PATCH] DOCS-1060, DOCS-1091: Add GitHub Action upload (#1782) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- .../movement-sensor/viam-visual-odometry.md | 4 +- docs/extend/_index.md | 2 +- docs/extend/modular-resources/_index.md | 20 ++-- 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 | 113 ++++++++++++++---- docs/manage/CLI.md | 25 ++-- docs/manage/fleet/organizations.md | 2 +- docs/viam/_index.md | 10 +- 10 files changed, 153 insertions(+), 81 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 97e28d9249..bbb60e6a2c 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](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/). @@ -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 7a6bcec36e..1d7a73dc4d 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -4,18 +4,18 @@ 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 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. @@ -42,17 +42,17 @@ To add a modular [component](/components/) from the Viam Registry to your robot: {{}} -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 **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,32 +84,32 @@ 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. {{}} ### 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**. @@ -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: 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 375b4c162f..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/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 @@ -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 ce5893d8d9..d1e00ce7e5 100644 --- a/docs/extend/modular-resources/upload/_index.md +++ b/docs/extend/modular-resources/upload/_index.md @@ -1,26 +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 --- -{{% 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. -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. @@ -113,16 +109,16 @@ To upload your custom module to the Viam Registry, either as a public or private 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: @@ -143,7 +139,7 @@ To upload your custom module to the Viam Registry, either as a public or private 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 @@ -168,35 +164,45 @@ To upload your custom module to the Viam Registry, either as a public or private The Viam registry page for your module displays the platforms your module supports for each version you have uploaded. {{% /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 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 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. + +### 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. 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: @@ -217,18 +223,81 @@ You can also use the [Viam CLI](/manage/cli/) to update an existing custom modul 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). + +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`](/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`](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. 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). + 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: + +- [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) diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index c6dae5cee2..1ce4ab69a6 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,19 +325,22 @@ 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 ``` 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 | ----------- | ----------- | ----------- | | `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 +359,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 @@ -381,7 +384,7 @@ The Viam registry page for your module displays the platforms your module suppor 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`. @@ -389,7 +392,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. @@ -399,9 +402,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 230059ffd1..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.