Nociones básicas sobre la API eedomus

En un artículo que publicamos hace unos meses en Domótica Doméstica, os hablamos de la posibilidad de usar scripts en la plataforma eedomus. En otro post muy reciente, nos hemos referido a una nueva forma de exportar los datos estadísticos de nuestros periféricos Z-Wave a Google Drive a través de la plataforma IFTTT.

Para llevar a cabo cualquiera de estos dos proyectos, necesitamos saber lo que es la API eedomus y cómo utilizarla. Cuando usamos nuestra cuenta o la aplicación móvil de eedomus, obtenemos los valores de nuestros distintos periféricos domóticos (temperatura en un momento preciso, apertura de una puerta, humedad, etc.) a través de la interfaz gráfica. Pero esos valores que aparecen en pantalla no los podemos explotar de ninguna otra manera, sólo los podemos consultar.

Si pretendemos exportar esos valores o crear un script basado en ellos, no tenemos otra opción que recurrir a la API eedomus. En este artículo, vamos a explicar algunas nociones básicas sobre la API eedomus para poder usarla a posteriori en proyectos más ambiciosos.

¿Qué es la API eedomus?

La API eedomus es una interfaz de programación que ofrece todo un abanico de funciones que permiten explotar y procesar los datos de nuestra cuenta eedomus.

La API permite no sólo obtener los datos de nuestros módulos domóticos, sino también controlar nuestros periféricos como si lo hiciéramos desde la interfaz gráfica.

Por tanto, con esta API en tiempo real podemos desarrollar aplicaciones para ampliar las funcionalidades de nuestro controlador eedomus.

La API eedomus está basada en el protocolo https, lo que significa que las URL’s que usamos (que contienen nuestras credenciales) están cifradas. Tambien es posible usar el protocolo http, aunque es menos recomendable por cuestiones de seguridad (para usar http, hay que ticar la opción correspondiente en “Configuración/Mi cuenta/Parámetros”).

¿Cuáles son los requisitos para usar la API de eedomus?

• Autenticación

Para acceder a las funciones de la API eedomus, ni que decir tiene que nos tenemos que identificar, pero para ello no podemos usar las credenciales de nuestra cuenta eedomus sino unas credenciales especiales llamadas “api_user” y “api_secret”.

Para obtener esas credenciales específicas para la API, debemos acceder a nuestra cuenta eedomus, ir a Configuración/Mi Cuenta/Paramétros, y pinchar en “API eedomus: ver sus credenciales”, tras lo cual, por seguridad, la plataforma nos pedirá que introduzcamos de nuevo la contraseña de nuestra cuenta eedomus.

Una vez hecho lo anterior, se abrirá una ventana nueva donde podremos ver nuestras “api_user” y “api_secret” así como breves explicaciones sobre cómo usar la API tanto a través del portal eedomus como a través de la red local, junto con una herramienta básica para comprender cómo se construyen las URL’s que deberemos usar para llamar a la API.

• Código API de cada periférico

Cada vez que añadimos un módulo domótico a nuestro controlador eedomus, éste le asigna un código único llamado “Código API”. Es importante que conozcamos el código de cada uno de nuestros dispositivos ya que para controlar esos módulos a través de la API eedomus o para obtener y exportar sus valores, tendremos que indicarlo en la URL correspondiente.

Para conocer el código API de cada periférico es muy sencillo. Nos iremos, en nuestra cuenta de eedomus, a Configuración, pulsaremos en el módulo correspondiente y luego en “Configurar”, tras lo cual se abrirá la típica ventana de configuración de periféricos que ya conocemos. Desplegaremos la sección “Parámetros expertos” y ahí veremos el código API del periférico en cuestión.

Formato de las llamadas http

Para llamar a la API eedomus, debemos usar URL’s con un formato muy concreto que debemos conocer, con una parte que podríamos calificar como “fija” y otra que cambia según la función y los parámetros que usemos y el dispositivo con el que queramos interactuar.

Si accedemos a la API a través del portal eedomus (desde otro servicio web u otro dispositivo, por ejemplo), el formato es el siguiente:

[plain]https://api.eedomus.com/[request_type]?action=[service.action]&[parameters]

Donde:

• [request_type]: Tipo de llamada http
• [service.action]: Acción que queramos ejecutar en el servicio especificado
• [parameters]: Parámetros obligatorios u opcionales necesarios para el servicio especificado[/plain]

Y si accedemos a la API desde nuestra red local, el formato es como sigue:

[plain]http://IP_LOCAL_EEDOMUS/api/[request_type]?action=[service.action]&[parameters]

Observaciones:

• En red local sólo podemos usar http, no https.
• Sí la llamada http se hace desde el propio controlador eedomus, a través de un actuador http, podemos obviar los parámetros “api_user” y “api_secret”[/plain]

Formato de las respuestas

Las respuestas a las llamadas http que recibe la API se hacen en formato JSON, que es un formato ligero de archivo para el intercambio de datos.

Veamos un ejemplo de respuesta a una llamada http sencilla basada en el servicio “auth.test” que sirve para hacer una prueba que nos confirme que una llamada http a la API eedomus funciona correctamente:

[plain]Llamada http:

https://api.eedomus.com/get?api_user=xxxxxx&api_secret=XXXXXXXXXXXXXXXX&action=auth.test

Respuesta:

{ “success”: 1 }[/plain]

Obviamente, podemos obtener respuestas mucho más largas y con más parámetros, en función de la llamada http que realicemos. En cualquier caso, el campo “success” está en cualquier respuesta, sea más o menos larga. El valor 1 indica que se ha completado con éxito la llamada http, y el valor 0 que ha habido errores, en cuyo caso la respuesta contiene explicaciones acerca de los errores encontrados.

Funciones de la API eedomus

La lista de funciones disponibles no es la misma si llamamos a la API a través del portal eedomus que si lo hacemos en red local, ya que en este último caso el numero de funciones es menor.

Si hacemos uso de la API eedomus a través de nuestra red local, sin pasar por el portal eedomus, las funciones que tenemos disponibles actualmente son las siguientes:

• get -> auth.test: Sirve para realizar una prueba de autenticación en la API
• get -> periph.caract: Sirve para obtener las características básicas de un periférico
• get -> periph.list: Sirve para obtener un listado completo de todos los periféricos incluidos en nuestra cuenta
• get -> periph.value_list: Sirve para obtener una lista con los valores possibles de un periférico (solo disponible para periféricos de tipo “lista”)
• set -> periph.value: Sirve para establecer un valor concreto en un periférico, ya sea un sensor o un actuador
• set -> periph.macro: Sirve para activar una macro en un periférico

Si usamos la API a través del portal de eedomus, tenemos a nuestra disposición todas las funciones que acabamos de ver y además la siguiente:

• get -> periph.history: Sirve para obtener los datos estadísticos de valores de un periférico

En este artículo no pretendemos hacer un manual de uso exhaustivo de la API eedomus, sino sentar las bases para entender su funcionamiento, por lo que no vamos a entrar en los detalles de cada función.

Si queréis obtener información detallada sobre cada una de las funciones de la API eedomus, el formato de las llamadas http para cada una de ellas, las respuestas, etc., os recomiendo que consultéis el artículo dedicado a la API en la Wiki de eedomus (en francés).

Y también os recomiendo la lectura de un artículo anterior de Domótica Doméstica sobre cómo controlar periféricos en eedomus a través de llamadas http, que tiene mucho (todo) que ver con la API.

Ejemplo concreto

Antes de terminar, vamos a dar un ejemplo concreto de cómo usar la API eedomus. Pongamos que queremos conocer los valores históricos de un periférico determinado, con las siguientes premisas:

• Código API del periférico = XXXX
• Fecha y hora a partir de las cuales queremos obtener los valores = YYYY-MM-DD HH:MM:SS
• Fecha y hora hasta las cuales queremos obtener los valores = YYYY-MM-DD HH:MM:SS
• Nuestra api_user = YYYY
• Nuestra api_secret = ZZZZ

La URL que deberíamos usar en este caso concreto es la siguiente (hemos señalado en rojo los parámetros indicados en nuestras premisas, que son los que debemos adaptar a nuestro caso concreto):

[plain]https://api.eedomus.com/get?action=periph.history&periph_id=XXXX&start_date=YYYY-MM-DD HH:MM:SS&end_date=YYYY-MM-DD HH:MM:SS&api_user=YYYY&api_secret=ZZZZ[/plain]

Con esta llamada http, obtendríamos la siguiente respuesta:

[plain]{
“success”: 1,
“body”:
{
“history”:
[
[“69″,”2010-02-12 14:35:50”],
[“69″,”2010-02-12 14:35:50”],
[“87″,”2010-04-03 19:36:38”],
[“82″,”2010-04-03 20:06:47”],
[“87″,”2010-04-03 21:07:03”],
[“81″,”2010-04-03 23:17:36”],
[“87″,”2010-04-03 23:47:43”],
[“76″,”2010-04-04 01:18:13”],
[“81″,”2010-04-04 01:38:18”],
[“87″,”2010-04-04 03:40:10”],
[“93″,”2010-04-04 06:40:59”]
]
}
}[/plain]

Esa llamada http la podemos hacer con cualquier dispositivo o aplicación que lo permita, desde un simple navegador de Internet hasta un dispositivo externo pasando por IFTTT. Sólo nos quedaría “tratar” la respuesta adecuadamente para poder explotar los datos que contiene.

Esperamos que este artículo os haya ayudado a adquirir conocimientos básicos sobre el funcionamiento y el uso de la API eedomus. Ahora ya estamos preparados para emprender proyectos concretos basados en la API eedomus.