Probamos el nuevo termostato Lyric T6 de Honeywell – Extra API Honeywell

por · 17/03/2017

  • En este artículo extra vamos a explicaros cómo utilizar la API de Honeywell para realizar consultas y enviar órdenes desde eedomus.

Lo prometido es deuda, así que tras una introducción en la anterior entrega sobre lo que es la autenticación OAuth, ahora vamos a ver en detalle los pasos a seguir para poder integrarlo en eedomus. Esto es algo no solamente aplicable al termostato de Honeywell y eedomus, muchos APIs utilizan este sistema de autenticación, por lo tanto siempre vendrá bien conocer el proceso que conlleva.

Antes de nada, comentar que para hacer posible esta integración, vamos a necesitar un servidor intermedio tipo Raspberry. Si, nuevamente una Raspberry podrá hacer de enlace entre nuestro controlador y otro objeto conectado. Como veis, la Raspberry es de lo más versátil. También nos puede valer un NAS o algún ordenador que tengamos siempre encendido y cumpla los requisitos software.

Los requisitos a nivel software para que funcione no son muchos, básicamente necesitaremos que tenga un servidor web (apache o similar), php y cURL, servicios que suelen venir instalados encima de cualquier distribución. Ya está, con esto ya deberíamos tener cubiertos los requisitos.

raspberry apache y php

Página de desarrolladores de Honeywell

El paso para realizar esta integración sería darse de alta en la página de desarrolladores de Honeywell. Para ello vamos a “SIGN UP” y rellenamos el cuestionario (nombre, apellido, usuario, email y password).

Una vez nos hayamos dado de alta, el siguiente paso es crear una aplicación. Tranquilos, vamos a ir viendo paso por paso cómo hacerlo.

Primero vamos a “CREATE NEW APP”. Necesitaremos darle un “App Name” (en mi caso utilicé “TEST_LYRIC” y así se quedó) y lo que se denomina una “Callback URL” (aquí puse un dominio que tengo en casa, pero tranquilos, no es necesario y podréis poner por ejemplo la dirección IP que tengáis en ese momento, o simplemente vuestra IP privada).

portal de desarrollo

Una vez creada la aplicación, ésta tiene que ser validada, aunque por lo general es un proceso automático y aparecerá como tal al instante. Al pinchar sobre nuestra aplicación ya tendremos una serie de valores, necesitamos los dos primeros:

  • Consumer Key (esto es lo que se conoce también como la API Key)
  • Consumer Secret

Ahora vamos a necesitar realizar una serie de peticiones para obtener los datos que utilizaremos más adelante. Para realizar alguna de estas peticiones podemos hacer uso del comando “cURL”, presente en linux, MacOS o si tenéis Windows hay una versión disponible.

Petición de autorización: 

Esta petición la realizaremos desde nuestro navegador escribiendo la siguiente dirección:

https://api.honeywell.com/oauth2/authorize?response_type=code&client_id={apikey}&redirect_uri={redirectUri}

Sustituiremos {apikey} por la Consumer Key obtenida anteriormente y {redirectUri} por la dirección que pusisteis en “Callback URL” para crear la aplicación. Una llamada real quedaría así:

https://api.honeywell.com/oauth2/authorize?response_type=code&client_id=nGXAdSsDCskEdSc6fGFVqpohGAeVz&redirect_uri=https://192.168.1.11

Esta petición lo que hará será redirigir hacia la Callback URL el código que necesitamos. En pantalla veremos un error. Es normal, lo que nos interesa es coger el código que hay en la petición (eGTEmbl5). Para verlo vamos a la barra del navegador y seleccionamos el texto, será algo como esto:

https://192.168.1.10/?code=eGTEmbl5&scope=

Conseguimos el “Authorization Code”

Tenemos que concatenar la ConsumerKey y la ConsumerSecret añadiendo dos puntos entre medias. Por ejemplo, si nuestra ConsumerKey es AAA y la ConsumerSecret es BBB, el valor sería AAA:BBB. Ahora esto debemos pasarlo a base64, podemos hacerlo en cualquier utilidad online como la que tenemos en esta página o si tenemos un dispositivo con linux, con el comando “base64”.

Una vez tenemos el valor concatenado en base64, tenemos que hacer la primera llamada desde un dispositivo con cURL, como por ejemplo linux:

curl -X POST -H "Authorization: Basic {VALOR_CONCAT_BASE64}" -H "Accept: application/json" -H e: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code={CODE}&redirect_uri={REDIRECT_URI}" "https://api.honeywell.com/oauth2/token"

Los cambios para realizar la petición son los siguientes:

  • {VALOR_CONCAT_BASE64} -> Por el valor que hemos obtenido al concatenar y pasar a base64.
  • {CODE} -> Por el código obtenido en el paso anterior (eGTEmbl5 en nuestro ejemplo).
  • {REDIRECT_URI} -> Por la “Callback URL” que pusimos al crear la aplicación.

Ejemplo de petición final:

curl -X POST -H "Authorization: Basic bkFlVno6NHB2OWXpwMnpJNmZHdOVdXNmROWW0yVYQU0nVaWRlZxcG9oRNmg==" -H "Accept: application/json" -H e: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=eGTEmbl5&redirect_uri=https%3A%2F%2F192.168.1.11" "https://api.honeywell.com/oauth2/token"

Como resultado obtendremos tres valores:

{"access_token":"RwcID5ToFOmxnan00KQQdKWrGlJX","refresh_token":"qTbl42iSRNCI6993rnU2qM8bW06Zjtdk","expires_in":"599"}

El access_token, el refresh_token y expires_in, que no es más que el tiempo que queda para que expire el access_token. En nuestro caso son 10 minutos desde que lo solicitamos. Aquí lo realmente importante es el refresh_token, que será el código que nos permita generar nuevos access_token cuando estos caduquen o incluso antes de que lo hagan.

Buscar el locationID y deviceID

Por último necesitamos otro par de datos, el locationID y el devideID de nuestro termostato. Los obtendremos pidiendo:

curl -H "Authorization: Bearer {REFRESH_TOKEN}" https://api.honeywell.com/v2/locations?apikey={API_KEY}

Ejemplo:

curl -H "Authorization: Bearer LLjnmraQGRmy8BEg7GGtDt1raDWc" https://api.honeywell.com/v2/locations?apikey=dkssdhcASfasfsFsASGYBQT

Donde el “Authorization: Bearer” es el refresh_token y la apikey es la consumerKey que nos proporcionaron al crear la aplicación. Como resultado tendremos los datos de nuestro termostato y configuración actual. Vamos a coger los siguientes valores:

"locationID": 122602,

"deviceID": "LCC-00D02DB3310F",

Bien, ya tenemos todos los valores que necesitaremos para automatizar el proceso de consulta y envío de cambios al termostato. Vamos a repasar todos los que nos hacen falta:

  • $api_key (es la Consumer Key del registro)
  • $api_secret (es la Consumer Secret del registro)
  • $refresh_token (obtenido en el paso anterior)
  • $deviceID (obtenido en este paso)
  • $locationId (obtenido en este paso)

Scripts

Ahora que tenemos todos los datos necesarios, los vamos a añadir en el siguiente script, con el que podremos realizar las siguientes acciones:

  • Consultar todos los valores del termostato
  • Apagar el termostato
  • Encender el termostato
  • Seleccionar la temperatura
<?php

// Control de la API de Honeywell para Lyric T-Series
// Carlos Fernandez - domoticadomestica.com

// User data
$api_key = 'VUESTRA_API_KEY';
$api_secret = 'VUESTRA_API_SECRET';
$deviceID = 'VUESTRO_DEVICE_ID';
$locationId = 'VUESTRO_LOCATION_ID';
$refresh_token = "VUESTRO_REFRESH_TOKEN";

// Global variables
$postvals = "grant_type=refresh_token&refresh_token=$refresh_token";
$token_url = 'https://api.honeywell.com/oauth2/token';
$base_url = 'https://api.honeywell.com/v2/devices/thermostats';
$full_url = "$base_url/$deviceID?apikey=$api_key&locationId=$locationId";
$mode = $_GET["set"];
$temp = $_GET["temp"];

// Refresh token
$ch = curl_init("$token_url");
$options = array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_POSTFIELDS => $postvals,
    CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
    CURLOPT_USERPWD => $api_key .":". $api_secret
);
curl_setopt_array($ch, $options);

$api_response = curl_exec($ch);
$response = json_decode($api_response);
curl_close($ch);

function on() {
        global $full_url;
        global $response;
        $token = $response->access_token;
        $data = array(
                "mode" => "Heat",
                "heatSetpoint" => 20.5,
                "coolSetpoint" => 74,
                "thermostatSetpointStatus" => "NoHold"
        );
        $data_string = json_encode($data);
        $ch = curl_init("$full_url");
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                'Authorization: Bearer ' .$token,
                'Content-Type: application/json'));
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
        $result = curl_exec($ch);
        curl_close($ch);
}

function off() {
	global $full_url;
	global $response;
	$token = $response->access_token;
	$data = array(
		"mode" => "Off",
                "heatSetpoint" => 20.5,
                "coolSetpoint" => 74,
                "thermostatSetpointStatus" => "TemporaryHold"
	);
	$data_string = json_encode($data);
	$ch = curl_init("$full_url");
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(
		'Authorization: Bearer ' .$token,
		'Content-Type: application/json'));
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
	$result = curl_exec($ch);
	curl_close($ch);
}

function change_temp() {
	global $temp;
        global $full_url;
        global $response;
        $token = $response->access_token;
        $data = array(
                'mode' => 'Heat',
                'heatSetpoint' => $temp,
                'coolSetpoint' => 74,
                'thermostatSetpointStatus' => 'PermanentHold'
        );
        $data_string = json_encode($data);
        $ch = curl_init("$full_url");
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                'Authorization: Bearer ' .$token,
                'Content-Type: application/json'));
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
        $result = curl_exec($ch);
        curl_close($ch);
}


if ($mode == 'on') {
    on();
    exit;
}
elseif($mode == 'off') {
    off();
    exit;
}
elseif (isset($temp)) {
    change_temp();
    exit;
}

// Get Lyric
$ch = curl_init("$full_url");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' .$response->access_token));

$result = curl_exec($ch);
curl_close($ch);

?>

Sólo tendréis que copiar el script de arriba y rellenar los datos bajo “User Data”:

// User data
$api_key = 'VUESTRA_API_KEY';
$api_secret = 'VUESTRA_API_SECRET';
$deviceID = 'VUESTRO_DEVICE_ID';
$locationId = 'VUESTRO_LOCATION_ID';
$refresh_token = "VUESTRO_REFRESH_TOKEN";

Una vez cambiado el script con vuestros datos, debéis subirlo a vuestra raspberry o servidor NAS con el nombre lyric.php. En Raspberry sería en la ruta: /var/www/html/ y en un NAS Synology en /volume1/web/

La forma de invocar al script será la siguiente:

  • http://<IP_RASPBERRY>/lyric.php -> Obtener todos los datos del termostato.
  • http://<IP_RASPBERRY>/lyric.php?set=on -> Encender
  • http://<IP_RASPBERRY>/lyric.php?set=off -> Apagar
  • http://<IP_RASPBERRY>/lyric.php?temp=21.5 -> Poner la calefacción a 21.5º

Creación de los distintos periféricos en nuestro controlador eedomus

En esta sección vamos a crear un par de tipos de dispositivos. El primero nos permitirá actuar sobre el termostato, de forma que podremos encenderlo, apagarlo o variar su temperatura (e incluso la programación y sus modos). El segundo tipo de dispositivo será para realizar la lectura de los parámetros del termostato, como temperatura, demanda, estado, humedad, etc.

pantalla de eedomus

Encender/Apagar o cambiar la temperatura:

  • Crear dispositivo tipo: HTTP – Actuador
  • Nombre personalizado: Lyric
  • Uso: Calefacción

Valores:

configuración acciones en eedomus

*En los valores de la imagen superior, están ocultos los valores entre 18,5º y 23,5º para reducir el tamaño de la imagen.

 

Lectura de la temperatura del termostato

  • Crear un dispositivo tipo: HTTP – Sensor

lectura temperatura eedomus

URL de llamada: Sustituir “192.168.1.11” por la IP de tu Raspberry o servidor web.

Lectura de la demanda de calefacción: (mismos valores salvo los siguientes)

  • Nombre personalizado: Lyric demanda
  • Ruta XPATH: /root/heatAndCoolDemand/demand

Lectura de la temperatura exterior: (mismos valores salvo los siguientes)

  • Nombre personalizado: Lyric temperatura exterior
  • Ruta XPATH: /root/outdoorTemperature

Lectura de la temperatura de consigna: (mismos valores salvo los siguientes)

  • Nombre personalizado: Lyric consigna
  • Ruta XPATH: /root/changeableValues/heatSetpoint

Lectura del estado del termostato: (mismos valores salvo los siguientes)

  • Nombre personalizado: Estado Lyric
  • Ruta XPATH: /root/operationStatus/mode

Valores:

  • EquipmentOff -> Sin calentar
  • Heat -> Calentando

 

Hasta aquí este tutorial para integrar el termostato Lyric T6 en eedomus, espero que os haya resultado útil.

Como os comenté al principio, el script puede ser utilizado en otros sistemas domóticos, directamente si disponen de PHP+cURL+Servidor web o indirectamente utilizando un equipo intermedio como en el ejemplo de hoy.

 

Etiquetas:

Carlos Fernández

Informático en el mundo de las telecomunicaciones y gran apasionado de las tecnologías, el mundo Apple y la domótica.


Deja una respuesta

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

Sígueme:

Si eres profesional y te quieres formar en Jeedom: