DOCS-3434: Document Micro-RDK OTA updates

docs/dev/reference/changelog.md

@@ -41,6 +41,12 @@ date: "2024-09-18"
 
 <!-- If there is no concrete date for a change that makes sense, use the end of the month it was released in. -->
 
+{{% changelog color="added" title="Over-the-air updates for the Micro-RDK" date="2025-01-08" %}}
+
+You can now update microcontroller firmware from anywhere using the [OTA update service](/operate/get-started/other-hardware/micro-module/#over-the-air-updates).
+
+{{% /changelog %}}
+
 {{% changelog date="2024-11-12" color="added" title="Builtin models moved to modules" %}}
 
 The following resource models have moved to modules.

docs/manage/software/deploy-packages.md

@@ -24,6 +24,12 @@ For example, you can configure a fragment with one resource, like a speech detec
 Add the fragment to all machines that need the speech detection service.
 As you improve the speech detection service, you can specify the version to deploy and all machines will reconfigure themselves to use the version specified in the update.
 
+{{% alert title="OTA updates for microcontrollers" color="note" %}}
+Fragments (as described on this page) are supported for microcontrollers running the Micro-RDK.
+
+However, if you want to update not just the configuration of your microcontroller but its entire firmware, see [Over-the-air firmware updates](/operate/get-started/other-hardware/micro-module/#over-the-air-updates).
+{{% /alert %}}
+
 ## Create a fragment
 
 {{< table >}}

docs/manage/software/update-packages.md

@@ -7,13 +7,17 @@ type: "docs"
 description: "As new versions of software modules or ML models become available, you can update the deployed version on all machines in one go."
 ---
 
-If you have already [deployed a package](/manage/software/deploy-packages/), you can inspect fragment you have created.
+If you have already [deployed a package](/manage/software/deploy-packages/), you can inspect the fragment you have created.
 The JSON object for the deployed package has a `version` field.
 
 As new versions of software modules or ML models become available, you can update the deployed version in one go using the fragment.
 
 We strongly recommend that you test updates on a subset of machines before deploying it to all machines.
 
+{{% alert title="Updates for microcontrollers" color="note" %}}
+To update the firmware on your microcontroller, see [Over-the-air updates](/operate/get-started/other-hardware/micro-module/#over-the-air-updates).
+{{% /alert %}}
+
 ## Test updates
 
 You can either create a second fragment that you add to a subset of machines, or manually overwrite the version of the package for a subset of machines.

docs/operate/get-started/other-hardware/micro-module.md

@@ -225,6 +225,70 @@ To create a new module compatible with the Micro-RDK, follow these steps.
 
 For further details on Micro-RDK development, including credentials management and developer productivity suggestions, please see the [development technical notes page on GitHub](https://github.com/viamrobotics/micro-rdk/blob/main/DEVELOPMENT.md).
 
+## Over-the-air updates
+
+To remotely update the firmware on your microcontroller without a physical connection to the device, add the OTA (over-the-air) service to your microcontroller's configuration in the [Viam app](https://app.viam.com).
+Use **JSON** mode to add the service as in the template below, then configure the URL from which to fetch new firmware, and the version name.
+
+There are two requirements for hosting firmware:
+
+- The hosting endpoint must use HTTP/2.
+- The hosting endpoint must _not_ use redirection.
+
+{{< tabs >}}
+{{% tab name="JSON Template" %}}
+
+```json {class="line-numbers linkable-line-numbers" data-line="3-10"}
+{
+  "services": [
+    {
+      "name": "OTA",
+      "api": "rdk:service:generic",
+      "model": "rdk:builtin:ota_service",
+      "attributes": {
+        "url": "<URL where firmware is stored in cloud storage>",
+        "version": "<version name>"
+      }
+    }
+  ]
+}
+```
+
+{{% /tab %}}
+{{% tab name="JSON Example" %}}
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "services": [
+    {
+      "name": "OTA",
+      "api": "rdk:service:generic",
+      "model": "rdk:builtin:ota_service",
+      "attributes": {
+        "url": "https://storage.googleapis.com/jordanna/micro-rdk-server-esp32-ota.bin",
+        "version": "myVersion1"
+      }
+    }
+  ]
+}
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Your device checks for configuration updates periodically.
+If the device receives a configuration with the OTA service and a modified `version` field in it, the device downloads the new firmware to an inactive partition and restarts.
+When the device boots it loads the new firmware.
+
+{{% alert title="Note" color="note" %}}
+There is no way to roll back to previous firmware after a bad upgrade without reflashing the device with a physical connection, so test your firmware thoroughly before deploying it to a fleet.
+{{% /alert %}}
+
+{{% alert title="Tip" color="tip" %}}
+To update the firmware version for a group of microcontrollers at the same time, you can [create a fragment](/manage/software/deploy-packages/) with the OTA service configuration and apply it to multiple machines.
+Then, whenever you update the `version` field in the fragment, the version will be updated for each machine that has that fragment in its config, triggering a firmware update the next time the devices fetch their configs.
+{{% /alert %}}
+
 ## Troubleshooting
 
 ### Error: `xtensa-esp32-elf-gcc: error: unrecognized command line option '--target=xtensa-esp32-espidf'` when building on macOS

static/include/micro-rdk-hardware.md

@@ -4,7 +4,7 @@ The following ESP32 microcontrollers are supported:
 
 - [ESP32-WROVER Series](https://www.espressif.com/en/products/modules/esp32)
 
-You will also need a data cable to connect the microcontroller to your development machine.
+You will also need a data cable to connect the microcontroller to your development machine, though subsequent firmware updates can be made remotely with the [over-the-air (OTA) service](/operate/get-started/other-hardware/micro-module/#over-the-air-updates).
 
 Your microcontroller should have at least the following resources available to work with `viam-micro-server`: