github.com/arduino/arduino-cloud-cli@v0.0.0-20240517070944-e7a449561083/designs/0002-tags.md (about)

     1  # Introduction of tags for device and thing
     2  
     3  ## Review Period
     4  
     5  Best before October, 18 2021.
     6  
     7  ## What is the problem?
     8  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.
     9  
    10  ## Out-of-Scope
    11  
    12  ## User Experience Walkthrough
    13  
    14  Example: arduino devices are put in each room of an hotel to control the room lamps.
    15  The customer needs to have:
    16  - specific thing template, having a switch variable for each lamp of the room
    17  - cloud sketch that reacts to changes on the switch variables and controls the lamps
    18  - specific dashboard template, with all the needed switch widgets
    19  
    20  Steps to setup an arduino device:
    21  - arduino device is provisioned, information about its future location are passed as tags: 
    22    `$ arduino-cloud-cli device create -n LedDevice101 --tags location=Milan,room=101,floor=1`
    23  - thing is created starting from the thing template and bound to the device: 
    24    `$ arduino-cloud-cli thing create -n LedThing101 -t LedThingTemplate.yaml `
    25    `$ arduino-cloud-cli thing bind -i <thingID> -d <deviceID>`
    26  - dashboard is created overriding the thing placeholder with the actual thing id:
    27    `$ arduino-cloud-cli dashboard create -n LedDashboard101 -t LedDashboardTemplate.yaml --override LedThing=<thingID>`
    28  - The sketch is uploaded to the device
    29  
    30  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`
    31  
    32  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:
    33    `$ arduino-cloud-cli ota upload --file <newFirmware.bin> --device-tags floor=1`
    34  In this case both the devices LedDevice101 and LedDevice102 will be updated.
    35  
    36  ## Implementation
    37  
    38  ### Project Changes
    39  
    40  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:
    41  
    42  `$ arduino-cloud-cli device create --name <deviceName> --tags <key0>=<value0>,<key1>=<value1>` and same for thing
    43  
    44  Commands that could regard multiple things or devices could be changed in order to accept tags.
    45  
    46  These commands can be:
    47  
    48  **list commands**:
    49  
    50  `thing list --tags <key0>=<value0>,<key1>=<value1>` to list all the things having all the tags passed
    51  
    52  `device list --tags <key0>=<value0>,<key1>=<value1>` to list all the devices having all the tags passed
    53  
    54  
    55  **delete commands**:
    56  
    57  `thing delete --tags <key0>=<value0>,<key1>=<value1>` to delete all the things having all the tags passed
    58  
    59  `device delete --tags <key0>=<value0>,<key1>=<value1>` to delete all the devices having all the tags passed
    60  
    61  
    62  **ota command**:
    63  
    64  `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
    65  
    66  
    67  **flags constraints**:
    68  In delete and ota commands, the `--id` flag should become **optional** instead of mandatory. 
    69  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.
    70  On the other hand, if both flags are passed, the command should return an error telling to choose only one of the two flags.
    71  
    72  **error handling**:
    73  When a command performs actions on multiple resources, its execution will stop as soon as an error is encountered. 
    74  
    75  ### Breaking Change
    76  
    77  The changes listed above should not break anything, the commands could be used as before.
    78  
    79  ### Design
    80  
    81  New commands should be introduced in order to add and delete tags to devices and things.
    82  
    83  `arduino-cloud-cli thing create-tags --thing <thingID> --tags <key0>=<value0>,<key1>=<value1>` and same for device
    84  
    85  `arduino-cloud-cli thing delete-tags --thing <thingID> --tags <key0>,<key1>` and same for device
    86  
    87  
    88  ### Documentation Changes
    89  
    90  Readme should be updated
    91  
    92  ## Additional Notes
    93  
    94  https://arduino.atlassian.net/jira/software/projects/IOT/boards/277?selectedIssue=IOT-1359