diff --git a/assets/modular-resources/add-odrive/add-odrive-attributes-ui.png b/assets/registry/add-odrive/add-odrive-attributes-ui.png similarity index 100% rename from assets/modular-resources/add-odrive/add-odrive-attributes-ui.png rename to assets/registry/add-odrive/add-odrive-attributes-ui.png diff --git a/assets/modular-resources/add-odrive/add-odrive-module-ui.png b/assets/registry/add-odrive/add-odrive-module-ui.png similarity index 100% rename from assets/modular-resources/add-odrive/add-odrive-module-ui.png rename to assets/registry/add-odrive/add-odrive-module-ui.png diff --git a/assets/modular-resources/add-odrive/add-odrive-resource-ui.png b/assets/registry/add-odrive/add-odrive-resource-ui.png similarity index 100% rename from assets/modular-resources/add-odrive/add-odrive-resource-ui.png rename to assets/registry/add-odrive/add-odrive-resource-ui.png diff --git a/assets/modular-resources/add-rplidar/add-rplidar-component-ui.png b/assets/registry/add-rplidar/add-rplidar-component-ui.png similarity index 100% rename from assets/modular-resources/add-rplidar/add-rplidar-component-ui.png rename to assets/registry/add-rplidar/add-rplidar-component-ui.png diff --git a/assets/modular-resources/add-rplidar/add-rplidar-module-ui-M1-M2.png b/assets/registry/add-rplidar/add-rplidar-module-ui-M1-M2.png similarity index 100% rename from assets/modular-resources/add-rplidar/add-rplidar-module-ui-M1-M2.png rename to assets/registry/add-rplidar/add-rplidar-module-ui-M1-M2.png diff --git a/assets/modular-resources/add-rplidar/add-rplidar-module-ui-linux.png b/assets/registry/add-rplidar/add-rplidar-module-ui-linux.png similarity index 100% rename from assets/modular-resources/add-rplidar/add-rplidar-module-ui-linux.png rename to assets/registry/add-rplidar/add-rplidar-module-ui-linux.png diff --git a/assets/modular-resources/configure/add-component-by-category.png b/assets/registry/configure/add-component-by-category.png similarity index 100% rename from assets/modular-resources/configure/add-component-by-category.png rename to assets/registry/configure/add-component-by-category.png diff --git a/assets/modular-resources/configure/add-component-by-name.png b/assets/registry/configure/add-component-by-name.png similarity index 100% rename from assets/modular-resources/configure/add-component-by-name.png rename to assets/registry/configure/add-component-by-name.png diff --git a/assets/modular-resources/configure/add-component-screen.png b/assets/registry/configure/add-component-screen.png similarity index 100% rename from assets/modular-resources/configure/add-component-screen.png rename to assets/registry/configure/add-component-screen.png diff --git a/assets/modular-resources/configure/add-local-module-config-builder.png b/assets/registry/configure/add-local-module-config-builder.png similarity index 100% rename from assets/modular-resources/configure/add-local-module-config-builder.png rename to assets/registry/configure/add-local-module-config-builder.png diff --git a/assets/modular-resources/configure/add-local-module-create.png b/assets/registry/configure/add-local-module-create.png similarity index 100% rename from assets/modular-resources/configure/add-local-module-create.png rename to assets/registry/configure/add-local-module-create.png diff --git a/assets/modular-resources/configure/add-local-module-csi-cam.png b/assets/registry/configure/add-local-module-csi-cam.png similarity index 100% rename from assets/modular-resources/configure/add-local-module-csi-cam.png rename to assets/registry/configure/add-local-module-csi-cam.png diff --git a/assets/modular-resources/configure/add-local-module-list.png b/assets/registry/configure/add-local-module-list.png similarity index 100% rename from assets/modular-resources/configure/add-local-module-list.png rename to assets/registry/configure/add-local-module-list.png diff --git a/assets/modular-resources/configure/add-service-by-category.png b/assets/registry/configure/add-service-by-category.png similarity index 100% rename from assets/modular-resources/configure/add-service-by-category.png rename to assets/registry/configure/add-service-by-category.png diff --git a/assets/modular-resources/configure/add-service-by-name.png b/assets/registry/configure/add-service-by-name.png similarity index 100% rename from assets/modular-resources/configure/add-service-by-name.png rename to assets/registry/configure/add-service-by-name.png diff --git a/assets/modular-resources/configure/add-service-screen.png b/assets/registry/configure/add-service-screen.png similarity index 100% rename from assets/modular-resources/configure/add-service-screen.png rename to assets/registry/configure/add-service-screen.png diff --git a/assets/modular-resources/configure/deployed-module-with-component.png b/assets/registry/configure/deployed-module-with-component.png similarity index 100% rename from assets/modular-resources/configure/deployed-module-with-component.png rename to assets/registry/configure/deployed-module-with-component.png diff --git a/assets/modular-resources/configure/deployed-module-with-service.png b/assets/registry/configure/deployed-module-with-service.png similarity index 100% rename from assets/modular-resources/configure/deployed-module-with-service.png rename to assets/registry/configure/deployed-module-with-service.png diff --git a/assets/modular-resources/triton/triton-config-builder.png b/assets/registry/triton/triton-config-builder.png similarity index 100% rename from assets/modular-resources/triton/triton-config-builder.png rename to assets/registry/triton/triton-config-builder.png diff --git a/docs/appendix/changelog.md b/docs/appendix/changelog.md index 71ba41b6cd..5cd48f8818 100644 --- a/docs/appendix/changelog.md +++ b/docs/appendix/changelog.md @@ -4,7 +4,7 @@ linkTitle: "Changelog" weight: 110 draft: false type: "docs" -description: "Changelog" +description: "A lof of added features, improvements, and changes over time." aliases: - "/appendix/release-notes/" # SME: @@ -419,9 +419,9 @@ The UR5 arm model has been improved using this new geometry type. ### Added: Modular resources -You can now implement your own custom {{< glossary_tooltip term_id="resource" text="resources" >}} as [_modular resources_](/modular-resources/). +You can now implement your own custom {{< glossary_tooltip term_id="resource" text="resources" >}} as [_modular resources_](/registry/). -The [old method](/modular-resources/advanced/custom-components-remotes/) of using a separate server to implement a custom resource is still supported, but implementation as a modular resource reduces network requests and is strongly recommended. +The [old method](/registry/advanced/custom-components-remotes/) of using a separate server to implement a custom resource is still supported, but implementation as a modular resource reduces network requests and is strongly recommended. {{% alert title="Important: Breaking Change" color="note" %}} diff --git a/docs/appendix/glossary/model-namespace-triplet.md b/docs/appendix/glossary/model-namespace-triplet.md index 739a705de1..45a713703a 100644 --- a/docs/appendix/glossary/model-namespace-triplet.md +++ b/docs/appendix/glossary/model-namespace-triplet.md @@ -1,7 +1,7 @@ --- title: Model Namespace Triplet id: model-namespace-triplet -full_link: /modular-resources/key-concepts/#naming-your-model-namespacerepo-namename +full_link: /registry/key-concepts/#naming-your-model-namespacerepo-namename short_description: namespace:repo-name:name or rdk:builtin:name aka: --- @@ -9,4 +9,4 @@ aka: {{< glossary_tooltip term_id="model" text="Models" >}} are uniquely namespaced as colon-delimited-triplets. Modular resource model names have the form `namespace:repo-name:name`. Built-in model names have the form `rdk:builtin:name`. -See [Naming your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename) for more information. +See [Naming your model](/registry/key-concepts/#naming-your-model-namespacerepo-namename) for more information. diff --git a/docs/appendix/glossary/model.md b/docs/appendix/glossary/model.md index 0ece6ddf1d..448bf334c4 100644 --- a/docs/appendix/glossary/model.md +++ b/docs/appendix/glossary/model.md @@ -9,3 +9,59 @@ aka: A particular implementation of a {{< glossary_tooltip term_id="resource" text="resource" >}} {{< glossary_tooltip term_id="subtype" text="subtype" >}}. For example: `ur5e` is a _model_ of arm, implementing the [resource API](/program/apis/) of the [arm](/components/arm/) subtype of {{< glossary_tooltip term_id="component" text="component" >}}, which, in turn, is a {{< glossary_tooltip term_id="type" text="type" >}} of resource. + +## Models + +A _model_ describes a specific implementation of a {{< glossary_tooltip term_id="resource" text="resource" >}} that implements (speaks) its [API](/program/apis/). +Models allow you to control hardware or software of a similar category, such as motors, with a consistent set of methods as an interface, even if the underlying implementation differs. + +For example, some DC motors communicate using [GPIO](/components/board/), while other DC motors use serial protocols like the [SPI bus](/components/board/#spis). +Regardless, you can power any motor model that implements the `rdk:component:motor` API with the `SetPower()` method. + +Models are uniquely namespaced as colon-delimited-triplets. +Modular resource model names have the form `namespace:repo-name:name`. +Built-in model names have the form `rdk:builtin:name`. +See [Naming your model](#naming-your-model-namespacerepo-namename) for more information. + +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 {{< glossary_tooltip term_id="module" text="custom modules" >}} available for download from the [Viam registry](https://app.viam.com/registry), and are written by either Viam or community users. + Custom modules can also be [local](/registry/configure/#local-modules). + +### Built-in models + +Viam provides many built-in models that implement API capabilities, each using `rdk` as the `namespace`, and `builtin` as the `family`. +These models run within `viam-server`. + +For example: + +- The `rdk:builtin:gpio` model of the `rdk:component:motor` API provides RDK support for [GPIO-controlled DC motors](/components/motor/gpio/). +- The `rdk:builtin:DMC4000` model of the same `rdk:component:motor` API provides RDK support for the [DMC4000](/components/motor/dmc4000/) motor. + +### 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. +You can also run modules [locally](/registry/configure/#local-modules). +These models run outside `viam-server` as a separate process. + +#### Naming your model: namespace:repo-name:name + +If you are [creating a custom module](/registry/create/) and [uploading that module](/registry/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`. +- Your model triplet must be all-lowercase. +- Your model triplet may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters. + +For the middle segment of your model triplet `repo-name`, use the name of the git repository where you store your module's code. +The `repo-name` should describe the common functionality provided across the model or models of that module. + +For example: + +- The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model uses the repository name [yahboom](https://github.com/viam-labs/yahboom). + The models implement the `rdk:component:arm` and the `rdk:component:gripper` API to support the Yahboom DOFBOT arm and gripper, respectively. +- The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout) + It implements the custom API `viam-labs:service:audioout`. + +The `viam` namespace is reserved for models provided by Viam. diff --git a/docs/appendix/glossary/modular-resource.md b/docs/appendix/glossary/modular-resource.md index 02a56cd2c4..62d3a8bf74 100644 --- a/docs/appendix/glossary/modular-resource.md +++ b/docs/appendix/glossary/modular-resource.md @@ -1,7 +1,7 @@ --- title: Modular Resource id: modular-resource -full_link: https://docs.viam.com/modular-resources/ +full_link: https://docs.viam.com/registry/ short_description: A modular resource is a custom model of a component or service that implements the standadized API methods for that resource. aka: --- @@ -11,4 +11,4 @@ Modular resources are provided by {{< glossary_tooltip term_id="module" text="mo A modular resource runs in the module process. This differs from built-in resources, which run as part of `viam-server`. -For more information see the [Modular Resource Documentation](/modular-resources/). +For more information see the [Modular Resource Documentation](/registry/). diff --git a/docs/appendix/glossary/module.md b/docs/appendix/glossary/module.md index b8e2459386..f614acd616 100644 --- a/docs/appendix/glossary/module.md +++ b/docs/appendix/glossary/module.md @@ -10,6 +10,6 @@ A _module_ provides one or more {{< glossary_tooltip term_id="modular-resource" Modules run alongside `viam-server` as separate processs, communicating with `viam-server` over UNIX sockets. When the module initializes, it registers those pairs on your robot, making the functionality defined by that pair available for use. -You can [create your own module](/modular-resources/create/) or [add existing modules from the Viam registry](/modular-resources/configure/). +You can [create your own module](/registry/create/) or [add existing modules from the Viam registry](/registry/configure/). -For more information see the [modular resource documentation](/modular-resources/). +For more information see the [modular resource documentation](/registry/). diff --git a/docs/appendix/glossary/resource.md b/docs/appendix/glossary/resource.md index ee937b1362..2dae8c290e 100644 --- a/docs/appendix/glossary/resource.md +++ b/docs/appendix/glossary/resource.md @@ -18,4 +18,4 @@ Resources are individual, addressable elements of a robot. Each part has local resources and can also have resources from another {{< glossary_tooltip term_id="remote" text="remote">}} robot part. The capabilities of each resource are exposed through the part’s API. -Each resource on your robot implements either one of the [existing Viam APIs](/modular-resources/create/#valid-apis-to-implement-in-your-model), or a [custom interface](/modular-resources/advanced/#new-api-subtypes). +Each resource on your robot implements either one of the [existing Viam APIs](/registry/create/#valid-apis-to-implement-in-your-model), or a [custom interface](/registry/advanced/#new-api-subtypes). diff --git a/docs/components/arm/_index.md b/docs/components/arm/_index.md index 479b059bc2..8f8faceff6 100644 --- a/docs/components/arm/_index.md +++ b/docs/components/arm/_index.md @@ -61,9 +61,9 @@ To use your arm with Viam, check whether one of the following [built-in models]( {{< alert title="Add support for other models" color="tip" >}} -If none of the existing models fit your use case, you can [create a modular resource](/modular-resources/) to add support for it. +If none of the existing models fit your use case, you can [create a modular resource](/registry/) to add support for it. -You can follow [this guide](/modular-resources/examples/custom-arm/) to implement your custom arm as a [modular resource](/modular-resources/). +You can follow [this guide](/registry/examples/custom-arm/) to implement your custom arm as a [modular resource](/registry/). {{< /alert >}} diff --git a/docs/components/board/jetson.md b/docs/components/board/jetson.md index d1bd18379e..4da3c50242 100644 --- a/docs/components/board/jetson.md +++ b/docs/components/board/jetson.md @@ -3,7 +3,7 @@ title: "Configure a jetson board" linkTitle: "jetson" weight: 20 type: "docs" -description: "Configure a jetson board." +description: "Configure a jetson board to integrate a NVIDIA Jetson Orin Module and Developer Kit, NVIDIA Jetson AGX, or NVIDIA Jetson Nano into your robot." images: ["/icons/components/board.svg"] tags: ["board", "components"] # SMEs: Gautham, Rand @@ -13,7 +13,7 @@ tags: ["board", "components"] Follow one of our Jetson [setup guides](/installation/) to prepare your board for running `viam-server` before configuring a `jetson` board. -If you have a CSI camera, follow [these instructions](/modular-resources/examples/csi/) to configure it using the `viam:camera:csi` model. +If you have a CSI camera, follow [these instructions](/registry/examples/csi/) to configure it using the `viam:camera:csi` model. {{% /alert %}} diff --git a/docs/components/movement-sensor/_index.md b/docs/components/movement-sensor/_index.md index 167f68f713..9916f9a275 100644 --- a/docs/components/movement-sensor/_index.md +++ b/docs/components/movement-sensor/_index.md @@ -51,7 +51,7 @@ Model | Description [`gps-nmea-rtk-serial`](./gps/gps-nmea-rtk-serial/) | [NTRIP-based](https://en.wikipedia.org/wiki/Networked_Transport_of_RTCM_via_Internet_Protocol) [RTK](https://en.wikipedia.org/wiki/Real-time_kinematic_positioning) GPS models using serial communication (**experimental**) [`imu-wit`](./imu/imu-wit/) | IMUs manufactured by [WitMotion](https://www.wit-motion.com/) [`accel-adxl345`](./adxl345/) | The [Analog Devices ADXL345](https://www.analog.com/en/products/adxl345.html) digital accelerometer -[`viam_visual_odometry`](./viam-visual-odometry/) | A [modular resource](/modular-resources/) that derives movement data from a [camera](/components/camera/) stream +[`viam_visual_odometry`](./viam-visual-odometry/) | A [modular resource](/registry/) that derives movement data from a [camera](/components/camera/) stream [`gyro-mpu6050`](./mpu6050/) | A gyroscope/accelerometer manufactured by TDK InvenSense [`merged`](./merged/) | A model that allows you to aggregate the API methods supported by multiple sensors into a singular sensor client, effectively merging the models of the individual resources [`wheeled-odometry`](./wheeled-odometry/) | A model that uses [encoders](/components/encoder/) to get an odometry estimate from a wheeled base diff --git a/docs/components/movement-sensor/viam-visual-odometry.md b/docs/components/movement-sensor/viam-visual-odometry.md index 4472d876e6..e239593ead 100644 --- a/docs/components/movement-sensor/viam-visual-odometry.md +++ b/docs/components/movement-sensor/viam-visual-odometry.md @@ -28,7 +28,7 @@ While `monocular-visual-odometry` enables you to add movement sensing abilities If your robot requires precise awareness of its location and its movement, you should consider using a dedicated movement sensor in addition to the `monocular-visual-odometry` module. The `monocular-visual-odometry` module is available [from the Viam registry](https://app.viam.com/module/viam/monocular-visual-odometry). -See [Modular resources](/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. +See [Modular resources](/registry/#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/components/movement-sensor/wheeled-odometry.md b/docs/components/movement-sensor/wheeled-odometry.md index f6f9d92555..71da73de49 100644 --- a/docs/components/movement-sensor/wheeled-odometry.md +++ b/docs/components/movement-sensor/wheeled-odometry.md @@ -33,7 +33,7 @@ After configuring a `wheeled-odometry` movement sensor, you can operate your bas To prepare your robot, attach [encoders](/components/encoder/) to each of the position-reporting motors on your base to measure their rotation. -- Select motors that can report their own position, like an encoded [`roboclaw`](/components/motor/roboclaw/) or [`gpio` motors](/components/motor/gpio/) with [encoders](/components/encoder/#supported-models), or the [`odrive`](/modular-resources/examples/odrive/) module. +- Select motors that can report their own position, like an encoded [`roboclaw`](/components/motor/roboclaw/) or [`gpio` motors](/components/motor/gpio/) with [encoders](/components/encoder/#supported-models), or the [`odrive`](/registry/examples/odrive/) module. You can access this property of a configured motor through the [motor API's `GetProperties()`](/components/motor/#getproperties). - Configure your rover as a [wheeled base component](/components/base/wheeled/). Make sure to configure the base width and circumference, as these measurements as a property of the base are vital for accurate odometry estimations by your movement sensor. diff --git a/docs/internals/RDK.md b/docs/internals/RDK.md index a9318c7abb..ebb9fd8cd1 100644 --- a/docs/internals/RDK.md +++ b/docs/internals/RDK.md @@ -61,6 +61,6 @@ During robot shutdown, the RDK handles modular resource instances similarly to b {{< cards >}} {{% card link="/program/apis/" %}} -{{% card link="/modular-resources/" %}} +{{% card link="/registry/" %}} {{% card link="/micro-rdk/" %}} {{< /cards >}} diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index 3503474d4d..3f812da570 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](/modular-resources/) in the Viam registry +- Upload and manage [modular resources](/registry/) in the Viam registry For example, this CLI command moves a servo to the 75 degree position: @@ -377,10 +377,10 @@ viam module update viam module upload --version "1.0.0" --platform "darwin/arm64" packaged-module.tar.gz ``` -See [Upload a custom module](/modular-resources/upload/#upload-a-custom-module) and [Update an existing module](/modular-resources/upload/#update-an-existing-module) for a detailed walkthrough of the `viam module` commands. +See [Upload a custom module](/registry/upload/#upload-a-custom-module) and [Update an existing module](/registry/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](/modular-resources/upload/#update-an-existing-module-using-a-github-action) using a GitHub Action. +[automatically upload new versions of your module on release](/registry/upload/#update-an-existing-module-using-a-github-action) using a GitHub Action. #### Command options @@ -494,7 +494,7 @@ The `meta.json` file includes the following configuration options: models object Required - A list of one or more models provided by your custom module. You must provide at least one model, which consists of an api and model key pair. + A list of one or more models provided by your custom module. You must provide at least one model, which consists of an api and model key pair. entrypoint @@ -523,14 +523,14 @@ For example, the following represents the configuration of an example `my-module ``` {{% alert title="Important" color="note" %}} -If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization). +If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/registry/key-concepts/#naming-your-model-namespacerepo-namename) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization). In the example above, the model namespace is set to `acme` to match the owning organization's namespace. If the two namespaces do not match, the command will return an error. {{% /alert %}} -See [Upload a custom module](/modular-resources/upload/#upload-a-custom-module) and [Update an existing module](/modular-resources/upload/#update-an-existing-module) for a detailed walkthrough of the `viam module` commands. +See [Upload a custom module](/registry/upload/#upload-a-custom-module) and [Update an existing module](/registry/upload/#update-an-existing-module) for a detailed walkthrough of the `viam module` commands. -See [Modular resources](/modular-resources/) for a conceptual overview of modules and the modular resource system at Viam. +See [Modular resources](/registry/) for a conceptual overview of modules and the modular resource system at Viam. ### organizations diff --git a/docs/manage/configuration.md b/docs/manage/configuration.md index 3c3a6cc4dd..340ed0c486 100644 --- a/docs/manage/configuration.md +++ b/docs/manage/configuration.md @@ -212,9 +212,9 @@ See the [services documentation](/services/) for more information. ## Modules -[Modular resources](/modular-resources/) are a way to add resource types or models that are not built into Viam. +[Modular resources](/registry/) are a way to add resource types or models that are not built into Viam. -To add a modular resource as a component or service of your robot, configure a module per the [modular resource documentation](/modular-resources/). +To add a modular resource as a component or service of your robot, configure a module per the [modular resource documentation](/registry/). ## Remotes diff --git a/docs/manage/fleet/_index.md b/docs/manage/fleet/_index.md index 579c131394..70edd0a1d8 100644 --- a/docs/manage/fleet/_index.md +++ b/docs/manage/fleet/_index.md @@ -120,7 +120,7 @@ If you are collaborating on a robot and controlling it using the [**Control** ta ### Deployment -You and your collaborators can deploy [control logic](/program/apis/), [modular resources](/modular-resources/), sidecar [processes](../configuration/#processes), or [machine learning models](/services/ml/) to your fleet of robots without manually copying files by uploading it to Viam's cloud and deploying it to your fleet. +You and your collaborators can deploy [control logic](/program/apis/), [modular resources](/registry/), sidecar [processes](../configuration/#processes), or [machine learning models](/services/ml/) to your fleet of robots without manually copying files by uploading it to Viam's cloud and deploying it to your fleet. ## The Viam mobile app diff --git a/docs/manage/fleet/organizations.md b/docs/manage/fleet/organizations.md index bd3b498a41..0e31f9c947 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](/modular-resources/) to the Viam registry, you must set a namespace for your organization to associate your module with. +When uploading [custom modules](/registry/) 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/manage/ml/_index.md b/docs/manage/ml/_index.md index bbb572323f..7ba58fc75e 100644 --- a/docs/manage/ml/_index.md +++ b/docs/manage/ml/_index.md @@ -55,7 +55,7 @@ Viam natively supports [TensorFlow Lite](https://www.tensorflow.org/lite) ML mod {{}} 5. Configure a service

For object detection and classification, you can use the vision service, which provides an ml model detector and an ml model classifier model.

-

For other usage, you can use a modular resource to integrate it with your robot.

+

For other usage, you can use a modular resource to integrate it with your robot.

@@ -70,5 +70,5 @@ Viam natively supports [TensorFlow Lite](https://www.tensorflow.org/lite) ML mod {{< cards >}} {{% card link="/tutorials/projects/pet-treat-dispenser/" customTitle="Smart Pet Feeder" %}} -{{% card link="/modular-resources/examples/tflite-module/" %}} +{{% card link="/registry/examples/tflite-module/" %}} {{< /cards >}} diff --git a/docs/manage/ml/upload-model.md b/docs/manage/ml/upload-model.md index 085ac9066d..c0eb5cf700 100644 --- a/docs/manage/ml/upload-model.md +++ b/docs/manage/ml/upload-model.md @@ -6,7 +6,7 @@ type: "docs" tags: ["data management", "ml", "model training"] aliases: - /manage/data/upload-model/ -description: "Upload an image classification model to Viam." +description: "Upload a Machine Learning model to Viam to use it with the ML Model service." # SME: Aaron Casas --- @@ -27,27 +27,6 @@ Once the model has finished training, it becomes visible in the **Models** secti ![The trained model](/manage/ml/stars-model.png) -#### Naming your model: namespace:repo-name:name - -If you are [creating a custom module](/modular-resources/create/) and want to [upload that module](/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`. -- Your model triplet must be all-lowercase. -- Your model triplet may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters. - -For the middle segment of your model triplet `repo-name`, use the name of the git repository where you store your module's code. -The `repo-name` should describe the common functionality provided across the model or models of that module. - -For example: - -- The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model uses the repository name [yahboom](https://github.com/viam-labs/yahboom). - The models implement the `rdk:component:arm` and the `rdk:component:gripper` API to support the Yahboom DOFBOT arm and gripper, respectively. -- The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout) - It implements the custom API `viam-labs:service:audioout`. - -The `viam` namespace is reserved for models provided by Viam. - ### Upload a new version of a model If you [deploy a model](/services/ml/) to a robot, Viam automatically assumes that this is the `latest` version of the model and that you would always like to deploy the `latest` version of the model to the robot. diff --git a/docs/modular-resources/key-concepts.md b/docs/modular-resources/key-concepts.md deleted file mode 100644 index bdc3ff8df7..0000000000 --- a/docs/modular-resources/key-concepts.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Key Concepts of Modular Resource APIs" -linkTitle: "Concepts" -weight: 10 -type: "docs" -tags: - [ - "server", - "rdk", - "extending viam", - "modular resources", - "components", - "services", - ] -description: "The key concepts behind how Viam's resource APIs and models are uniquely namespaced and modular resource management with the RDK." -no_list: true -aliases: - - "/program/extend/modular-resources/key-concepts/" ---- - -## Models - -A _model_ describes a specific implementation of a {{< glossary_tooltip term_id="resource" text="resource" >}} that implements (speaks) its [API](/program/apis/). -Models allow you to control hardware or software of a similar category, such as motors, with a consistent set of methods as an interface, even if the underlying implementation differs. - -For example, some DC motors communicate using [GPIO](/components/board/), while other DC motors use serial protocols like the [SPI bus](/components/board/#spis). -Regardless, you can power any motor model that implements the `rdk:component:motor` API with the `SetPower()` method. - -Models are uniquely namespaced as colon-delimited-triplets. -Modular resource model names have the form `namespace:repo-name:name`. -Built-in model names have the form `rdk:builtin:name`. -See [Naming your model](#naming-your-model-namespacerepo-namename) for more information. - -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 {{< glossary_tooltip term_id="module" text="custom modules" >}} available for download from the [Viam registry](https://app.viam.com/registry), and are written by either Viam or community users. - Custom modules can also be [local](/modular-resources/configure/#local-modules). - -### Built-in models - -Viam provides many built-in models that implement API capabilities, each using `rdk` as the `namespace`, and `builtin` as the `family`. -These models run within `viam-server`. - -For example: - -- The `rdk:builtin:gpio` model of the `rdk:component:motor` API provides RDK support for [GPIO-controlled DC motors](/components/motor/gpio/). -- The `rdk:builtin:DMC4000` model of the same `rdk:component:motor` API provides RDK support for the [DMC4000](/components/motor/dmc4000/) motor. - -### 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. -You can also run modules [locally](/modular-resources/configure/#local-modules). -These models run outside `viam-server` as a separate process. - -#### Naming your model: namespace:repo-name:name - -If you are [creating a custom module](/modular-resources/create/) and [uploading that module](/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`. -- Your model triplet must be all-lowercase. -- Your model triplet may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters. - -For the middle segment of your model triplet `repo-name`, use the name of the git repository where you store your module's code. -The `repo-name` should describe the common functionality provided across the model or models of that module. - -For example: - -- The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model uses the repository name [yahboom](https://github.com/viam-labs/yahboom). - The models implement the `rdk:component:arm` and the `rdk:component:gripper` API to support the Yahboom DOFBOT arm and gripper, respectively. -- The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout) - It implements the custom API `viam-labs:service:audioout`. - -The `viam` namespace is reserved for models provided by Viam. diff --git a/docs/program/use-extra-params.md b/docs/program/use-extra-params.md index 4d0f367932..8dbd2fbb24 100644 --- a/docs/program/use-extra-params.md +++ b/docs/program/use-extra-params.md @@ -86,14 +86,14 @@ If passing an object of type `nil`, you must specify `nil` in the method call or ## Define -If `extra` information must be passed to a resource, it is handled within a new, _modular_ resource model's [custom API](/modular-resources/) wrapper. +If `extra` information must be passed to a resource, it is handled within a new, _modular_ resource model's [custom API](/registry/) wrapper. {{%expand "Click for instructions on defining a custom model to utilize extra params" %}} To do this, define a custom implementation of the resource's API as a new _model_, and modify the resource's API methods to handle the `extra` information you send. -Follow the steps in the [Modular Resources documentation](/modular-resources/create/) to do so. +Follow the steps in the [Modular Resources documentation](/registry/create/) to do so. -For an example of how to check the values of keys in an `extra` parameter of a built-in resource [API method](/program/apis/), reference this modification to the built-in [sensor](/components/sensor/) resource type's [Readings](/components/sensor/#getreadings) method in the code of a [new sensor model](/modular-resources/): +For an example of how to check the values of keys in an `extra` parameter of a built-in resource [API method](/program/apis/), reference this modification to the built-in [sensor](/components/sensor/) resource type's [Readings](/components/sensor/#getreadings) method in the code of a [new sensor model](/registry/): {{< tabs >}} {{% tab name="Python" %}} @@ -159,6 +159,6 @@ func (s *mySensor) Readings(ctx context.Context, extra map[string]interface{}) ( {{% /tab %}} {{% /tabs %}} -See [Extend Viam with Modular Resources](/modular-resources/) for more information and [instructions](/modular-resources/) on modifying built-in API specifications. +See [Extend Viam with Modular Resources](/registry/) for more information and [instructions](/registry/) on modifying built-in API specifications. {{% /expand%}} diff --git a/docs/modular-resources/_index.md b/docs/registry/_index.md similarity index 80% rename from docs/modular-resources/_index.md rename to docs/registry/_index.md index 3fbc587d91..97f6287fd2 100644 --- a/docs/modular-resources/_index.md +++ b/docs/registry/_index.md @@ -1,6 +1,6 @@ --- -title: "Extend Viam with Modular Resources" -linkTitle: "Modular Resources" +title: "Extend Viam with Modules from the Viam Registry" +linkTitle: "Viam Registry" weight: 50 type: "docs" tags: @@ -12,14 +12,15 @@ tags: "components", "services", ] -description: "You can use hardware components or services that Viam does not natively support, by adding them through existing modular resources from the Viam Registry or by creating new modular resources." +description: "Support additional hardware components or services by adding them from the Viam Registry or by creating new modular resources." no_list: true aliases: - - "/program/extend/modular-resources/" - - "/extend/modular-resources/" + - "/program/extend/registry/" + - "/extend/registry/" - "/extend/" - - "/program/extend/modular-resources/key-concepts/" + - "/program/extend/registry/key-concepts/" - "/modular-resources/key-concepts/" + - "/modular-resources/" --- Viam provides built-in support for a variety of {{< glossary_tooltip term_id="resource" text="resources" >}}: @@ -71,10 +72,10 @@ If none of the existing modular resources in the Viam registry support your use You can write modules in a variety of programming languages, such as, Go, Python, C++, Rust, while implementing the same [APIs](/program/apis/). To create a new modular resource: -1. [Create a module](/modular-resources/create/) with one or more modular resources by implementing all methods for the component's or service's [standardized API](/program/apis/). -1. [Upload the module to the Viam registry](/modular-resources/upload/) to make it available for deployment to robots or add it as a [local module](/modular-resources/configure/#local-modules). +1. [Create a module](/registry/create/) with one or more modular resources by implementing all methods for the component's or service's [standardized API](/program/apis/). +1. [Upload the module to the Viam registry](/registry/upload/) to make it available for deployment to robots or add it as a [local module](/registry/configure/#local-modules). You can upload _private_ modules for your [organization](/manage/fleet/organizations/) or _public_ modules. -1. Once you have uploaded your module to the registry, [deploy and configure the module](/modular-resources/configure/) from [the Viam app](https://app.viam.com/). +1. Once you have uploaded your module to the registry, [deploy and configure the module](/registry/configure/) from [the Viam app](https://app.viam.com/). You can test your added resource using the [**Control** tab](/manage/fleet/#remote-control) and [program](/program/) it with Viam's Go or Python SDKs. ## Related tutorials @@ -82,5 +83,5 @@ To create a new modular resource: {{< cards >}} {{% card link="/tutorials/projects/make-a-plant-watering-robot/" %}} {{% card link="/tutorials/custom/custom-base-dog/" %}} -{{% card link="/modular-resources/examples/custom-arm/" %}} +{{% card link="/registry/examples/custom-arm/" %}} {{< /cards >}} diff --git a/docs/modular-resources/advanced/_index.md b/docs/registry/advanced/_index.md similarity index 81% rename from docs/modular-resources/advanced/_index.md rename to docs/registry/advanced/_index.md index 28ba054396..4dd73d1fed 100644 --- a/docs/modular-resources/advanced/_index.md +++ b/docs/registry/advanced/_index.md @@ -17,6 +17,7 @@ tags: description: "Some usage may require you to define new APIs or deploy custom components using a server on a remote part" aliases: - "/program/extend/" + - "/modular-resources/advanced/" --- Some use cases may require you to define a new API, or deploy a custom component using a server on a {{< glossary_tooltip term_id="remote" text="remote part" >}}. @@ -27,9 +28,9 @@ The [component APIs](/program/apis/#component-apis) and [service APIs](/program/ If you want to use most of an existing API but need just a few other functions, try using the [`DoCommand`](/program/apis/#docommand) endpoint and [extra parameters](/program/use-extra-params/) to add custom functionality to an existing subtype. -If your resource does not fit into any of the existing {{< glossary_tooltip term_id="component" text="component" >}} or {{< glossary_tooltip term_id="service" text="service" >}} {{< glossary_tooltip term_id="subtype" text="subtypes" >}} or you want to define different methods for the API, you can use the [generic API](/components/generic/) with the [`DoCommand`](/program/apis/#docommand) or [define a new resource subtype and an API for that subtype](/modular-resources/advanced/create-subtype/). +If your resource does not fit into any of the existing {{< glossary_tooltip term_id="component" text="component" >}} or {{< glossary_tooltip term_id="service" text="service" >}} {{< glossary_tooltip term_id="subtype" text="subtypes" >}} or you want to define different methods for the API, you can use the [generic API](/components/generic/) with the [`DoCommand`](/program/apis/#docommand) or [define a new resource subtype and an API for that subtype](/registry/advanced/create-subtype/). ## Custom components as remotes Running {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}} on the [board](/components/board/) directly connected to your components is the preferred way of managing and controlling custom components. -However, if you are unable to use [modular resources](/modular-resources/) because you have to host `viam-server` on a non-Linux system or have an issue with compilation, you may need to [implement a custom component and register it on a server configured as a remote](/modular-resources/advanced/custom-components-remotes/) of your robot. +However, if you are unable to use [modular resources](/registry/) because you have to host `viam-server` on a non-Linux system or have an issue with compilation, you may need to [implement a custom component and register it on a server configured as a remote](/registry/advanced/custom-components-remotes/) of your robot. diff --git a/docs/modular-resources/advanced/create-subtype.md b/docs/registry/advanced/create-subtype.md similarity index 96% rename from docs/modular-resources/advanced/create-subtype.md rename to docs/registry/advanced/create-subtype.md index 83dfc78ab1..6b595586bc 100644 --- a/docs/modular-resources/advanced/create-subtype.md +++ b/docs/registry/advanced/create-subtype.md @@ -7,7 +7,8 @@ tags: ["rdk", "extending viam", "modular resources", "API"] description: "Define a new API for a resource that does not fit into existing component or service subtypes." no_list: true aliases: - - "/extend/modular-resources/create/create-subtype/" + - "/extend/registry/create/create-subtype/" + - "/modular-resources/advanced/create-subtype" --- You can define a new {{< glossary_tooltip term_id="resource" text="resource" >}} _{{< glossary_tooltip term_id="subtype" text="subtype" >}}_ API if: @@ -71,7 +72,7 @@ The following steps guide you through this process in more detail: ## Next steps {{< cards >}} -{{% manualcard link="/modular-resources/create/#code-a-new-resource-model"%}} +{{% manualcard link="/registry/create/#code-a-new-resource-model"%}}

Implement your API

diff --git a/docs/modular-resources/advanced/custom-components-remotes.md b/docs/registry/advanced/custom-components-remotes.md similarity index 84% rename from docs/modular-resources/advanced/custom-components-remotes.md rename to docs/registry/advanced/custom-components-remotes.md index da298827f8..3f65bbdbd9 100644 --- a/docs/modular-resources/advanced/custom-components-remotes.md +++ b/docs/registry/advanced/custom-components-remotes.md @@ -8,12 +8,13 @@ aliases: - "/program/extend/sdk-as-server/" - "/program/extend/custom-components-remotes/" - "/extend/custom-components-remotes/" + - "/modular-resources/advanced/custom-components-remotes" description: "If you are unable to use modular resources, you can implement custom components and register them on a server configured as a remote of your robot." --- Running {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}} on the [board](/components/board/) directly connected to your components is the preferred way of managing and controlling custom components. -However, if you are unable to use [modular resources](/modular-resources/) because you need to host `viam-server` on a non-Linux system or have an issue with compilation, you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. +However, if you are unable to use [modular resources](/registry/) because you need to host `viam-server` on a non-Linux system or have an issue with compilation, you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. Once you have coded your custom component and configured the remote servers, you can control and monitor your component with the Viam SDKs, like any other component. @@ -29,7 +30,7 @@ To add a custom resource as a [remote](/manage/parts-and-remotes/): 1. Code a new model of a built-in resource type. You can do this by creating a new interface that implements required methods. - The new model must implement any functions of the built-in resource type marked as required in its [RDK API definition](/modular-resources/create/#valid-apis-to-implement-in-your-model). + The new model must implement any functions of the built-in resource type marked as required in its [RDK API definition](/registry/create/#valid-apis-to-implement-in-your-model). 2. Register the custom component on a new gRPC server instance and start the server. 3. Add the server as a [remote](/manage/parts-and-remotes/) of your robot. 4. (Optional) [Configure a process](/manage/configuration/#processes) to launch this remote server to ensure the remote server is always running alongside the rest of your robot. @@ -45,7 +46,7 @@ For more detailed instructions, see the full example in the [Python SDK document 1. Code a new model of a built-in resource type. You can do this by subclassing a built in resource type like `sensor` or `arm`. - The new model must implement any methods of the built-in resource type marked as required in its [RDK API definition](/modular-resources/create/#valid-apis-to-implement-in-your-model). + The new model must implement any methods of the built-in resource type marked as required in its [RDK API definition](/registry/create/#valid-apis-to-implement-in-your-model). 1. Register the custom component on a new gRPC server instance and start the server. You can do this with the [`viam.rpc` library](https://python.viam.dev/autoapi/viam/rpc/index.html) by creating a new `rpc.server.Server` instance. 1. Add the server as a [remote](/manage/parts-and-remotes/) of your robot. diff --git a/docs/modular-resources/configure.md b/docs/registry/configure.md similarity index 82% rename from docs/modular-resources/configure.md rename to docs/registry/configure.md index 600c9589b7..8e535062b7 100644 --- a/docs/modular-resources/configure.md +++ b/docs/registry/configure.md @@ -15,7 +15,8 @@ tags: description: "Add a modular resource to your robot by configuring it." no_list: true aliases: - - "/program/extend/modular-resources/configure/" + - "/program/extend/registry/configure/" + - "/registry/configure/" --- You can extend Viam by adding a module on your robot that provides one or more {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}} ([components](/components/) or [services](/services/)): @@ -46,15 +47,15 @@ To add a modular [component](/components/) from the Viam registry to your robot: 1. Click on the **Components** subtab and click the **Create component** button. 1. Browse the list of available component types, and select the specific modular component you'd like to add. - {{}} + {{}} You can also start typing to search for a module by name or to narrow down your search results. - {{}} + {{}} 1. After selecting the modular component, click the **Add module** button, enter a name for your modular component, and click **Create** to add it to your robot's component configuration. - {{}} + {{}} Be sure the modular component you select supports the [platform](/manage/cli/#using-the---platform-argument) you intend to use it with, such as `linux arm64`. You can see which platforms the module supports at bottom of the module information screen before you add it. @@ -75,15 +76,15 @@ To add a modular [service](/services/) from the Viam registry to your robot: 1. Click on the **Services** subtab and click the **Create service** button. 1. Browse the list of available service types and select the specific modular service you'd like to add. - {{}} + {{}} You can also start typing to search for a module by name or to narrow down your search results. - {{}} + {{}} 1. After selecting the modular service, click the **Add module** button, enter a name for your modular service, and click **Create** to add it to your robot's service configuration. - {{}} + {{}} Be sure the modular service you select supports the [platform](/manage/cli/#using-the---platform-argument) you intend to use it with, such as `linux arm64`. You can see which platforms the module supports at bottom of the module information screen before you add it. @@ -98,7 +99,7 @@ Deleting a module _does not_ delete any configured modular resources it provides ### Add additional modular resources from a registry module -Once you have [added a module](#add-a-modular-resource-from-the-viam-registry) from the Viam registry, you can add any number of the modular resources it provides to your robot by adding new components or services configured with your modular resource's [model](/modular-resources/key-concepts/#models). +Once you have [added a module](#add-a-modular-resource-from-the-viam-registry) from the Viam registry, you can add any number of the modular resources it provides to your robot by adding new components or services configured with your modular resource's [model](/registry/key-concepts/#models). Follow the same steps as when you added the first modular resource, clicking **Create component** or **Create service** as applicable. You will be prompted to click **Add module** again while configuring the resource, though no duplicate module will be added to the `modules` section of the configuration. @@ -108,11 +109,11 @@ If you prefer to use raw JSON, the following properties are available for modula | Name | Type | Inclusion | Description | | ---- | ---- | --------- | ----------- | -| `namespace` | string | **Required** | The namespace of the API (the first part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/modular-resources/create/#valid-apis-to-implement-in-your-model) | -| `type` | string | **Required** | The {{< glossary_tooltip term_id="subtype" text="subtype">}} of the API (the third part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/modular-resources/create/#valid-apis-to-implement-in-your-model). | +| `namespace` | string | **Required** | The namespace of the API (the first part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/registry/create/#valid-apis-to-implement-in-your-model) | +| `type` | string | **Required** | The {{< glossary_tooltip term_id="subtype" text="subtype">}} of the API (the third part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/registry/create/#valid-apis-to-implement-in-your-model). | | `name` | string | **Required** | What you want to name this instance of your modular resource. | -| `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's [model](/modular-resources/key-concepts/#models). | -| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your robot alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/modular-resources/key-concepts/#dependency-management). | +| `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's [model](/registry/key-concepts/#models). | +| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your robot alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/registry/key-concepts/#dependency-management). | All standard properties for configuration, such as `attributes` and `depends_on`, are also supported for modular resources. The `attributes` available vary depending on your implementation. @@ -187,7 +188,7 @@ Once you have added a modular resource to your robot, you can view and edit the 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 @@ -227,8 +228,8 @@ You can add your own custom modules as local modules, or you can add pre-built m First determine the module you wish to add as a local module: -- If you are adding your own custom module, be sure that you have followed the steps to [create your own module](/modular-resources/create/) to code and compile your module and generate an executable. -- If you are using a pre-built module, make sure you have installed the module and determined the filename of [the module's executable](/modular-resources/create/#compile-the-module-into-an-executable). +- If you are adding your own custom module, be sure that you have followed the steps to [create your own module](/registry/create/) to code and compile your module and generate an executable. +- If you are using a pre-built module, make sure you have installed the module and determined the filename of [the module's executable](/registry/create/#compile-the-module-into-an-executable). Then, ensure that `viam-server` is able to find and run the executable: @@ -240,7 +241,7 @@ Then, ensure that `viam-server` is able to find and run the executable: sudo chmod a+rx ``` -See the instructions to [compile your module into an executable](/modular-resources/create/#compile-the-module-into-an-executable) for more information. +See the instructions to [compile your module into an executable](/registry/create/#compile-the-module-into-an-executable) for more information. ### Add a local module @@ -253,17 +254,17 @@ To add a local module on your robot: 1. Then, select the `local modular resource` type from the list. - {{}} + {{}} 1. On the next screen: - Select the type of modular resource provided by your module, such as a [camera](/components/camera/), from the drop down menu. - - Enter the {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of your modular resource's [model](/modular-resources/key-concepts/#models). + - Enter the {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of your modular resource's [model](/registry/key-concepts/#models). If you are adding a pre-built modular resource, the model triplet should be provided for you in the module's documentation. - Enter a name for this instance of your modular resource. This name must be different from the module name. - {{}} + {{}} 1. Click **Create** to create the modular resource provided by the local module. @@ -273,13 +274,13 @@ You can also add the module directly, without first adding its modular component 1. Click on the **Modules** subtab. 1. Scroll to the **Add local module** section. 1. Enter a **Name** for this instance of your modular resource. -1. Enter the [module's executable path](/modular-resources/create/#compile-the-module-into-an-executable). +1. Enter the [module's executable path](/registry/create/#compile-the-module-into-an-executable). This path must be the absolute path to the executable on your robot's filesystem. 1. Then, click the **Add module** button, and click **Save config**. - {{}} + {{}} - This example shows the configuration for adding a [CSI camera](/modular-resources/examples/csi/) as a local module. + This example shows the configuration for adding a [CSI camera](/registry/examples/csi/) as a local module. ### Edit the configuration of a local module @@ -303,7 +304,7 @@ Add these properties to your module's configuration: {{< tabs >}} {{% tab name="Config Builder" %}} -{{}} +{{}} {{% /tab %}} {{% tab name="JSON Template" %}} @@ -325,18 +326,18 @@ Add these properties to your module's configuration: ### Add a local modular resource -Once you have added a local module to your robot, you can add any number of the {{< glossary_tooltip term_id="resource" text="resources" >}} provided by that module to your robot by adding new components or services that use your modular resource's [model](/modular-resources/key-concepts/#models). +Once you have added a local module to your robot, you can add any number of the {{< glossary_tooltip term_id="resource" text="resources" >}} provided by that module to your robot by adding new components or services that use your modular resource's [model](/registry/key-concepts/#models). The following properties are available for modular resources: | Name | Type | Inclusion | Description | | ---- | ---- | --------- | ----------- | -| `namespace` | string | **Required** | The namespace of the API (the first part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/modular-resources/create/#valid-apis-to-implement-in-your-model). | -| `type` | string | **Required** | The {{< glossary_tooltip term_id="subtype" text="subtype">}} of the API (the third part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/modular-resources/create/#valid-apis-to-implement-in-your-model). | +| `namespace` | string | **Required** | The namespace of the API (the first part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/registry/create/#valid-apis-to-implement-in-your-model). | +| `type` | string | **Required** | The {{< glossary_tooltip term_id="subtype" text="subtype">}} of the API (the third part of the {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet">}}). See [Valid APIs to implement in your model](/registry/create/#valid-apis-to-implement-in-your-model). | | `name` | string | **Required** | A custom name for this instance of your modular resource. | -| `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's [model](/modular-resources/key-concepts/#models). | -| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your robot alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/modular-resources/key-concepts/#dependency-management). | +| `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's [model](/registry/key-concepts/#models). | +| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your robot alongside your modular resource. Often a [board](/components/board/). Unnecessary if you coded [implicit dependencies](/registry/key-concepts/#dependency-management). | All standard properties for configuration, such as `attributes` and `depends_on`, are also supported for modular resources. The `attributes` available vary depending on your implementation. diff --git a/docs/modular-resources/create/_index.md b/docs/registry/create/_index.md similarity index 93% rename from docs/modular-resources/create/_index.md rename to docs/registry/create/_index.md index 92e7aa3323..0ff298b836 100644 --- a/docs/modular-resources/create/_index.md +++ b/docs/registry/create/_index.md @@ -14,17 +14,18 @@ tags: ] description: "Use the Viam module system to implement modular resources that can be included in any Viam-powered smart machine." aliases: - - "/extend/modular-resources/create/" + - "/extend/registry/create/" + - "/modular-resources/create/" no_list: true --- -If you cannot find existing modular resources from the [Viam Registry](/modular-resources/#the-viam-registry) that support your hardware or software, you can add new {{< glossary_tooltip term_id="module" text="modules" >}}. +If you cannot find existing modular resources from the [Viam Registry](/registry/#the-viam-registry) that support your hardware or software, you can add new {{< glossary_tooltip term_id="module" text="modules" >}}. A _module_ provides one or more {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}, which add {{< glossary_tooltip term_id="resource" text="resource" >}} {{< glossary_tooltip term_id="type" text="types" >}} or {{< glossary_tooltip term_id="model" text="models" >}} that are not built into Viam. Modules run alongside `viam-server` as separate processs, communicating with `viam-server` over UNIX sockets. When the module initializes, it registers those pairs on your robot, making the functionality defined by that pair available for use. -In most cases, the {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}} you create should be a new [model](/modular-resources/key-concepts/#models) that implements an existing Viam [API](/program/apis/). +In most cases, the {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}} you create should be a new [model](/registry/key-concepts/#models) that implements an existing Viam [API](/program/apis/). For example, if you have a custom base, you can create a new base model that implements the `rdk:component:base` API. ## Find your reference files @@ -85,13 +86,13 @@ For example, the `base` component subtype is defined in [rdk/components/ba ### Valid APIs to implement in your model -When implementing a custom [model](/modular-resources/key-concepts/#models) of an existing [component](/components/), valid [APIs](/program/apis/) always have the following parameters: +When implementing a custom [model](/registry/key-concepts/#models) of an existing [component](/components/), valid [APIs](/program/apis/) always have the following parameters: - `namespace`: `rdk` - `type`: `component` - `subtype`: any one of [these component proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/component), for example `motor` -When implementing a custom [model](/modular-resources/key-concepts/#models) of an existing [service](/services/), valid [APIs](/program/apis/) always have the following parameters: +When implementing a custom [model](/registry/key-concepts/#models) of an existing [service](/services/), valid [APIs](/program/apis/) always have the following parameters: - `namespace`: `rdk` - `type`: `service` @@ -102,11 +103,11 @@ When implementing a custom [model](/modular-resources/key-concepts/#models) of a If you are using unique hardware that does not already have an [appropriate API](/program/apis/#component-apis) defined to support it, you can use the [generic API](/components/generic/) to add support for that unique hardware type to your smart machine. Some use cases may require you to define a new API, or to deploy custom components using a server on a remote part. -For more information, see [Advanced Modular Resources](/modular-resources/advanced/). +For more information, see [Advanced Modular Resources](/registry/advanced/). ## Create a custom module -A custom module wraps one or more [models](/modular-resources/key-concepts/#models). +A custom module wraps one or more [models](/registry/key-concepts/#models). To create a custom module, follow these steps: 1. [Code a new resource model](#code-a-new-resource-model) server. @@ -121,7 +122,7 @@ Your new resource model server must have all the methods that the Viam RDK requi Create a folder for your module and save your code as a file named my_modular_resource.py inside. -The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/modular-resources/key-concepts/#models) as a new model, `"mybase"`, using the model family `acme:demo:mybase`. +The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/registry/key-concepts/#models) as a new model, `"mybase"`, using the model family `acme:demo:mybase`. my_base.py implements "mybase", a custom model of the base component. @@ -304,7 +305,7 @@ Your new resource model server must have all the methods that the Viam RDK requi Create a folder for your module and save your code as a file named my_modular_resource.go inside. -The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/modular-resources/key-concepts/#models) as a new model, `"mybase"`, using the model family `acme:demo:mybase`. +The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/registry/key-concepts/#models) as a new model, `"mybase"`, using the model family `acme:demo:mybase`. mybase.go implements "mybase", a custom model of the base component, and registers the new model and API helper functions with the Go SDK. @@ -513,7 +514,7 @@ Additional examples are available in the [in the RDK GitHub repository](https:// Name your model according to the namespace of the built-in API you are implementing using all lowercase letters for optimal performance with Viam's SDKs. For example, `mybase` or `my-cool-sensor`. -For more information see [Naming your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename). +For more information see [Naming your model](/registry/key-concepts/#naming-your-model-namespacerepo-namename). {{% /alert %}} @@ -647,7 +648,7 @@ Additionally, return any values designated in the function's return signature, t ### Compile the module into an executable -To [add a module](/modular-resources/configure/) to the configuration of your robot, you need to have an [executable](https://en.wikipedia.org/wiki/Executable) that: +To [add a module](/registry/configure/) to the configuration of your robot, you need to have an [executable](https://en.wikipedia.org/wiki/Executable) that: - runs your module when executed, - can take a local socket as a command line argument, @@ -778,14 +779,14 @@ The examples from [Code a new resource model](#code-a-new-resource-model) includ ## Next steps -Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/modular-resources/upload/) to the [Viam registry](https://app.viam.com/registry) to share it with other Viam users or just to other users in your organization. -For added convenience, you can configure [automated uploads for new module versions](/modular-resources/upload/#update-an-existing-module-using-a-github-action) through a continuous integration (CI) workflow, using a GitHub Action. +Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/registry/upload/) to the [Viam registry](https://app.viam.com/registry) to share it with other Viam users or just to other users in your organization. +For added convenience, you can configure [automated uploads for new module versions](/registry/upload/#update-an-existing-module-using-a-github-action) through a continuous integration (CI) workflow, using a GitHub Action. -You can also add your module to your robot as a [local module](/modular-resources/configure/#local-modules), without uploading it to the Viam registry. +You can also add your module to your robot as a [local module](/registry/configure/#local-modules), without uploading it to the Viam registry. {{< cards >}} -{{% card link="/modular-resources/upload/" %}} -{{% manualcard link="/modular-resources/configure/#local-modules" %}} +{{% card link="/registry/upload/" %}} +{{% manualcard link="/registry/configure/#local-modules" %}}

Local module

diff --git a/docs/modular-resources/examples/_index.md b/docs/registry/examples/_index.md similarity index 69% rename from docs/modular-resources/examples/_index.md rename to docs/registry/examples/_index.md index 5d0db63108..bff239f41a 100644 --- a/docs/modular-resources/examples/_index.md +++ b/docs/registry/examples/_index.md @@ -19,8 +19,9 @@ tags: "services", ] aliases: - - "/program/extend/modular-resources/examples/" - - "/extend/modular-resources/examples/" + - "/program/extend/registry/examples/" + - "/extend/registry/examples/" + - "/modular-resources/examples/" --- To familiarize yourself with creating and using {{< glossary_tooltip term_id="modular-resource" text="modular resources" >}}, follow one of these example [tutorials](#tutorials) or clone one of these example [repositories](#repositories). @@ -29,13 +30,13 @@ Once you have created a modular resource, you can test your modular resource usi ## Tutorials {{< cards >}} -{{% card link="/modular-resources/examples/rplidar/" customTitle="Add an RPlidar camera as a Modular Resource" %}} -{{% card link="/modular-resources/examples/odrive/" customTitle="Add an ODrive motor as a Modular Resource" %}} -{{% card link="/modular-resources/examples/csi/" customTitle="Add a CSI Camera as a Modular Resource" %}} +{{% card link="/registry/examples/rplidar/" customTitle="Add an RPlidar camera as a Modular Resource" %}} +{{% card link="/registry/examples/odrive/" customTitle="Add an ODrive motor as a Modular Resource" %}} +{{% card link="/registry/examples/csi/" customTitle="Add a CSI Camera as a Modular Resource" %}} {{% card link="/components/movement-sensor/viam-visual-odometry/" customTitle="Add a Visual Odometry sensor as a Modular Resource" %}} -{{% card link="/modular-resources/examples/custom-arm/" %}} -{{% card link="/modular-resources/examples/tflite-module/" customTitle="Add a TensorFlow Lite Modular Service" %}} -{{% card link="/modular-resources/examples/triton/" customTitle="Add a Triton MLModel Modular Service" %}} +{{% card link="/registry/examples/custom-arm/" %}} +{{% card link="/registry/examples/tflite-module/" customTitle="Add a TensorFlow Lite Modular Service" %}} +{{% card link="/registry/examples/triton/" customTitle="Add a Triton MLModel Modular Service" %}} {{% card link="/tutorials/custom/custom-base-dog/" %}} {{% card link="/tutorials/custom/controlling-an-intermode-rover-canbus/" %}} {{< /cards >}} diff --git a/docs/modular-resources/examples/csi.md b/docs/registry/examples/csi.md similarity index 96% rename from docs/modular-resources/examples/csi.md rename to docs/registry/examples/csi.md index 78cf4902ed..1abc64abea 100644 --- a/docs/modular-resources/examples/csi.md +++ b/docs/registry/examples/csi.md @@ -21,7 +21,9 @@ tags: "camera", ] aliases: - - "/extend/modular-resources/examples/csi/" + - "/extend/registry/examples/csi/" + - "/modular-resources/examples/csi/" + # SMEs: Sean --- @@ -33,7 +35,7 @@ Instead, Viam supports CSI cameras by providing a {{< glossary_tooltip term_id=" This {{< glossary_tooltip term_id="module" text="module" >}} includes a simple wrapper around `GStreamer` and a control interface for the **Control** tab of the [Viam app](https://app.viam.com) so you can utilize the hardware accelerated GST plugins and use the embedded CSI cameras on your `jetson` boards with Viam. The `csi-cam` module is available [from the Viam registry](https://app.viam.com/module/viam/csi-cam). -See [Modular resources](/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. +See [Modular resources](/registry/#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-csi` GitHub repository](https://github.com/seanavery/viam-csi). diff --git a/docs/modular-resources/examples/custom-arm.md b/docs/registry/examples/custom-arm.md similarity index 93% rename from docs/modular-resources/examples/custom-arm.md rename to docs/registry/examples/custom-arm.md index d0951635ae..7faed31b8d 100644 --- a/docs/modular-resources/examples/custom-arm.md +++ b/docs/registry/examples/custom-arm.md @@ -17,7 +17,8 @@ tags: "CAN", ] aliases: - - "/extend/modular-resources/examples/custom-arm/" + - "/extend/registry/examples/custom-arm/" + - "/modular-resources/examples/custom-arm/" # SMEs: Nicole Jung --- @@ -38,7 +39,7 @@ See [Arm Configuration](/components/arm/#supported-models) for the current list If you have a robot arm that is not already supported by the RDK, create a module that provides a customized model for your arm to [program](/program/) and control it with the [arm API](/components/arm/#api), or use it with [services](/services/) like [Motion](/services/motion/), just as you would with a built-in model. -See [Modular Resources](/modular-resources/) for more information. +See [Modular Resources](/registry/) for more information. ## Get your arm's kinematics file @@ -81,13 +82,13 @@ To create a custom arm model, code a module in Python with the module support li {{% alert title="Info" color="info" %}} This guide uses Viam's Python SDK to implement a custom arm module, but if you want to use the Go Client SDK, you can. -Follow [this guide](/modular-resources/create/#code-a-new-resource-model) and select **Go** on the code samples to learn how to code a modular arm in Go. +Follow [this guide](/registry/create/#code-a-new-resource-model) and select **Go** on the code samples to learn how to code a modular arm in Go. {{% /alert %}} Save the following two files, my_modular_arm.py and \_\_init\_\_.py, on your computer and edit the code as applicable. -This module template registers a modular resource implementing Viam's built-in [Arm API](/components/arm/#api) [(rdk:service:arm)](/modular-resources/key-concepts/#models) as a new model, `"myarm"`: +This module template registers a modular resource implementing Viam's built-in [Arm API](/components/arm/#api) [(rdk:service:arm)](/registry/key-concepts/#models) as a new model, `"myarm"`: - my_modular_arm.py implements a custom model of the arm component built-in resource, `"myarm"`. @@ -232,7 +233,7 @@ The best practice with the Python SDK is to put `pass` or raise an `NotImplement ### Compile the module into an executable -To [add a module](/modular-resources/configure/) to the configuration of your robot, you need to have an [executable](https://en.wikipedia.org/wiki/Executable) that runs your module when executed, can take a local socket as a command line argument, and cleanly exits when sent a termination signal. +To [add a module](/registry/configure/) to the configuration of your robot, you need to have an [executable](https://en.wikipedia.org/wiki/Executable) that runs your module when executed, can take a local socket as a command line argument, and cleanly exits when sent a termination signal. Your options for completing this step are flexible, as this file does not need to be in a raw binary format. @@ -261,4 +262,4 @@ Your executable will be run by `viam-server` as root, so dependencies need to be ## Configure the module and modular resource on your robot -Follow [these configuration instructions](/modular-resources/configure/) to add your custom resource to your robot. +Follow [these configuration instructions](/registry/configure/) to add your custom resource to your robot. diff --git a/docs/modular-resources/examples/odrive.md b/docs/registry/examples/odrive.md similarity index 98% rename from docs/modular-resources/examples/odrive.md rename to docs/registry/examples/odrive.md index 8f7565e560..338cb51189 100644 --- a/docs/modular-resources/examples/odrive.md +++ b/docs/registry/examples/odrive.md @@ -17,7 +17,8 @@ tags: "CAN", ] aliases: - - "/extend/modular-resources/examples/odrive/" + - "/extend/registry/examples/odrive/" + - "/modular-resources/examples/odrive/" # SMEs: Kim, Martha, Rand --- @@ -25,7 +26,7 @@ Viam provides an `odrive` {{< glossary_tooltip term_id="modular-resource" text=" The `odrive` {{< glossary_tooltip term_id="module" text="module" >}} supports an ODrive motor driver connected in either `serial` or `canbus` mode. The `odrive` module is available [from the Viam registry](https://app.viam.com/module/viam/odrive). -See [Modular resources](/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. +See [Modular resources](/registry/#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 [`odrive` GitHub repository](https://github.com/viamrobotics/odrive). diff --git a/docs/modular-resources/examples/rplidar.md b/docs/registry/examples/rplidar.md similarity index 92% rename from docs/modular-resources/examples/rplidar.md rename to docs/registry/examples/rplidar.md index e794011a5a..34c2874107 100644 --- a/docs/modular-resources/examples/rplidar.md +++ b/docs/registry/examples/rplidar.md @@ -10,10 +10,11 @@ images: ["/program/modular-resources/rplidar-on-robot.png"] tags: ["slam", "services", "modular resources", "lidar", "rplidar"] no_list: true aliases: - - "/program/extend/modular-resources/add-rplidar-module/" - - "/program/extend/modular-resources/examples/add-rplidar-module/" - - "/extend/modular-resources/examples/add-rplidar-module/" - - "/extend/modular-resources/examples/rplidar/" + - "/program/extend/registry/add-rplidar-module/" + - "/program/extend/registry/examples/add-rplidar-module/" + - "/extend/registry/examples/add-rplidar-module/" + - "/extend/registry/examples/rplidar/" + - "/modular-resources/examples/rplidar/" # SMEs: Kat, Jeremy --- @@ -21,7 +22,7 @@ Viam provides an `rplidar` {{< glossary_tooltip term_id="modular-resource" text= Currently, the `rplidar` {{< glossary_tooltip term_id="module" text="module" >}} has been tested with the [RPlidar A1](https://www.slamtec.com/en/Lidar/A1), [RPlidar A3](https://www.slamtec.com/en/Lidar/A3), and [RPlidar S1](http://bucket.download.slamtec.com/f19ea8efcc2bb55dbfd5839f1d307e34aa4a6ca0/LD601_SLAMTEC_rplidar_datasheet_S1_v1.4_en.pdf). The `rplidar` module is available [from the Viam registry](https://app.viam.com/module/viam/rplidar). -See [Modular resources](/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. +See [Modular resources](/registry/#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 [`rplidar` GitHub repository](https://github.com/viamrobotics/rplidar). diff --git a/docs/modular-resources/examples/tflite-module.md b/docs/registry/examples/tflite-module.md similarity index 99% rename from docs/modular-resources/examples/tflite-module.md rename to docs/registry/examples/tflite-module.md index 2b4d69cc02..2f8f6a7eaa 100644 --- a/docs/modular-resources/examples/tflite-module.md +++ b/docs/registry/examples/tflite-module.md @@ -6,7 +6,8 @@ type: "docs" description: "Add an ML model modular-resource-based service which uses TensorFlow Lite to classify audio samples." tags: ["ml", "model training", "services"] aliases: - - "/extend/modular-resources/examples/tflite-module/" + - "/extend/registry/examples/tflite-module/" + - "/modular-resources/examples/tflite-module/" # SMEs: Andrew Morrow --- diff --git a/docs/modular-resources/examples/triton.md b/docs/registry/examples/triton.md similarity index 98% rename from docs/modular-resources/examples/triton.md rename to docs/registry/examples/triton.md index bd615c507b..dcf9525f16 100644 --- a/docs/modular-resources/examples/triton.md +++ b/docs/registry/examples/triton.md @@ -6,7 +6,8 @@ type: "docs" description: "Add an ML model modular service backed by NVIDIA's Triton Server." tags: ["ml", "model training", "services"] aliases: - - "/extend/modular-resources/examples/triton//" + - "/extend/registry/examples/triton/" + - "/modular-resources/examples/triton/" # SMEs: Abe Winter, Andrew Morrow --- @@ -82,7 +83,7 @@ Add the following to your `"services"` array: The model will now be configured with a card like the following: -![The triton service card in the Viam app config builder, showing deployment options.](/modular-resources/triton/triton-config-builder.png) +![The triton service card in the Viam app config builder, showing deployment options.](/registry/triton/triton-config-builder.png) Note that the parameters shown, `"model_path"`, `"label_path"`, and `"num_threads"` are not applicable for this module, and should be left blank. Ignore this card's interface and move to [creating a model repository](#create-a-repository-to-store-the-ml-model-to-deploy). diff --git a/docs/modular-resources/upload/_index.md b/docs/registry/upload/_index.md similarity index 85% rename from docs/modular-resources/upload/_index.md rename to docs/registry/upload/_index.md index 67a64b3a5a..d04967a132 100644 --- a/docs/modular-resources/upload/_index.md +++ b/docs/registry/upload/_index.md @@ -12,15 +12,37 @@ tags: "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 as a public module or as a private module that is shared only within your organization." no_list: true aliases: - - "/extend/modular-resources/upload/" + - "/extend/registry/upload/" + - "/modular-resources/upload/" --- -Once you have [created a custom module](/modular-resources/create/), use the [Viam CLI](/manage/cli/) to upload it to the Viam registry as a public module that is shared with other Viam users, or as a private module that is shared only within your [organization](/manage/fleet/organizations/). +Once you have [created a custom module](/registry/create/), use the [Viam CLI](/manage/cli/) to upload it to the Viam registry as a public module that is shared with other Viam users, or as a private module that is shared only within your [organization](/manage/fleet/organizations/). -Once uploaded, you can also [update your modules](/modular-resources/upload/#update-an-existing-module). +Once uploaded, you can also [update your modules](/registry/upload/#update-an-existing-module). + +#### Naming your model: namespace:repo-name:name + +If you are [creating a custom module](/registry/create/) and want to [upload that module](/registry/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`. +- Your model triplet must be all-lowercase. +- Your model triplet may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters. + +For the middle segment of your model triplet `repo-name`, use the name of the git repository where you store your module's code. +The `repo-name` should describe the common functionality provided across the model or models of that module. + +For example: + +- The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model uses the repository name [yahboom](https://github.com/viam-labs/yahboom). + The models implement the `rdk:component:arm` and the `rdk:component:gripper` API to support the Yahboom DOFBOT arm and gripper, respectively. +- The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout) + It implements the custom API `viam-labs:service:audioout`. + +The `viam` namespace is reserved for models provided by Viam. ## Upload a custom module @@ -111,7 +133,7 @@ If you mark your module as public, you cannot change it back to private. models object Required - A list of one or more models provided by your custom module. You must provide at least one model, which consists of an api and model key pair. If you are publishing a public module ("visibility": "public"), the namespace of your model must match the namespace of your organization. + A list of one or more models provided by your custom module. You must provide at least one model, which consists of an api and model key pair. If you are publishing a public module ("visibility": "public"), the namespace of your model must match the namespace of your organization. entrypoint @@ -166,7 +188,7 @@ If the two namespaces do not match, the command will return an error. tar -czf module.tar.gz run.sh requirements.txt src ``` - Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. + Where `run.sh` is your [entrypoint file](/registry/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/registry/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. Supply the path to the resulting archive file in the next step. @@ -256,7 +278,7 @@ To update an existing module in the [Viam registry](https://app.viam.com/registr tar -czf module.tar.gz run.sh requirements.txt src ``` - Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. + Where `run.sh` is your [entrypoint file](/registry/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/registry/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module. Supply the path to the resulting archive file in the next step. @@ -353,6 +375,6 @@ For more details, see the [`upload-module` GitHub Action documentation](https:// ## Next Steps {{< cards >}} -{{% card link="/modular-resources/configure/" %}} -{{% card link="/modular-resources/examples/" %}} +{{% card link="/registry/configure/" %}} +{{% card link="/registry/examples/" %}} {{< /cards >}} diff --git a/docs/services/ml/_index.md b/docs/services/ml/_index.md index 1f0e2af53f..faa74c1e70 100644 --- a/docs/services/ml/_index.md +++ b/docs/services/ml/_index.md @@ -16,7 +16,7 @@ Once you have [trained](/manage/ml/train-model/) or [uploaded](/manage/ml/upload You can use the following built-in model: {{< alert title="Note" color="note" >}} -For some models, like the [Triton MLModel](/modular-resources/examples/triton/) for Jetson boards, you can configure the service to use the available CPU or GPU. +For some models, like the [Triton MLModel](/registry/examples/triton/) for Jetson boards, you can configure the service to use the available CPU or GPU. {{< /alert >}} @@ -355,6 +355,6 @@ Configure your `mlmodel classifier`. {{% /manualcard %}} -{{% card link="/modular-resources/examples/tflite-module/" customTitle="Example: TensorFlow Lite Modular Service" %}} +{{% card link="/registry/examples/tflite-module/" customTitle="Example: TensorFlow Lite Modular Service" %}} {{< /cards >}} diff --git a/docs/services/slam/_index.md b/docs/services/slam/_index.md index 9bcab333de..897c05b3eb 100644 --- a/docs/services/slam/_index.md +++ b/docs/services/slam/_index.md @@ -20,7 +20,7 @@ Breaking changes are likely to occur, and occur often. SLAM is an important area of ongoing research in robotics, particularly for mobile applications such as drones, boats, and rovers. The Viam SLAM service supports the integration of SLAM as a service on your robot. -You can conduct SLAM with data collected live by a [RPlidar](/modular-resources/examples/rplidar/) or with LIDAR data you provide in configuration, and easily view the map you build on the **SLAM library** tab of your location's page in the [Viam app](https://app.viam.com): +You can conduct SLAM with data collected live by a [RPlidar](/registry/examples/rplidar/) or with LIDAR data you provide in configuration, and easily view the map you build on the **SLAM library** tab of your location's page in the [Viam app](https://app.viam.com): ![Completed SLAM maps in the SLAM library tab](/services/slam/view-map-page.png) diff --git a/docs/services/slam/cartographer/_index.md b/docs/services/slam/cartographer/_index.md index 48ca19702b..d4c1e34cfe 100644 --- a/docs/services/slam/cartographer/_index.md +++ b/docs/services/slam/cartographer/_index.md @@ -14,7 +14,7 @@ aliases: [The Cartographer Project](https://github.com/cartographer-project) contains a C++ library that performs dense SLAM. To use Cartographer with the Viam {{< glossary_tooltip term_id="slam" text="SLAM" >}} service, you can use the [`cartographer`](https://app.viam.com/module/viam/cartographer) {{< glossary_tooltip term_id="modular-resource" text="modular resource" >}}. -See [Modular resources](/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. +See [Modular resources](/registry/#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-cartographer` GitHub repository](https://github.com/viamrobotics/viam-cartographer). @@ -60,7 +60,7 @@ See Viam's [Pricing](https://www.viam.com/product/pricing) page to understand th - [RPlidar A1 adapter STL](https://github.com/viamrobotics/Rover-VR1/blob/master/CAD/RPIidarA1_adapter.STL) - [RPlidar A3 adapter STL](https://github.com/viamrobotics/Rover-VR1/blob/master/CAD/RPIidarA3_adapter.STL) -- In addition, you must [add the `rplidar` module to your robot](/modular-resources/examples/rplidar/) to support the RPlidar hardware, if you have not done so already. +- In addition, you must [add the `rplidar` module to your robot](/registry/examples/rplidar/) to support the RPlidar hardware, if you have not done so already. {{< alert title="SUPPORT" color="note" >}} @@ -88,7 +88,7 @@ Creating a new map uses an instance of the cartographer module running in the cl 1. Click **Add module**, give your service a name of your choice, then click **Create**. 1. In the resulting `SLAM` service configuration pane, first choose `Create new map` as the **Mapping mode**, then configure the rest of the **Attributes** for that mapping mode: - - **Camera**: Select the `name` of the camera component that you created when you [added the `rplidar` module to your robot](/modular-resources/examples/rplidar/). + - **Camera**: Select the `name` of the camera component that you created when you [added the `rplidar` module to your robot](/registry/examples/rplidar/). Example: "my-rplidar" - Then set a **Data capture rate (Hz)** for it. Example: "5" diff --git a/docs/tutorials/custom/controlling-an-intermode-rover-canbus.md b/docs/tutorials/custom/controlling-an-intermode-rover-canbus.md index 235f1ce97d..189f481f66 100644 --- a/docs/tutorials/custom/controlling-an-intermode-rover-canbus.md +++ b/docs/tutorials/custom/controlling-an-intermode-rover-canbus.md @@ -49,7 +49,7 @@ This tutorial will show how we can both leverage this protocol and abstract it i {{% alert title="Tip" color="tip"%}} Even if you don't have an Intermode rover, many of the other concepts presented here are still relevant to other robotic projects. -While this tutorial can be followed verbatim for the Intermode rover, much of it can be applied to other [base](/components/base/), **CAN bus**, or [modular resource](/modular-resources/)-based projects. +While this tutorial can be followed verbatim for the Intermode rover, much of it can be applied to other [base](/components/base/), **CAN bus**, or [modular resource](/registry/)-based projects. {{% /alert %}} The tutorial uses the following hardware: @@ -114,10 +114,10 @@ If you want to directly configure this modular resource code with your robot, sk ### Create a custom model using the Viam RDK base API The [base](/components/base/) component exposes an API for controlling a mobile robot’s movements. -To use it for the Intermode rover, you must create a new [model](/modular-resources/key-concepts/#models) with its own implementation of each method. +To use it for the Intermode rover, you must create a new [model](/registry/key-concepts/#models) with its own implementation of each method. Both the **API** and **model** of any Viam resource are represented as colon-separated triplets where the first element is a namespace. -Since you will conform to an existing Viam API for [base](/components/base/), the [API](/modular-resources/create/#valid-apis-to-implement-in-your-model) you will use is: +Since you will conform to an existing Viam API for [base](/components/base/), the [API](/registry/create/#valid-apis-to-implement-in-your-model) you will use is: **rdk:component:base** This base model is being created for tutorial purposes only, and will implement only partial functionality for demonstration purposes. @@ -241,7 +241,7 @@ Now the intermode base can receive and execute _SetPower_ commands using the sam ### Leaving some methods unimplemented -In some cases, you may not want to implement specific methods provided by the resource type's [API](/modular-resources/create/#valid-apis-to-implement-in-your-model). +In some cases, you may not want to implement specific methods provided by the resource type's [API](/registry/create/#valid-apis-to-implement-in-your-model). For example, some hardware may not support specific functionality. When you want to leave a method unimplemented you must still create that method, but return an appropriate error message. @@ -305,7 +305,7 @@ Change this to the correct location in `executable_path` when adding the module } ``` -More details about modules and how they work can be found in the [modular resources documentation](/modular-resources/). +More details about modules and how they work can be found in the [modular resources documentation](/registry/). ### Control the rover diff --git a/docs/tutorials/custom/custom-base-dog.md b/docs/tutorials/custom/custom-base-dog.md index ff85df96a1..2bb2d397b6 100644 --- a/docs/tutorials/custom/custom-base-dog.md +++ b/docs/tutorials/custom/custom-base-dog.md @@ -207,7 +207,7 @@ You can also try turning the robot off and on again, and then retrying the proce ## Implement the custom base code -Now that the Freenove server is set up, you will follow the [process for creating modular resources](../../../modular-resources/). +Now that the Freenove server is set up, you will follow the [process for creating modular resources](../../../registry/). You will use [this module creation tool](https://github.com/viam-labs/generator-viam-module) to simplify the process and generate the necessary stub files. Then, you will edit them as necessary to define how each base API method interacts with your robot dog. @@ -334,7 +334,7 @@ Don't forget to save. ### Make your module executable Now that you defined the methods for the custom component, you need to set up an [executable file](https://en.wikipedia.org/wiki/Executable) to run your custom component module. -You can find more information in [the relevant section of the modular resource documentation](/modular-resources/). +You can find more information in [the relevant section of the modular resource documentation](/registry/). Since the command line tool already created a run.sh for you, all you need to do is make that shell script executable by running this command from your robotdog directory: ```sh {class="command-line" data-prompt="$"} diff --git a/docs/viam/_index.md b/docs/viam/_index.md index 12686c3737..deafd853a3 100644 --- a/docs/viam/_index.md +++ b/docs/viam/_index.md @@ -138,9 +138,9 @@ You can also extend Viam to support additional hardware components or software s The Viam registry allows hardware and software engineers to collaborate on their smart machine projects by writing and sharing custom modules with each other. You can add a module from the Viam registry directly from your smart machine'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](/modular-resources/upload/). +You can also [upload your own module to the Viam registry](/registry/upload/). -See [Modular resources](/modular-resources/) for more information. +See [Modular resources](/registry/) for more information. ## Next steps diff --git a/layouts/shortcodes/modular-resources.html b/layouts/shortcodes/modular-resources.html index 9733be548a..77ece378a9 100644 --- a/layouts/shortcodes/modular-resources.html +++ b/layouts/shortcodes/modular-resources.html @@ -1,4 +1,4 @@ -

Search for additional {{.Get "type" }} models that you can add from the Viam Registry: +

Search for additional {{.Get "type" }} models that you can add from the Viam Registry:

For configuration information, click on the model name: