Integración domótica TP-Link Omada, gratuita y de código abierto
Red Omada: presencia, puntos de acceso, switches, puerta de enlace y WAN, PoE.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Lleva su red TP-Link Omada a Gladys: quién está en casa (los teléfonos en el Wi-Fi), el estado de sus puntos de acceso, switches y puerta de enlace, su conexión a Internet y algunos comandos para sus escenas.
Sin relación con TP-Link. Desarrollada sin el hardware: sus comentarios son bienvenidos — la integración se ha probado contra un controlador simulado construido a partir de respuestas publicadas de controladores reales, aún no contra uno real.
Presentación
- Presencia: cada teléfono, portátil o dispositivo conectado a la red puede convertirse en un sensor de presencia, con un retardo de salida para que un teléfono en reposo no «se vaya» cada pocos minutos.
- Equipos Omada: un dispositivo Gladys por puerta de enlace, switch y punto de acceso: en línea, clientes conectados, tiempo de actividad, uso de CPU y de memoria, caudal de los clientes, potencia PoE consumida en un switch PoE y, para la puerta de enlace, el estado de Internet y el caudal de cada puerto WAN.
- Disparadores de escena: un nuevo dispositivo desconocido se une a la red, un equipo Omada pasa a estar fuera de línea, un puerto WAN pierde Internet o lo recupera.
- Comandos (desactivados por defecto): activar o cortar el PoE de un puerto de switch, reiniciar un equipo Omada, activar o desactivar un SSID (el Wi-Fi de invitados).
- Widget del panel: clientes, caudal de Internet, puertos WAN y equipos Omada fuera de línea de un vistazo.
Requisitos previos
- Un controlador Omada: Software Controller, OC200 u OC300, accesible desde Gladys en la red local. Un controlador en la nube puede funcionar mediante su dirección Open API (no probado).
- Recomendado: la Open API (controlador 5.9 o posterior). En el controlador, abra Vista global → Ajustes → Integración de plataforma → Open API, añada una aplicación en modo Cliente, dele el sitio que desea seguir y anote su ID de cliente y su secreto de cliente. Un rol de observador basta para leer; los comandos necesitan un rol autorizado a modificar el sitio (administrador).
- O una cuenta de administrador local (cualquier versión 5.x del controlador): cree una cuenta local dedicada en el controlador. En este modo la integración solo lee: ningún comando.
Configuración
En Gladys, Integraciones → TP-Link Omada → Configuración:
| Campo | Qué introducir |
|---|---|
| Dirección del controlador | https://<dirección>:8043 para el Software Controller, https://<dirección> para un OC200 / OC300. |
| Modo de conexión | Open API (recomendado) o cuenta de administrador local (solo lectura). |
| ID / secreto de cliente de la Open API | La aplicación creada arriba (modo Open API). |
| Usuario / contraseña de la cuenta local | La cuenta dedicada (modo de cuenta local). |
| Sitio | El nombre del sitio Omada (Default por defecto). |
| Aceptar un certificado autofirmado | El controlador viene con un certificado autofirmado: active esta opción, salvo que haya instalado uno de confianza. |
| Omada ID | Déjelo vacío para un controlador local. Solo controlador en la nube: el Omada ID de su página Open API. |
| Ofrecer los clientes de la red | Muestra los clientes en línea en la pestaña Descubrir, para añadir los que desee seguir. |
| Retardo de salida | Minutos que un cliente debe estar ausente antes de considerarlo fuera (5 por defecto). |
| Intervalo de actualización | 30 s, 1 min (por defecto), 2 min o 5 min. |
| Permitir el control del PoE / los reinicios / el control de los SSID | Cada comando está desactivado por defecto: active solo lo que necesiten sus escenas. |
| Idioma de los nombres de las funciones | Francés por defecto; los nombres se fijan al añadir un dispositivo. |
Después haga clic en Probar la conexión: el mensaje indica el sitio, la versión del controlador y lo que se ha encontrado. Abra la pestaña Descubrir para añadir los equipos Omada y los clientes que desee seguir.
Lo que la integración pide al controlador. Una lectura del sitio por intervalo de actualización: la lista de equipos, los clientes conectados, el estado WAN de la puerta de enlace y el consumo PoE (de 4 a 6 solicitudes). Los controladores Omada aceptan unas 10 solicitudes por segundo; la integración espacia sus solicitudes y nunca envía más de una a la vez. Abrir un panel no le cuesta nada al controlador: el widget muestra la última lectura. El token de acceso de la Open API solo vive en memoria y se renueva con las credenciales de cliente cuando caduca (dos horas).
Dispositivos
Puerta de enlace, switch, punto de acceso (un dispositivo Gladys cada uno, con el nombre del controlador):
| Función | Unidad | Equipos |
|---|---|---|
| En línea | 0 / 1 | todos |
| Clientes conectados | número | todos (los clientes conectados al equipo) |
| Tiempo de actividad | horas | todos |
| Uso de CPU, uso de memoria | % | todos |
| Descarga / subida de los clientes | Mbit/s | switch, punto de acceso |
| Potencia PoE | W | switch PoE |
| Internet, descarga, subida por puerto WAN | 0 / 1, Mbit/s | puerta de enlace |
El caudal de los clientes de un switch o de un punto de acceso es la suma de la actividad en tiempo real de los clientes conectados a él, tal como la indica el controlador — no el tráfico de su enlace ascendente.
Cliente de la red (un teléfono, un portátil…): una función Presencia (presence-sensor,
sí/no). Vale 1 mientras el cliente está conectado y pasa a 0 cuando lleva ausente más tiempo que el
retardo de salida. Un controlador que no responde nunca hace salir a nadie: la presencia solo se evalúa
en una lectura correcta. Los clientes añadidos permanecen en la pestaña Descubrir incluso cuando están
ausentes.
Todo es de solo lectura: los comandos son acciones (véase más abajo), a propósito nunca interruptores que un asistente de voz o un clic desafortunado pudieran accionar.
Widget
Red Omada: mosaicos para los clientes (total, Wi-Fi, por cable) y la descarga y subida de Internet; después el estado de cada puerto WAN (con su dirección IP pública), el número de equipos Omada en línea y el nombre de los que están fuera de línea. Muestra la última lectura y se actualiza con ella.
Disparadores de escena
| Disparador | Filtros | Variables |
|---|---|---|
| Nuevo cliente de red desconocido | conexión (Wi-Fi / por cable), SSID, red de invitados | nombre, dirección MAC, dirección IP, SSID, conexión, conectado a |
| Equipo Omada fuera de línea | equipo, tipo (puerta de enlace, switch, punto de acceso) | nombre del equipo, modelo, tipo |
| WAN caída o restablecida | cambio (Internet perdido / restablecido), puerta de enlace | cambio, puerto WAN, puerta de enlace, dirección IP WAN |
- Nuevo cliente desconocido se dispara con una dirección MAC nunca vista en el sitio. La primera
lectura tras la instalación solo aprende los clientes ya presentes; las direcciones MAC conocidas se
guardan en
/data(solo direcciones MAC, nada más). - Equipo fuera de línea cubre todos los equipos Omada del sitio, incluso los que no se han añadido a Gladys, y da su nombre para la notificación.
- Solo las transiciones disparan: un reinicio de Gladys, de la integración o del controlador nunca dispara nada.
Comandos
Solo en el modo Open API, cada uno activado en la configuración. Disponibles como botones de la pantalla de configuración y como acciones de escena:
- PoE de un puerto de switch: elija el switch, el número de puerto y activado / desactivado. El puerto recibe una sustitución de perfil en el controlador, porque el PoE de un puerto que sigue su perfil no puede cambiar. Atención: cortar el PoE apaga lo que alimenta el puerto — una cámara de seguridad, un punto de acceso, un teléfono. Resérvelo para lo que realmente quiera apagar (un punto de acceso por la noche, un dispositivo que reiniciar), nunca para una cámara que protege la casa.
- Reiniciar un equipo Omada: el equipo queda fuera de línea unos minutos.
- Activar o desactivar un SSID: escriba el nombre de la red (por ejemplo
Invitados); se activa o desactiva en todos los puntos de acceso que lo emiten.
Cada comando escribe una línea en los registros de la integración.
Ejemplos de escenas
- Nadie en casa: cuando la presencia de todos los teléfonos vale 0, poner la casa en modo ausente, apagar las luces, armar la alarma.
- Wi-Fi de invitados con horario: cada día a las 8:00, acción de escena Activar o desactivar un
SSID →
Invitados, activado; a las 23:00, desactivado. - Internet caído: disparador WAN caída o restablecida, cambio Internet perdido → enviar un mensaje «{{triggerEvent.data.port_name}} ha perdido Internet».
- Intruso en el Wi-Fi: disparador Nuevo cliente de red desconocido, SSID
Casa→ enviar un mensaje con {{triggerEvent.data.name}} y {{triggerEvent.data.ip}}. - Punto de acceso apagado por la noche: a las 0:30, PoE de un puerto de switch desactivado para el puerto del punto de acceso del jardín; a las 7:00, activado.
Solución de problemas
- «certificado rechazado»: active Aceptar un certificado autofirmado.
- «credenciales rechazadas»: compruebe el ID y el secreto de cliente (Open API) o el usuario y la contraseña (cuenta local). Una aplicación Open API eliminada o modificada en el controlador recibe un nuevo secreto.
- «sitio no encontrado»: el mensaje enumera los sitios visibles con esas credenciales; copie el nombre.
- «acceso denegado»: dé a la aplicación Open API (o a la cuenta) acceso al sitio; para los comandos, un rol autorizado a modificar el sitio.
- «no responde como un controlador Omada»: compruebe el puerto (8043 para el Software Controller) y que la Open API existe (controlador 5.9 o posterior).
- Un comando responde con un error en un switch: algunos switches (serie Agile) rechazan el comando PoE de la Open API; se muestra el mensaje del controlador.
- Más detalles: ponga la variable de entorno
LOG_LEVELendebug. Los registros nunca contienen un secreto.
Límites
- Desarrollada sin el hardware: la forma de las solicitudes procede de la guía de acceso de la Open API y de clientes que funcionan con controladores reales; los comentarios desde el terreno son bienvenidos.
- El modo de cuenta local solo lee: los comandos necesitan la Open API.
- La presencia sigue al Wi-Fi: un teléfono que deja el Wi-Fi en reposo profundo más tiempo que el retardo se considera fuera. Aumente el retardo si es necesario.
- Los teléfonos con una dirección MAC privada (aleatoria) por red son un cliente nuevo en cada red a la que se unen.
- El caudal de los clientes de un switch o de un punto de acceso es la suma de la actividad de sus clientes, no un contador de puerto. Las velocidades WAN son las que indica el controlador.
- Gladys fija los nombres de las funciones al añadir un dispositivo: cambie el idioma antes de añadirlos.
- Un puerto WAN de la puerta de enlace que aparece más tarde (una WAN nueva) muestra un botón «Actualizar» en la pestaña Descubrir.
Parámetros de configuración
Estos son los parámetros que TP-Link Omada te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Controlador Omada | section | No | Software Controller, OC200 u OC300. Recomendado: la Open API (controlador 5.9 o posterior), con una aplicación creada en Vista global > Ajustes > Integración de plataforma > Open API, en modo cliente. El modo de cuenta local solo lee. |
| Dirección del controlador | string | Sí | Con el puerto: 8043 para el Software Controller, ninguno para un OC200 u OC300. |
| Modo de conexión | select | Sí | |
| ID de cliente de la Open API | string | No | |
| Secreto de cliente de la Open API | secret | No | |
| Usuario de la cuenta local | string | No | Solo en el modo de cuenta local: una cuenta de administrador dedicada del controlador. |
| Contraseña de la cuenta local | secret | No | |
| Sitio | string | No | Nombre del sitio Omada, tal como aparece en el controlador. |
| Aceptar un certificado autofirmado | boolean | No | El controlador viene con un certificado autofirmado: active esta opción, salvo que haya instalado uno de confianza. |
| Omada ID (controlador en la nube) | string | No | Déjelo vacío para un controlador local. Para un controlador en la nube: el Omada ID de su página Open API, con su dirección Open API arriba. |
| Presencia y actualización | section | No | Los clientes en línea aparecen en la pestaña Descubrir: añada los teléfonos que desee seguir, cada uno se convierte en un sensor de presencia. |
| Ofrecer los clientes de la red en Descubrir | boolean | No | |
| Retardo de salida (minutos) | number | No | Tiempo que un cliente debe estar ausente antes de considerarlo fuera (un teléfono en reposo deja el Wi-Fi un rato). |
| Intervalo de actualización | select | No | |
| Comandos (desactivados por defecto) | section | No | Solo en el modo Open API, con una aplicación autorizada a escribir. Cortar el PoE de un puerto apaga lo que alimenta: una cámara de seguridad, un punto de acceso. Active solo lo que necesiten sus escenas. |
| Permitir el control del PoE | boolean | No | |
| Permitir los reinicios | boolean | No | |
| Permitir el control de los SSID | boolean | No | |
| Idioma de los nombres de las funciones | select | No | También se usa para los mensajes de la integración. Los nombres se fijan al añadir un dispositivo. |
Cómo instalar TP-Link Omada en Gladys
- En Gladys, abre Integraciones: TP-Link Omada 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-omada: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-omada.
TP-Link Omada 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
TP-Link Omada 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, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación