Merge branch 'main' into DOCS-821-Add-Power-Sensor

.github/workflows/lexi-lint.yml

@@ -0,0 +1,23 @@
+name: Report readability
+
+# This action only works on pull request events
+on:
+  pull_request_target:
+    branches: [ main ]
+    types: [ labeled, synchronize ]
+
+jobs:
+    report-readability:
+        if: ${{ contains(github.event.*.labels.*.name, 'safe to build') }}
+        name: Report readability
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v3
+              with:
+                  ref: ${{github.event.pull_request.head.sha}}
+                  fetch-depth: 0
+            - uses: npentrel/[email protected]
+              with:
+                  github-token: ${{ secrets.PR_TOKEN }}
+                  glob: '**/*.md'

.htmltest.yml

@@ -24,6 +24,7 @@ IgnoreURLs:
 - "universal-robots.com"
 - "digikey.com"
 - "ufactory.cc"
+- "medium.com"
 IgnoreDirs:
 - "lib"
 CacheExpires: "6h"

README.md

@@ -2,6 +2,7 @@
 
 > **Note**
 > Looking to contribute? Check out the [Contributor Guide](https://github.com/viamrobotics/docs/blob/main/CONTRIBUTING.md).
+> For help knowing what and how to write, check out our templates: our [tutorial template](docs/tutorials/template/) and [component page template](docs/components/component/) are accessible on the site when building the docs in Draft mode, or accessible here on GitHub.
 
 ## Build the docs locally
 

assets/js/index.js

@@ -154,7 +154,7 @@ docsearch({
         protocol: 'https'
       }],
       apiKey: 'GHQK6od8KfpvTEh4YpA113gUc2dU5fGR'
-    },
+    }
   });
   docsearch({
     inputSelector: '.td-sidebar__search .td-search-input',
@@ -166,5 +166,5 @@ docsearch({
         protocol: 'https'
       }],
       apiKey: 'GHQK6od8KfpvTEh4YpA113gUc2dU5fGR'
-    },
+    }
 });

assets/js/tutorials.js

@@ -216,10 +216,15 @@ search.on('render', function() {
 
 document.body.addEventListener('click', function(event) {
   let filter_box = document.getElementById('tutorial-filter-items');
-    if (!filter_box.contains(event.target)) {
-      open_elem = filter_box.getElementsByClassName("show");
-      if (open_elem) {
-        open_elem[0].classList.remove("show");
-      }
+  let tutorial_menu = document.getElementById('tutorial-menu');
+  if (!filter_box.contains(event.target) && !tutorial_menu.contains(event.target)) {
+    document.querySelectorAll('.filter').forEach( el => {
+      el.setAttribute("aria-expanded", false);
+      el.classList.add("collapsed");
+    });
+    let open_elem = filter_box.getElementsByClassName("show");
+    if (open_elem) {
+      open_elem[0].classList.remove("show");
     }
+  }
 }, true);

assets/scss/_styles_project.scss

@@ -1167,6 +1167,15 @@ ul.sectionlist > li:hover {
   border: 1px solid black;
 }
 
+#tutorial-filters > .filter:hover {
+  background-color: #e7e5e4;
+  cursor: pointer;
+}
+
+#tutorial-filters > .filter[aria-expanded="true"]{
+  background-color: #e7e5e4;
+}
+
 .ais-Hits-item {
   display: flex;
 }
@@ -1298,6 +1307,24 @@ a.ais-Pagination-link:hover {
   flex-grow: 1;
 }
 
+.ds-dataset-1, .ds-dataset-2, .ds-dataset-3 {
+  max-height: 500px !important;
+}
+
+/* Add margin in front of breadcrumbs on small screens */
+@media (max-height: 600px) {
+  .ds-dataset-1, .ds-dataset-2, .ds-dataset-3 {
+    max-height: 300px !important;
+  }
+}
+
+/* Add margin in front of breadcrumbs on small screens */
+@media (max-height: 400px) {
+  .ds-dataset-1, .ds-dataset-2, .ds-dataset-3 {
+    max-height: 200px !important;
+  }
+}
+
 // Search-autocomplete end
 
 // Make videos work without js
@@ -1310,4 +1337,4 @@ a.ais-Pagination-link:hover {
 
 .row.flex-xl-nowrap {
   min-height: 100%;
-}
+}

docs/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Viam Documentation"
 linkTitle: "Viam Documentation"
-description: "Viam is a complete software platform for robots that runs on any 64-bit Linux OS and macOS."
+description: "Viam is a complete software platform for smart machines that runs on any 64-bit Linux OS and macOS."
 weight: 1
 no_list: true
 type: "docs"
@@ -13,7 +13,7 @@ sitemap:
 <div class="max-page">
   <p>
     Welcome to the Viam Documentation!
-    Viam is a complete software platform for robots that runs on Linux and macOS and supports a wide variety of popular systems, including:
+    Viam is a complete software platform for {{< glossary_tooltip term_id="smart-machine" text="smart machines">}} that runs on Linux and macOS and supports a wide variety of popular systems, including:
   </p>
 </div>
 
@@ -136,23 +136,23 @@ sitemap:
       </div>
       <div class="col hover-card landing purple">
         <div>
-          <div>Configure your robots</div>
+          <div>Configure your smart machine</div>
           <div style="text-align: left">
             <ol style="padding-inline-start: 1.1rem">
-              <li><a href="manage/configuration/">Configure your robot</a> or <a href="manage/fleet/">fleet</a></li>
-              <li><a href="installation/">Install Viam on your robot</a></li>
-              <li><a href="components/">Configure robot components</a> and <a href="services/">add services</a></li>
-              <li><a href="manage/fleet/robots/#control">Control and test your robot</a></li>
+              <li>Configure a <a href="manage/configuration/"> machine</a> or a <a href="manage/fleet/">fleet</a></li>
+              <li><a href="installation/">Install Viam on your machine</a></li>
+              <li>Configure <a href="components/">components</a> and <a href="services/">add services</a></li>
+              <li><a href="manage/fleet/robots/#control">Control and test your machine</a></li>
             </ol>
           </div>
         </div>
         {{<gif webm_src="/blink.webm" mp4_src="/blink.mp4" alt="A blinking L.E.D. connected to a Raspberry Pi">}}
       </div>
       <div class="col hover-card landing teal">
         <div>
-          <div>Program your robots</div>
+          <div>Program your machine</div>
           <p style="text-align: left;">
-            Program and control your robots in <a href="program/apis/"> the languages you already know</a> like <a href="https://python.viam.dev/">Python</a>, <a href="https://pkg.go.dev/go.viam.com/rdk">Go</a>, <a href="https://ts.viam.dev/">TypeScript</a>, <a href="https://cpp.viam.dev/" target="_blank">C++</a>, or <a href="https://flutter.viam.dev/" target="_blank">Flutter</a>.
+            Program and control your machines in <a href="program/apis/"> the languages you already know</a> like <a href="https://python.viam.dev/">Python</a>, <a href="https://pkg.go.dev/go.viam.com/rdk">Go</a>, <a href="https://ts.viam.dev/">TypeScript</a>, <a href="https://cpp.viam.dev/" target="_blank">C++</a>, or <a href="https://flutter.viam.dev/" target="_blank">Flutter</a>.
           </p>
         </div>
         <div class="hover-card-img">
@@ -162,7 +162,7 @@ sitemap:
       <div class="col hover-card landing pink">
         <div>
           <div>Community</div>
-          <p style="text-align: left;">Have questions, or want to meet other people working on robots? <a href="https://discord.gg/viam">Join us in the Community Discord!</a></p>
+          <p style="text-align: left;">Have questions, or want to meet other people working on smart machines? <a href="https://discord.gg/viam">Join us in the Community Discord!</a></p>
         </div>
         {{<gif webm_src="/heart.webm" mp4_src="/heart.mp4" alt="A robot drawing a heart">}}
       </div>

docs/appendix/glossary/component.md

@@ -7,3 +7,5 @@ aka:
 ---
 
 A resource that represents a physical component in a robot which a computer controls; for example, a servo, a camera, or an arm.
+
+For more information, see [Components](/components/).

docs/appendix/glossary/fragment.md

@@ -9,4 +9,4 @@ aka:
 A reusable configuration block that you can share across multiple robots.
 For example, if you are deploying a specific mobile robot that is always physically connected the same way, you can create a fragment to make managing your fleet easy.
 
-For more information see [Fragments](../../manage/configuration/#fragments).
+For more information, see [Fragments](../../manage/configuration/#fragments).

docs/appendix/glossary/location.md

@@ -1,11 +1,11 @@
 ---
 title: Location
 id: location
-full_link:
+full_link: /manage/fleet/locations/
 short_description: A location is a virtual grouping of robots that allows you to organize robots and manage access to your fleet.
 aka:
 ---
 
 A location is a virtual grouping of robots that allows you to organize robots and manage access to your fleet.
 
-For more information, see [Fleet Management](/manage/fleet/).
+For more information, see [Manage Locations and Sub-Locations](/manage/fleet/locations/).

docs/appendix/glossary/organization.md

@@ -1,7 +1,7 @@
 ---
 title: Organization
 id: organization
-full_link:
+full_link: /manage/fleet/organizations/
 short_description: An organization is a group of one or more locations that helps you organize your fleet and manage who has access to your fleet.
 aka:
 ---
@@ -10,4 +10,4 @@ An organization is the highest level grouping in the Viam platform, which genera
 Every {{< glossary_tooltip term_id="location" text="location" >}} is grouped into an organization.
 You can also have organizations for departments or other entities, or for personal use.
 
-For more information, see [Fleet Management](/manage/fleet/).
+For more information, see [Manage Organizations](/manage/fleet/organizations/).

docs/appendix/glossary/process.md

@@ -11,3 +11,5 @@ Processes are binaries or scripts that run on a {{< glossary_tooltip term_id="pa
 You can use processes to create a new local instance of `viam-server` to implement drivers for custom {{< glossary_tooltip term_id="component" text="components" >}}, or to run a client application, for example.
 They provide an OS-specific process managed by `viam-server` to either run once or indefinitely.
 For example, you could use a process to run a camera server.
+
+For information on how to configure a process, see [Configure a Robot](/manage/configuration/#processes).

docs/appendix/glossary/remote.md

@@ -8,4 +8,4 @@ aka:
 
 A robot part which is controlled by another robot part.
 
-For more information see [Robot Architecture: Parts, Sub-Parts and Remotes](../../manage/parts-and-remotes/).
+For more information, see [Robot Architecture: Parts, Sub-Parts and Remotes](../../manage/parts-and-remotes/).

docs/appendix/glossary/robot-config.md

@@ -1,11 +1,11 @@
 ---
 title: Robot Config
 id: robot-config
-full_link:
+full_link: /manage/configuration/
 short_description: The complete configuration of a single robot part.
 aka:
 ---
 
 The complete configuration of a single robot {{< glossary_tooltip term_id="part" text="part" >}}.
 
-For more information see [Configuration](../../manage/configuration/).
+For more information, see [Configuration](../../manage/configuration/).

docs/appendix/glossary/robot.md

@@ -1,11 +1,11 @@
 ---
 title: Robot
 id: robot
-full_link: /manage/fleet/#robots
+full_link: /manage/fleet/robots/
 short_description: An organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks.
 aka:
 ---
 
 An organizational concept, consisting of either one *{{< glossary_tooltip term_id="part" text="part" >}}*, or multiple *parts* working closely together to complete tasks.
 
-For more information, see [Robots](../../manage/fleet/#robots).
+For more information, see [Robots](../../manage/fleet/robots/).

docs/appendix/glossary/service.md

@@ -6,4 +6,6 @@ short_description: Built-in software packages for complex capabilities such as S
 aka:
 ---
 
-Services are built-in software packages for complex capabilities such as SLAM, Computer Vision, Motion Planning, and Data Collection.
+Services are built-in software packages for complex capabilities such as SLAM, computer vision, motion planning, and data collection.
+
+For more information, see [Services](/services/).

docs/appendix/glossary/slam.md

@@ -7,3 +7,5 @@ aka:
 ---
 
 Simultaneous Localization and Mapping (SLAM) is an algorithm that allows your robot to create a map of its surroundings and find its location within that map.
+
+For more information, see [SLAM](/services/slam/).

docs/appendix/glossary/smart-machine.md

@@ -0,0 +1,10 @@
+---
+title: Smart Machine
+id: smart-machine
+full_link:
+short_description: A machine or device that lives in the real world and has some ability to perceive the world (with a sensor, for example) and perform actions like operating a motor.
+aka:
+---
+
+A machine or device that lives in the real world and has some ability to perceive the world (with a sensor, for example) and perform actions like operating a motor.
+The machine might also interact with other systems, with the cloud, or with users.

docs/components/arm/_index.md

@@ -60,6 +60,8 @@ Supported arm models include:
 | [`yahboom-dofbot`](yahboom-dofbot/) | [Yahboom DOFBOT](https://category.yahboom.net/collections/r-robotics-arm) |
 | [`ur5e`](ur5e/) | [Universal Robots UR5e](https://www.universal-robots.com/products/ur5-robot) |
 
+Follow [this guide](/extend/modular-resources/examples/custom-arm/) to implement your custom arm as a [modular resource](/extend/modular-resources/).
+
 ## Control your arm with Viam's client SDK libraries
 
 To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated.

docs/components/board/upboard.md

@@ -13,7 +13,7 @@ Configure an `upboard` board to integrate an Intel-based board like the [UP4000]
 
 Complete the following setup requirements, then move on to configuring your board in [the Viam app](https://app.viam.com):
 
-## Set up requirements
+## Setup requirements
 
 Flash your Intel-based board with:
 
@@ -38,10 +38,6 @@ Edit and fill in the attributes as applicable.
 {{% /tab %}}
 {{% tab name="JSON Template" %}}
 
-Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
-Select **Raw JSON** mode and copy and paste the following:
-
 ```json {class="line-numbers linkable-line-numbers"}
 {
   "components": [
@@ -82,9 +78,6 @@ Select **Raw JSON** mode and copy and paste the following:
 {{% /tab %}}
 {{< /tabs >}}
 
-Save the config.
-Edit and fill in the attributes as applicable.
-
 The following attributes are available for `upboard` boards:
 
 | Name | Type | Inclusion | Description |

docs/components/camera/_index.md

@@ -118,7 +118,7 @@ If the server does not know how to return the specified MIME type, the server re
 ```python {class="line-numbers linkable-line-numbers"}
 my_camera = Camera.from_robot(robot=robot, name="my_camera")
 
-frame = await my_cam.get_image()
+frame = await my_camera.get_image()
 ```
 
 <br>
@@ -200,7 +200,7 @@ The multiple images returned from GetImages do not represent a time series of im
 ```python {class="line-numbers linkable-line-numbers"}
 my_camera = Camera.from_robot(robot=robot, name="my_camera")
 
-images, metadata = await my_cam.get_images()
+images, metadata = await my_camera.get_images()
 img0 = images[0].image
 timestamp = metadata.captured_at
 ```
@@ -342,7 +342,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c
 
 Execute model-specific commands that are not otherwise defined by the component API.
 For native models, model-specific commands are covered with each model's documentation.
-If you are implementing your own camera and add features that have no native API method, you can access them with `DoCommand`.
+If you are implementing your own camera and adding features that have no native API method, you can access them with `DoCommand`.
 
 {{< tabs >}}
 {{% tab name="Python" %}}

docs/components/component/model1.md

@@ -17,10 +17,6 @@ Optional additional description/information.
 {{% tab name="Config Builder" %}}
 
 Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
-
-Enter a name for your arm, select the `arm` type, and select the `model1` model.
-
 Click on the **Components** subtab and click **Create component**.
 Select the `arm` type, then select the `model1` model.
 Enter a name for your arm and click **Create**.

docs/components/motor/_index.md

@@ -41,6 +41,15 @@ Model | Description <a name="model-table"></a>
 [`roboclaw`](./roboclaw/) | [Standard brushed DC motor](https://en.wikipedia.org/wiki/DC_motor) driven by [Basicmicro's](https://www.basicmicro.com/) [RoboClaw](https://www.basicmicro.com/RoboClaw-2x30A-Motor-Controller_p_9.html) motor controller
 [`fake`](./fake/) | Used to test code without hardware
 
+Viam also provides the following motor models as [modular resources](/extend/modular-resources/):
+
+ Model | Description
+ ----- | -----------
+ [`viam:odrive:canbus`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with CANbus communication
+ [`viam:odrive:serial`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with serial communication
+
+These modules can be [added to your robot from the Viam registry](/extend/modular-resources/configure/#add-a-module-from-the-viam-registry).
+
 ## Control your motor with Viam's client SDK libraries
 
 To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated.

docs/components/movement-sensor/adxl345.md

@@ -17,10 +17,9 @@ If you are using a [Viam Rover](https://docs.viam.com/try-viam/), this is the ac
 {{% tab name="Config Builder" %}}
 
 Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
-Enter a name for your movement sensor, select the `movement-sensor` type, and select the `accel-adxl345` model.
-
-Click **Create Component**
+Click on the **Components** subtab and click **Create component**.
+Select the `movement-sensor` type, then select the `accel-adxl345` model.
+Enter a name for your movement sensor and click **Create**.
 
 {{< imgproc src="/components/movement-sensor/adxl345-builder.png" alt="Creation of an `accel-adxl345` movement sensor in the Viam app config builder." resize="600x" >}}