Merge branch 'main' into DOCS-1029-add-sensor-control-view

.github/workflows/lexi-lint.yml

@@ -17,7 +17,7 @@ jobs:
               with:
                   ref: ${{github.event.pull_request.head.sha}}
                   fetch-depth: 0
-            - uses: npentrel/lexi@v1.1
+            - uses: Rebilly/lexi@v2
               with:
                   github-token: ${{ secrets.PR_TOKEN }}
                   glob: '**/*.md'

docs/components/arm/_index.md

@@ -49,7 +49,7 @@ Arm drivers are also paired, in the RDK, with JSON files that describe the kinem
 
 ## Configuration
 
-Supported arm models include:
+For configuration information, click on one of the supported arm models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/base/_index.md

@@ -28,7 +28,7 @@ Most mobile robots with a base need at least the following hardware:
 
 ## Configuration
 
-Supported base models include:
+For configuration information, click on one of the supported base models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/camera/_index.md

@@ -33,7 +33,7 @@ You can use different models to:
 
 ## Configuration
 
-For configuration information, click on one of the following models:
+For configuration information, click on one of the supported camera models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/encoder/_index.md

@@ -33,11 +33,7 @@ Most robots with an encoder need at least the following hardware:
 
 ## Configuration
 
-To configure an encoder as a component of your robot, first configure the [board](/components/board/) controlling the encoder.
-If you are configuring an encoded motor, you must also configure the [motor](/components/motor/) first.
-
-The configuration of your encoder component depends on your encoder model.
-For configuration information, click on one of the following models:
+For configuration information, click on one of the supported encoder models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/gantry/_index.md

@@ -36,7 +36,7 @@ Most robots with a gantry need at least the following hardware:
 
 ## Configuration
 
-Supported gantry models include:
+For configuration information, click on one of the supported gantry models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/gantry/single-axis.md

@@ -11,7 +11,8 @@ aliases:
 # SME: Rand, Martha
 ---
 
-Configure a `single-axis` gantry to integrate a single-axis gantry into your robot:
+Configure a `single-axis` gantry to integrate a single-axis gantry into your robot.
+Before configuring the gantry, configure any [motor components](/components/motor/) that are part of the gantry.
 
 {{< tabs >}}
 {{% tab name="Config Builder" %}}

docs/components/movement-sensor/adxl345.md

@@ -131,3 +131,5 @@ Name | Type | Inclusion | Default Value | Description
 `interrupt_pin` | string | **Required** | The `name` of the [digital interrupt](/components/board/#digital_interrupts) you configured for the pin on the [board](/components/board/) wired to the `accelerometer_pin`.
 `threshold` | float | Optional | The acceleration on each axis is compared with this value to determine if a free-fall event occurred (in milligrams, between 0 and 15,937). <br> Default: `437.5`
 `time_ms` | float | Optional | Unsigned time value representing the minimum time that the value of all axes must be less than `threshold` to generate a free-fall interrupt (in milliseconds, between 0 and 1,275). <br> Default: `160`
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/cameramono.md

@@ -96,3 +96,5 @@ Name | Type | Inclusion | Description
 ---- | ---- | --------- | -----------
 `camera` | string | **Required** | The `name` of the [camera](/components/camera/) you want to use for visual odometry.
 `motion_estimation_config` | object | **Required** | See [motionestimation.go in RDK](https://github.com/viamrobotics/rdk/blob/99f62a1640f4c267b744bdfc2924e9fd4f7a3c60/vision/odometry/motionestimation.go).
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/fake.md

@@ -59,3 +59,5 @@ Edit and fill in the attributes as applicable.
 
 {{% /tab %}}
 {{< /tabs >}}
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/gps/gps-nmea-rtk-pmtk.md

@@ -121,3 +121,5 @@ You will need to research the options available to you.
 If you are not sure where to start, check out this [GPS-RTK2 Hookup Guide from SparkFun](https://learn.sparkfun.com/tutorials/gps-rtk2-hookup-guide/connecting-the-zed-f9p-to-a-correction-source).
 
 {{% /alert %}}
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/gps/gps-nmea-rtk-serial.md

@@ -119,3 +119,5 @@ You will need to research the options available to you.
 If you are not sure where to start, check out this [GPS-RTK2 Hookup Guide from SparkFun](https://learn.sparkfun.com/tutorials/gps-rtk2-hookup-guide/connecting-the-zed-f9p-to-a-correction-source).
 
 {{% /alert %}}
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/gps/gps-nmea.md

@@ -156,3 +156,5 @@ Name | Type | Inclusion | Description
 
 {{% /tab %}}
 {{< /tabs >}}
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/imu/imu-vectornav.md

@@ -83,3 +83,5 @@ Name | Type | Inclusion | Description |
 `chip_select_pin` | string | **Required** | The ({{< glossary_tooltip term_id="pin-number" text="pin number" >}}) of the pin on the board (other than the SPI bus pins) connected to the IMU chip. Used to tell the chip whether the current SPI message is meant for it or for another device.
 `spi_baud_rate` | int | **Required** | The rate at which data is sent from the IMU. <br> Default: `115200`
 `polling_frequency_hz` | int | **Required** | How many times per second the sensor is polled.
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/imu/imu-wit.md

@@ -84,3 +84,5 @@ Name | Type | Inclusion | Description
 ---- | ---- | --------- | -----------
 `serial_path` | string | **Required** | The full filesystem path to the serial device, starting with <file>/dev/</file>. With your serial device connected, you can run `sudo dmesg \| grep tty` to show relevant device connection log messages, and then match the returned device name, such as `ttyS0`, to its device file, such as <file>/dev/ttyS0</file>. If you omit this attribute, Viam will attempt to automatically detect the path.
 `serial_baud_rate` | int | Optional | The rate at which data is sent from the sensor over the serial connection. Valid rates are `9600` and `115200`. The default rate will work for all models. *Only the HWT901B can have a different serial baud rate.* Refer to your model's data sheet. <br>Default: `115200`
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/merged.md

@@ -101,3 +101,5 @@ Name | Type | Inclusion | Description
 Note that only one sensor from each array can be used to retrieve each type of reading.
 Your robot uses the first sensor in the array that has implemented the relevant API method in its model and does not raise an error at runtime.
 For instance, in the **JSON Example** above, if both `"vectornav"` and `"mpu6050"` support returning `angular_velocity`, `"mpu6050"` is only used to read angular velocity on the robot if `"vectornav"` returns an error at runtime.
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/mpu6050.md

@@ -86,3 +86,5 @@ Name | Type | Inclusion | Description
 `board` | string | **Required** | The `name` of the [board](/components/board/) to which the device is wired.
 `i2c_bus` | string | **Required** | The `name` of the [I<sup>2</sup>C bus configured](/components/board/#i2cs) on your [board](/components/board/) wired to this device.
 `use_alt_i2c_address` | boolean | **Required** | Depends on whether you wire AD0 low (leaving the default address of 0x68) or high (making the address 0x69). If high, set `true`. If low, set `false`. <br> Default: `false`
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/viam-visual-odometry.md

@@ -251,3 +251,5 @@ The following attributes are available to configure the `viam-visual-odometry` m
 | `ransac_threshold_px` | float | Optional | `0.5` | Maximum error to be classified as an inlier.|
 
 See the [ORB openCV documentation](https://docs.opencv.org/3.4/db/d95/classcv_1_1ORB.html) for more details.
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/movement-sensor/wheeled-odometry.md

@@ -61,3 +61,5 @@ The following attributes are available for `wheeled-odometry` movement sensors:
 | `left_motors` | object | **Required** | A list containing the name of each of the bases' left [position-reporting motors](/components/motor/gpio/). |
 | `right_motors` | object | **Required** | A list containing the name of each of the bases' right [position-reporting motors](/components/motor/gpio/). |
 | `time_interval_msec` | number | Optional | The time in milliseconds between each wheeled odometry calculation.<br>Default: `500.0`</br> |
+
+{{< readfile "/static/include/components/movement-sensor-control.md" >}}

docs/components/sensor/_index.md

@@ -31,7 +31,7 @@ Most robots with a sensor need at least the following hardware:
 
 ## Configuration
 
-Supported sensor models include:
+For configuration information, click on one of the supported sensor models:
 
 | Model | Description |
 | ----- | ----------- |

docs/components/servo/_index.md

@@ -40,7 +40,7 @@ Check your device's data sheet and configure that type of servo as an [encoded m
 
 {{% /alert %}}
 
-Supported servo models include:
+For configuration information, click on one of the supported servo models:
 
 | Model | Description |
 | ----- | ----------- |

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"
@@ -35,7 +35,7 @@ Once the module has been uploaded to the Registry, you can [deploy the module](/
 ### Uploading to Viam Registry
 
 After you finish programming your module, you can [upload your module to the Viam registry](/extend/modular-resources/upload/) to make it available for deployment to robots.
-As part of the upload process, you decide whether your module is *public* (visible to all users) or *private* (visible only to other members of your [organization](/manage/fleet/organizations/)).
+As part of the upload process, you decide whether your module is *private* (visible only to other members of your [organization](/manage/fleet/organizations/)), or *public* (visible to all Viam users).
 
 You can see details about each module in the [Viam registry](https://app.viam.com/registry) on its module details page.
 See the [Odrive module](https://app.viam.com/module/viam/odrive) for an example.
@@ -47,7 +47,8 @@ When you make changes to your module, you can [uploaded the newer version](/exte
 
 Once you [upload a module to the Viam registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/).
 Navigate to your robot's **Configuration** tab, click the **+ Create component** button, then start typing the name of the module you would like to deploy.
-If you uploaded your module and set its visibility to private, the module will only appear for users within your [organization](/manage/fleet/organizations/).
+
+By default, a newly-created module is *private*, meaning that the module will only appear for users within your [organization](/manage/fleet/organizations/), but you can later [update your module](/extend/modular-resources/upload/#update-an-existing-module) to set it to be *public*, which makes your module available to all Viam users.
 
 When you deploy a module to your robot, you can [choose how to update that module](/extend/modular-resources/configure/#configure-version-update-management-for-a-registry-module) when new versions become available.
 

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: