|
1 | | -<h1 id="cli-update">Update devices</h1> |
| 1 | +<h1 id="dm-deprecated">Device management</h1> |
2 | 2 |
|
3 | | -Arm Mbed OS allows you to update your device firmware using Pelion Device Management. Mbed CLI includes features to prepare and ship updates for devices managed through [Device Management Portal](https://www.pelion.com/docs/device-management/current/introduction/index.html). |
4 | | - |
5 | | -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 Device Management with a project. |
6 | | - |
7 | | -<span class="tips">**Tip**: This page is about using Device Management to update an application on a device in the field. To update dependencies of an application on your computer, [see `mbed update`](../build-tools/compile.html#update-programs-and-libraries).</span> |
8 | | - |
9 | | -## Requirements |
10 | | - |
11 | | -To use the `mbed dm` command to update a device, your device must be running an application with Device Management Client and a supported managed or unmanaged bootloader. |
12 | | - |
13 | | -This command only works for devices running Device Management Client, and the application is combined with a bootloader. To test this feature, you can run the [Device Management Client Example](https://github.com/ARMmbed/mbed-cloud-client-example) or [using our tutorials](https://www.pelion.com/docs/device-management/current/connecting/device-management-client-tutorials.html) on one of our reference boards. |
14 | | - |
15 | | -## Project setup |
16 | | - |
17 | | -Configure your Device Management SDK API key, target and toolchain. [Obtain the API key](https://cloud.mbed.com/docs/latest/integrate-web-app/api-keys.html) from Device Management Portal. |
18 | | - |
19 | | -``` |
20 | | -$ mbed config -G CLOUD_SDK_API_KEY <API_KEY> |
21 | | -$ mbed target <TARGET> |
22 | | -$ mbed toolchain <TOOLCHAIN> |
23 | | -``` |
24 | | - |
25 | | -<span class="notes">**Note:** The API key must have Administrator privileges to use this feature.</span> |
26 | | - |
27 | | -Initialize the Device Management feature of Mbed CLI with the following command: |
28 | | - |
29 | | -``` |
30 | | -$ mbed dm init -d "<company domain name>" --model-name "<product model identifier>" |
31 | | -``` |
32 | | - |
33 | | -<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> |
34 | | - |
35 | | -This command asks for information about your update certificate. After completing the prompts, Mbed CLI creates several files: |
36 | | - |
37 | | -- A certificate in `.update-certificates/default.der`. |
38 | | -- A matching private key in `.update-certificates/default.key.pem`. |
39 | | -- A set of default settings in `.manifest_tool.json`. |
40 | | -- Device Management update credentials in `update_default_resources.c`. |
41 | | -- Device Management settings in `.mbed_cloud_config.json`, including default settings for: |
42 | | - - A unique vendor identifier, based on the domain name supplied as the `-d` parameter to `mbed dm init`. |
43 | | - - A unique model identifier, based on the vendor identifier and the model name supplied as the `--model-name` to `mbed dm init`. |
44 | | - - The path of the update certificate and private key. |
45 | | -- Device Management developer credentials in `mbed_cloud_dev_credentials.c`. |
46 | | - |
47 | | -<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> |
48 | | - |
49 | | -## Single-device update |
50 | | - |
51 | | -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: |
52 | | - |
53 | | -``` |
54 | | -$ mbed compile |
55 | | -``` |
56 | | - |
57 | | -This generates an image to update the device with. After generating the image, update the device through Device Management with: |
58 | | - |
59 | | -``` |
60 | | -$ mbed dm update device -D <device ID> -m <target> |
61 | | -``` |
62 | | - |
63 | | -This performs several actions: |
64 | | - |
65 | | -1. Uploads the image, generated by `mbed compile`, to Device Management. |
66 | | -1. Hashes the image, and create a manifest that links to its location in Device Management. |
67 | | -1. Creates an update campaign for the supplied device ID, with the newly created manifest. |
68 | | -1. Starts the campaign. |
69 | | -1. Waits for the campaign to complete. |
70 | | -1. Deletes the image, manifest and update campaign out of Device Management. |
71 | | - |
72 | | -## Multidevice update |
73 | | - |
74 | | -To update more than one device, use Mbed CLI to generate and upload a manifest and image to Device Management Portal. Then use 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 images by running: |
75 | | - |
76 | | -``` |
77 | | -$ mbed compile |
78 | | -``` |
79 | | - |
80 | | -This generates an image to update the device with. |
81 | | - |
82 | | -After generating the image, upload the image and manifest with: |
83 | | - |
84 | | -``` |
85 | | -$ mbed dm update prepare |
86 | | -``` |
87 | | - |
88 | | -`mbed dm update prepare` automatically uses the update image that `mbed compile` generates. You may provide a name and description for the image and corresponding manifest with additional arguments: |
89 | | - |
90 | | -``` |
91 | | -$ mbed dm update prepare -n <PAYLOAD_NAME> -d <PAYLOAD_DESCRIPTION>\ |
92 | | - --manifest-name <MANIFEST_NAME> --manifest-description <MANIFEST_DESCRIPTION> |
93 | | -``` |
94 | | - |
95 | | -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. |
96 | | - |
97 | | -Once you execute `mbed dm update prepare`, Mbed CLI automatically uploads the image and manifest to Device Management, and you can then create and start an [update campaign](https://www.pelion.com/docs/device-management/current/updating-firmware/update-campaigns.html) using the Device Management Portal. |
98 | | - |
99 | | - |
100 | | -## Advanced use |
101 | | - |
102 | | -Mbed CLI allows for significantly more flexibility than the model above shows in exactly the same way as [the manifest tool](https://www.pelion.com/docs/device-management/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`. |
| 3 | +Device management is deprecated since Mbed OS 6.15. Please use [the Pelion manifest-tool](https://github.com/PelionIoT/manifest-tool#manifest-dev-tool). |
0 commit comments