Integración domótica SwitchBot, gratuita y de código abierto
Dispositivos SwitchBot por la API oficial en la nube: bots, enchufes, cortinas, cerraduras, luces.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Controle sus dispositivos SwitchBot desde Gladys con la API oficial en la nube de SwitchBot (v1.1): bots, enchufes, cortinas y persianas, cerraduras, termómetros, sensores de apertura, de movimiento y de fugas de agua, luces, humidificador, purificador de aire, ventiladores, aspiradoras robot y los mandos infrarrojos de sus hubs.
Desarrollada sin el hardware: se agradecen los comentarios. Esta integración se ha construido y probado con las respuestas documentadas por SwitchBot y con los datos de prueba de la integración de Home Assistant, no con dispositivos físicos ni con una cuenta SwitchBot real. Si algo no funciona como se describe, indíquelo en el foro de Gladys o en las issues.
Sin relación con SwitchBot (Wonderlabs). SwitchBot es una marca de su propietario.
Lo que necesita
- Gladys Assistant 5.1.0 o posterior, con conexión a Internet (la integración habla con la nube de SwitchBot, no con los dispositivos de su red).
- Una cuenta SwitchBot y la aplicación SwitchBot, versión 9 o posterior.
- Para los dispositivos Bluetooth (Bot, cortina, Meter, sensor de apertura, cerradura…): un hub SwitchBot (Hub Mini, Hub 2, Hub 3…) y el servicio en la nube activado para cada dispositivo en la aplicación SwitchBot. Los dispositivos Wi-Fi (enchufes, luces, Hub 2…) no necesitan nada más.
- Opcional, para el tiempo real: una suscripción a Gladys Plus (véase más abajo).
Configuración
- Instale la integración: en Gladys, Integraciones → Instalar desde GitHub con
https://github.com/guim31/gladys-switchbot, o desde el catálogo cuando aparezca en él. - En la aplicación SwitchBot: Perfil → Preferencias → Acerca de, toque 10 veces Versión de la aplicación y abra Opciones de desarrollador: la aplicación muestra un token y una clave secreta.
- En Gladys: Integraciones → SwitchBot → Configuración, pegue el token y la clave secreta y guarde. El estado pasa a verde y la integración lee la lista de sus dispositivos.
- Abra la pestaña Descubrir: cada dispositivo compatible aparece allí, con el nombre dado en la aplicación SwitchBot. Pulse Añadir, elija una habitación y guarde. Solo se leen los dispositivos añadidos.
- El botón Probar la conexión muestra lo que ha encontrado la integración: dispositivos, los no compatibles, mandos IR, el ritmo de lectura y las llamadas a la API del día.
Otros ajustes:
- Mandos IR: publica también los mandos infrarrojos virtuales de sus hubs (véase más abajo).
- Permitir bloquear y desbloquear: desactivado por defecto, las cerraduras son entonces de solo lectura (véase más abajo).
- Idioma de los nombres de las funciones: los nombres dados a las funciones de los dispositivos añadidos después del cambio (francés por defecto). Los demás textos siguen el idioma de su Gladys.
El token y la clave secreta se quedan en la configuración de Gladys: firman cada solicitud y nunca aparecen en los registros. Generar un nuevo token en la aplicación invalida el anterior: pegue el nuevo.
Intervalo de actualización y cuota
SwitchBot permite 10 000 llamadas a la API al día por cuenta, incluidas todas las aplicaciones que usan el mismo token. Por encima, SwitchBot rechaza cualquier llamada hasta medianoche. La integración lee cada dispositivo añadido una vez por periodo (una llamada por dispositivo):
- Automático (por defecto): cada 2 minutos como máximo, y más despacio si tiene muchos dispositivos, para que la consulta nunca use más de la mitad de la cuota. Ejemplos: 10 dispositivos cada 3 minutos, 26 cada 8 minutos, 50 cada 15 minutos.
- Un intervalo fijo (de 1 minuto a 1 hora) se alarga si usara más de la mitad de la cuota.
La otra mitad queda para sus comandos, la relectura tras cada comando (una llamada, unos segundos
después), las lecturas en tiempo real y sus otras aplicaciones. La integración cuenta sus llamadas
(guardadas en /data, un reinicio no las olvida): a partir de 9000 llamadas, la consulta se
detiene hasta medianoche y los comandos siguen funcionando. No ve las llamadas de sus otras
aplicaciones (Home Assistant, scripts…): alargue el intervalo si comparte el token.
Tiempo real con Gladys Plus (opcional)
Sin él, un cambio hecho fuera de Gladys (una puerta abierta, un botón pulsado en el dispositivo) aparece en la lectura siguiente. Con una suscripción a Gladys Plus, SwitchBot puede avisar a Gladys al instante:
- En Gladys Plus, cree una clave Open API (Ajustes → Open API).
- En la configuración de la integración SwitchBot, péguela en el bloque Webhooks de Gladys Plus.
- Active Tiempo real con Gladys Plus y guarde.
La integración registra entonces la dirección de Gladys Plus en SwitchBot. Cada aviso de cambio provoca una lectura de ese dispositivo por la API (un aviso es un disparador, nunca se aplica tal cual), y esos dispositivos solo se consultan cada 30 minutos, para recuperar un aviso perdido. SwitchBot guarda un solo webhook por cuenta: registrar este elimina el que otra aplicación (Home Assistant…) había registrado. Desactivar la opción retira la dirección de Gladys.
Lo que ofrece cada dispositivo
| Dispositivo | Funciones en Gladys |
|---|---|
| Bot | Pulsar / interruptor (en modo pulsación todo comando pulsa y el estado vuelve a apagado), batería |
| Plug, Relay Switch 1 | Encendido/apagado |
| Plug Mini (US, JP) | Encendido/apagado, consumo eléctrico (W), tensión (V), corriente (A) |
| Plug Mini (EU), Relay Switch 1PM | Encendido/apagado, consumo, tensión, corriente, consumo de hoy (kWh) |
| Curtain, Curtain 3, Roller Shade, Blind Tilt | Posición (100 = abierto), abrir / cerrar / detener, batería (no en el Blind Tilt) |
| Lock, Lock Pro, Lock Ultra, Lock Vision… | Estado de la cerradura, puerta (no en el Lock Lite), batería; bloquear / desbloquear con la opción |
| Meter, Meter Plus, Outdoor Meter, Meter Pro | Temperatura, humedad, batería |
| Meter Pro CO2 | Temperatura, humedad, CO2 (ppm), batería |
| Hub 2, Hub 3 | Temperatura, humedad, luminosidad (1 a 20); movimiento en el Hub 3 |
| Contact Sensor | Apertura (abierto / cerrado), movimiento, batería |
| Motion Sensor | Movimiento, batería |
| Water Leak Detector | Fuga de agua, batería |
| Color Bulb, Strip Light 3, Floor Lamp, tira / lámpara RGBICWW | Luz, brillo, color, temperatura de color |
| Strip Light, cordones de neón RGBIC | Luz, brillo, color |
| Ceiling Light, Ceiling Light Pro | Luz, brillo, temperatura de color |
| Humidifier | Encendido/apagado, humedad, temperatura, depósito de agua (bajo cuando está vacío) |
| Air Purifier (VOC, PM2.5, modelos de mesa) | Encendido/apagado, modo (normal, auto, sueño, mascotas) |
| Circulator Fan, Battery Circulator Fan, Standing Fan | Encendido/apagado, velocidad (1 a 100 %, pasa al modo directo), batería en los modelos con batería |
| Robot Vacuum S1, S1 Plus, K10+, K10+ Pro | Estado, limpieza (iniciar / detener), volver a la base, batería |
| Robot Vacuum S10, S20, K10+ Pro Combo, K20+ Pro, K11+ | Estado, volver a la base, batería (inícielos desde la aplicación SwitchBot) |
Los demás dispositivos SwitchBot (Hub Mini sin sensores, cámaras, teclados…) no se publican: el botón Probar la conexión los enumera. Algunos valores llegan con retraso: tras un comando, el dispositivo se vuelve a leer 5 segundos después (15 segundos para una cortina).
Cortinas y persianas
Gladys lee una posición como 100 = abierto, 0 = cerrado: la integración convierte las posiciones de SwitchBot, que cuentan al revés. Un Blind Tilt está abierto en su posición central y cerrado en ambos extremos: su posición vale 100 con las lamas abiertas, y al fijar una posición conserva el sentido (arriba o abajo) que usó por última vez. Solo las cortinas pueden detenerse por comando.
Cerraduras
Una cerradura de puerta es un dispositivo de seguridad: por defecto la integración solo la lee (bloqueada, desbloqueada, en movimiento, atascada o mal cerrada, y el estado de la puerta). Para bloquear y desbloquear desde Gladys (panel, escenas, asistentes de voz vinculados a Gladys), active Permitir bloquear y desbloquear y añada la cerradura después (o actualícela desde la pestaña Descubrir). Piense en quién y qué puede alcanzar esos comandos.
Mandos IR
Con la opción Mandos IR, cada mando virtual de sus hubs (TV, aire acondicionado, ventilador, luz…) se convierte en un dispositivo con un botón de encendido y el último comando enviado. SwitchBot no da ningún estado para ellos: el encendido muestra el último comando enviado, no el aparato. Cualquier otro botón, incluidos los personalizados, se envía con la acción de escena Enviar un comando IR SwitchBot. Los mandos «Others» solo tienen botones personalizados.
Widget del panel
El widget SwitchBot muestra de un vistazo:
- hasta seis temperaturas (mosaicos en directo de sus termómetros y hubs);
- las puertas y ventanas abiertas (y las que siguen abiertas), las cerraduras no bloqueadas o atascadas, las fugas de agua, las baterías bajas;
- las llamadas a la API del día, y la nube de SwitchBot cuando rechaza o no responde.
No lee nada en SwitchBot por sí mismo: muestra las últimas lecturas.
Disparadores de escena
En el editor de escenas, categoría Integraciones:
- Puerta o ventana SwitchBot: un sensor de apertura indica abierto, cerrado o abierto demasiado tiempo (el plazo fijado en la aplicación SwitchBot, que un simple estado no puede expresar). Filtros: el sensor, los estados. Variables: nombre del dispositivo, estado.
- Movimiento detectado por SwitchBot: un sensor de movimiento, el de un sensor de apertura o un Hub 3 empieza a detectar movimiento. Variable: nombre del dispositivo.
- Fuga de agua SwitchBot: un detector de fugas pasa de seco a mojado. Variable: nombre del dispositivo.
- Batería baja SwitchBot: una batería baja al 20 % o menos, una vez, hasta que vuelva a superar el 30 %. Variables: nombre del dispositivo, batería.
Solo se disparan con un cambio, nunca al arrancar. Sin tiempo real, un cambio más corto que el intervalo de actualización (un movimiento breve) puede pasar desapercibido: use la opción de Gladys Plus para el movimiento.
Acciones de escena
- Pulsar con un Bot SwitchBot: una pulsación del Bot elegido, sea cual sea su modo.
- Enviar un comando IR SwitchBot: un mando (con la opción de mandos IR), un comando y un
parámetro opcional. Comandos estándar:
turnOn,turnOff,volumeAdd,volumeSub,channelAdd,channelSub,setMute,Play,Pause,Stop,Next,Previous,swing,lowSpeed,middleSpeed,highSpeed,brightnessUp,brightnessDown,SetChannel(parámetro: el canal) ysetAllpara un aire acondicionado (parámetro:temperatura,modo,ventilación,encendido, por ejemplo26,2,1,on: modo 1 auto, 2 frío, 3 deshumidificación, 4 ventilación, 5 calor; ventilación 1 auto, 2 baja, 3 media, 4 alta). Cualquier otro nombre es un botón personalizado del mando, respetando mayúsculas y minúsculas.
Ejemplos de escenas
- Puerta abierta demasiado tiempo: disparador Puerta o ventana SwitchBot, estado Abierto demasiado tiempo → enviar un mensaje «{{triggerEvent.data.device_name}} sigue abierta».
- Fuga de agua: disparador Fuga de agua SwitchBot → mensaje «Fuga de agua: {{triggerEvent.data.device_name}}», y apagar el enchufe de la lavadora.
- Café de la mañana: a las 7:00 entre semana → Pulsar con un Bot SwitchBot (el Bot de la cafetera), y abrir la cortina del salón al 100 %.
- Refrescar: cuando la temperatura del dormitorio supera 27 °C → Enviar un comando IR
SwitchBot,
setAllcon24,2,1,onal mando del aire acondicionado. - Baterías: disparador Batería baja SwitchBot → mensaje «Cambie la batería de {{triggerEvent.data.device_name}} ({{triggerEvent.data.battery}} %)».
Solución de problemas
- «SwitchBot rechaza las credenciales»: compruebe el token y la clave secreta (cópielos de nuevo desde la aplicación; un nuevo token invalida el anterior). La misma respuesta llega cuando se ha agotado la cuota diaria: espere a medianoche y alargue el intervalo si comparte el token con otra aplicación. La integración lo reintenta cada 30 minutos.
- «La nube de SwitchBot no responde»: compruebe la conexión a Internet de Gladys. La integración lo reintenta cada 5 minutos.
- Falta un dispositivo en Descubrir: puede que no sea compatible (véase Probar la conexión), o que su servicio en la nube esté desactivado en la aplicación SwitchBot. Vuelva a buscar desde la pestaña Descubrir una vez corregido.
- Un dispositivo aparece inaccesible: SwitchBot indica que el dispositivo o su hub está desconectado (batería agotada, fuera del alcance Bluetooth del hub, hub desenchufado).
- Los valores llegan con retraso: es el intervalo de actualización (véase Probar la conexión); active el tiempo real de Gladys Plus para las puertas y el movimiento.
- El tiempo real no funciona: compruebe que la clave Open API está pegada en el bloque de webhooks de Gladys Plus y que la opción está activada; puede que otra aplicación haya registrado su propio webhook desde entonces (SwitchBot guarda uno): vuelva a guardar la configuración.
- Registros: ponga
LOG_LEVEL=debugen la integración para ver cada lectura; el token y la clave secreta nunca aparecen en ellos.
Límites
- Solo nube: sin control Bluetooth local, los dispositivos necesitan un hub y una conexión a Internet, y los servidores de SwitchBot deben responder.
- 10 000 llamadas a la API al día por cuenta: los valores se actualizan cada pocos minutos, no al instante, salvo con el tiempo real de Gladys Plus.
- La API de SwitchBot es para uso personal (véanse sus condiciones).
- Sin estado para los mandos IR; sin programas de limpieza para las aspiradoras más recientes; sin modos de ventilador, luces nocturnas ni bloqueos infantiles; todavía sin teclados, cámaras, videoporteros, termostatos ni Relay Switch 2PM.
- La integración solo cuenta sus propias llamadas a la API, no las de sus otras aplicaciones.
- Desarrollada sin el hardware ni una cuenta SwitchBot: los nombres y valores de los campos proceden de la documentación de SwitchBot y de las pruebas de Home Assistant.
Parámetros de configuración
Estos son los parámetros que SwitchBot te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Su token de SwitchBot | section | No | En la aplicación SwitchBot (versión 9 o posterior): Perfil, Preferencias, Acerca de, toque 10 veces Versión de la aplicación y luego Opciones de desarrollador: copie el token y la clave secreta aquí. Los dispositivos Bluetooth necesitan un hub SwitchBot y el servicio en la nube activado. |
| Token | secret | Sí | El token que se muestra en Opciones de desarrollador de la aplicación SwitchBot. |
| Clave secreta | secret | Sí | La clave secreta que aparece bajo el token. Firma cada solicitud y nunca sale de Gladys. |
| Intervalo de actualización | select | No | Frecuencia de lectura de cada dispositivo. SwitchBot permite 10 000 llamadas al día por cuenta: el modo automático usa como máximo la mitad y un intervalo más corto se alarga si la superara. |
| Tiempo real con Gladys Plus | boolean | No | Requiere Gladys Plus y su clave Open API en el bloque de webhooks. SwitchBot guarda UN webhook por cuenta: se sustituye el de otra aplicación (Home Assistant…). |
| Mandos IR | boolean | No | Publicar también los mandos infrarrojos virtuales de sus hubs (TV, aire acondicionado…), para su botón de encendido y la acción de escena «Enviar un comando IR». |
| Permitir bloquear y desbloquear | boolean | No | Desactivado: las cerraduras son de solo lectura. Activado: las cerraduras añadidas después se bloquean y desbloquean desde Gladys, sus escenas y sus asistentes. |
| Idioma de los nombres de las funciones | select | No | Nombres dados a las funciones de los nuevos dispositivos (Temperatura, Posición, Batería…). |
Cómo instalar SwitchBot en Gladys
- En Gladys, abre Integraciones: SwitchBot aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/guim31/gladys-switchbot:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-switchbot.
SwitchBot requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
SwitchBot es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.
- Explorar todas las integraciones externas
- Descubrir las integraciones nativas incluidas en Gladys
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación