Nociones básicas sobre la API eedomus

    • En este artículo, explicamos de forma sencilla qué es y cómo funciona la API eedomus para poder usarla en proyectos avanzados como la creación de scripts.

    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.

    Valores de distintos periféricos en la interfaz gráfica de eedomus

    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.

    Obtención de las credenciales de la API de eedomus

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

    Obtención del código API de cada dispositivo en eedomus

    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:

    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

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

    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”

    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:

    Llamada http:

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

    Respuesta:

    { “success”: 1 }

    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):

    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

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

    {
    “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”]
    ]
    }
    }

    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.

    Philippe

    Madrileño de adopción. Tecnófilo. Podcaster. Obsesionado por la domótica. Y unas cuantas cosas más, casi todas buenas. Keywords: viajes, libertad, amistad, amor, tecnología, pasión, equilibrio...


    4 Respuestas

    1. Santiago dice:

      Muy buen artículo como siempre, da gusto entre el blog y el foro el “soporte” que tenemos para la domótica DIY.

      Compré Eedomus hace 3 semanas y es ahora cuando estaba pensando en ir probando las API.

      Una idea que se me ha ocurrido mientras leía el artículo es el hacer una página web en local en casa para poder acceder a Eedomus localmente y tener el diseño algo más “atractivo”. Una de las dudas es que si pierdes la conexión a internet en casa o los servidores de eedomus se caen… ¿es accesible eedomus localmente?

      Pero la verdad es que la API abre mucho las puertas para bastantes opciones.

      • Philippe dice:

        En efecto, perfectamente se debería poder hacer una interfaz web más atractiva a través de la API. La API es abierta para un uso no comercial. Si bien es cierto que la interfaz web no es de las más atractivas, piensa que tiene muchas opciones de personalización y que por ahí se puede mejorar. Por otra parte, si buscas una interfaz bonita y altamente personalizable, te recomiendo la App para Android Imperihome, si no la conoces ya, aunque sólo te servirá para controlar tu eedomus, no para configurar periféricos.

        Si, eedomus es accesible localmente. Es un sistema parcialmente basado en la nube. De hecho, cuando te conectas a tu eedomus a través de la aplicación móvil, la App mira si estás en red local o no. Si estás en red local, accede directamente al controlador y éste es quien comunica los cambios al servidor. En cambio, si no estás en red local, la app se conecta a tu eedomus a través de los servidores de la plataforma. Si te quedas sin Internet, tu eedomus sigue funcionando ya que las reglas/escenas están almacenadas en local y además, como te digo, a través de la App o de un navegador de Internet (mediante lo que se llama el portal de emergencia) puedes acceder en local y controlar perfectamente tu instalación. En cambio, si no tienes Internet, no puedes añadir nuevos periféricos ni cambiar la configuración. Por otra parte y como es lógico, si tienes reglas/escenas basadas en servicios web (meteorología, hora de amanecer/anochecer, fecha, etc.), esas escenas no funcionan si no tienes acceso a Internet.

        Saludos.

    2. Margu dice:

      Yo uso la api con una tableta android. Mediante tasker si la batería esta a un 15% enciendo el enchufe donde esta la tableta y esta se carga. Al llegar al 100% de batería apaga el enchufe.

    Deja un comentario

    Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *