Usando o AWS IoT 1-Click com a CLI da AWS

Para demonstrar o uso da Interface da linha de comando da AWS (CLI da AWS), considere o cenário de uma empresa de descarte que deseja agilizar seu serviço de coleta de lixo usando o AWS IoT 1-Click.

Nesse cenário, cada lixeira é emparelhada com um AWS IoT Enterprise Button. Quando uma lixeira está cheia, o cliente só precisa pressionar o botão associado para solicitar que a lixeira seja substituída.

nota

Todas as IDs de dispositivo AWS IoT Enterprise Button começam com “G030PM”.

As etapas a seguir são usadas pela empresa de coleta de lixo para preparar o AWS IoT Enterprise Button para uso do cliente.

Para preparar o AWS IoT Enterprise Button para uso do cliente

A única maneira de configurar o Wi-Fi para um AWS IoT Enterprise Button é usar o aplicativo móvel do AWS IoT 1-Click. Para instalar o aplicativo, consulte Aplicativo móvel AWS IoT 1-Click. Depois de instalar o aplicativo, não pressione Fazer login na conta da AWS (como seria normalmente o caso). Neste exercício, queremos demonstrar como usar a CLI da AWS. Se você pressionar Fazer login na conta da AWS, os comandos initiate-device-claim e finalize-device-claim serão invocados para você, e queremos fazer isso “manualmente” usando a CLI, conforme mostrado nas etapas a seguir.
Para fins de demonstração da ILC da AWS, em vez de pressionarFazer login na conta da AWS, escolha o pequeno ícone de Wi-Fi redondo no canto superior direito. Depois, escolha Configurar Wi-Fi. Digitalize ou insira o ID do dispositivo e siga as instruções restantes do aplicativo móvel.
Se você não tiver a CLI da AWS instalada, siga as instruções descritas emInstalar a AWS CLI. Para listar os comandos da CLI da AWS IoT 1-Click, execute os dois comandos a seguir.
```
aws iot1click-projects help
```
```
aws iot1click-devices help
```
Para associar o agora conectado pelo AWS IoT Enterprise Button à conta da AWS da empresa de coleta de lixo, execute o seguinte comando usando o ID do dispositivo.
```
aws iot1click-devices initiate-device-claim --device-id G030PM0123456789
{
    "State": "CLAIM_INITIATED"
}
```
Pressione o botão no dispositivo. Após a luz branca piscar de maneira intermitente, você deve ver uma luz verde sólida por cerca de um segundo. Caso contrário, repita o procedimento de conexão Wi-Fi anterior.
Depois de ver a luz verde sólida na etapa anterior, execute o seguinte comando (usando o valor de ID do dispositivo).
```
aws iot1click-devices finalize-device-claim --device-id G030PM0123456789
{
    "State": "CLAIMED"
}
```
O"State": "CLAIMED"Indica que o dispositivo foi registrado com êxito com o serviço 1-Click do AWS IoT.
nota
Se o fabricante do dispositivo fornecer um código de reivindicação começando com “C-”, você poderá usar apenas o comando aws iot1click-devices claim-devices-by-claim-code para reivindicar um ou mais dispositivos usando um único código de reivindicação, conforme mostrado no exemplo a seguir.
```
aws iot1click-devices claim-devices-by-claim-code --claim-code C-123EXAMPLE
{
    "Total": 9
    "ClaimCode": "C-123EXAMPLE"
}
```
Neste exemplo,"Total": 9Indica que os nove dispositivos associados ao código de reivindicaçãoC-123EXAMPLEForam reivindicadas com êxito pelo serviço 1-Click do AWS IoT.

Depois, prepare-se para criar um projeto do AWS IoT 1-Click para a empresa de descarte criando um arquivo de texto JSON chamadocreate-project.json. Esse arquivo contém o seguinte.


{
   "projectName": "SeattleDumpsters",
   "description": "All dumpsters in the Seattle region.",
   "placementTemplate": {
      "defaultAttributes": {
         "City" : "Seattle"
      },
      "deviceTemplates": {
         "empty-dumpster-request" : {
            "deviceType": "button"
         }
      }
   }
}

Os pares de chave-valor placementTemplate e deviceTemplates são os atributos que serão aplicados a todos os botões que fazem parte do projeto SeattleDumpsters. Para criar esse projeto, execute o seguinte comando (que pressupõe quecreate-project.jsonestá noDiretório de trabalho atualdo prompt de comando da ILC da AWS).


aws iot1click-projects create-project --cli-input-json file://create-project.json

Para exibir o projeto recém-criado, execute o seguinte comando.


aws iot1click-projects list-projects
{
    "projects": [
        {
            "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
            "projectName": "SeattleDumpsters",
            "createdDate": 1563483100,
            "updatedDate": 1563483100,
            "tags": {}
        }
    ]
}

Para obter mais detalhes, execute o comando describe-project da seguinte forma.


aws iot1click-projects describe-project --project-name SeattleDumpsters
{
    "project": {
        "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
        "projectName": "SeattleDumpsters",
        "description": "All dumpsters in the Seattle region.",
        "createdDate": 1563483100,
        "updatedDate": 1563483100,
        "placementTemplate": {
            "defaultAttributes": {
                "City": "Seattle"
            },
            "deviceTemplates": {
                "empty-dumpster-request": {
                    "deviceType": "button",
                    "callbackOverrides": {}
                }
            }
        },
        "tags": {}
    }
}

Com o projeto criado para a região de Seattle, você criará um posicionamento para uma lixeira específica (para o cliente 217), da seguinte forma. As aspas são necessárias para o Windows.


aws iot1click-projects create-placement --project-name SeattleDumpsters --placement-name customer217 --attributes "{\"location\": \"1800 9th Ave Seattle, WA 98101\", \"phone\": \"206-123-4567\"}"

Para exibir o posicionamento recém-criado, execute o seguinte comando.


aws iot1click-projects list-placements --project-name SeattleDumpsters
{
    "placements": [
        {
            "projectName": "SeattleDumpsters",
            "placementName": "customer217",
            "createdDate": 1563488454,
            "updatedDate": 1563488454
        }
    ]
}

Para obter mais detalhes, execute o comando describe-placement da seguinte forma.


aws iot1click-projects describe-placement --project-name SeattleDumpsters --placement-name customer217
{
    "placement": {
        "projectName": "SeattleDumpsters",
        "placementName": "customer217",
        "attributes": {
            "phone": "206-123-4567",
            "location": "1800 9th Ave Seattle, WA 98101"
        },
        "createdDate": 1563488454,
        "updatedDate": 1563488454
    }
}

Embora o dispositivo agora esteja associado à conta do AWS IoT 1-Click da empresa de descarte, ele não está associado ao posicionamento. Confirme isso executando o seguinte comando.


aws iot1click-projects get-devices-in-placement --project-name SeattleDumpsters --placement-name customer217
{
    "devices": {}
}

Para associar o dispositivo ao posicionamento, execute o seguinte comando.


aws iot1click-projects associate-device-with-placement --project-name SeattleDumpsters --placement-name customer217 --device-template-name empty-dumpster-request --device-id G030PM0123456789

Para confirmar o comando anterior, execute get-devices-in-placement novamente.


aws iot1click-projects get-devices-in-placement --project-name SeattleDumpsters --placement-name customer217
{
    "devices": {
        "empty-dumpster-request": "G030PM0123456789"
    }
}

Para obter mais detalhes, execute o comando describe-device, da seguinte forma (observe a alternância de iot1click-projects para iot1click-devices).


aws iot1click-devices describe-device --device-id G030PM0123456789
{
    "DeviceDescription": {
        "Arn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",  
        "Attributes": {
            "projectRegion": "us-west-2",
            "projectName": "SeattleDumpsters",
            "placementName": "customer217",
            "deviceTemplateName": "empty-dumpster-request"
        },
        "DeviceId": "G030PM0123456789",
        "Enabled": false,
        "RemainingLife": 99.9,
        "Type": "button",
        "Tags": {}
    }
}

Como há atualmente apenas um dispositivo, o comando a seguir produz resultados semelhantes.


aws iot1click-devices list-devices --device-type button
{
    "Devices": [
        {
            "Arn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",
            "Attributes": {
                "projectRegion": "us-west-2",
                "projectName": "SeattleDumpsters",
                "placementName": "customer217",
                "deviceTemplateName": "empty-dumpster-request"
            },
            "DeviceId": "G030PM0123456789",
            "Enabled": false,
            "RemainingLife": 99.9,
            "Type": "button",
            "Tags": {}
        }
    ]
}

Para verificar se o dispositivo está funcionando corretamente, execute o seguinte comando. Ajuste os carimbos de data/hora adequadamente, que estão no formato ISO 8061.


aws iot1click-devices list-device-events --device-id G030PM0123456789 --from-time-stamp 2019-07-17T15:45:12.880Z --to-time-stamp 2019-07-19T15:45:12.880Z
{
    "Events": [
        {
            "Device": {
                "Attributes": {},
                "DeviceId": "G030PM0123456789",
                "Type": "button"
            },
            "StdEvent": "{\"clickType\": \"SINGLE\", \"reportedTime\": \"2019-07-18T23:47:55.015Z\", \"certificateId\": \"fe8798a6c97c62ef8756b80eeefdcf2280f3352f82faa8080c74cc4f4a4d1811\", \"remainingLife\": 99.85000000000001, \"testMode\": false}"
        }
    ]
}

Aqui vemos que um evento de clique único (\"clickType\": \"SINGLE\") ocorreu em 2019-07-18T23:47:55.015Z. Agora clique duas vezes no dispositivo (dois pressionamentos rápidos no botão em sucessão) e execute o comando novamente. Agora observe o evento de clique duplo (\"clickType\": \"DOUBLE\"), semelhante ao seguinte.


aws iot1click-devices list-device-events --device-id G030PM0123456789 --from-time-stamp 2019-07-17T15:45:12.880Z --to-time-stamp 2019-07-19T15:45:12.880Z
{
    "Events": [
        {
            "Device": {
                "Attributes": {},
                "DeviceId": "G030PM0123456789",
                "Type": "button"
            },
            "StdEvent": "{\"clickType\": \"SINGLE\", \"reportedTime\": \"2019-07-18T23:47:55.015Z\", \"certificateId\": \"fe8798a6c97c62ef8756b80eeefdcf2280f3352f82faa8080c74cc4f4a4d1811\", \"remainingLife\": 99.85000000000001, \"testMode\": false}"
        },
        {
            "Device": {
                "Attributes": {},
                "DeviceId": "G030PM0123456789",
                "Type": "button"
            },
            "StdEvent": "{\"clickType\": \"DOUBLE\", \"reportedTime\": \"2019-07-19T00:14:41.353Z\", \"certificateId\": \"fe8798a6c97c62ef8756b80eeefdcf2280f3352f82faa8080c74cc4f4a4d1811\", \"remainingLife\": 99.8, \"testMode\": false}"
        }
    ]
}

Cada tipo de dispositivo tem um conjunto de métodos de dispositivo invocáveis. Para listar os métodos disponíveis para o tipo de dispositivo, execute o comando get-device-methods, da seguinte forma.


aws iot1click-devices get-device-methods --device-id G030PM0123456789
{
    "DeviceMethods": [
        {
            "MethodName": "getDeviceHealthParameters"
        },
        {
            "MethodName": "setDeviceHealthMonitorCallback"
        },
        {
            "MethodName": "getDeviceHealthMonitorCallback"
        },
        {
            "MethodName": "setOnClickCallback"
        },
        {
            "MethodName": "getOnClickCallback"
        }
    ]
}

Para invocar um dos métodos disponíveis, use o comando invoke-device-method, como mostrado a seguir.


aws iot1click-devices invoke-device-method --cli-input-json file://invoke-device-method.json
{
    "DeviceMethodResponse": "{\"remainingLife\": 99.8}"
}

Aqui, invoke-device-method.json contém o seguinte.


{
    "DeviceId": "G030PM0123456789",
    "DeviceMethod": {
        "DeviceType": "device",
        "MethodName": "getDeviceHealthParameters"
    }
}

nota

Os métodos get (como getDeviceHealthParameters) não esperam parâmetros. Portanto, a linha "DeviceMethodParameters": "" dentro do arquivo JSON não pode ser usada (caso isso aconteça, ocorrerá o seguinte: An error occurred (InvalidRequestException) when calling the InvokeDeviceMethod operation: A request parameter was invalid.)

Ao executar aws iot1click-devices list-devices --device-type button, você pode ver que o valor padrão para Enabled é false. O comando a seguir define essa chave como true.
```
aws iot1click-devices update-device-state --device-id G030PM0123456789 --enabled
```
Para configurá-lo de volta para false, execute o comando anterior, usando novamente o argumento --no-enabled.

Se as informações do cliente forem alteradas, você poderá atualizar as informações de posicionamento de um dispositivo conforme mostrado a seguir (observe a mudança de iot1click-devices para iot1click-projects). Execute o seguinte comando para exibir as informações atuais de customer217 (consulte attributes).


aws iot1click-projects describe-placement --project-name SeattleDumpsters --placement-name customer217
{
    "placement": {
        "projectName": "SeattleDumpsters",
        "placementName": "customer217",
        "attributes": {
            "phone": "206-123-4567",
            "location": "1800 9th Ave Seattle, WA 98101"
        },
        "createdDate": 1563488454,
        "updatedDate": 1563488454
    }
}

Depois, execute o seguinte comando para atualizar os atributos de telefone e local do cliente.


aws iot1click-projects update-placement --cli-input-json file://update-placement.json

Aqui, update-placement.json contém o seguinte.


{
    "projectName": "SeattleDumpsters",
    "placementName": "customer217",
    "attributes": {
        "phone": "206-266-1000",
        "location": "410 Terry Ave N Seattle, WA 98109"
    }
}

Para revisar essa atualização, execute describe-placement novamente, conforme mostrado.


aws iot1click-projects describe-placement --project-name SeattleDumpsters --placement-name customer217
{
    "placement": {
        "projectName": "SeattleDumpsters",
        "placementName": "customer217",
        "attributes": {
            "phone": "206-266-1000",
            "location": "410 Terry Ave N Seattle, WA 98109"
        },
        "createdDate": 1563488454,
        "updatedDate": 1563572842
    }
}

Para atualizar as informações do projeto, use o comando update-project. Um projeto geralmente contém vários posicionamentos de clientes. Estas são as informações existentes do projeto SeattleDumpster.


aws iot1click-projects describe-project --project-name SeattleDumpsters
{
    "project": {
        "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
        "projectName": "SeattleDumpsters",
        "description": "All dumpsters in the Seattle region.",
        "createdDate": 1563483100,
        "updatedDate": 1563483100,
        "placementTemplate": {
            "defaultAttributes": {
                "City": "Seattle"
            },
            "deviceTemplates": {
                "empty-dumpster-request": {
                    "deviceType": "button",
                    "callbackOverrides": {}
                }
            }
        },
        "tags": {}
    }
}

Para alterar “Todas as lixeiras na região de Seattle” para “Todas as lixeiras (jardadesperdício, reciclagem e lixo) na região de Seattle”, execute o seguinte comando.


aws iot1click-projects update-project --project-name SeattleDumpsters --description "All dumpsters (yard waste, recycling, garbage) in the Seattle region."

Você pode ver que o valor da chave "description" foi atualizado para todos os posicionamentos SeattleDumpsters.


aws iot1click-projects describe-project --project-name SeattleDumpsters
{
    "project": {
        "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
        "projectName": "SeattleDumpsters",
        "description": "All dumpsters (yard waste, recycling, garbage) in the Seattle region.",
        "createdDate": 1563483100,
        "updatedDate": 1563819039,
        "placementTemplate": {
            "defaultAttributes": {
                "City": "Seattle"
            },
            "deviceTemplates": {
                "empty-dumpster-request": {
                    "deviceType": "button",
                    "callbackOverrides": {}
                }
            }
        },
        "tags": {}
    }
}

Você pode usar tags para aplicar metainformações aos recursos de projeto (iot1click-projects) e aos recursos de posicionamento (iot1click-devices), da seguinte forma.


aws iot1click-projects tag-resource --cli-input-json file://projects-tag-resource.json

Aqui, projects-tag-resource.json contém o seguinte.


{
    "resourceArn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
    "tags": {
        "Account": "45215",
        "Manager": "Tom Jones"
    }
}

Para listar as tags para o recurso de projeto, execute o seguinte.


aws iot1click-projects list-tags-for-resource --resource-arn "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters"
{
    "tags": {
        "Manager": "Tom Jones",
        "Account": "45215"
    }
}

Para ver as tags do projeto no contexto, execute o seguinte.


aws iot1click-projects describe-project --project-name SeattleDumpsters
{
    "project": {
        "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
        "projectName": "SeattleDumpsters",
        "description": "All dumpsters (yard waste, recycling, garbage) in the Seattle region.",
        "createdDate": 1563483100,
        "updatedDate": 1563819039,
        "placementTemplate": {
            "defaultAttributes": {
                "City": "Seattle"
            },
            "deviceTemplates": {
                "empty-dumpster-request": {
                    "deviceType": "button",
                    "callbackOverrides": {}
                }
            }
        },
        "tags": {
            "Manager": "Tom Jones",
            "Account": "45215"
        }
    }
}

Para descobrir os nomes de recurso da Amazon (ARNs) dos dispositivos, execute o seguinte.


aws iot1click-devices list-devices
{
    "Devices": [
        {
            "Arn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",
            "Attributes": {
                "projectRegion": "us-west-2",
                "projectName": "SeattleDumpsters",
                "placementName": "customer217",
                "deviceTemplateName": "empty-dumpster-request"
            },
            "DeviceId": "G030PM0123456789",
            "Enabled": true,
            "RemainingLife": 99.7,
            "Type": "button",
            "Tags": {}
        }
    ]
}

Para adicionar tags ao dispositivo anterior, execute o seguinte.


aws iot1click-devices tag-resource --cli-input-json file://devices-tag-resource.json

Aqui, devices-tag-resources.json contém o seguinte (observe a capitalização obrigatória de ResourceArn e Tags).


{
    "ResourceArn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",
    "Tags": {
        "Driver": "John Smith",
        "Driver Phone": "206-123-4567"
    }
}

Para listar as tags para o recurso de dispositivo, execute o seguinte.


aws iot1click-devices list-tags-for-resource --resource-arn "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789"
{
    "Tags": {
        "Driver Phone": "206-123-4567",
        "Driver": "John Smith"
    }
}

Para ver as tags do dispositivo no contexto, execute list-devices.


aws iot1click-devices list-devices
{
    "Devices": [
        {
            "Arn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",
            "Attributes": {
                "projectRegion": "us-west-2",
                "projectName": "SeattleDumpsters",
                "placementName": "customer217",
                "deviceTemplateName": "empty-dumpster-request"
            },
            "DeviceId": "G030PM0123456789",
            "Enabled": true,
            "RemainingLife": 99.7,
            "Type": "button",
            "Tags": {
                "Driver Phone": "206-123-4567",
                "Driver": "John Smith"
            }
        }
    ]
}

Neste ponto, você pode associar uma ação pressionando o botão do dispositivo, como acionar uma função do AWS Lambda ou enviar uma mensagem do Amazon SNS. Você pode fazer isso facilmente usando o console do AWS IoT 1-Click (oModelo de programação do AWS IoT 1-Clicktambém é uma opção). Depois que as ações apropriadas forem associadas ao dispositivo, você poderá levar o dispositivo para o local do cliente e conectá-lo à rede Wi-Fi usando o mesmo procedimento descrito nas etapas 1 e 2.

Desmontagem do dispositivo AWS IoT 1-Click

As etapas a seguir descrevem como reverter (desfazer) as etapas anteriores.

Para desmarcar um recurso de projeto, execute o seguinte comando.


aws iot1click-projects untag-resource --resource-arn "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters" --tag-keys "Manager"

Isso remove a tag Manager do projeto, como mostrado a seguir.


aws iot1click-projects describe-project --project-name SeattleDumpsters
{
    "project": {
        "arn": "arn:aws:iot1click:us-west-2:012345678901:projects/SeattleDumpsters",
        "projectName": "SeattleDumpsters",
        "description": "All dumpsters (yard waste, recycling, garbage) in the Seattle region.",
        "createdDate": 1563483100,
        "updatedDate": 1563819039,
        "placementTemplate": {
            "defaultAttributes": {
                "City": "Seattle"
            },
            "deviceTemplates": {
                "empty-dumpster-request": {
                    "deviceType": "button",
                    "callbackOverrides": {}
                }
            }
        },
        "tags": {
            "Account": "45215"
        }
    }
}

Para desmarcar um recurso de dispositivo, execute o seguinte comando.


aws iot1click-devices untag-resource --resource-arn "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789" --tag-keys "Driver Phone" "Driver"

Isso remove as tags do dispositivo, como mostrado a seguir (observe a lista vazia "Tags": {}).


aws iot1click-devices list-devices
{
    "Devices": [
        {
            "Arn": "arn:aws:iot1click:us-west-2:012345678901:devices/G030PM0123456789",
            "Attributes": {
                "projectRegion": "us-west-2",
                "projectName": "SeattleDumpsters",
                "placementName": "customer217",
                "deviceTemplateName": "empty-dumpster-request"
            },
            "DeviceId": "G030PM0123456789",
            "Enabled": true,
            "RemainingLife": 99.7,
            "Type": "button",
            "Tags": {}
        }
    ]
}

Para desassociar um dispositivo de um posicionamento, execute o seguinte comando.


aws iot1click-projects disassociate-device-from-placement --project-name SeattleDumpsters --placement-name customer217 --device-template-name empty-dumpster-request

Como você pode ver a seguir, o posicionamento customer217 não tem mais um dispositivo associado.


aws iot1click-projects get-devices-in-placement --project-name SeattleDumpsters --placement-name customer217
{
    "devices": {}
}

Para excluir um posicionamento de um projeto, execute o seguinte comando.
```
aws iot1click-projects delete-placement --project-name SeattleDumpsters --placement-name customer217
```
Como você pode ver a seguir, o projeto SeattleDumpsters não tem posicionamentos porque o posicionamento customer217 era o único posicionamento dentro de SeattleDumpsters.
```
aws iot1click-projects list-placements --project-name SeattleDumpsters
{
    "placements": []
}
```
Para excluir um projeto, execute o seguinte comando.
```
aws iot1click-projects delete-project --project-name SeattleDumpsters
```
Como você pode ver a seguir, todos os projetos são removidos porqueSeattleDumpstersfoi o único projeto associado à sua conta de AWS IoT 1-Click.
```
aws iot1click-projects list-projects
{
    "projects": []
}
```
Se, por exemplo, você quiser permitir que um amigo experimente seu dispositivo usando a conta da AWS dele, primeiro cancele a reivindicação do dispositivo de sua conta do AWS IoT 1-Click, conforme mostrado a seguir.
```
aws iot1click-devices unclaim-device --device-id G030PM0123456789
{
    "State": "UNCLAIMED"
}
```
O dispositivo agora pode ser usado com qualquer conta do AWS IoT 1-Click.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Guia do usuário do botão do AWS IoT Enterprise

ApAWS IoT 1-Click