Integración domótica Tractive, gratuita y de código abierto
Localizadores GPS Tractive para perros y gatos: en casa o no, distancia, batería, actividad.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.2.0
- ★ 0
Siga el localizador GPS Tractive de su perro o de su gato en Gladys: si está en casa, a qué distancia, la batería, la actividad del día, y el zumbador y la luz para encontrarlo. Integración no oficial, sin relación con Tractive.
Desarrollada sin el hardware: sus comentarios son bienvenidos. La integración se basa en la API que usa la aplicación Tractive, tal como la leen la biblioteca libre aiotractive y la integración de Home Assistant, y está probada con sus respuestas grabadas, no con un localizador real. Indique lo que funciona y lo que no en las issues.
Presentación
- Un dispositivo por mascota con un localizador Tractive en su cuenta: batería, carga, distancia a casa, precisión de la posición, en casa o no, localizador en línea, ahorro de energía, actividad y descanso del día, objetivo de actividad diario.
- Comandos: seguimiento en directo, zumbador y luz (LED), si el localizador y la suscripción lo permiten.
- Tiempo real: la batería, las posiciones y los interruptores llegan en el momento, por el flujo de eventos que escucha la aplicación Tractive.
- Disparadores de escena: La mascota ha salido de casa, La mascota ha vuelto a casa, Batería Tractive baja.
- Widget del panel Mascota Tractive, con botones de zumbador y luz.
La posición en sí (latitud, longitud) nunca se guarda en Gladys, que no tiene función para ello: Gladys guarda la distancia a su casa, calculada por la integración.
Requisitos
- Gladys Assistant 5.2.0 o posterior.
- Un localizador Tractive con una suscripción activa, y la dirección de correo y la contraseña de la cuenta Tractive a la que pertenece. Una cuenta creada con «Iniciar sesión con Apple» o Google no tiene contraseña: defina una primero en la aplicación Tractive (ajustes de la cuenta).
- Para la distancia y «en casa»: una casa de Gladys con ubicación (Ajustes → Casas, coloque la casa en el mapa).
- Gladys debe acceder a Internet (
graph.tractive.com,aps-api.tractive.com,channel.tractive.com).
Configuración
- En Gladys, abra Integraciones → Instalar desde GitHub (o el catálogo) e instale Tractive. La pantalla de instalación pide leer la ubicación de sus casas: sirve para calcular la distancia.
- En Configuración, rellene:
- la Dirección de correo y la Contraseña de su cuenta Tractive;
- la Casa desde la que se mide la distancia (vacío: la primera casa con ubicación);
- el Radio de la casa (m): dentro de esta distancia la mascota está en casa (100 m por defecto). Se considera fuera a partir de un 20 % más lejos (25 m como mínimo), para que los saltos del GPS en el borde no la hagan ir y venir;
- el Umbral de batería baja (%): 15 % por defecto;
- el Intervalo de actualización (min): la actualización completa (15 min por defecto, de 5 a 60);
- el Idioma de los nombres de funciones: francés por defecto, también se usa para los errores de los comandos.
- Guarde y use Probar la conexión: muestra las mascotas encontradas.
- Abra la pestaña Descubrimiento y añada sus mascotas.
La integración guarda un token de sesión en su propio volumen /data: un
reinicio no vuelve a iniciar sesión. La contraseña se queda en la
configuración de Gladys.
Qué hace cada dispositivo
Un dispositivo por mascota, con el nombre de la mascota. Las funciones dependen del localizador: un localizador sin luz no tiene función de luz, por ejemplo.
| Función | Qué muestra |
|---|---|
| Batería | Nivel de batería del localizador (%) |
| Cargando | 1 mientras carga (localizadores que lo indican) |
| Distancia a casa | Distancia entre la última posición y la casa elegida (m) |
| Precisión de la posición | Incertidumbre de la última posición, según Tractive (m) |
| En casa | 1 dentro del radio de la casa, 0 fuera |
| Localizador en línea | 0 cuando el localizador deja de informar o se ha apagado |
| Ahorro de energía | 1 mientras ahorra batería (en reposo en la wifi de casa) |
| Actividad de hoy | Minutos activos desde medianoche |
| Descanso de hoy | Minutos de calma desde medianoche (localizadores con seguimiento del sueño) |
| Objetivo de actividad diario | El objetivo fijado en la aplicación Tractive (minutos) |
| Seguimiento en directo | Interruptor: modo de seguimiento en directo, una posición cada pocos segundos |
| Zumbador | Interruptor: el localizador suena, para encontrar a la mascota cerca |
| Luz (LED) | Interruptor: la luz del localizador, para ver a la mascota en la oscuridad |
Comandos
Seguimiento en directo, Zumbador y Luz (LED) se envían al localizador a través de Tractive. El zumbador y la luz se apagan solos al cabo de un rato en el localizador; Gladys los muestra apagados en cuanto Tractive lo indica. El seguimiento en directo gasta la batería: apáguelo cuando haya encontrado a la mascota.
Un comando se rechaza con un mensaje claro cuando:
- el localizador duerme en su zona de ahorro de energía (wifi de casa): ahí no acepta comandos;
- la suscripción o el modelo de localizador no permite la función;
- la integración no está conectada a Tractive.
Nada aquí abre, desbloquea ni desarma nada.
Widget del panel
Añada el widget Mascota Tractive a un panel y elija la mascota en sus ajustes. Muestra:
- la distancia a casa y la batería (en directo);
- la actividad del día frente al objetivo diario;
- en casa o no, la antigüedad de la última posición y el estado del localizador (en línea, sin conexión, ahorro de energía);
- un botón de zumbador y un botón de luz (si el localizador los tiene). Una función en marcha muestra una marca de verificación: pulse de nuevo para detenerla.
Disparadores de escena
| Disparador | Cuándo | Variables |
|---|---|---|
| La mascota ha salido de casa | La mascota supera el radio de la casa más el margen | nombre de la mascota, distancia (m) |
| La mascota ha vuelto a casa | La mascota vuelve al radio de la casa | nombre de la mascota, distancia (m) |
| Batería Tractive baja | La batería baja del umbral, una vez (de nuevo solo tras 5 puntos por encima), no mientras carga | nombre de la mascota, batería (%) |
Cada disparador puede limitarse a una mascota (vacío: cualquiera). Añaden a las funciones En casa y Batería lo que un estado de dispositivo no dice: un evento por cada paso real, el nombre de la mascota para un mensaje, las posiciones menos precisas que 500 m ignoradas (una posición por antena de telefonía nunca hace «salir» a un gato dormido), nada con el primer valor tras un reinicio.
Prueba de la conexión
El botón Probar la conexión inicia sesión en Tractive con la configuración guardada y responde con las mascotas encontradas, el estado de las actualizaciones en tiempo real y si falta una casa con ubicación. También sirve para reintentar después de que Tractive rechazara la contraseña, una vez corregida.
Ejemplos de escenas
- El perro se ha escapado: disparador La mascota ha salido de casa para el perro → enviar un mensaje «{{triggerEvent.data.pet_name}} ha salido, a {{triggerEvent.data.distance}} m» → encender Seguimiento en directo.
- Bienvenida: disparador La mascota ha vuelto a casa → apagar Seguimiento en directo y enviar «{{triggerEvent.data.pet_name}} está en casa».
- Cargar el localizador: disparador Batería Tractive baja → enviar «Cargue el localizador de {{triggerEvent.data.pet_name}} ({{triggerEvent.data.battery}} %)».
- Control nocturno: cada noche a las 22 h, si En casa vale 0 → enviar un mensaje.
Actualización y límites de la API
Tractive no ofrece una API pública: la integración usa la de la aplicación Tractive, como Home Assistant, y procura no sobrecargarla.
- Primero el tiempo real: una sola conexión larga al flujo de eventos de Tractive trae la batería, las posiciones y los interruptores. Si se pierde, se reconecta tras 10 s, y después hasta cada 5 minutos mientras falle.
- Actualización completa cada 15 minutos (ajustable, de 5 a 60): localizador, batería, posición y actividad solo de las mascotas añadidas a Gladys, una petición tras otra, 2 segundos entre dos mascotas. No se recurre al planificador de Gladys: la integración tiene su propio temporizador.
- Un solo inicio de sesión por vida del token: se guarda en
/datay se renueva una hora antes de caducar. Una contraseña rechazada no se reintenta hasta que cambie la configuración o pulse Probar la conexión. - Una respuesta «demasiadas peticiones» (429) se reintenta tras 8 segundos, luego hasta 60 segundos, tres veces como máximo.
- Solo se envían a Gladys los valores que cambian, más un recordatorio cada 6 horas de los que no cambian.
Solución de problemas
- «Tractive rechaza la dirección de correo o la contraseña»: compruébelas en la aplicación Tractive o en my.tractive.com. Una cuenta de Google o Apple necesita una contraseña definida en la aplicación Tractive.
- Ninguna mascota en Descubrimiento: la mascota debe tener un localizador asignado en su cuenta; un localizador compartido con usted por otra cuenta no aparece. Pulse Probar la conexión.
- La distancia y «En casa» quedan vacías: dé una ubicación a la casa (Ajustes → Casas) o elija una casa con ubicación en la configuración.
- Un comando falla: lea el mensaje; en la zona wifi de casa el localizador duerme y no acepta comandos.
- Los valores parecen antiguos: en ahorro de energía el localizador
informa con menos frecuencia; compruébelo en la aplicación Tractive.
LOG_LEVEL=debugen la integración muestra cada actualización en sus registros.
Limitaciones
- Desarrollada sin el hardware: probada solo con respuestas grabadas de la API.
- La API es la de la aplicación Tractive, no una pública: Tractive puede cambiarla sin aviso y romper la integración hasta su actualización.
- Sin mapa: Gladys no tiene función para una posición, solo la distancia a una casa.
- El estado de los interruptores (zumbador, luz, seguimiento en directo) solo se conoce cuando el flujo en tiempo real lo indica.
- La actividad es la del día, tal como la cuenta Tractive.
- Una sola cuenta Tractive por Gladys.
- Las zonas (geofences), el historial de Tractive y las alertas de salud de la aplicación no están disponibles.
Parámetros de configuración
Estos son los parámetros que Tractive te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Su cuenta Tractive | section | No | La dirección de correo y la contraseña que usa en la aplicación Tractive. Se necesita un localizador con una suscripción activa. Integración no oficial, sin relación con Tractive. |
| Dirección de correo | string | Sí | |
| Contraseña | secret | Sí | Solo se guarda en la configuración de Gladys; la integración guarda un token de sesión en su volumen /data, nunca la contraseña. |
| Casa | section | No | La distancia y «en casa» se calculan en Gladys a partir de la ubicación de una casa de Gladys (Ajustes, Casas). La posición en sí nunca se guarda en Gladys. |
| Casa | select | No | Vacío: la primera casa con ubicación. |
| Radio de la casa (m) | number | No | Dentro de esta distancia la mascota está en casa. Se considera fuera a partir de un 20 % más lejos (25 m como mínimo), contra los saltos del GPS. |
| Umbral de batería baja (%) | number | No | Por debajo de este nivel, el disparador de escena «Batería Tractive baja» se activa una vez. |
| Intervalo de actualización (min) | number | No | Las posiciones y la batería llegan en tiempo real. Esta actualización completa lee la actividad y cubre los momentos sin tiempo real. |
| Idioma de los nombres de funciones | select | No | Se usa para los dispositivos añadidos a partir de ahora y para los errores de los comandos. |
Cómo instalar Tractive en Gladys
- En Gladys, abre Integraciones: Tractive 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-tractive: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-tractive.
Tractive requiere Gladys >=5.2.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
Tractive 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