Best before October, 18 2021.
We need to design the commands to handle tags for things and devices. Tags could be attached and detached to/from any thing or device. Also, certain commands could take tags as input in order to perform operations on multiple things/devices.
Example: arduino devices are put in each room of an hotel to control the room lamps. The customer needs to have:
- specific thing template, having a switch variable for each lamp of the room
- cloud sketch that reacts to changes on the switch variables and controls the lamps
- specific dashboard template, with all the needed switch widgets
Steps to setup an arduino device:
- arduino device is provisioned, information about its future location are passed as tags:
$ arduino-cloud-cli device create -n LedDevice101 --tags location=Milan,room=101,floor=1 - thing is created starting from the thing template and bound to the device:
$ arduino-cloud-cli thing create -n LedThing101 -t LedThingTemplate.yaml$ arduino-cloud-cli thing bind -i <thingID> -d <deviceID> - dashboard is created overriding the thing placeholder with the actual thing id:
$ arduino-cloud-cli dashboard create -n LedDashboard101 -t LedDashboardTemplate.yaml --override LedThing=<thingID> - The sketch is uploaded to the device
This steps should be repeated for every arduino device. So, for example, another device in a different room could be provisioned with: $ arduino-cloud-cli device create -n LedDevice102 --tags location=Milan,room=102,floor=1
When the customer wants to update the firmware of the devices, he can use the ota command specifying the tags of the devices to be updated:
$ arduino-cloud-cli ota upload --file <newFirmware.bin> --device-tags floor=1
In this case both the devices LedDevice101 and LedDevice102 will be updated.
Commands to create a device or a thing will accept an optional --tags flag. The tags passed in this way will be added to the resource after its creation:
$ arduino-cloud-cli device create --name <deviceName> --tags <key0>=<value0>,<key1>=<value1> and same for thing
Commands that could regard multiple things or devices could be changed in order to accept tags.
These commands can be:
list commands:
thing list --tags <key0>=<value0>,<key1>=<value1> to list all the things having all the tags passed
device list --tags <key0>=<value0>,<key1>=<value1> to list all the devices having all the tags passed
delete commands:
thing delete --tags <key0>=<value0>,<key1>=<value1> to delete all the things having all the tags passed
device delete --tags <key0>=<value0>,<key1>=<value1> to delete all the devices having all the tags passed
ota command:
ota upload --device-tags <key0>=<value0>,<key1>=<value1> --file <sketch-file.ino.bin> to perform an upload via ota to all the devices having all the tags passed
flags constraints:
In delete and ota commands, the --id flag should become optional instead of mandatory.
Then, if neither --id nor --tags is passed, the command should return an error telling the user to specify at least one of the two flags.
On the other hand, if both flags are passed, the command should return an error telling to choose only one of the two flags.
error handling: When a command performs actions on multiple resources, its execution will stop as soon as an error is encountered.
The changes listed above should not break anything, the commands could be used as before.
New commands should be introduced in order to add and delete tags to devices and things.
arduino-cloud-cli thing create-tags --thing <thingID> --tags <key0>=<value0>,<key1>=<value1> and same for device
arduino-cloud-cli thing delete-tags --thing <thingID> --tags <key0>,<key1> and same for device
Readme should be updated
https://arduino.atlassian.net/jira/software/projects/IOT/boards/277?selectedIssue=IOT-1359