Os dispositivos para casas inteligentes da Shelly podem ser consultados de múltiplas maneiras, inclusive através de uma API web que pode ser acedida na Internet com qualquer sistema que efectue ligações HTTP com o método POST, como por exemplo a linguagem R.
Decidi experimentar alguns dos dispositivos da Shelly1, mais por piada do que propriamente por necessidade. Apareceram-me cá em casa em plena pausa Natal/Fim de ano. Como quando acabar a pausa tenho o trabalho final de Computação Estatística em R para fazer, decidi que era uma boa oportunidade para praticar.
Instalação dos dispositivos
Para os primeiros testes mandei vir uma tomada inteligente2 e um monitorizador ambiental de Temperatura e humidade3, 22.30€ e 23.35€ respectivamente na mauser4. A instalação é bastante simples e está descrita nos manuais5,6 que acompanham os produtos. O processo resume-se a instalar a aplicação Shelly Cloud num telemóvel android ou iphone e, depois de criar uma conta, detectar os dispositivos. Todo processo é automático e, se tudo correr bem, não precisa de grande intervenção.
Para podermos aceder aos dispositivos fora de casa, através do site Shelly Cloud, temos de aceitar a opção “connect to cloud” sem a qual o dispositivo só pode ser acedido quando estamos conectados à mesma rede wi-fi que ele.
Após a instalação abrimos https://my.shelly.cloud/ no browser do computador para podermos configurar a API que nos vai permitir ler o estado dos dispositivos no R. Se tudo estiver bem configurado já vemos os dispositivos no site (Figura 1).
Figura 1: My Shelly Cloud com os dispositivos configurdas e fotografia da sala
Dados para acesso à API
A API não precisa de ser activada nem configurada. A partir do momento que aceitamos que o nosso dispositivo se conecte à shelly cloud o sistema fica funcional, só precisamos de o usar.
Para aceder aos dados precisamos de 3 peças de informação:
Os dois primeiros são consultados no user settings (Figura 2).
Figura 2: Página principal do MY Shelly Cloud
Dentro do User Settings, na opção Security \ Autorization Cloud Key temos um botão Get Key que dá acesso à informação que precisamos:
Figura 3: Obter servidor e código de acesso para API
O id do dispositivo é obtido na página de configuração respectiva, que se acede clicando no ícone do dispositivo apresentado na página da sala (Figura 1).
A partir da página do dispositivo, clicamos em Settings e no fim da página abrimos o separador Device Information (Figura 4). O Device ID aparece em hexadecimal e em decimal. Queremos o valor hexadecimal.
Figura 4:Configuração do dispositivo
Resumindo os dados necessários para a consulta:
Link |
https://[servidor indicado na conta] |
Auth_key |
[chave de autenticação da conta] |
Id |
[id do dispositivo] |
Tabela 1: Dados para consulta
Aceder à API
Para aceder à API além dos dados que já temos precisamos de indicar qual a operação a realizar. Podemos ler informação, mas também podemos alterar a configuração dos dispositivos. No nosso caso, só queremos ler o estado e nesse caso usamos o comando device/status. Para uma lista de todas as opções disponíveis podem ler a documentação disponível7,8 no site da Shelly onde podemos consultar, entre outras informações, a informação que a API no fornece:
Figura 5: Atributos devolvidos pela API
Para o nosso caso, interessa-nos o consumo actual (power), o total (diário) e a hora da consulta (timestamp).
Neste momento, temos tudo o que precisamos. O que queremos obter e como lá chegar. Podemos agora ler o estado do dispositivo em R, mas antes vamos experimentar a configuração usando uma ferramenta mais visual onde será mais fácil detectar possíveis erros. Usamos o site https://reqbin.com/. Introduzimos os dados que temos, não esquecendo que o método a usar é o POST, e verificamos os resultados:
Figura 6: Chamada à API do Shelly no site Reqbin
Após um pedido efectuado com sucesso podemos consultar o resultado para confirmar que obtemos os dados indicados na documentação:
Figura 7: Dados obtidos conforme Reqbin
Confirma-se que obtemos o power, o timestamp e o total. Para garantir que estamos a ver a informação certa , é uma boa ideia confirmar os valores obtidos pela API com os valores que o portal indica para o dispositivo, não esquecendo, que como diz a API, o total é em Watts/minuto e o site está em KWatts/hora.
Também podemos ver que existe um campo _updated que não está documentado e que também tem a data de leitura dos dados.
Tudo confirmado e a funcionar, avancemos para o R.
Da Shelly para o R
A magia para colocar o R a ler o dispositivo está na biblioteca httr9 e na sua função POST. Já vimos o que precisamos fazer, agora só precisamos traduzir para R, e dificilmente poderia ser mais simples:
library(httr)
# Carregar variáveis
shellyurl <- “https://shelly-21-eu.shelly.cloud/device/status”
shellybody <- list(auth_key=”NGE4ZDB1*****C43AD1E18C876″,id=”9****8″)
# Executar Pedido
shelly <- POST(shellyurl,body = shellybody,encode = “multipart”)
# Consultar dados obtidos
content(shelly)
Listagem 1:Post à API do Shelly
O código é simples e não me parece que seja necessária qualquer explicação adicional, mas o mesmo não se pode dizer dos dados obtidos. O que obtemos com o content(shelly) é, como seria de esperar e como vimos anteriormente, um sem fim de informação. No entanto nós sabemos o que queremos e só precisamos de procurar por esses campos no resultado:
$data$device_status$`_updated`
[1] “2020-12-25 20:43:59”
$data$device_status$meters[[1]]$power
[1] 82.74
$data$device_status$meters[[1]]$total
[1] 11163
Para obtermos os valores individualmente, só precisamos de concatenar as duas partes, por exemplo, para obter o consumo actual, consultamos:
content(shelly)$data$device_status$meters[[1]]$power
Esta informação já é suficiente para fazer um pequeno programa: vamos ler durante uma hora, minuto a minutos os dados do nosso PlugS:
library(httr)
# Carregar variáveis
shellyurl <- “https://shelly-21-eu.shelly.cloud/device/status”
shellybody <- list(auth_key=”NGE4ZDB1*****C43AD1E18C876″,id=”9****8″)
# Executar Pedido
shelly <- POST(shellyurl,body = shellybody,encode = “multipart”)
# Consultar dados obtidos
content(shelly)
#inicialização de vectores a conter as leituras
datahora <- c()
consumos <- c()
total <- c()
while (length(datahora) < 60)
{
# faz pedido à API
shelly <- POST(shellyurl,body = shellybody,encode = “multipart”)
# guarda dados lidos para vector
datahora <- c(datahora,content(shelly)$data$device_status$`_updated`)
consumos <- c(consumos,content(shelly)$data$device_status$meters[[1]]$power )
total <- c(total,content(shelly)$data$device_status$meters[[1]]$total )
# pausa 1 minuto
Sys.sleep(60)
}
# visualizar resultados
par(mfrow=c(1,2))
plot(total,xaxt=”n”,xlab=”hora”)
axis(1, at=1:60,labels=datahora)
plot(consumos,xaxt=”n”,xlab=”hora”)
axis(1, at=1:60,labels=datahora)
Listagem 2: Ler uma hora de consumos
Gráfico 1: Resultados de 1 hora de consumos
Ler dados de outro tipo de dispositivo passa por um processo idêntico. É só obter o id do dispositivo e consultar a documentação para perceber o que a API disponibiliza. Por exemplo, o código seguinte lê a temperatura e humidade do sensor respectivo:
library(httr)
# Carregar variáveis
shellyurl <- “https://shelly-21-eu.shelly.cloud/device/status”
shellybody <- list(auth_key=”NGE4ZDB1*****C43AD1E18C876″,id=”A****3″)
# Executar Pedido
shelly <- POST(shellyurl,body = shellybody,encode = “multipart”)
# Consultar informação
content(shelly)$data$device_status$`_updated`
content(shelly)$data$device_status$tmp$tC
content(shelly)$data$device_status$hum$value
Listagem 3: Código para ler temperatura e humidade
R e mais além
Esta abordagem de ligar à API a partir do R serve para testes e para situações pontuais mas para projectos reais o ideal é carregar os dados para uma base de dados à qual vamos aceder com o R.
Esse carregamento pode ser efectuado por uma aplicação criada em qualquer linguagem moderna ou até em serviços que dispensam conhecimentos de programação, como por exemplo o Logic Apps10, um dos inúmeros serviços do Azure11. Na Figura 8 está o fluxograma construído para ler a temperatura e humidade do sensor e enviar essa informação por e-mail. O programa é executado com a periocidade indicada na tarefa Recurrence.
Supostamente, é ainda possível ignorar a shelly cloud e colocar os dispositivos a enviarem informação directamente para um serviço web que configuremos para receber a informação. E digo supostamente, porque ainda não testei essa potencialidade.
Como vemos, temos várias alternativas de aceder à informação dos dispositivos, só precisamos de ver a melhor para as nossas necessidades e limitações.
Figura 8: Logic Apps para ler Shelly API
Conclusão
A API da Shelly é de fácil configuração e com acesso completo a toda a informação e configuração dos dispositivos. Por outro lado, a biblioteca httr é de simples utilização. Deu algum trabalho a encontrar e encaixar todas as peças, mas após esse esforço inicial o processo é simples.
1. Home | Shelly Cloud.
https://shelly.cloud/.
2. Shelly Plug S | Shelly Cloud.
https://shelly.cloud/products/shelly-plug-s-smart-home-automation-device/.
3. Shelly H&T | Shelly Cloud.
https://shelly.cloud/products/shelly-humidity-temperature-smart-home-automation-sensor/.
4. Robert Mauser Lda.
https://mauser.pt/.
5. Shelly PLUGS user guide.
https://shelly.cloud/documents/user_guide/shelly_plug_s.pdf.
6. Shelly Humidity and Temperature Sensor H&T user guide.
https://shelly.cloud/documents/user_guide/shelly_ht.pdf.
7. Shelly cloud API access.
https://shelly.cloud/documents/developers/shelly_cloud_api_access.pdf.
8. Shelly Family Overview – API Reference.
https://shelly-api-docs.shelly.cloud/.
9. httr package | R Documentation.
https://www.rdocumentation.org/packages/httr/versions/1.4.2.
10. Serviço de Aplicações Lógicas | Microsoft Azure.
https://azure.microsoft.com/pt-pt/services/logic-apps/.
11. Serviços de Computação na Cloud | Microsoft Azure.
https://azure.microsoft.com/pt-pt/.