Integración domótica BookStack, gratuita y de código abierto
Su wiki BookStack en Gladys: contadores, páginas modificadas, páginas y diario desde escenas.
Publicado por guim31
- Dispositivos
- Versión 1.0.0
- Requiere Gladys >=5.1.0
- ★ 0
Conecte Gladys a BookStack, el wiki autoalojado organizado en estantes, libros, capítulos y páginas: siga sus contadores, reaccione cuando se crea o modifica una página, escriba páginas desde sus escenas y lleve un diario (la caldera, la alarma, el jardín…) que Gladys rellena línea a línea. Todo se queda en su red local: Gladys habla directamente con su BookStack.
Probada con un BookStack v26.09.2 real (la imagen Docker de linuxserver.io). Sus comentarios son bienvenidos en el foro de Gladys.
Requisitos previos
- Gladys Assistant 5.1 o posterior.
- BookStack accesible desde la máquina de Gladys (cualquier versión reciente; se recomienda v24 o posterior).
- Un token de API: en BookStack, abra Mi cuenta → Acceso y seguridad → Tokens API y cree uno. Copie su Token ID y su Token secret (el secreto se muestra una sola vez). Su propietario necesita el permiso API de sistema de acceso (el rol Admin lo tiene; déselo a otro rol en Ajustes → Roles) y el derecho de editar los libros en los que escriben sus escenas. La integración ve lo que ve este usuario.
Configuración
- Abra la pestaña Configuración de la integración.
- En Dirección de BookStack, introduzca la dirección en la que abre
BookStack, por ejemplo
192.168.1.50:6875ohttps://wiki.example.org. - Pegue el ID del token y el Secreto del token.
- Leer BookStack cada: 5, 15 (por defecto), 30 o 60 minutos. Las páginas modificadas se anuncian en la siguiente lectura.
- Idioma de nombres y mensajes fija los nombres de las funciones (fijados al añadir un dispositivo) y los textos de la integración. Francés por defecto.
- Guarde y use Probar la conexión: muestra el número de libros y páginas.
- En la pestaña Descubrimiento, añada el dispositivo BookStack y los libros que quiera seguir.
Dispositivos
BookStack (un dispositivo para la instancia):
| Función | Valor |
|---|---|
| Libros | número de libros |
| Estantes | número de estantes |
| Páginas | número de páginas |
| Páginas modificadas hoy | páginas creadas o guardadas desde medianoche |
| Última página modificada | nombre de la última página creada o guardada |
Un dispositivo por libro, con el nombre del libro y una función, Páginas: su número de páginas. Añada solo los que le interesen: sirven de filtro de libro a los disparadores y al widget.
Los contadores conservan su historial.
Widget del panel
BookStack: tres mosaicos (libros, páginas, hoy) y las ocho últimas páginas modificadas, con su libro y la hora del cambio. En los ajustes del widget, Libro elige un dispositivo de libro: el widget muestra entonces su número de páginas y sus últimas páginas modificadas. Ocultar los contadores deja solo la lista. Cuando BookStack se alcanza por https, cada página se abre en BookStack.
Disparadores de escena
- Página de BookStack creada o modificada: se crea o guarda una página en BookStack. Filtros: Libro (un dispositivo de libro; vacío: todos) y Cambio (creada, actualizada, o vacío: ambos).
- Página de BookStack etiquetada modificada: lo mismo, para las páginas con
una etiqueta: Etiqueta (obligatoria, el nombre exactamente como en
BookStack, p. ej.
journal), Libro y Cambio. Una página con varias etiquetas se dispara una vez por nombre de etiqueta: una escena configurada con una etiqueta se ejecuta una vez.
Variables: Nombre de la página, Libro, Cambio (created o
updated), Dirección de la página, Actualizada por, Etiquetas
(nombre: valor, separadas por comas), Id. de la página, y Etiqueta
para el segundo disparador.
La primera lectura tras la instalación es silenciosa: las páginas ya presentes no se anuncian. Las páginas escritas por esta integración nunca se anuncian. Se anuncian como máximo diez páginas por lectura, las más antiguas primero; las siguientes esperan a la próxima lectura. Si hay más de 50 cambios entre dos lecturas (una importación), se anuncian diez y el resto se cuenta como visto.
Acciones de escena
- Crear una página de BookStack: Libro (el nombre de un libro
existente, en mayúsculas o minúsculas, o su id.), Nombre de la página, y
opcionalmente Contenido (Markdown) y Etiquetas (separadas por comas,
nombre=valorpara una etiqueta con valor). Un libro desconocido es un error: la integración nunca crea uno. - Añadir una línea a una página de BookStack: Libro, Nombre de la página y Línea. La línea se añade al final de la página, como nuevo párrafo, precedida de la fecha y la hora salvo si Empezar con la fecha y la hora está desactivado. La página se crea con su primera línea. Las páginas Markdown reciben la línea en Markdown, las demás como texto plano.
Ambas devuelven Id. de la página, Nombre de la página, Libro, Dirección de la página y Página creada.
Ejemplos de escenas
- Diario de la caldera: cuando la presión de la caldera baja de 1 bar →
Añadir una línea a una página de BookStack, libro
Casa, páginaDiario de la caldera, línea «Presión por debajo de 1 bar». - Saber qué ha cambiado: disparador Página de BookStack creada o modificada, libro Procedimientos → enviar un mensaje «{{triggerEvent.data.updated_by}} modificó {{triggerEvent.data.page_name}}».
- Lista de la compra en el wiki: disparador Página de BookStack
etiquetada modificada, etiqueta
compra→ enviar la dirección de la página a la familia. - Informe de vacaciones: cuando se desactiva la alarma a la vuelta →
Crear una página de BookStack en el libro
Casa, con la etiquetainforme.
Solución de problemas
- «BookStack rechazó el token de API»: el token se eliminó, caducó o se escribió mal. Cree uno nuevo en Mi cuenta → Acceso y seguridad.
- «El propietario del token no puede usar la API»: dé a su rol el permiso API de sistema de acceso en Ajustes → Roles.
- «El propietario del token no puede escribir en este libro»: dé al usuario el permiso de edición de ese libro (o de todos) en BookStack.
- «BookStack no responde»: compruebe la dirección y el puerto desde la
máquina de Gladys. El contenedor usa una red en puente:
localhostes el propio contenedor, introduzca la dirección IP del servidor. - «Esta dirección no responde como BookStack»: responde la página de inicio de sesión de un proxy en lugar de BookStack. Introduzca la dirección del propio BookStack.
- Falta un libro en el filtro de un disparador o en los ajustes del widget: añada primero su dispositivo en la pestaña Descubrimiento.
- Para ver más en los registros de la integración, configure
LOG_LEVEL=debug.
Límites
- Un solo usuario de BookStack: el propietario del token, con sus permisos.
- Los disparadores se activan en la siguiente lectura (15 minutos por defecto), no al instante: BookStack no envía nada por sí mismo. Las páginas eliminadas, movidas o solo comentadas no se anuncian; una página guardada varias veces entre dos lecturas se anuncia una vez.
- Una lectura cuesta unas pocas peticiones, más una por libro añadido a Gladys y una por página anunciada: muy por debajo de las 180 peticiones por minuto que permite BookStack.
- El descubrimiento ofrece los 100 primeros libros, por orden alfabético.
- La integración nunca elimina ni mueve nada en BookStack.
- Sin relación con BookStack.
Parámetros de configuración
Estos son los parámetros que BookStack te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Conectar BookStack | section | No | Introduzca la dirección de su BookStack y un token de API: en BookStack, abra Mi cuenta → Acceso y seguridad → Tokens API y cree uno. Su propietario necesita el permiso «API de sistema de acceso» (el rol Admin lo tiene) y el derecho de editar los libros en los que escriben sus escenas. |
| Dirección de BookStack | string | Sí | La dirección en la que abre BookStack (su APP_URL). |
| ID del token | string | Sí | |
| Secreto del token | secret | Sí | Se muestra una sola vez, al crear el token. |
| Leer BookStack cada | select | No | Las páginas modificadas se anuncian en la siguiente lectura. |
| Idioma de nombres y mensajes | select | No | Los nombres de las funciones se fijan al añadir un dispositivo a Gladys. |
Cómo instalar BookStack en Gladys
- En Gladys, abre Integraciones: BookStack 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-bookstack:1.0.0), 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-bookstack.
BookStack 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
BookStack 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