diff --git a/designs/0002-tags.md b/designs/0002-tags.md new file mode 100644 index 00000000..6c891581 --- /dev/null +++ b/designs/0002-tags.md @@ -0,0 +1,94 @@ +# Introduction of tags for device and thing + +## Review Period + +Best before October, 18 2021. + +## What is the problem? +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. + +## Out-of-Scope + +## User Experience Walkthrough + +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 -d ` +- dashboard is created overriding the thing placeholder with the actual thing id: + `$ arduino-cloud-cli dashboard create -n LedDashboard101 -t LedDashboardTemplate.yaml --override LedThing=` +- 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 --device-tags floor=1` +In this case both the devices LedDevice101 and LedDevice102 will be updated. + +## Implementation + +### Project Changes + +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 --tags =,=` 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 =,=` to list all the things having all the tags passed + +`device list --tags =,=` to list all the devices having all the tags passed + + +**delete commands**: + +`thing delete --tags =,=` to delete all the things having all the tags passed + +`device delete --tags =,=` to delete all the devices having all the tags passed + + +**ota command**: + +`ota upload --device-tags =,= --file ` 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. + +### Breaking Change + +The changes listed above should not break anything, the commands could be used as before. + +### Design + +New commands should be introduced in order to add and delete tags to devices and things. + +`arduino-cloud-cli thing create-tags --thing --tags =,=` and same for device + +`arduino-cloud-cli thing delete-tags --thing --tags ,` and same for device + + +### Documentation Changes + +Readme should be updated + +## Additional Notes + +https://arduino.atlassian.net/jira/software/projects/IOT/boards/277?selectedIssue=IOT-1359