Add documentation about mbed dm

docs.json

@@ -708,6 +708,10 @@
                                 "type": "markdown",
                                 "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/offline/cli-compile.md"
                             },
+                            {
+                                "type": "markdown",
+                                "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/offline/cli-device-management.md"
+                            },
                             {
                                 "type": "markdown",
                                 "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/offline/cli-collaborate.md"

docs/tools/offline/cli-device-management.md

@@ -0,0 +1,86 @@
+### Updating Devices with Mbed CLI
+
+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 uses the subcommands starting with `mbed device-management`, `mbed dev-mgmt` or `mbed dm` to manage devices.  As `device-management` is very long to type, the remainder of this document uses the `mbed dm` alias for all device management subcommands. This document explains the steps to enable and use Mbed Device Managment with a project.
+
+#### Project Setup
+
+Configuring 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. When Mbed CLI has enough information, it 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`.
+* Mbed Device Management update credentials in `update_defalut_resources.c`
+* Mbed 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.
+* Mbed 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, as 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, perform firmware updates on a single-device by running:
+
+```
+$ mbed compile
+```
+
+This will generate a payload to update the device with. After generating the payload, update the device through Mbed Device Management with:
+
+```
+$ mbed dm update device -D <device ID>
+```
+
+This will perform several actions:
+
+1. Upload the payload, generated by `mbed compile`, to Mbed Device Management.
+1. Hash the payload and create a manifest that links to its location in Mbed 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 Mbed Device Management.
+
+#### Multidevice update
+
+To update more than one device, use Mbed CLI to generate and upload a manifest and payload to the Mbed Device Management portal. Then use the Mbed Device Management portal to create device filters that include many devices in an update campaign. After the steps in Project Setup, you can create and upload manifests and palyoads by running:
+
+```
+$ mbed compile
+```
+
+This will generate 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 generated by `mbed compile`. 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 Mbed 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 Mbed Cloud portal.
+
+### Advanced usage
+
+Mbed CLI allows for significantly more flexibility than the model above shows in exactly the same way as Manifest Tool. 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`.