}
```
@@ -747,9 +861,10 @@ The following attributes are available for `rdk:sensor:jessamy:weather:meteo_PM`
{{% /tablestep %}}
{{% tablestep %}}
-**2. Create a GitHub repo (optional)**
+**2. Create a GitHub repo**
Create a GitHub repository with all the source code and the README for your module.
+This is required for cloud build to work.
Add the link to that repo as the `url` in the meta.json file.
@@ -806,7 +921,8 @@ Do not change the module_id.
models |
object |
Required |
-A list of one or more {{< glossary_tooltip term_id="model" text="models" >}} provided by your custom module. You must provide at least one model, which consists of an api and model key pair. If you are publishing a public module ("visibility": "public"), the namespace of your model must match the namespace of your organization. |
+A list of one or more {{< glossary_tooltip term_id="model" text="models" >}} provided by your custom module. You must provide at least one model, which consists of an api and model key pair. If you are publishing a public module ("visibility": "public"), the namespace of your model must match the namespace of your organization.
+You are strongly encouraged to include a markdown_link to the section of the README containing configuration information about each model, so that the section will be displayed alongside the configuration panel when configuring the model. For example, "README.md#configure-your-meteo_pm-sensor". Please also include a short_description describing what hardware the model supports. |
entrypoint |
@@ -838,22 +954,82 @@ Do not change the module_id.
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 meta.json file):
{{< tabs >}}
-{{% tab name="Python: pyinstaller (recommended)" %}}
+{{% 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 build.sh entrypoint script.
{{% /alert %}}
-The build.sh script packaged a tarball for you when you ran it before [testing](#test-your-module-locally).
+Edit your meta.json file back to its original state, reverting the edits you made for local testing purposes.
+It should resemble the following:
+
+```json {class="line-numbers linkable-line-numbers" data-start="13" data-line="1, 4, 6" }
+ "entrypoint": "dist/main",
+ "first_run": "",
+ "build": {
+ "build": "./build.sh",
+ "setup": "./setup.sh",
+ "path": "dist/archive.tar.gz",
+ "arch": [
+ "linux/amd64",
+ "linux/arm64"
+ ]
+ }
+```
+
+Delete the reload.sh script since it was only meant for testing purposes.
+
+Now you are ready to build and upload your module, either using Viam's cloud build tooling which is recommended for continuous integration, or a more manual process:
+
+{{< tabs >}}
+{{% tab name="PyInstaller cloud build (recommended)" %}}
+
+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.
+
+The `viam module generate` command already generated the `build-action` file in your .github/workflows folder, so you just need to set up authentication in GitHub, and then create a new release to trigger the action:
+
+1. In your terminal, run `viam organizations list` to view your organization ID.
+1. Create an organization API key by running the following command:
+
+ ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+ viam organization api-key create --org-id YOUR_ORG_UUID --name descriptive-key-name
+ ```
+
+1. In the GitHub repo for your project, go to **Settings** → **Secrets and variables** → **Actions**.
+ Create two new secrets using the **New repository secret** button:
+
+ - `VIAM_KEY_ID` with the UUID from `Key ID:` in your terminal
+ - `VIAM_KEY_VALUE` with the string from `Key Value:` in your terminal
+
+1. From the main code page of your GitHub repo, find **Releases** in the right side menu and click **Create a new release**.
+1. In the **Choose a tag** dropdown, create a new tag such as `1.0.0`.
+ _Do not prepend the tag with `v` or the GH action will not trigger._
+ For details about versioning, see [Module versioning](/operate/reference/module-configuration/#module-versioning).
+
+1. Click **Publish release**.
+ The cloud build action will begin building the new module version for each architecture listed in your meta.json, and any machines configured to use the latest release of the module will receive the update once it has finished building.
+
+See [Update an existing module using a GitHub action](/operate/get-started/other-hardware/manage-modules/#update-an-existing-module-using-a-github-action) for more information.
+
+{{% /tab %}}
+{{% tab name="Manual PyInstaller build" %}}
+
+From within the module 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
+```
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
+viam module upload --version 1.0.0 --platform any dist/archive.tar.gz
```
For details on platform support, see [Using the `--platform` argument](/dev/tools/cli/#using-the---platform-argument).
@@ -867,8 +1043,8 @@ Use the _same version number_ when running multiple `upload` commands of the sam
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](/operate/get-started/other-hardware/manage-modules/#update-an-existing-module-using-a-github-action) for more information.
+{{% /tab %}}
+{{< /tabs >}}
{{% alert title="Note" color="note" %}}
diff --git a/docs/operate/get-started/other-hardware/hello-world-module.md b/docs/operate/get-started/other-hardware/hello-world-module.md
index c93ba37d2c..24192642c3 100644
--- a/docs/operate/get-started/other-hardware/hello-world-module.md
+++ b/docs/operate/get-started/other-hardware/hello-world-module.md
@@ -186,6 +186,12 @@ If you prefer the simpler path, skip the sensor sections in the steps below.
The easiest way to generate the files for your module is to use the [Viam CLI](/dev/tools/cli/).
+{{% alert title="Note" color="note" %}}
+The steps below suggest that you disable cloud build when generating your stub files, for simplicity of local testing.
+If you plan to publish your module to the Viam registry, we recommend enabling cloud build, and then following the testing, packaging and uploading steps in [Integrate other hardware](/operate/get-started/other-hardware/) once you are done writing your API implementation in this guide.
+Enabling cloud build will set up your module for a more automated deployment process if you plan to use your module for more than just learning.
+{{% /alert %}}
+
### Generate the camera files
The CLI module generator generates the files for one modular resource at a time.
diff --git a/docs/operate/get-started/other-hardware/manage-modules.md b/docs/operate/get-started/other-hardware/manage-modules.md
index 38ea0af25b..bd3f8a12fa 100644
--- a/docs/operate/get-started/other-hardware/manage-modules.md
+++ b/docs/operate/get-started/other-hardware/manage-modules.md
@@ -154,7 +154,7 @@ At the end of your meta.json, add the build configuration:
{{%expand "Click to view example setup.sh" %}}
-```sh { class="command-line"}
+```sh {class="command-line" data-prompt="$"}
#!/bin/bash
set -e
UNAME=$(uname -s)
@@ -179,7 +179,7 @@ pip3 install -r requirements.txt
{{%expand "Click to view example build.sh (with setup.sh)" %}}
-```sh { class="command-line"}
+```sh { class="command-line" data-prompt="$"}
#!/bin/bash
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
@@ -190,7 +190,7 @@ tar -czvf dist/archive.tar.gz
{{%expand "Click to view example build.sh (without setup.sh)" %}}
-```sh { class="command-line"}
+```sh { class="command-line" data-prompt="$"}
#!/bin/bash
set -e
UNAME=$(uname -s)