From 513f6f7281e26aa7ee289144209f30aa581a6efe Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Tue, 12 Oct 2021 15:51:45 +0200 Subject: [PATCH 1/9] Draft tags introduction --- designs/0002-tags.md | 71 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 designs/0002-tags.md diff --git a/designs/0002-tags.md b/designs/0002-tags.md new file mode 100644 index 00000000..650974a0 --- /dev/null +++ b/designs/0002-tags.md @@ -0,0 +1,71 @@ +# 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 + + +## Implementation + +### Project Changes + +Commands that could regard multiple things or devices could be changed in order to accept tags. + +These commands can be: + +list commands: + +`thing list --tag =,=` to list all the things having all the tags passed +`device list --tag =,=` to list all the devices having all the tags passed +alternative: `--filter` instead of `--tag` + + +delete commands: + +`thing delete --tag =,=` to delete all the things having all the tags passed +`device delete --tag =,=` to delete all the devices having all the tags passed + + +ota command: + +`ota upload --device-tag =,= --file ` to perform an upload via ota to all the devices having all the tags passed + + +To be decided, **which flag is mandatory and which is optional**: +In delete and ota commands, the `--id` flag should become **optional** instead of mandatory. +Then, if neither `--id` nor `--tag` is passed, the command could return an error telling the user to specify at least one of the two flags. +On the other hand, if both flags are passed, we could follow different approaches: return an error, use only one flag (only tags or only id), try to use both flags. + +Another thing to be decided is **how to handle errors**: +- Try to execute the command on all the indicated resources, without stopping in case of errors. At the end, print all the errors details. +- 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. Here are some alternatives: + +Implementing a tag command: +`arduino-cloud-cli tag create --thing --tags =,=` + +Adding a tag subcommand in device and thing commands: +`arduino-cloud-cli thing create-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 From e9325201eb03ebf7ef6d4130c540f34a23d4ae3f Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Tue, 12 Oct 2021 15:56:37 +0200 Subject: [PATCH 2/9] Improve doc format --- designs/0002-tags.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index 650974a0..83eb8929 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -20,20 +20,23 @@ Commands that could regard multiple things or devices could be changed in order These commands can be: -list commands: +**list commands**: `thing list --tag =,=` to list all the things having all the tags passed + `device list --tag =,=` to list all the devices having all the tags passed + alternative: `--filter` instead of `--tag` -delete commands: +**delete commands**: `thing delete --tag =,=` to delete all the things having all the tags passed + `device delete --tag =,=` to delete all the devices having all the tags passed -ota command: +**ota command**: `ota upload --device-tag =,= --file ` to perform an upload via ota to all the devices having all the tags passed From dfd99cf3a69311ae85ccaca67ad972e4f67d5af7 Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Fri, 15 Oct 2021 18:02:44 +0200 Subject: [PATCH 3/9] Rename tag into tags --- designs/0002-tags.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index 83eb8929..036ade5b 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -22,28 +22,26 @@ These commands can be: **list commands**: -`thing list --tag =,=` to list all the things having all the tags passed +`thing list --tags =,=` to list all the things having all the tags passed -`device list --tag =,=` to list all the devices having all the tags passed - -alternative: `--filter` instead of `--tag` +`device list --tags =,=` to list all the devices having all the tags passed **delete commands**: -`thing delete --tag =,=` to delete all the things having all the tags passed +`thing delete --tags =,=` to delete all the things having all the tags passed -`device delete --tag =,=` to delete all the devices having all the tags passed +`device delete --tags =,=` to delete all the devices having all the tags passed **ota command**: -`ota upload --device-tag =,= --file ` to perform an upload via ota to all the devices having all the tags passed +`ota upload --device-tags =,= --file ` to perform an upload via ota to all the devices having all the tags passed To be decided, **which flag is mandatory and which is optional**: In delete and ota commands, the `--id` flag should become **optional** instead of mandatory. -Then, if neither `--id` nor `--tag` is passed, the command could return an error telling the user to specify at least one of the two flags. +Then, if neither `--id` nor `--tags` is passed, the command could return an error telling the user to specify at least one of the two flags. On the other hand, if both flags are passed, we could follow different approaches: return an error, use only one flag (only tags or only id), try to use both flags. Another thing to be decided is **how to handle errors**: From 10c4b50ae4a797f6541dc88e67262b81c53bc75b Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Fri, 15 Oct 2021 18:06:45 +0200 Subject: [PATCH 4/9] Update flags constraints --- designs/0002-tags.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index 036ade5b..bc56a037 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -39,10 +39,10 @@ These commands can be: `ota upload --device-tags =,= --file ` to perform an upload via ota to all the devices having all the tags passed -To be decided, **which flag is mandatory and which is optional**: +**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 could return an error telling the user to specify at least one of the two flags. -On the other hand, if both flags are passed, we could follow different approaches: return an error, use only one flag (only tags or only id), try to use both flags. +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. Another thing to be decided is **how to handle errors**: - Try to execute the command on all the indicated resources, without stopping in case of errors. At the end, print all the errors details. From 436e8264209fd2c3dddccedaf1b90efcec77c14d Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Fri, 15 Oct 2021 18:13:08 +0200 Subject: [PATCH 5/9] Update error handling --- designs/0002-tags.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index bc56a037..a6e3968b 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -44,9 +44,8 @@ In delete and ota commands, the `--id` flag should become **optional** instead o 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. -Another thing to be decided is **how to handle errors**: -- Try to execute the command on all the indicated resources, without stopping in case of errors. At the end, print all the errors details. -- Stop as soon as an error is encountered. +**error handling**: +When a command performs actions on multiple resources, its execution will stop as soon as an error is encountered. ### Breaking Change From 529d57d1928d8b81123726a5a8688868d1d84f69 Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Fri, 15 Oct 2021 18:16:54 +0200 Subject: [PATCH 6/9] Update new command design --- designs/0002-tags.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index a6e3968b..5005909c 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -53,14 +53,12 @@ The changes listed above should not break anything, the commands could be used a ### Design -New commands should be introduced in order to add and delete tags to devices and things. Here are some alternatives: +New commands should be introduced in order to add and delete tags to devices and things. -Implementing a tag command: -`arduino-cloud-cli tag create --thing --tags =,=` - -Adding a tag subcommand in device and thing commands: `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 From aac5c46eaa03ba0280f5b0102def3b41654fc8be Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Tue, 19 Oct 2021 13:18:36 +0200 Subject: [PATCH 7/9] Insert use experience --- designs/0002-tags.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index 5005909c..21c64679 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -11,6 +11,26 @@ We need to design the commands to **handle tags** for things and devices. Tags c ## 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 LedDevice --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. + +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=2` ## Implementation From 109f579b6cd7b31ba4a69ffe9b2c412191e2f7b3 Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Tue, 19 Oct 2021 13:53:32 +0200 Subject: [PATCH 8/9] Add second device in usecase --- designs/0002-tags.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index 21c64679..c782e634 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -19,7 +19,7 @@ The customer needs to have: 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 LedDevice --tags location=Milan,room=101,floor=1` + `$ 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 ` @@ -27,10 +27,11 @@ Steps to setup an arduino device: `$ 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. +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=2` + `$ arduino-cloud-cli ota upload --file --device-tags floor=1` +In this case both the devices LedDevice101 and LedDevice102 will be updated. ## Implementation From a811c5be312fe19f147425e4bffa5c2d7a719232 Mon Sep 17 00:00:00 2001 From: Paolo Calao Date: Tue, 19 Oct 2021 14:16:04 +0200 Subject: [PATCH 9/9] Add tags during resource creation --- designs/0002-tags.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/designs/0002-tags.md b/designs/0002-tags.md index c782e634..6c891581 100644 --- a/designs/0002-tags.md +++ b/designs/0002-tags.md @@ -37,6 +37,10 @@ In this case both the devices LedDevice101 and LedDevice102 will be updated. ### 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: