JT edits pt 2

docs/dev/reference/apis/components/arm.md

@@ -3,14 +3,15 @@ title: "Arm API"
 linkTitle: "Arm"
 weight: 10
 type: "docs"
-description: "Give commands to your arm components for linear motion planning, including self-collision prevention and obstacle avoidance."
+description: "Give commands to your arm components for linear motion planning."
 icon: true
 images: ["/icons/components/arm.svg"]
 date: "2022-01-01"
 # updated: ""  # When the content was last entirely checked
 ---
 
-The arm API allows you to give commands to your [arm components](/components/arm/) for linear motion planning, including self-collision prevention and obstacle avoidance.
+The arm API allows you to give commands to your [arm components](/components/arm/) for linear motion planning with self-collision prevention.
+If you want the arm to avoid obstacles, or you want to plan complex motion in an automated way, use the [motion API](/dev/reference/apis/services/motion/).
 
 The arm component supports the following methods:
 

docs/dev/reference/apis/services/motion.md

@@ -3,14 +3,14 @@ title: "Motion Service API"
 linkTitle: "Motion"
 weight: 40
 type: "docs"
-description: "Give commands to move a machine based on a SLAM map or GPS coordinates or to move a machine's components form one location to another."
+description: "Give commands to move a machine's components from one location or pose to another."
 icon: true
 images: ["/icons/components/arm.svg"]
 date: "2022-01-01"
 # updated: ""  # When the content was last entirely checked
 ---
 
-The motion service API allows you to give commands to your [motion service](/services/motion/) for moving a machine based on a SLAM map or GPS coordinates or for moving a machine's components from one location to another.
+The motion service API allows you to give commands to your [motion service](/services/motion/) for moving a mobile robot based on a SLAM map or GPS coordinates or for moving a machine's components from one pose to another.
 
 The motion service supports the following methods:
 

docs/operate/_index.md

@@ -41,7 +41,10 @@ overview: true
 {{< cards >}}
 {{% card link="/operate/mobility/define-geometry/" noimage="true" %}}
 {{% card link="/operate/mobility/define-obstacles/" noimage="true" %}}
-{{% card link="/operate/mobility/define-dynamic-obstacles/" noimage="true" %}}
+
+<!-- unlisting for now
+{{% card link="/operate/mobility/define-dynamic-obstacles/" noimage="true" %}}-->
+
 {{% card link="/operate/mobility/move-base/" noimage="true" %}}
 {{% card link="/operate/mobility/move-arm/" noimage="true" %}}
 {{% card link="/operate/mobility/move-gantry/" noimage="true" %}}

docs/operate/control/headless-app.md

@@ -25,7 +25,7 @@ You can run your code directly on the machine's single-board computer (SBC), or
 
 ### On a separate computer
 
-We recommend running your script on a laptop, desktop, or server if:
+We recommend running your code on a laptop, desktop, or server if:
 
 - You are using computationally-intensive programs involving, for example, computer vision or motion planning, and
 - You have a stable internet connection
@@ -34,7 +34,7 @@ The client code will establish a connection to the instance of `viam-server` on
 
 ### On the machine itself
 
-We recommend running your script on the SBC that directly controls your hardware if:
+We recommend running your code on the SBC that directly controls your hardware if:
 
 - Your machines have intermittent or no network connectivity, or
 - You want to reduce latency, for example for running [PID control loops](https://en.wikipedia.org/wiki/Proportional%E2%80%93integral%E2%80%93derivative_controller), or
@@ -93,7 +93,7 @@ You can use the toggle to include the machine API key and API key ID, though we
 
 If your code will connect to multiple machines or use [Platform APIs](/dev/reference/apis/#platform-apis) you can create an API key with broader access.
 
-## Write your control script
+## Write your control code
 
 For API reference including code snippets for each method, see [Viam's Client APIs](/dev/reference/apis/).
 
@@ -335,13 +335,13 @@ if __name__ == '__main__':
 
 {{< /expand >}}
 
-## Run your script
+## Run your code
 
-You can run your script manually from your terminal, or you can automatically run it each time your machine starts.
+You can run your code manually from your terminal, or you can automatically run it each time your machine starts.
 
-### Run your script manually
+### Run your code manually
 
-To run your script on a laptop or desktop, or to run it on your machine's SBC manually for testing purposes, execute the following command in a terminal:
+To run your code on a laptop or desktop, or to run it on your machine's SBC manually for testing purposes, execute the following command in a terminal:
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -365,13 +365,13 @@ For information on running C++ code see [the instructions on GitHub](https://git
 {{% /tab %}}
 {{< /tabs >}}
 
-### Run your script as an automatic process
+### Run your code as an automatic process
 
-If you want your script to run each time your machine boots, configure the script as a _{{< glossary_tooltip term_id="process" text="process" >}}_ on your machine.
+If you want your code to run each time your machine boots, configure the code as a _{{< glossary_tooltip term_id="process" text="process" >}}_ on your machine.
 Configured processes are managed by `viam-server` and are a way to run any specified command either once on boot or continuously over the lifecycle of `viam-server`.
 
 {{% alert title="Tip" color="tip" %}}
-If you are running your code from a laptop or desktop, we do not recommend configuring your script to run as a process because doing so will cause the process to run whenever you boot your computer, even when you are using your computer for unrelated purposes.
+If you are running your code from a laptop or desktop, we do not recommend configuring your code to run as a process because doing so will cause the process to run whenever you boot your computer, even when you are using your computer for unrelated purposes.
 {{% /alert %}}
 
 To configure a process, click the **+** button on your machine's **CONFIGURE** tab and select **Process**.

docs/operate/control/mobile-app/_index.md → docs/operate/control/mobile-app.md

@@ -38,7 +38,7 @@ Refer to the [Viam Flutter SDK](https://flutter.viam.dev/) documentation for ava
 
 ### Example usage
 
-The following code, part of [Drive a rover in a square in 2 minutes](/how-tos/drive-rover/), shows how you could move a robotic rover base in a square using the base API's [`moveStraight`](https://flutter.viam.dev/viam_sdk/Base/moveStraight.html) and [`spin`](https://flutter.viam.dev/viam_sdk/Base/spin.html) methods:
+The following code, part of [Drive a rover in a square in 2 minutes](/tutorials/control/drive-rover/), shows how you could move a robotic rover base in a square using the base API's [`moveStraight`](https://flutter.viam.dev/viam_sdk/Base/moveStraight.html) and [`spin`](https://flutter.viam.dev/viam_sdk/Base/spin.html) methods:
 
 ```dart {class="line-numbers linkable-line-numbers"}
 import 'package:flutter/material.dart';
@@ -78,7 +78,7 @@ class BaseScreen extends StatelessWidget {
 See the guide for full code and instructions to get started by building a simple app to control a rented Viam rover:
 
 {{< cards >}}
-{{% card link="/operate/control/mobile-app/drive-rover/" %}}
+{{% card link="/tutorials/control/drive-rover/" %}}
 {{< /cards >}}
 
 For a more in-depth guide with more screens, see the following guide:

docs/operate/get-started/other-hardware/_index.md

@@ -100,8 +100,8 @@ Authenticate your CLI session with Viam using one of the following options:
 | Namespace/Organization ID | In the [Viam app](https://app.viam.com), navigate to your organization settings through the menu in upper right corner of the page. Find the **Public namespace** and copy that string. |
 | Resource to add to the module (API) | The [component API](/appendix/apis/#component-apis) your module will implement. |
 | Model name | Name your component model based on what it supports, for example, if it supports a model of ultrasonic sensor called “XYZ Sensor 1234” you could call your model `xyz_1234` or similar. Must be all-lowercase and use only alphanumeric characters (`a-z` and `0-9`), hyphens (`-`), and underscores (`_`). |
-| Enable cloud build | You can select `No` if you will always build the module yourself before uploading it. If you select `Yes` and push the generated files (including the <file>.github</file> folder) and create a release of the format `vX.X.X`, the module will build and upload to the Viam registry and be available for all Viam-supported architectures without you needing to build for each architecture. |
-| Register module | Select `Yes` unless you are creating a local-only module for testing purposes and do not intend to upload it. |
+| Enable cloud build | If you select `Yes` (recommended) and push the generated files (including the <file>.github</file> folder) and create a release of the format `vX.X.X`, the module will build and upload to the Viam registry and be available for all Viam-supported architectures without you needing to build for each architecture. `Yes` also makes it easier to [upload](#upload-your-module) using PyInstaller by creating a build entrypoint script. You can select `No` if you will always build the module yourself before uploading it. |
+| Register module | Select `Yes` unless you are creating a local-only module for testing purposes and do not intend to upload it. If you decline to register the module at this point, you can run [`viam module create`](/dev/tools/cli/#module) to register it later. |
 
 {{< /expand >}}
 
@@ -535,7 +535,24 @@ Make sure to physically connect your sensor to your machine's computer to prepar
 **1. Prepare to run your module**
 
 {{< tabs >}}
-{{% tab name="Python" %}}
+{{% tab name="Python: pyinstaller (recommended)" %}}
+{{% alert title="Note" color="note" %}}
+To follow these PyInstaller packaging steps, you must have enabled cloud build when moving through the module generator prompts.
+If you did not, you will need to manually create a <file>build.sh</file> entrypoint script.
+{{% /alert %}}
+
+From within the <file>hello-world</file> directory, create a virtual Python environment with the necessary packages and then build an executable by running the setup and build scripts:
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+sh setup.sh
+sh build.sh
+```
+
+This environment is where the local module will run.
+`viam-server` does not need to run inside this environment.
+
+{{% /tab %}}
+{{% tab name="Python: venv" %}}
 
 Create a virtual Python environment with the necessary packages by running the setup file from within the <file>hello-world</file> directory:
 
@@ -566,7 +583,26 @@ make build
 On your machine's **CONFIGURE** tab in the [Viam app](https://app.viam.com), click the **+** (create) icon in the left-hand menu.
 Select **Local module**, then **Local module**.
 
-Type in the _absolute_ path on your machine's filesystem to your module's executable file, for example <file>/Users/jessamy/my-python-sensor-module/run.sh</file> or <file>/Users/artoo/my-go-module/main.go</file>.
+Type in the _absolute_ path on your machine's filesystem to your module's executable file, for example:
+
+{{< tabs >}}
+{{% tab name="Python: pyinstaller (recommended)" %}}
+
+<file>Users/jessamy/my-python-sensor-module/dist/main</file>
+
+{{% /tab %}}
+{{% tab name="Python: venv" %}}
+
+<file>/Users/jessamy/my-python-sensor-module/run.sh</file>
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+<file>/Users/artoo/my-go-module/main.go</file>
+
+{{% /tab %}}
+{{< /tabs >}}
+
 Click **Create**.
 
 {{% /tablestep %}}
@@ -595,15 +631,34 @@ For example, if you created a sensor component, check whether readings are displ
 
 {{<imgproc src="/how-tos/sensor-test.png" resize="x1100" declaredimensions=true alt="The test section of an example modular sensor, with readings displayed." style="max-width:600px" >}}
 
-If it works, you're almost ready to share your module by uploading it to the registry.
+{{% /tablestep %}}
+{{% tablestep %}}
+**4. Iterate**
+
+If your component works, you're almost ready to share your module by uploading it to the registry.
 If not, you have some debugging to do.
+
+Each time you make changes to your local module, you need to rebuild the module and then restart its instance on your machine.
+Run the following command to rebuild it:
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+viam module build local
+```
+
+Then restart it in your machine's **CONFIGURE** tab in the Viam app.
+In upper right corner of the module's card, click the three dot (**...**) icon, then click **Restart**.
+
+{{<imgproc src="/registry/restart-module.png" resize="x600" declaredimensions=true alt="Module menu." style="max-width:300px" >}}
+
 For help, don't hesitate to reach out on the [Community Discord](https://discord.gg/viam).
 
 {{% /tablestep %}}
 {{< /table >}}
 
 ## Upload your module
 
+Once you are done testing locally, you can upload your module to the [Viam Registry](https://app.viam.com/registry) and make it available either to all machines in your organization, or to the general public.
+
 {{< table >}}
 {{% tablestep %}}
 **1. Create a README (optional)**
@@ -752,7 +807,54 @@ Do not change the <code>module_id</code>.</p>
 To package (for Python) and upload your module and make it available to configure on machines in your organization (or in any organization, depending on how you set `visibility` in the <file>meta.json</file> file):
 
 {{< tabs >}}
-{{% tab name="Python" %}}
+{{% tab name="Python: pyinstaller (recommended)" %}}
+
+The recommended approach for Python is to use [PyInstaller](https://pypi.org/project/pyinstaller/) to compile your module into a packaged executable: a standalone file containing your program, the Python interpreter, and all of its dependencies.
+When packaged in this fashion, you can run the resulting executable on your desired target platform or platforms without needing to install additional software or manage dependencies manually.
+
+{{% alert title="Note" color="note" %}}
+To follow these PyInstaller packaging steps, you must have enabled cloud build when moving through the module generator prompts.
+{{% /alert %}}
+
+The <file>build.sh</file> script packaged a tarball for you when you ran it before [testing](#test-your-module-locally).
+
+Run the `viam module upload` CLI command to upload the module to the registry, replacing `any` with one or more of `linux/any` or `darwin/any` if your module requires Linux OS-level support or macOS OS-level support, respectively.
+If your module does not require OS-level support (such as platform-specific dependencies), you can run the following command exactly:
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+viam module upload --version 1.0.0 --platform any module.tar.gz
+```
+
+For details on platform support, see [Using the `--platform` argument](/cli/#using-the---platform-argument).
+
+For details about versioning, see [Module versioning](/operate/get-started/supported-hardware/#module-versioning).
+
+{{% alert title="Important" color="note" %}}
+The `viam module upload` command only supports one `platform` argument at a time.
+If you would like to upload your module with support for multiple platforms, you must run a separate `viam module upload` command for each platform.
+Use the _same version number_ when running multiple `upload` commands of the same module code if only the `platform` support differs.
+The Viam Registry page for your module displays the platforms your module supports for each version you have uploaded.
+{{% /alert %}}
+
+We recommend you use PyInstaller with the [`build-action` GitHub action](https://github.com/viamrobotics/build-action) which provides a simple cross-platform build setup for multiple platforms: x86 and Arm Linux distributions, and MacOS.
+See [Update an existing module using a GitHub action](/how-tos/manage-modules/#update-an-existing-module-using-a-github-action) for more information.
+
+{{% alert title="Note" color="note" %}}
+
+PyInstaller does not support relative imports in entrypoints (imports starting with `.`).
+If you get `"ImportError: attempted relative import with no known parent package"`, set up a stub entrypoint as described on [GitHub](https://github.com/pyinstaller/pyinstaller/issues/2560).
+
+In addition, PyInstaller does not support cross-compiling: you must compile your module on the target architecture you wish to support.
+For example, you cannot run a module on a Linux `arm64` system if you compiled it using PyInstaller on a Linux `amd64` system.
+Viam makes this easy to manage by providing a build system for modules.
+Follow [these instructions](/cli/#using-the-build-subcommand) to automatically build for each system your module can support using Viam's [CLI](/cli/).
+
+{{% /alert %}}
+
+{{% /tab %}}
+{{% tab name="Python: venv" %}}
+
+You can use the following package and upload method if you opted not to enable cloud build when you ran `viam module generate`.
 
 1.  To package the module as an archive, run the following command from inside the module directory:
 

docs/operate/get-started/other-hardware/manage-modules.md

@@ -101,7 +101,7 @@ For more information, see the [`viam module` command](/cli/#module).
 ### Update an existing module using a GitHub action
 
 To update an existing module in the [Viam Registry](https://app.viam.com/registry) using continuous integration (CI), you can use one of two GitHub actions.
-You can only use these GitHub actions if you have already created the module by running `viam module create` and `viam module update`.
+You can only use these GitHub actions if you have already created the module by running `viam module create` and `viam module upload` (or `viam module generate` and opting to register the module, and then `viam module upload`).
 For most use cases, we recommend the [`build-action` GitHub action](https://github.com/viamrobotics/build-action) which provides a simple cross-platform build setup for multiple platforms: x86, ARM Linux, and MacOS.
 However, if you already have your own CI with access to arm runners or only intend to build on `x86` or `mac`, you may also use the [`upload-module` GitHub action](https://github.com/viamrobotics/upload-module) instead which allows you to define the exact build steps.