DOCS-1080: Add a local module (#1815)

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"

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 <path-to-your-module-directory>/<your-module>
-```
+   ``` shell
+   sudo chmod a+rx <path-to-your-module-executable>
+   ```
+
+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.
+
+   {{<imgproc src="extend/modular-resources/configure/add-local-module-list.png" resize="300x" declaredimensions=true alt="The add a component modal showing the list of components to add with 'local modular resource' shown at the bottom">}}
+
+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.
+
+   {{<imgproc src="extend/modular-resources/configure/add-local-module-create.png" resize="400x" declaredimensions=true alt="The add a component modal showing the create a module step for an intel realsense module">}}
+
+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**.
+
+   {{<imgproc src="extend/modular-resources/configure/add-local-module-csi-cam.png" resize="600x" declaredimensions=true alt="The add a local module pane with name 'my-csi-ca' and executable path '/usr/local/bin/viam-csi'">}}
+
+   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" >}}
+{{<imgproc src="extend/modular-resources/configure/add-local-module-config-builder.png" resize="600x" declaredimensions=true alt="The add a local module pane with an example name and executable path">}}
 
 {{% /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:
 

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.
 

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

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.