Mender Hub - Mender Binary Delta.diff

Mender Hub - Mender Binary Delta.diff

--- "Mender Hub - Mender Binary Delta - orig.md"	2020-04-20 14:10:32.774369664 +0200
+++ "Mender Hub - Mender Binary Delta.md"	2020-04-21 11:20:47.557365686 +0200
@@ -123,7 +123,7 @@
 
 **NOTE!** The trailing `:` in `FILESEXTRAPATHS_prepend_pn-mender-binary-delta` is intentional and important to have in place.
 
-## Generating images, artifacts and deltas
+## Preparing images and artifacts
 
 For the purpose of this tutorial you can set the `MENDER_ARTIFACT_NAME` to the following:
 
@@ -200,16 +200,20 @@
 mender-binary-delta  mender-binary-delta-generator  release-v.1.0.mender  release-v.2.0.mender
 ```
 
+## Generating delta Artifacts
+
+This tutorial assumes that Mender Enterprise is being used. If not, then dependencies need to be tracked manually, which is not recommended. See the [troubleshooting](#troubleshooting) section for ways to deal with this.
+
 Generate delta for `v1.0 -> v2.0` update path:
 
 ```
-./mender-binary-delta-generator -n v2.0-deltafrom-v1.0 -o v2.0-deltafrom-v1.0.mender release-v.1.0.mender release-v.2.0.mender
+./mender-binary-delta-generator -o v2.0-deltafrom-v1.0.mender release-v.1.0.mender release-v.2.0.mender
 ```
 
 Generate delta for `v2.0 -> v1.0` update path:
 
 ```
-./mender-binary-delta-generator -n v1.0-deltafrom-v2.0 -o v1.0-deltafrom-v2.0.mender release-v.2.0.mender release-v.1.0.mender
+./mender-binary-delta-generator -o v1.0-deltafrom-v2.0.mender release-v.2.0.mender release-v.1.0.mender
 ```
 
 ## Using the delta Mender Artifacts
@@ -221,13 +225,34 @@
 - v1.0-deltafrom-v2.0.mender (mender-binary-delta)
 - v2.0-deltafrom-v1.0.mender (mender-binary-delta)
 
+After having uploaded these four Artifacts, you should have two Releases in the Mender UI. This is because the rootfs-image Artifact and the corresponding mender-binary-delta Artifact are referring to the same software.
+
 If you have followed this tutorial your provisioned device should be running `release-v1.0` which was provisioned using a disk image (e.g `sdimg`).
 
-### First deploy a full image update (Yocto Project thud or older)
+### Deploy delta updates
+Start off with deploying `release-v.2.0.mender` to the device, and once that is completed you can deploy `release-v.1.0.mender`. Note that at this point there is no distinction between deploying a full rootfs-image Artifact and a mender-binary-delta Artifact. Mender keeps track of dependencies automatically and selects the correct one. More formally, it selects the smallest Artifact which satisfies the dependencies, but will select the bigger rootfs-image Artifact if the device has an unknown delta base.
+
+Note that the very first update after provisioning a device is always a `rootfs-image` update. This is needed because the checksum is not tracked when using a `sdimg` file, only when using a `mender` file. This is only needed **once** after you have provisioned a device, and after the first deployment is done, delta Artifacts will be used if they are available. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
 
-If you are using Yocto Project **warrior (2.7) or newer** you can skip this section, as it is not required.
+If you want to verify that the mender-binary-delta Artifact is indeed being used, delete the rootfs-image from the one of the Releases in the UI, and then deploy that release.
 
-If you are using Yocto Project version **thud (2.6) or older**, you must deploy a `rootfs-image` update **once** after you have provisioned your device, e.g using the disk image (`sdimg`). This is needed because the checksum of the file system image is not the same in an `sdimg` and in a `mender` file, even if they are generated during the same build. And because we generated the delta Artifacts from the `mender` files, we must deploy one of these first before we can proceed in deploying deltas. As mentioned this is only needed **once** after you have provisioned a device, after that is done you can use delta Artifacts. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
 
-### Deploy delta updates
-Start of with deploying `release-v.2.0.mender` to the device, and once that is completed you can deploy `v1.0-deltafrom-v2.0.mender` and after one is completed you can deploy `v2.0-deltafrom-v1.0.mender`.
+## Troubleshooting
+
+### Error message: `Artifact dependency "rootfs_image_checksum" not satisfied by currently installed artifact`
+
+This message will usually only be reported if you are not using Mender Enterprise, and is usually because of one of these reasons:
+
+* You are using a non-Enterprise version of Mender, and there are several mender-binary-delta and/or rootfs-image Artifacts with the same name (grouped under the same Release in the UI). In non-Enterprise versions of Mender, there is no automatic dependency tracking, so each Artifact needs to have a different name, even if the only difference between two Artifacts is the delta base.
+
+* You are trying to deploy a mender-binary-delta Artifact onto a device which does not have the delta base checksum that the Artifact was made for. If this is the case, you need to make a new mender-binary-delta Artifact based on the Artifact which is currently installed on the device, and install that instead.
+
+* It can also be an indication that [the very first rootfs-image Artifact](#first-deploy-a-full-image-update) has not been deployed yet. If so, you need to install a rootfs-image Artifact to the device first, and make sure that the next mender-binary-delta Artifact uses this Artifact as a base. This only needs to be done once for each device. This requirement may be lifted in the future, see [this ticket](https://tracker.mender.io/browse/MEN-2834) for more information.
+
+### Deployment finishes with "No artifact" without updating the device
+
+This can happen if a Release only has mender-binary-delta Artifacts uploaded, and none of them match the delta base on the device. If so, you need to do one of these things:
+
+* Upload a mender-binary-delta Artifact using the currently installed Artifact of the device as a base.
+
+* Upload a rootfs-image Artifact, which will always match, but will also use more bandwidth than a mender-binary-delta Artifact.

@estenberg: Alright, updated!

Looks good!