Editing Módulo HM-10

== Módulo HM-10 ==
=== Introducción ===
El HM-10 es un módulo Bluetooth Low Energy (BLE, Bluetooth 4.0 o Bluetooth Smart) basado en los chips de Texas Instruments CC2540 o CC2541.
El fabricante chino  Jinan Huamao Technology es el creador de la placa y el firmware original aunque han salido varios clones como el propio fabricante indica en su documentación (http://www.jnhuamao.cn/bluetooth40_en.zip)

[[File:HM-10-fake.jpg]]

El módulo se puede adquirir también montado sobre una placa (breakout) que expone seis pines macho. Este es el factor de forma más sencillo de integrar en un proyecto si no se quiere soldar (los pines pueden conectarse a un Arduino u a otro microcontrolador por medio de una breadboard o de cables tipo jumper). 

Un aspecto importante de este módulo es que una vez configurado, puede funcionar de forma autónoma sin necesidad de estar conectado a un microcontrolador que lo gestione. Simplemente alimentando el módulo (pines Vcc y GND)

[[File:HM-10.jpg]]

Nota: Este artículo asume un conocimiento básico de la tecnología BLE. En la wiki de Makespace se puede encontrar una buena introducción [[Bluetooth Low Energy]]

=== Alimentación ===
Los chips de Texas Instruments y el módulo básico funcionan a 3.3V con lo que no se pueden conectar directamente a un Arduino (5V). Sin embargo, las placas que exportan 6 pines incluyen también reguladores y conversores de tensión para poder funcionar a 5V con lo que podemos conectarlos a Arduino sin miedo a quemarlos.

=== Funcionamiento básico (emuación conexión serie) ===
El Módulo HM-10 abstrae y empaqueta una conexión Bluetooth Low Energy en una conexión serie. En la configuración "de fábrica" del firmware el módulo se comporta como un periférico BLE que expone un servicio BLE de conectividad (UUID: <code>0000ffe0-0000-1000-8000-00805f9b34fb</code>) que permite la comuniciación entre el módulo y cualquier otro dispositivo central que se conecte a él. Para ello utiliza una característica (UUID: <code>0000ffe1-0000-1000-8000-00805f9b34fb</code>) que almacena una lista de bytes (sin formato) con la siguiente lógica de funcionamiento:
*Cuando el dispositivo central quiere enviar algún dato al módulo, hace un WRITE en la característica con el contenido del dato.
*Cuando el módulo quiere enviar un dato al dispositivo central conectado, envía una NOTIFICATION al dispositivo central.

El módulo HM-10 implementa una conexión serie en los pines 1(TXD) y 2(RXD) que está conectada a nivel lógico con la conexión BLE. Todo lo que le entra por el pin RXD lo envía vía notificaciones al dispositivo central y todo lo que escribe el dispositivo central se saca vía el pin TXD. De esta forma aunque los dos dispositivos (módulo HM-10 y dispositivo central) se están comunicando a través de BLE, de cara al micro que controla el módulo se trata de una simple conexión serie. En el caso de Arduino, está conexión se gestiona como cualquier otra conexión serie utilizando las librerías Serial o SoftwareSerial según los pines de Arduino a los que se conecten los pines TXD y RXD del módulo.

===  Código de ejemplo ===
En este ejemplo empleamos un Arduino Uno que utiliza la consola del IDE para comunicarse vía BLE con una aplicación móvil Android.
El sketch de Arduino sólo conecta el puerto serie de la consola (pines 0 y 1 del Arduino) con el puerto serie "software" al que se conecta el módulo BLE. Cualquier dato que recibe el módulo HM-10 se pasa al puerto serie de Arduino (Serial) para que se muestra en la consola. Del mismo modo, cualquier dato introducido en la consola de Arduino (Serial) se pasa al puerto serie software para que el módulo lo transmita vía BLE a la aplicación Android instalada en el dispostivo central al que está conectado.
Si el módulo BLE no está conectado a ningún dispositivo central, los datos simplemente se pierden.

 #include <SoftwareSerial.h>
 
 SoftwareSerial mySerial(7, 8); // RX, TX
 // Connect HM10      Arduino Uno
 //	 Pin 1/TXD			Pin 7
 //	 Pin 2/RXD			Pin 8
 
 void setup() {
   Serial.begin(9600);
   // If the baudrate od the HM-10 module has been updated you may need to change 9600 by another value
   // Once you have found the correct baudrate you can update it using AT+BAUDx command (AT+BAUD0 for 9600 bauds)
   mySerial.begin(9600);
 }
 
 void loop() {
   char c;
   if (Serial.available()) {
     c = Serial.read();
     mySerial.print(c);
   }
   if (mySerial.available()) {
     c = mySerial.read();
     Serial.print(c);	
   }
 }


Se puede conectar el Arduino con el módulo HM-10 a un teléfono o tablet Android con la aplicación MSMBLE que se puede descargar desde [[https://play.google.com/store/apps/details?id=com.tumaku.msmble&hl=en Google Play]]. Requiere versión Android 4.4 o superior y que el dispositivo implemente BLE. La aplicación permite escanear la presencia de dispositivos BLE y mostrar los servicios y características que implementan. En particular es capaz de detectar módulos HM-10, conectarse a ellos e intercambiar datos por medio del mecanismo explicado en la sección anterior.
 
Para más detalles acerca de la aplicación BLe, el código está disponible en [[https://github.com/jmgjmg/MSMBle github]]

=== Configuración del módulo HM-10 ===
El módulo HM-10 puede configurarse a través de la conexión serie (pines TXD y RXD) por medio de comandos AT. Aunque la documentación del módulo define numerosos comandos, no todos son soportados por la versión que hemos probado del módulo (v 540). Es importante resaltar que los comandos no requieren Salto de línea o Retorno de Carro con lo que si los enviamos utilizando la consola de Arduino, debemos seleccionar la opción  "No hay fin de línea" en el menú desplegable de la parte inferior de la ventana.

Algunos comandos interesantes son:
* <code>AT</code>  simplemente devuelve OK y nos informa de que el módulo está activo y a la espera de nuevos comandos
* <code>AT+ADDR?</code>  devuelve la dirección MAC del módulo HM-10
* <code>AT+VERR?</code>  devuelve la versión actual del firmware
* <code>AT+RENEW</code>  revierte el módulo a la configuración de fábrica
* <code>AT+RESET</code>  reinicializa el módulo
* <code>AT+MODEx</code>  cambia el funcionamiento del módulo de cara al procesamiento de comandos AT
** <code>AT+MODE0</code> (valor por defecto). Sólo acepta comandos AT vía la conexión serie (TXD/RXD) hasta que se conecta un dispositivo BLE central al módulo
** <code>AT+MODE2</code> Igual que el MODE0 pero,una vez establecida la conexión, se pueden enviar comandos AT desde el dispositivo BLE central. Por ejemplo se puede cambiar el valor de uno de los pines GPIO del módulo HM-10 sin necesidad de un micro adicional.
* <code>AT+UUID0xnnnn</code>  cambia el UUID del servicio utilizado por el módulo HM-10 para encapsular la conexión serie (el valor por defecto es 0xFFE1)
* <code>AT+CHAR0xnnnn</code>  cambia el UUID de la característica utilizada por el módulo HM-10 para encapsular la conexión serie (el valor por defecto es 0xFFE1)
* <code>AT+PIOxy</code> (x: 2-B ; y: 0-1) Permite activar el pin GPIO x del módulo HM-10 con el valor y (0 Off; 1 On)- Por ejemplo para encender el GPIO 2 hay que enviar <code>AT+PIO21</code>
Este comando permite por ejemplo controlar un relé desde un dispositivo BLE central (un smartphone) si se configura el módulo HM-10 en modo 2 (ver <code>AT+MODE</code> más arriba)
* <code>AT+BEFCxyz</code> define el valor de los pines GPIO 2 a B cuando el módulo es alimentado (valores permitidos 000 a 3FF). Por ejemplo para que configurar a alto el GPIO2 nada más alimentar el módulo, hay que utilizar el comando <code>AT+BEF200</code>
* <code>AT+NAMExxxxxxxxx</code>  permite cambiar el nombre del módulo
* <code>AT+ROLEx</code> (x: 0-1; 0 periférico; 1 - central; valor por defecto 0) permite definir el rol del módulo HM-10. En el caso de configurar el módulo como un dispositivo central, se pueden utilizar los comandos <code>AT+DISC?</code>, <code>AT+CON</code> y <code>AT+CONN</code> para conectarlo a otro dispositivo periférico

Hay más comandos que permiten configurar y controlar otros parámetros del HM-10. Se recomienda leer la documentación y experimentar con ellos.

A veces algunos comandos cuelgan la conexión serie (no sabemos por qué; desconectando la alimentación del módulo y volviéndola a conectar se puede seguir trabajando con el módulo con la configuración actualizada).

=== Configuración del módulo HM-10 como un dispostivo central === 
El firmware del módulo permite configurarlo como un dispositivo central que se puede conectar a otro dispositivo (periférico) e intercambiar datos vía BLE. Para ello hay que ejecutar los siguientes comandos:
 AT+ROLE1
 AT+IMME1
 AT+RESET

Una vez reseteado el módulo, podemos descubrir dispositivos BLE(periféricos) disponibles y conectarnos a ellos:
 AT+DISC?             (mostrará las direcciones MAC de los periféricos BLE encontrados)
 AT+CONnnnnnnnnnnnn   (dirección MAC en hexadecimal)

Una vez conectados, los dos módulos pueden comenzar el intercambio de información encapsulada en sus respectivas conexiones serie. En principio este mecanismo permite conectar dos módulos HM-10, aunque en teoría serviría para conectar cualquier otro periférico BLE que implemente una característica para intercambio de información usando la funcionalidad Write y Notification (el UUID de la característica se podría configurar con el comando <code>AT+CHAR</code>)
 
Hay que tener en cuenta que en el firmware que hemos probado (versión 540) sólo se transmiten caracteres ASCII (no cualquier código/byte hexadecimal)

Este mecanismo también permite enviar comandos AT desde el módulo central al periférico (requiere haber cambiado previamente el modo con el comando <code>AT+MODE2</code> en el periférico).

=== Configuración del módulo HM-10 como un iBeacon ===
(Esta sección está basada en el tutorial de blueminance http://www.blueluminance.com/HM-10-as-iBeacon.pdf)

 <code>AT+RENEW </code>     Recuperar la configuración por defecto de fábrica
 <code>AT+RESET</code>      Reinicializar el módulo
 <code>AT</code>            Reintentar hasta que le módulo esté listo y responda OK
 <code>AT+MARJ0xnnn</code>  Definir el valor Mayor del iBeacon (hexadecimal)
 <code>AT+MINO0xnnnn</code> Definir el valor Minor del iBeacon (hexadecimal)
 <code>AT+ADVI5</code>      Definir el intervalo de anuncio/broadcast (5 corresponde a 546.25 milisegundos)
 <code>AT+NAMEMakespaceMadrid</code>    Definir el nombre del iBeacon (elegir un valor único)
 <code>AT+ADTY3</code>      Configurar el dispositivo BLE como no conectable
 <code>AT+IBEA1</code>      Habilitar el modo iBeacon
 <code>AT+DELO2</code>      Configurar iBeacon como sólo broadcast
 <code>AT+PWRM0</code>      Habilitar auto-sleep para reducir consumo
 <code>AT+RESET</code>      Reiniciar el módulo

Una vez configurado como iBeacon, el módulo deja de encender el led de la placa y está dormido la mayor parte del tiempo con lo que no responde a los comandos AT
Para despertar el módulo y poder mandarle nuevos comandos AT, hay dos opciones:
* Enviarle una cadena larga (más de 80 bytes) de caracteres sin la cadena AT (repetir varias veces hasta que recibamos de respuesta OK+WAKE.
* Conectar el pin PIO0/System Key (pin BRK en la placa breakout) a tierra/GND durante más de un segundo.

=== Actualización del firmware ===
(Se requiere sistema operativo Windows)

(CUIDADO: si el proceso de instalación del nuevo firmware no termina con éxito, el módulo puede quedar inservible. Si sigues, asumes ese riesgo bajo tu responsabilidad)

Para conectar el módulo HM-10 al PC y reprogramarlo hace falta un adaptador USB a TTL serie (a 3.3V si no utilizamos la placa breakout). Una alternativa que nosotros hemos utilizado es usar una placa Arduino Uno con el chip ATmega en formato "through hole". Si quitamos el chip ATmega de su zócalo, la placa se comporta como un adaptador USB a TTL serie a 5V exponiendo la conexión serie TTL en los pines 0 y 1. Como las placa breakout incluye los reguladores de tensión, podemos conectar directamente el pin 0 y 1 de la placa Arduino a los pines RXD y TXD del módulo HM-10 sin miedo a quemarlos. También hay que conectar los pines GND y 5V de la placa Arduino a los pines GND y VCC de la placa breakout del módulo.

Ahora podemos conectar la placa Arduino al ordenador, abir el Device Manager de Windows y anotar el número de puerto serie/COM que se le ha asignado.

Para actualizar el firmware del módulo HM-10, hay que descargar la última versión disponible de la web de Jinan Huamao Technology (http://www.jnhuamao.cn/download_rom_en.asp?id=)
En esta página hay un manual de instrucciones además de las últimas versiones del firmware para diferentes módulos configuraciones.
Descargar el fichero "HM-10 HMSoft CC254x Vyyy firmware update file". Hay que comprobar (leyendo si hace falta con una lupa) si nuestro módulo integra el chip CC2540 o el CC2541 (las versiones ´más actuales del módulo suelen incluir el CC2541).

Una vez descargado el fichero, desempaquetarlo en una carpeta y ejecutar el programa HMSoft.exe. En el campo Image File seleccionar el fichero HMSoft.bin presente en la misma carpeta. Actualizar también el puerto COM con el valor que hemos obtenido con el Device Manager.

Abrir el IDE de Arduino, seleccionar el puero COM de nuestra placa Arduino y abrir una consola. Configurar los menús desplegables de la parte inferior de la ventana a 9600 baudios y "No hay fin de línea". Si hemos realizado bien las conexiones y nuestro módulo está configurado a 9600 baudios, podemos enviar el comando <code>AT</code> en el campo de entrada de texto y veremos en la caja de texto de salida <code>OK</code>. Para saber la versión actual del firmware podemos enviar el comando <code>AT+VERR?</code>

Una vez llegados a este punto, podemos comenzar el proceso de instalación del nuevo firmware

IMPORTANTE: Si el proceso de instalación de un nuevo firmware no termina con éxito el módulo puede volverse inservible ("bricked"). Conviene realizar todo el prrpoceso sin desconectar el módulo del ordenador hasta que el programa HMSoft indique que ha terminado con éxito.

Para comenzar la instalación, lo primero que tenemos que hacer es informar al módulo por medio de un comando AT enviado desde la consola de Arduino:
 AT+SBLUP

A partir de este momento se enciende el led verde fijo en el módulo con una intensidad baja que indica que el módulo se está reprogramando.
Ahora hay que cerrar la consola de Arduino para liberar el puerto COM y que lo pueda emplear el programa HMSoft. Pulsar "Load Image" en el programa y la descarga al módulo  empezará. Tras un rato, el proceso terminará y el módulo estará listo con la nueva versión (el led verde brillará de modo intenso e intermitente y aparece una ventana de éxito en el PC)

Si ahora abrimos de nuevo la consola de Arduino, podemos mandar el comando <code>At+VERR?</code> para comprobar que la versión del firmware se ha actualizado.

Si el proceso falla y se queda el módulo con el LED verde fijo a baja intensidad, se puede intentar resetear el proceso conectando el pin PIO0 (pin BRK en la placa breakout) a tierra/GND (¡no aseguramos que este mecanismo funcione!).

=== Enlaces interesantes === 
* http://www.jnhuamao.cn/download_rom_en.asp?id=
* http://www.jnhuamao.cn/bluetooth40_en.zip
* http://www.blueluminance.com/HM-10-as-iBeacon.pdf
* http://www.shashankteotia.in/experiments-with-ble-4-0
* http://letsmakerobots.com/node/40237?page=1
* https://punchthrough.com/bean/
* https://github.com/aanon4/BlueBasic/wiki/Getting-started:-Hello-World