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,76 @@
+### Updating Devices with Mbed CLI
+
+Mbed CLI includes features that help prepare and ship updates for devices managed through Pelion. The Mbed CLI uses the subcommands starting with `mbed device-management`, `mbed dev-mgmt` or `mbed dm` to manage devices.
+
+Start by configuring your Mbed Cloud SDK API Key, target and toolchain. Obtain the API Key from the Pelion portal.
+
+```
+$ mbed config -G CLOUD_SDK_API_KEY ak_...
+$ mbed target K64F
+$ mbed toolchain GCC_ARM
+```
+
+Next, initialize the device management feature of Mbed CLI with the following command:
+
+```
+$ mbed device-management init -d "<company domain name>" -m "<product model identifier>"
+```
+
+First, 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 Cloud settings in `.mbed_cloud_config.json`.
+* Mbed Cloud developer credentials in `mbed_cloud_dev_credentials.c`
+* Mbed Cloud update credentials in `update_defalut_resources.c`
+
+The default settings include:
+* A unique vendor identifier, based on the domain name supplied to `init`.
+* A unique model identifier, based on the vendor identifier and the model name supplied to `init`.
+* The path of the certificate and private key.
+
+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.
+
+As `device-management` is very long to type, the remainder of this document will use the `mbed dm` alias for all device management subcommands.
+
+<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, please 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
+Once you have run `mbed device-management init`, you can perform updates on a single device by:
+
+```
+$ mbed compile
+$ mbed dm update device -D <device ID>
+```
+
+This will perform several actions:
+1. Upload the payload, generated by `mbed compile`, to Mbed Cloud.
+1. Hash the payload and create a manifest that links to its location in Mbed Cloud.
+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 Cloud.
+
+This allows development with a device for testing purposes.
+
+#### Multidevice update
+If you need to update more than one device, you can use the Mbed Cloud portal to create device filters that can include many devices into an update campaign. First, you need a manifest. Once you have run `mbed device-management init`, you can create manifests by:
+
+```
+$ mbed compile
+$ mbed dm update prepare
+```
+
+Optionally, a name and description for the payload and corresponding manifest can be provided:
+
+```
+$ 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. See below for more details.
+
+Once you execute `mbed dm update prepare`, Mbed CLI automatically uploads to Mbed Cloud and you can then create and start an update campaign 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`.