diff --git a/assets/extend/modular-resources/configure/add-local-module-config-builder.png b/assets/extend/modular-resources/configure/add-local-module-config-builder.png new file mode 100644 index 0000000000..8c601b831d Binary files /dev/null and b/assets/extend/modular-resources/configure/add-local-module-config-builder.png differ diff --git a/assets/extend/modular-resources/configure/add-local-module-create.png b/assets/extend/modular-resources/configure/add-local-module-create.png new file mode 100644 index 0000000000..b5bec51e17 Binary files /dev/null and b/assets/extend/modular-resources/configure/add-local-module-create.png differ diff --git a/assets/extend/modular-resources/configure/add-local-module-csi-cam.png b/assets/extend/modular-resources/configure/add-local-module-csi-cam.png new file mode 100644 index 0000000000..7476aeea4a Binary files /dev/null and b/assets/extend/modular-resources/configure/add-local-module-csi-cam.png differ diff --git a/assets/extend/modular-resources/configure/add-local-module-list.png b/assets/extend/modular-resources/configure/add-local-module-list.png new file mode 100644 index 0000000000..3de8f61394 Binary files /dev/null and b/assets/extend/modular-resources/configure/add-local-module-list.png differ diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 2c69031b72..f26f666ea3 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -1,5 +1,5 @@ --- -title: "Integrate Modular Resources into your Robot" +title: "Extend Viam with Modular Resources" linkTitle: "Modular Resources" weight: 10 type: "docs" diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 0825ed7547..8444d317a8 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -9,7 +9,8 @@ no_list: true --- You can extend Viam by adding a module on your robot that provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} ([components](/components/) or [services](/services/)). -You can [add a module from the Viam registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). + +You can [add a module from the Viam registry](#add-a-module-from-the-viam-registry), or you can [add a local module](#local-modules). See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concepts/) for more information. @@ -199,46 +200,89 @@ The custom model is configured as a component with the name "my-realsense". {{% /tab %}} {{% /tabs %}} -## Add a local module to your robot +## Local modules -If you are developing your own modular resource, and intend to deploy it to your robot locally, first follow [these steps](/extend/modular-resources/create/) to code your own module and generate an executable. -If you are using a pre-built modular resource, make sure you install the module and determine the filename of [the module's executable](/extend/modular-resources/create/#compile-the-module-into-an-executable). +If you wish to add a module to your robot without uploading it to the Viam registry, you can add your module as a *local module*. -Follow these steps to configure a module and its modular resources locally: +You can add your own custom modules as local modules, or you can add pre-built modules written by other Viam users. -1. [Save the executable](#make-sure-viam-server-can-access-your-executable) in a location your `viam-server` instance can access. -2. [Add a **module**](#configure-your-module) referencing this executable to the configuration of your robot. -3. [Add a new component or service](#configure-your-modular-resource) referencing the modular resource provided by the configured **module** to the configuration of your robot. +### Prepare a local module -### Make sure `viam-server` can access your executable +First determine the module you wish to add as a local module: -Ensure that your module executable is saved where the instance of `viam-server` behind your robot can read and execute it. +- If you are adding your own custom module, be sure that you have followed the steps to [create your own module](/extend/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](/extend/modular-resources/create/#compile-the-module-into-an-executable). -For example, if you are running `viam-server` on an Raspberry Pi, you'll need to save the module on the Pi's filesystem. +Then, ensure that `viam-server` is able to find and run the executable: -Obtain the real (absolute) path to the executable file on your computer's filesystem by running the following command in your terminal: +- Ensure that the module executable is saved to a location on the filesystem of your robot that `viam-server` can access. + For example, if you are running `viam-server` on an Raspberry Pi, you must save the module executable on the Pi's filesystem. +- Ensure that this file is executable (runnable) with the following command: -``` shell -realpath / -``` + ``` shell + sudo chmod a+rx + ``` + +See the instructions to [compile your module into an executable](/extend/modular-resources/create/#compile-the-module-into-an-executable) for more information. + +### Add a local module + +To add a local module on your robot: + +1. Navigate to the **Config** tab of your robot's page on [the Viam app](https://app.viam.com). + - If you are adding a modular [component](/components/), click the **Components** subtab and click **Create component**. + - If you are adding a modular [service](/services/), click the **Services** subtab and click **Create service**. + +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](/extend/modular-resources/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. -### Configure your module +You can also add the module directly, without first adding its modular component or service: -To configure your new *module* on your robot, navigate to the **Config** tab of your robot's page on [the Viam app](https://app.viam.com) and click on the **Modules** subtab. +1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). +1. Click on the **Modules** subtab. +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](/extend/modular-resources/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](/extend/modular-resources/examples/csi/) as a local module. + +## Configure a local module + +Once you have added a modular resource to your robot, you can view and configure the module itself from the **Modules** subtab: + +1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). +1. Click on the **Modules** subtab. + Local modules you have added to your robot appear under the **Local** section. The following properties are available for modules: | Name | Type | Inclusion | Description | | ---- | ---- | --------- | ----------- | `name` | string | **Required**| Name of the module you are registering. | -`executable_path` | string | **Required**| The robot's computer's filesystem path to the module executable. | +`executable_path` | string | **Required**| The absolute path to the executable on your robot's filesystem. | Add these properties to your module's configuration: {{< tabs >}} {{% tab name="Config Builder" %}} -{{< imgproc src="/program/modular-resources/module-ui-config.png" alt="Creation of a new module in the Viam app config builder." resize="1000x" >}} +{{}} {{% /tab %}} {{% tab name="JSON Template" %}} @@ -257,9 +301,9 @@ Add these properties to your module's configuration: {{% /tab %}} {{% /tabs %}} -### Configure your modular resource +### Configure a modular resource -Once you have configured a module as part of your robot configuration, you can add any number of the resources that the module makes available to your robot by adding new components or services configured with your modular resources' [model](/extend/modular-resources/key-concepts/#models). +Once you have 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 resources' [model](/extend/modular-resources/key-concepts/#models). The following properties are available for modular resources: diff --git a/docs/extend/modular-resources/create/_index.md b/docs/extend/modular-resources/create/_index.md index dd73c9fbe5..79af668231 100644 --- a/docs/extend/modular-resources/create/_index.md +++ b/docs/extend/modular-resources/create/_index.md @@ -15,7 +15,7 @@ A common use case for modular resources is to create a new [model](/extend/modul Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/extend/modular-resources/upload/) to the [Viam registry](https://app.viam.com/registry), to share it with other Viam users or just to other users in your organization. You can also configure [automatic uploads of new versions of your module](/extend/modular-resources/upload/#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action. -Alternatively, you can add your module locally to your robot without uploading to the Viam registry. +You can also add your module to your robot as a [local module](/extend/modular-resources/configure/#local-modules), without uploading it to the Viam registry. ## Create a custom module @@ -468,7 +468,7 @@ Otherwise, the class won’t instantiate. ### Compile the module into an executable -To [add a module](/extend/modular-resources/configure/#configure-your-module) 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](/extend/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. Your options for completing this step are flexible, as this file does not need to be in a raw binary format. diff --git a/docs/extend/modular-resources/examples/csi.md b/docs/extend/modular-resources/examples/csi.md index 78fe6d6042..f9adeeb262 100644 --- a/docs/extend/modular-resources/examples/csi.md +++ b/docs/extend/modular-resources/examples/csi.md @@ -123,6 +123,8 @@ Next, add the following JSON object to your components array to configure a `csi {{% /tab %}} {{< /tabs >}} +For more information, see [installing local modules](/extend/modular-resources/configure/#local-modules). + Edit and fill in the attributes to configure your component. The following attributes are available for the `viam:camera:csi` model: @@ -138,3 +140,5 @@ The following attributes are available for the `viam:camera:csi` model: Then, save the config. Check the [**Logs** tab](/program/debug/) of your robot in the Viam app to make sure your camera has connected and no errors are being raised. + +For more information, see [installing local modules](/extend/modular-resources/configure/#local-modules). diff --git a/docs/extend/modular-resources/examples/custom-arm.md b/docs/extend/modular-resources/examples/custom-arm.md index fdf6809366..ff60ee01dd 100644 --- a/docs/extend/modular-resources/examples/custom-arm.md +++ b/docs/extend/modular-resources/examples/custom-arm.md @@ -218,7 +218,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](/extend/modular-resources/configure/#configure-your-module) 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](/extend/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. Your options for completing this step are flexible, as this file does not need to be in a raw binary format.