Configurar enchufe Zigbee TS011F con zigbee2mqtt

Este enchufe con conectividad Zigbee se puede encontrar bajo diversas marcas (Tuya, BlitzWolf o Vikefon). Es un modelo muy compacto, que teóricamente soporta una intensidad de 16A. Está diseñado para funcionar con la aplicación Tuya Smart Life, pero veremos cómo configurarlo para su uso con zigbee2mqtt, lo que abre el paso para su control mediante scripts o programas propios y a la integración plataformas como Home Assistant, pero sin requerir de servicios externos.

Debemos disponer de los siguientes componentes ya instalados y configurados:

• Broker MQTT. En este artículo se explica cómo instalar mosquitto en una Raspberry pi.
• Zigbee2mqtt. La instalación y configuración básica se describen en este artículo

Para emparejar el dispositivo con nuestra pasarela, debemos pulsar el botón de encendido durante 5 segundos. El led del botón se pondrá a parpadear para indicar que está en el modo de emparejamiento. Cuando deja de parpadear puede indicarnos que ha finalizado el emparejamiento o que no ha sido capaz de realizarlo. Según la documentación, se indica que si al dejar de parpadear el led queda en color rojo, significa que el emparejamiento se ha realizado correctamente, y si queda en color azul, significa que el emparejamiento no se ha realizado correctamente. En mi caso el led no se encendía tras el emparejamiento correcto. La forma más clara de verificar el emparejamiento es revisando los logs de zigbee2mqtt. Con la configuración del artículo al que hemos hecho referencia, el log principal es el archivo /opt/zigbee2mqtt/data/logs/zigbee2mqtt.log. Si entramos a nuestra Raspberry pi o servidor que haga de pasarela y consultamos los logs:

tail -f /opt/zigbee2mqtt/data/logs/zigbee2mqtt.log

Veremos en este caso que el emparejamiento ha tenido éxito por el mensaje device has successfully been paired, además de otra información del dispositivo:

Zigbee2MQTT:info  2022-01-20 22:21:39: Device '0xa4c138c495df5e80' joined
Zigbee2MQTT:info  2022-01-20 22:21:39: MQTT publish: topic 'zigbee2mqtt/bridge/event', payload '{"data":{"friendly_name":"0xa4c138c495df5e80","ieee_address":"0xa4c138c495df5e80"},"type":"device_joined"}'
Zigbee2MQTT:info  2022-01-20 22:21:39: Starting interview of '0xa4c138c495df5e80'
Zigbee2MQTT:info  2022-01-20 22:21:39: MQTT publish: topic 'zigbee2mqtt/bridge/event', payload '{"data":{"friendly_name":"0xa4c138c495df5e80","ieee_address":"0xa4c138c495df5e80","status":"started"},"type":"device_interview"}'
Zigbee2MQTT:info  2022-01-20 22:21:39: MQTT publish: topic 'zigbee2mqtt/bridge/event', payload '{"data":{"friendly_name":"0xa4c138c495df5e80","ieee_address":"0xa4c138c495df5e80"},"type":"device_announce"}'
Zigbee2MQTT:info  2022-01-20 22:21:40: Successfully interviewed '0xa4c138c495df5e80', device has successfully been paired
Zigbee2MQTT:info  2022-01-20 22:21:40: Device '0xa4c138c495df5e80' is supported, identified as: TuYa Smart plug (with power monitoring by polling) (TS011F_plug_3)
Zigbee2MQTT:info  2022-01-20 22:21:40: MQTT publish: topic 'zigbee2mqtt/bridge/event', payload '{"data":{"definition":{"description":"Smart plug (with power monitoring by polling)","exposes":[{"features":[{"access":7,"description":"On/off state of the switch","name":"state","property":"state","type":"binary","value_off":"OFF","value_on":"ON","value_toggle":"TOGGLE"}],"type":"switch"},{"access":1,"description":"Instantaneous measured power","name":"power","property":"power","type":"numeric","unit":"W"},{"access":1,"description":"Instantaneous measured electrical current","name":"current","property":"current","type":"numeric","unit":"A"},{"access":1,"description":"Measured electrical potential value","name":"voltage","property":"voltage","type":"numeric","unit":"V"},{"access":1,"description":"Sum of consumed energy","name":"energy","property":"energy","type":"numeric","unit":"kWh"},{"access":3,"description":"Recover state after power outage","name":"power_outage_memory","property":"power_outage_memory","type":"enum","values":["on","off","restore"]},{"access":1,"description":"Link quality (signal strength)","name":"linkquality","property":"linkquality","type":"numeric","unit":"lqi","value_max":255,"value_min":0}],"model":"TS011F_plug_3","options":[{"access":2,"description":"This device does not support reporting electric measurements so it is polled instead. The default poll interval is 60 seconds, set to -1 to disable.","name":"measurement_poll_interval","property":"measurement_poll_interval","type":"numeric","value_min":-1}],"supports_ota":false,"vendor":"TuYa"},"friendly_name":"0xa4c138c495df5e80","ieee_address":"0xa4c138c495df5e80","status":"successful","supported":true},"type":"device_interview"}'
Zigbee2MQTT:info  2022-01-20 22:21:40: Configuring '0xa4c138c495df5e80'
Zigbee2MQTT:info  2022-01-20 22:21:40: Successfully configured '0xa4c138c495df5e80'
Zigbee2MQTT:info  2022-01-20 22:21:44: MQTT publish: topic 'zigbee2mqtt/0xa4c138c495df5e80', payload '{"energy":0,"linkquality":92}'
Zigbee2MQTT:info  2022-01-20 22:21:45: MQTT publish: topic 'zigbee2mqtt/0xa4c138c495df5e80', payload '{"energy":0,"linkquality":89,"state":"OFF"}'

Todos los dispositivos Zigbee tienen un identificador único hexadecimal, que es el nombre que se les asigna por defecto en zigbee2mqtt, pero podemos asignar un friendly_name fácil de recordar, por ejemplo enchufe. Para ello debemos en primer lugar parar el servicio zigbee2mqtt:

sudo systemctl stop zigbee2mqtt

Luego modificamos el archivo configuration.yaml de zigbee2mqtt para especificar el nuevo nombre:

devices:
  '0xa4c138c495df5e80':
    friendly_name: 'enchufe'

y arrancamos el servicio zigbee2mqtt para que haga efecto el cambio:

sudo systemctl start zigbee2mqtt

Ahora podremos hacer pruebas directamente con mensajes MQTT utilizando el topic zigbee2mqtt/enchufe.

La manipulación del enchufe la podemos hacer publicando mensajes en el servidor MQTT en el topic zigbee2mqtt/enchufe/set, incluyendo en el mensaje o payload un texto en formato JSON que tendrá el contenido {"state": "<estado>"}, donde <estado> tendrá diferentes valores según la operación que queramos realizar.

Las llamadas que vemos a continuación se van a realizar desde la propia Raspberry pi donde se está ejecutando zigbee2mqtt y el broker MQTT, de ahí que se utilice localhost en el parámetro -h que indica el nombre o dirección del host MQTT. Si accedemos desde otro equipo tendremos que poner la dirección IP de la máquina donde se esté ejecutando el broker MQTT.

Para encender, el payload deberá ser {"state": "ON"}:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe/set" \
-m '{"state": "ON"}'

Para apagar, el payload deberá ser {"state": "OFF"}:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe/set" \
-m '{"state": "OFF"}'

Para cambiar al estado contrario, el payload deberá ser {"state": "TOGGLE"}:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe/set" \
-m '{"state": "TOGGLE"}'

Este dispositivo admite algunas opciones de configuración que permiten por ejemplo, calibrar las mediciones o indicar cada cuánto tiempo queremos que informe del estado actual. La configuración se realiza a través de las siguientes variables de configuración:

• measurement_poll_interval. Desde el último trimestre de 2021, Tuya ha desactivado el envío automático de la información de potencia, voltaje y corriente. Los dispositivos afectados por esta limitación se detectan como TS011F_plug_3 en lugar de TS011F_plug_1 como ocurría con las versiones previas. Para solucionar esto hay que preguntar (poll) al dispositivo de forma activa para obtener la información. El intervalo entre consultas se puede controlar a través de la variable measurement_poll_intervall. Si no se especifica un valor, no se realiza la consulta de estos valores. Si queremos desactivarla hay que especificar el valor -1.
• power_calibration. Calibra el valor de la potencia, mediante un valor numérico que supone un porcentaje de corrección y que se aplica en la siguiente lectura.
• current_calibration. Calibra el valor de la corriente, mediante un valor numérico que supone un porcentaje de corrección y que se aplica en la siguiente lectura.
• voltage_calibration. Calibra el valor del voltaje, mediante un valor numérico que supone un porcentaje de corrección y que se aplica en la siguiente lectura.

Las opciones se pueden indicar añadiéndolas en el archivo configuration.yaml dentro de la sección devices, en el dispositivo correspondiente, realizando el reinicio del servicio zigbee2mqtt tras el cambio:

devices:
  '0xa4c138c495df5e80':
    friendly_name: enchufe
    measurement_poll_interval: '60'
    power_calibration: 5
    current_calibration: 1
    voltage_calibration: 2

Otra forma de ajustar la configuración del dispositivo es enviar payloads al topic zigbee2mqtt/bridge/request/device/options con el contenido {"id": "<friendly_name>", "options":{"<nombre_opcion>":"<valor>"}}.

Actualización del intervalo de tiempo transcurrido entre medidas a 30 segundos:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/bridge/request/device/options" \
-m '{"id": "enchufe", "options":{"measurement_poll_interval":"30"}}' 

Calibración del voltaje para incrementarlo en un 2%:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/bridge/request/device/options" \
-m '{"id": "enchufe", "options":{"voltage_calibration":"2"}}' 

Calibración de la corriente para incrementarla en un 1%:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/bridge/request/device/options" \
-m '{"id": "enchufe", "options":{"current_calibration":"1"}}' 

Calibración de la potencia para reducirla en un 1%:

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/bridge/request/device/options" \
-m '{"id": "enchufe", "options":{"power_calibration":"-1"}}' 

Para leer los parámetros actuales de estado y consumo del dispositivo podemos utilizar mosquitto_sub, aunque primero tendremos que publicar inicialmente en el topic zigbee2mqtt/<friendly_name>/state el mensaje {"state":""} (a través de mosquitto_pub):

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe/state" \
-m '{"state": ""}' 

Una vez hecho eso, veremos en los logs mensajes con los valores que devuelve el dispositivo:

tail -f /opt/zigbee2mqtt/data/log/zigbee2mqtt.log 

info  2022-02-14 22:30:30: MQTT publish: topic 'zigbee2mqtt/enchufe', payload '{"current":0.14,"energy":0,"linkquality":72,"power":13,"power_outage_memory":null,"state":"ON","voltage":225}'
ltage":225}'

La información recibida es un mensaje JSON con los siguientes parámetros:

• power. Medida instantánea de la potencia. Es un valor numérico cuya unidad es el Watio (W).
• current. Medida instantánea de la corriente. Es un valor numérico cuya unidad es el Amperio (A).
• voltage. Medida instantánea de potencial electríco. Es un valor numérico cuya unidad es el Voltio (V).
• energy. Suma de energía consumida. La unidad de este valor es el Kilowatio-hora (KWh).
• power_outage_memory. Indica el estado de activación en que quedará el echufe tras un corte de luz. Para escribir un valor nuevo, hay que escribir en el topic zigbee2mqtt/<friendly_name>/set un mensaje con el valor {"power_outage_memory": <VALOR>}. Los posibles valores son: on (encendido), off (apagado) y restore (estado anterior).
• linkquality. Fuerza de la señal. El valor mínimo es 0 y el máximo 255. La unidad de este valor es lqi (Link Quality Indicator).

Actualización del estado de activación (power_outage_memory):

mosquitto_pub -h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe/set" \
-m '{"power_outage_memory": "restore"}' 

En los logs podremos ver cómo aparece el valor de éste parámetro:

tail -f /opt/zigbee2mqtt/data/log/zigbee2mqtt.log 

info  2022-02-14 22:48:21: MQTT publish: topic 'zigbee2mqtt/enchufe', payload '{"current":0,"energy":0.01,"linkquality":129,"power":0,"power_outage_memory":"restore","state":"OFF","voltage":230}'

Al margen de los logs, podemos leer los valores de la información que muestra el enchufe utilizando mosquitto_sub con el siguiente comando:

mosquitto_sub -C 1 \
-h localhost -p 1883 \
-u $MQTTUSER -P $MQTTPASS \
-t "zigbee2mqtt/enchufe"

{"current":0.09,"energy":0.01,"linkquality":120,"power":13,"power_outage_memory":"restore","state":"ON","voltage":222}

Disponiendo de un gateway Zigbee y un broker MQTT podemos emparejar un enchufe inteligente, configurarlo y manipularlo a través de la publicación y suscripción a topics MQTT. Esto nos permite gestionar el enchufe desde scripts y consultar detalles de consumo, voltaje y corriente.

• https://www.zigbee2mqtt.io/devices/TS011F_plug_3.html
• https://www.zigbee2mqtt.io/guide/usage/mqtt_topics_and_messages.html