Merge pull request #744 from theotherjimmy/document-mbed-dm

Document mbed dm

README.md

@@ -787,6 +787,94 @@ All unit tests are under `mbed-os/UNITTESTS` directory. You can **generate** the
 $ mbed test --unittests --new rtos/Semaphore.cpp
 ```
 
+## Device Update
+
+Arm Mbed OS allows you to update your device firmware, enabled by our Pelion IoT platform. Mbed CLI includes features to prepare and ship updates for devices managed through the [Device Management Portal](https://cloud.mbed.com/docs/current/introduction/index.html). Mbed CLI provides the subcommand `mbed device-management` to manage devices (`mbed dev-mgmt` and `mbed dm` are also available as shorter aliases). The remainder of this document uses the `mbed dm` alias for all device management subcommands. This document explains the steps to enable and use Pelion Device Management with a project.
+
+### Project setup
+
+Configure your Mbed Cloud SDK API key, target and toolchain. Obtain the API key from the the Device Management Portal.
+
+```
+$ mbed config -G CLOUD_SDK_API_KEY <API_KEY>
+$ mbed target K64F
+$ mbed toolchain GCC_ARM
+```
+
+Initialize the device management feature of Mbed CLI with the following command:
+
+```
+$ mbed dm init -d "<company domain name>" --model-name "<product model identifier>"
+```
+
+<span class="notes">**Note:** If you do not want to enter the subject information for your update certificate (country, state, city, organization and so on), add the `-q` flag to the command above.</span>
+
+This command asks for information about your update certificate. After completing the prompts, Mbed CLI creates several files:
+
+- A certificate in `.update-certificates/default.der`.
+- A matching private key in `.update-certificates/default.key.pem`.
+- A set of default settings in `.manifest_tool.json`.
+- Device Management update credentials in `update_defalut_resources.c`
+- Device Management settings in `.mbed_cloud_config.json`, including default settings for:
+   - A unique vendor identifier, based on the domain name supplied as the `-d` parameter to `mbed dm init`.
+   - A unique model identifier, based on the vendor identifier and the model name supplied as the `--model-name` to `mbed dm init`.
+   - The path of the update certificate and private key.
+- Device Management developer credentials in `mbed_cloud_dev_credentials.c`
+
+<span class="notes">**Note:** The certificate created in `mbed dm init` is not suitable for production. Use it for testing and development only. To create a certificate for production purposes, use an air-gapped computer or a Hardware Security Module. When going to production, conduct a security review on your manifest signing infrastructure because it is the core of the security guarantees for update client.</span>
+
+### Single-device update
+
+Mbed CLI provides a subcommand, `mbed dm update device`, for development with a device and for testing purposes. After following the steps in [Project setup](#project-setup), perform firmware updates on a device by running:
+
+```
+$ mbed compile
+```
+
+This generates a payload to update the device with. After generating the payload, update the device through Device Management with:
+
+```
+$ mbed dm update device -D <device ID> -m <target>
+```
+
+This performs several actions:
+
+1. Upload the payload, generated by `mbed compile`, to Device Management.
+1. Hash the payload, and create a manifest that links to its location in Device Management.
+1. Create an update campaign for the supplied device ID, with the newly created manifest.
+1. Start the campaign.
+1. Wait for the campaign to complete.
+1. Delete the payload, manifest and update campaign out of Device Management.
+
+### Multidevice update
+
+To update more than one device, use Mbed CLI to generate and upload a manifest and payload to the Device Management portal. Then use the Device Management portal to create device filters that include many devices in an update campaign. After the steps in [Project Setup](#project-setup), you can create and upload manifests and payloads by running:
+
+```
+$ mbed compile
+```
+
+This generates a payload to update the device with. After generating the payload, upload the payload and manifest with:
+
+```
+$ mbed dm update prepare
+```
+
+`mbed dm update prepare` automatically uses the update payload that `mbed compile` generates. You may provide a name and description for the payload and corresponding manifest with additional arguments:
+
+```
+$ mbed dm update prepare -n <PAYLOAD_NAME> -d <PAYLOAD_DESCRIPTION>\
+    --manifest-name <MANIFEST_NAME> --manifest-description <MANIFEST_DESCRIPTION>
+```
+
+Both methods of creating a manifest use the defaults created in `mbed dm init`. You can override each default using an input file or command-line arguments.
+
+Once you execute `mbed dm update prepare`, Mbed CLI automatically uploads the payload and manifest to Device Management, and you can then create and start an [update campaign](https://cloud.mbed.com/docs/current/updating-firmware/update-campaigns.html) using the Device Management Portal.
+
+### Advanced use
+
+Mbed CLI allows for significantly more flexibility than the model above shows in exactly the same way as [the manifest tool](https://cloud.mbed.com/docs/current/updating-firmware/manifest-tool.html). You can override each of the defaults that `mbed dm init` sets by using the command-line or an input file. Mbed CLI supports a variety of commands. You can print a full list of commands by using `manifest-tool --help`.
+
 ## Publishing your changes
 
 ### Checking status