Device Management
Device management is a feature which can be used for device campaign type operations like remotely updating firmware, settings, instructions or data on the entire population, or part of the population.
A device campaign is called a Job and it is executed on one or many defined Targets where each target is a Thing Group.
- Thing Groups allow you to manage several Things at once by categorizing them into groups.
- Job is the actual description of what shall be done and on what things this shall be done. When creating a job, you specify the Targets, i.e. a list of thing groups on which the job shall execute on.
- Job Document is describing the remote operations to be performed by the things in the targets. It can contain any information your things need to perform a job. For example, the job document may provide the instructions required by the thing to execute a firmware update, or it could contain instructions corresponding to a batch change of a resource or any other setting or command on the thing. When starting a job, MIC sends a message to all things in the targets to inform that a job is available. The progress of the job execution can be followed as the things reports their status performing the tasks in the job. Once finished, each thing reports complete and if it was not able to complete the Job, that is reported too.
In order for device campaigns to work, the thing application need to support the communication mechanisms used for device management and the instructions used in the job document.
In order to have controlled roll-out of new firmware and other updates, device campaigns are limited to notify 100 things per minute about the job.
The App-Board functionality for Device Management uses the Thing Jobs API and the Thing Groups API for the back end functionality needed.
The Device Connector has some capabilities for device management which will be exemplified in this guide.
App Board Device Management
MIC Device Management uses AWS IoT Jobs and everything that applies to AWS IoT Jobs also applies to MIC Device Management in regard to e.g. how to format the job document etc.
Create a job
Target Selection
First target groups need to be created, click + CREATE GROUP to start creating a group.
Enter a group name and select which domain the group should exist in
Click SAVE
Add things to group by clicking + ADD THINGS
Select the things that should belong to group by clicking the + sign next to the Thing.
Click SAVE
Click GROUPS to go back to Device Management overview.
Click on the newly created group to open it.
Job creation
Click JOBS and next + CREATE JOB to start creating a job
Enter description, select which domain the job should belong to and Type of job.
There are two strategies for selecting targets for a jobs: snapshot and continuous.
When a snapshot job is created, it will execute for all targets and then be completed. Once a snapshot job is started, the targets cannot be changed. After all things in the targets have completed the job (or report that they are unable to do so), the job is complete.
When a continuous job is created, it will execute for all targets. If a thing is later added to a group in the target list, the job will execute for the new thing as well. Ergo, a continuous job is never completed. A continuous job can e.g. be used to onboard or upgrade devices as they are added to a Thing Group, e.g. initial bootstrapping or initial configuration.
Select the job targets by clicking + ADD GROUPS to add target groups to the job execution, press SAVE when done addind targets.
Next, a job document needs to be added, the job document is delivered to the device in a JobExecution Object according to the documentation found here:
All the information about how the device shall interact with AWS IoT Core Jobs that MIC Device Managment is built upon can be found at the location above.
The jobDocument can contain any valid JSON but the total jobDocument size must be smaller than 32kB.
The jobDocument contents is specific to the target device implementation, a couple of typical job documents for the MIC Device Connector target can be seen below.
When done adding the job document, click CREATE JOB to create the job and when done, go back to Device Management overview.
MIC Device Connector Device Management support
In the MIC Device Connector there is some basic but important support for Device Management tasks.
The Connector supports a jobDocument with these limitations:
- The jobDocument must be a JSON document with a maximum of two key/value-pairs with these limitations:
- The first key is the jobName, the jobName can be a string of max length 25 characters, including the null terminator. This key must match the name registered for a job in the Device Connector.
- The first value is the first parameter associated with the job, this is a string with max length 150 characters, including the null terminator
- The second value is used for any extra information that is needed for the job in question, see example below.
Firmware Update
A firmware update job updates the firmware of the Device to the firmware specified in jobDocument.
Firmware Update jobDocument example
{"firmware_url":"root/fw/TestFirmware_V735745ADL.bin","pending_fw_version":"V735745A"}
The device will look for a firmware file in the path specified in the firmware_url key, download it, check it´s checksum and reboot to let the bootloader install the new FW if checksum was OK.
After the reboot and the bootloader has either installed new FW or just skipped to application the FW version of the running FW is checked towards the value of the key pending_fw_version
If there is a match, device will report job as SUCCEEDED, if not, it will report it as FAILED