Merge pull request #435 from golioth/cohorts

Document Cohorts and Packages

docs/device-management/3-blueprints-and-tags/1-blueprints.md

@@ -3,8 +3,8 @@
 Blueprints are a great way to segment your IoT fleet by hardware-type. You might
 create a blueprint for each revision of a particular board, or use one blueprint
 for each hardware variation that uses a different type of sensor. These
-blueprints can be used to target firmware binaries at the correct device types,
-and to adjust settings for groups of devices with a single action.
+blueprints can be used to adjust settings for groups of devices with a single
+action.
 
 ## Create a new blueprint
 
@@ -23,12 +23,6 @@ and to adjust settings for groups of devices with a single action.
 You may add a blueprint to a device when it is created, or use the edit button
 on the device summary to add or remove a blueprint from an existing device.
 
-## Use a blueprint to filter OTA firmware updates
-
-A blueprint may be used to filter over the air (OTA) firmware updates. Choose a
-blueprint when you upload an artifact. This will be honored when a release is
-created that uses the artifact.
-
 ## Use a blueprint to filter Device Settings
 
 You can update settings for all devices that share the same blueprint by

docs/device-management/3-blueprints-and-tags/2-tags.md

@@ -8,9 +8,8 @@ an example, you might create a tag for each of the following groups:
 - All devices that have a camera
 - A subset of devices used in pre-production OTA testing
 
-Tags may be used in filtering over the air (OTA) firmware updates and when
-querying the Golioth REST API. Tags are optional, and multiple tags may be added
-to each device.
+Tags may be used when querying the Golioth REST API. Tags are optional, and
+multiple tags may be added to each device.
 
 ## Create a new tag
 
@@ -30,24 +29,3 @@ on the device summary to add or remove tags from an existing device.
 ![Add a new tag](./assets/device-summary-tags.png)
 
 Tags associated with a device will be shown on that device's summary page.
-
-## Use tags to filter OTA firmware updates
-
-Tags may be used to filter over the air (OTA) firmware updates. Choose zero or
-more tags when you create a release.
-
-:::tip Release tags apply to all devices that **exactly** match those tags
-
-When you apply one or more tags to a firmware release, all devices must exactly
-match that combination of tags to be notified of the firmware release. The
-exception to this rule is that a release that has no tags will notify all
-devices, no matter if the devices have tags applied or not. For example:
-
-- Release that has no tags will be received by all devices, even those that have
-  tags.
-- Release that has the `pre-production` tag will only be received by devices
-  that only have the `pre-production` tag (and no other tags) assigned.
-- Release that has both `pre-production` and `building-5` tags will **NOT** be
-  received by a devices that only has the `pre-production` tag.
-
-:::

docs/device-management/5-ota/2-managing-packages.md

@@ -0,0 +1,58 @@
+---
+id: managing-packages
+title: Managing packages
+---
+
+A package represents a single upgradeable component on your embedded device.
+Each package has a list of versions, each with a version number and an artifact,
+as well as a description and user defined metadata fields for categorizing the
+package.
+
+Generally, it's recommended to make one package for each unique component in
+your project. For example, if two different devices in your project use the same
+AI model, you only need to create a single package to represent it. You can
+deploy the AI model package to both types of devices individually.
+
+To upgrade a package on one of your devices, you'll first need to upload the new
+version to Golioth as an artifact.
+
+We provide a [firmware update sample
+application](https://github.com/golioth/golioth-firmware-sdk/tree/main/examples/zephyr/fw_update)
+that can be used to test our OTA service. The sample listens for new deployment
+events from our backend and automatically downloads and installs them with
+MCUboot.
+
+Follow [the Firmware OTA Upgrade
+guide](/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade) to
+build the sample application for your target board.
+
+## Creating a new package in the Golioth Web Console
+
+1. Navigate to [the packages section](https://console.golioth.io/packages) of
+   the Golioth Web Console
+2. Click the `Create` button
+3. Fill in the relevant information:
+    - Give the package a name (Use `main` if you're working with the firmware
+      update sample)
+    - Optional: Give the package a short description
+    - Optional: Set properties to help categorize your package (e.g. `type`:
+      `firmware`)
+
+    ![Creating a package](./assets/web-console-create-package.png)
+
+## Uploading a new package version in the Golioth Web Console
+
+1. Navigate to [the packages section](https://console.golioth.io/packages) of
+   the Golioth Web Console
+2. Open your package in the list
+3. Click the `New Version` button
+4. Fill in the relevant information
+    - Set the version number of your artifact (eg: `1.2.3` or `2024-Q4`)
+    - Choose the binary you want to upload
+
+    ![Creating an Artifact](./assets/web-console-create-artifact.png)
+
+5. Click the `Upload Artifact` button and the new version will appear in the
+   version list:
+
+    ![Version list](./assets/web-console-artifact-list.png)

docs/device-management/5-ota/3-managing-cohorts.md

@@ -0,0 +1,58 @@
+---
+id: managing-cohorts
+title: Managing cohorts
+---
+
+In order to deploy OTA updates to your devices, you'll need to assign them to a
+cohort. A cohort is a group of devices that should have the same set of
+packages, and receive the same firmware updates.
+
+Typically, you'll need to create a cohort for each type of device in your
+project. For example, if your project contains both light switches and light
+bulbs, you should form one "Light Switch" cohort and one "Light Bulb" cohort, so
+that you can manage the firmware of the two types of devices separately. You may
+also want to create dedicated cohorts for devices that should receive the
+updates early, such as internal test devices or external beta testers.
+
+## Assigning devices to a cohort
+
+There are three ways to assign a device to a cohort in the Golioth Web Console:
+
+- In the cohort's page:
+    1. Click the `Add Devices` button in the top right corner
+    2. Find the device you want to add to the cohort in the table
+    3. Click the `Add` button next to your device in the table
+- In the Device Index:
+    1. Select the devices you want to add using the checkboxes in the device
+       list
+    2. Click `Bulk Actions` in the top right corner
+    3. Select `Assign to cohort`
+    4. Select the right cohort and press `Assign`
+- In the Edit Device page:
+    1. Click the `Edit` button in the top right corner
+    2. Select a cohort in the `cohort` dropdown in the form
+    3. Click `Save`
+
+If your device is online and observing the OTA manifest, it will immediately
+receive a manifest update and start updating its packages to match the cohort's
+active deployment.
+
+
+## Removing devices from a cohort
+
+You can remove a device from a cohort through the Device Index and the Edit
+Device page using the same workflow as when you added them. You can also remove
+the device from a cohort in the Devices tab of the cohort page by selecting the
+device in the table and clicking `Remove Device` in the top right corner.
+
+When you remove a device from a cohort, it stops receiving updates about its deployments. Contrary to when you added a device to a cohort, removing it will **not** prompt an immediate manifest change event on the device.
+
+:::warning Fallback to legacy releases
+
+If you have previously used the old releases concept to distribute OTA updates,
+devices that are removed from their cohorts will fall back to using releases as
+a basis for their manifest. You can avoid this by disabling rollout for all your
+old releases. See [the migration
+documentation](./5-migrating-from-releases/README.md) for more information.
+
+:::

docs/device-management/5-ota/4-deploying-updates.md

@@ -0,0 +1,61 @@
+---
+id: deploying-updates
+title: Deploying Updates
+---
+
+You can push OTA updates to all devices in a cohort by creating deployments.
+Each deployment contains a set of packages, which decide the composition of the
+firmware and assets on all devices in the cohort. Each cohort can only have one
+active deployment at a time, and deployments are always pushed to all devices in
+the cohort with as soon as they connect to Golioth's servers.
+
+:::info Deployments are immutable
+
+Once a deployment has been pushed to your cohort, it cannot be reverted or
+deleted. To roll back to a previous version of a package, you have to create a
+new deployment.
+
+:::
+
+The deployment history for your cohort is available in cohort's page the Golioth
+Web Console. Here, you can see the changes in packages and their versions from
+deployment to deployment. New deployments are added to the top of the list, and
+all packages that have been used in any of the last 10 deployments are displayed
+in their own column.
+
+![Deployment History](./assets/web-console-deployment-history.png)
+
+You can add and remove packages from one deployment to the next. It's up to you
+how you want your firmware to handle changes to the set of included packages.
+While it may make sense to delete the on-device copy of an asset like an image
+when it is removed from the OTA manifest of the active deployment, the same is
+usually not true for the main application firmware.
+
+Packages that don't change from one deployment to the next do not need to be
+downloaded again, but the device firmware should be able to handle both upgrades
+and downgrades of all package types.
+
+Each deployment has a sequence number that is included in the manifest of the
+OTA update pushed to your devices. The sequence number is strictly increasing,
+and can be stored by the device to determine whether an update has been handled
+or not.
+
+## Creating Deployments
+
+Before you create a deployment, make sure you have [uploaded the required
+artifacts to the Golioth Cloud](./2-managing-packages.md).
+
+1. Navigate to [the cohorts section](https://console.golioth.io/cohorts) of
+   the Golioth Web Console
+2. Select the cohort you want to deploy to
+3. Click `Deploy` in the top right corner
+3. Select a name and the included packages for your deployment
+
+    ![Creating a Deployment](./assets/web-console-deploy.png)
+
+4. Click the `Next` button and review the changes in your deployment.
+
+    ![releases list](./assets/web-console-deployment-changes.png)
+
+5. Click `Start Deployment` to start distributing the update to the devices in
+   your cohort.

docs/device-management/5-ota/3-release-firmware-update.md → docs/device-management/5-ota/5-migrating-from-releases/2-legacy-releases.md

@@ -1,11 +1,17 @@
 ---
-id: release-firmware-update
-title: Releasing Firmware Updates
+id: legacy-releases
+title: Legacy Releases
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+:::warning Deprecated
+
+Releases have been deprecated in favor of [Cohorts and Deployments](../3-managing-cohorts.md). This page documents the workflow for the old Releases page for projects that haven't been migrated to Cohorts.
+
+:::
+
 To make a firmware update available to your devices, you must first create a
 Release. A release is a set of available artifact versions that may optionally
 be targeted using Blueprints and Tags.