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:

• O servidor a consultar
• O código de autorização para aceder aos dispositivos da nossa conta
• O id do dispositivo

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/.

.