JT edits pt 2

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

@@ -3,7 +3,7 @@ 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 based on a SLAM map or GPS coordinates or to move a machine's components from one location to another."
 icon: true
 images: ["/icons/components/arm.svg"]
 date: "2022-01-01"

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/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/mobile-app/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,7 +100,7 @@ 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. |
+| 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. |
 
 {{< /expand >}}
@@ -752,7 +752,74 @@ 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.
+If you did not, you will need to manually create a <file>build.sh</file> entrypoint script.
+{{% /alert %}}
+
+To create a packaged executable:
+
+1. First, activate the [Python virtual environment](/sdks/python/python-venv/) the module generator created for you to ensure your module has access to any required libraries.
+   Run the following command from inside your module's directory to activate the virtual environment:
+
+   ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+   source venv/bin/activate
+   ```
+
+   Be sure you are within your Python virtual environment for the rest of these steps.
+   Your terminal prompt should include the name of your virtual environment in parentheses.
+
+1. Edit the <file>requirements.txt</file> file, adding PyInstaller (`pyinstaller`), and the Google API Python client (`google-api-python-client`) to the list of dependencies:
+
+   ```sh { class="command-line" data-prompt="$"}
+   pyinstaller
+   google-api-python-client
+   ```
+
+1. Install the dependencies listed in your `requirements.txt` file within your Python virtual environment using the following command:
+
+   ```sh { class="command-line" data-prompt="$"}
+   python -m pip install -r requirements.txt -U
+   ```
+
+1. Then compile your module, adding the Google API Python client as a hidden import:
+
+   ```sh { class="command-line" data-prompt="$"}
+   python -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
+   ```
+
+   If you need to include any additional data files to support your module, specify them using the `--add-data` flag:
+
+   ```sh { class="command-line" data-prompt="$"}
+   python -m PyInstaller --onefile --hidden-import="googleapiclient" --add-data src/arm/my_arm_kinematics.json:src/arm/ src/main.py
+   ```
+
+   By default, the output directory for the packaged executable is <file>dist</file>, and the name of the executable is derived from the name of the input script (in this case, main).
+
+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.
 

docs/operate/get-started/setup.md

@@ -8,11 +8,39 @@ no_list: true
 description: "Install the software that drives hardware and connects your device to the cloud."
 ---
 
+Get started by installing the open-source software that drives your hardware and connects your device to the cloud.
+The easiest way to do this is through the Viam app, so that your machines are automatically connected to configuration and remote operation tools.
+
 ## Quickstart
 
 1. Create a [Viam app](https://app.viam.com) account.
    The Viam app is the online hub for configuring and managing devices as well as viewing data.
 1. Add a new _{{< glossary_tooltip term_id="machine" text="machine" >}}_ in the app.
    A machine represents your device.
-1. From the machine page, follow the setup instructions to install `viam-server` on your device and connect it to the cloud.
+1. From your machine's page in the Viam app, follow the setup instructions to install `viam-server` on your device and connect it to the cloud.
    `viam-server` is the executable binary that runs on your device and manages hardware drivers, software, and data capture and sync.
+1. Use the **+** button on your machine's **CONFIGURE** tab to add [supported hardware components](/operate/get-started/supported-hardware/) so that `viam-server` can control your specific hardware.
+1. Use this same **+** button to configure software services such as [data capture and sync](/data-ai/capture-data/capture-sync/).
+
+As soon as you configure each component and save the configuration, you can use the **TEST** panel of the component's config card to, for example, view your camera's stream or turn your motor.
+
+## Concepts
+
+### What is a machine?
+
+A _machine_ is a computer (often a single-board computer like a Raspberry Pi or Jetson) or microcontroller and all the hardware attached to it, as well as the software running on it.
+You can think of one machine as representing one device, or one robot.
+
+When you create a new machine in the Viam app, Viam generates a unique set of credentials for that machine that connect the physical machine to its instance in the Viam app.
+
+### How the configuration works
+
+The machine setup steps displayed in the Viam app copy your machine's credentials to your machine.
+When you turn on your machine, `viam-server` starts up and uses the provided credentials to fetch its configuration from the Viam app.
+Once the machine has a configuration, it caches it locally and can use the config for up to 60 days.
+Since the configuration is cached locally, your machine does not need to stay connected to the Viam app after it has obtained its configuration file.
+
+If it is online, the machine checks for new configurations every 15 seconds and changes its config automatically when a new config is available.
+All communication happens securely over HTTPS using secret tokens that are in the machine's config.
+
+If your machine will never connect to the internet, you can also create a [local configuration file](/operate/reference/local-configuration-file/) on the machine itself.

docs/operate/get-started/supported-hardware.md

@@ -85,6 +85,25 @@ After installing `viam-server` or `viam-micro-server` on your computer or microc
 
    For details on configuring versioning and environment variables for modules, see [Modular Resource and Module Configuration Details](/operate/reference/module-configuration/).
 
+## Add software services to your machine
+
+In addition to hardware driver _{{< glossary_tooltip term_id="component" text="components" >}}_ and abstracted "virtual hardware" components, Viam offers _{{< glossary_tooltip term_id="service" text="services" >}}_ to provide higher-level software capabilities.
+You can read more about the Viam-maintained services and how to configure them in their respective documentation:
+
+- [Data capture and sync](/data-ai/capture-data/capture-sync/)
+- [ML model deployment](/data-ai/ai/deploy/)
+- [Computer vision](/data-ai/ai/run-inference/)
+- Motion planning for various components:
+  - [Robot arm motion](/operate/mobility/move-arm/)
+  - [Mobile robot navigation](/operate/mobility/move-base/)
+
+To add a service to your machine:
+
+1. Click the **+** button on your machine's **CONFIGURE** tab.
+1. Click **Service**, then select from available services.
+   The dropdown list includes services from the Viam Registry as well as the built-in services.
+1. Add required attributes according to the README or other documentation.
+
 ## How modules run
 
 Modules run alongside [`viam-server`](/architecture/viam-server/) as separate processes, communicating with `viam-server` over UNIX sockets.