Editing Bombilla LED de colores con Bluetooth Low Energy

== Bombilla LED de colores con Bluetooth Low Energy ==
ESTADO: Propuesto para M-Week Feb 2014

Miembros: [[User:tumaku|Javier M.]]

=== Objetivo ===
Controlar una bombilla LED desde internet a través de un móvil

=== Motivación ===
Aprender cómo funciona Bluetooth Low Energy y poder integrarlo después en otros proyectos

=== Antecedentes ===
Tengo una bombilla yeelight comprada en [http://www.seeedstudio.com/depot/Yeelight-Blue-p-1678.html?cPath=81_116 Seeedstudio]. Hay publicado un pseudo [http://www.yeelight.com/download/blue/sdk/ SDK para Android]. 
Las últimas semanas he estado trasteando con Bluetooth Low Energy y el último API de Android. Tras el "Hola mundo", ahora  me gustaría programar algo "de verdad". 

No tengo ni experiencia, ni dispositivos, ni entorno de desarrollo iOS. Si alguien se anima, se puede hacer el mismo proyecto en paralelo para entorno Apple y comparar las plataformas.

Para interactuar con la bombilla, y si da tiempo quiero utilizar el SDK de [http://dwl.twinsprite.com/ twinsprite], una startup de unos amigos que une objetos virtuales y objetos físicos.


=== Métodos y técnicas utilizadas ===
* Bombilla yeelight
* Bluetooth Low Energy
* Android (+ iOS?)
* API de twinsprite


=== Detalles ===

Tras leer el código, esto es todo lo que hay que saber para controlar la bombilla yeelight (color en formato RGB e intensidad de 0 a 100):

    public static final String YEELIGHT_SERVICE = "0000fff0-0000-1000-8000-00805f9b34fb";
    public static final String CHARACTERISTIC_CONTORL = "0000fff1-0000-1000-8000-00805f9b34fb";
    data = r + "," + g + "," + b + "," + bright + ","
    // 30 2C 31 30 38 2C 36 30 2C 38 34 2C 2C 2C 2C 2C 2C 2C
 	
    // 128,1,0,50,,,,,,,,
    // 31 32 38 2C 31 2C 30 2C 35 30 2C 2C 2C 2C 2C 2C 2C 2C
 	
    characteristic.setValue(data.getBytes());
    gatt.writeCharacteristic(characteristic);


Dicho y hecho. Realmente sólo hace falta ese código y cuatro días de eclipse, android, stackoverflow y makespace para conseguirlo!!!
Aunque escribiré un tutorial más detallado sobre el proyecto, aquí resalto algunos puntos importantes:

* He utilizado el IDE de eclipse compilando para el API19 de Android (4.4.2) que es el disponible en Nexus 7
* Recomiendo la documentación creada por Yeelight y compartida desde su web [http://www.yeelight.com/en_US/info/download]. En el API de Android hay código fuente aunque por desgracia todavía no hay una app de ejemplo. El servicio de soporte técnico de Yeelight es muy bueno y responde rápido :-)
* Para aprender como funciona Bluetooth Low Energy en Android, el mejor tutorial y código que he encontrado es el de Dave Smith [http://www.doubleencore.com/2013/12/bluetooth-smart-for-android/] con código fuente en [https://github.com/devunwired/accessory-samples/tree/master/BluetoothGatt]
* Bluetooth Low energy (BLE) implementa el concepto de cliente y servidor. En el caso de la bombilla Yeelight, la bombilla es un servidor que ofrece sus servicios (control del color e intensidad de la bombilla) y el dispositivo android (Nexus 7) es el cliente que hace peticiones a este servicio (encender el color naranja con intensidad 50%).
* Simplificando mucho, un servicio BLE se compone de una serie de características. Las características no son más que un conjunto de bytes que se pueden escribir o leer según unas propiedades que se especifican en el servicio (por ejemplo,hay que autenticarse antes de leer, los datos se encriptarán,...). Las características también pueden implementar el concepto de notificación. Cuando una caracterítica cambia de valor, informa a todos los clientes que se hayan registrado a sus notificaciones (no hace falta hacer polling desde el cliente, será el servidor quién haga un push cuando haga falta). 
* El flujo de una aplicación BLE en Android es es siguiente.
# Obtener el adaptador Bluetooth de Android para poder acceder a la funcionalidad BLE
# Escanear/Buscar dispositivos BLE (servidores) disponibles en el entorno (este escaneo tiene que ser limitado en el tiempo) por medio de la función <code>startLeScan()</code>. Tras unos segundos, parar el escaneo a través de la función <code>stopLeScan()</code>. Este proceso genera eventos <code>onLeScan()</code> para cada dispositivo detectado.
# Para descubrir los servicios que ofrece un dispositivo hay que utilizar el servicio GATT de BLE(''The GATT profile is a general specification for sending and receiving short pieces of data known as "attributes" over a BLE link. All current Low Energy application profiles are based on GATT.'') La mayoría de funciones de GATT funcionan en modo asíncrono, esto es, se hace una petición (por ejemplo, para leer el valor de una característica se utiliza: <code>mGatt.readCharacteristic(characteristic)</code>) y la respuesta se recibe a posteriori en otra función a través de un mecanismo de ''callback'' definido en el API BLE de Android (en el caso anterior, <code>onCharacteristicRead()</code> )
En el proyecto se han utilizado los siguientes comandos de GATT:
# <code>connect()</code> para conectarse al dispositivo desde el cliente. Genera el callback <code>onConnectionStateChange()</code>
# <code>discoverServices</code> para descubrir los servicios y características disponibles en un dispositivo. Genera el callback <code>onServicesDiscovered</code>
# <code>readCharacteristic()</code> para leer el valor de una característica. El valor de la caracteristica en el deispositivo es recibido por el cliente en el callback <code>onCharacteristicRead()</code>
# <code>writeCharacteristic()</code> para leer el valor de una característica. El resultado (éxito, error) de la operación de escritura  en el servidor lo recibe el cliente a través del callback <code>onCharacteristicWrite()</code>
# <code>discconnect()</code> para desconectar el cliente del dispositivo servidor.
# La bombilla Yeelight impementa un servicio propietario pero perfectamente documentado. Su identificador (UUID en terminología BLE) es:
 public static final String YEELIGHT_SERVICE = "0000fff0-0000-1000-8000-00805f9b34fb";
# El color de la bombilla y su intensidad se controla a través de una única característica:
 public static final String CHARACTERISTIC_CONTROL = "0000fff1-0000-1000-8000-00805f9b34fb";
# Esta característica almacena un vector de 18 bytes en ASCCI según el formato ya descrito en la introducción del proyecto:
    data = r + "," + g + "," + b + "," + bright + ","
    // 30 2C 31 30 38 2C 36 30 2C 38 34 2C 2C 2C 2C 2C 2C 2C
 	
    // 128,1,0,50,,,,,,,,
    // 31 32 38 2C 31 2C 30 2C 35 30 2C 2C 2C 2C 2C 2C 2C 2C