Monitores de datos¶

El campo Monitor de datos crea un tipo especial de observación que recoge datos de forma automática a partir de una fuente —un sensor, un dispositivo o un servicio web— que envía información de forma periódica y recurrente. Peneira guarda el histórico de todas las mediciones y lo muestra en una gráfica o en una tabla, incluso después de cerrar la aplicación.

Es útil para estaciones meteorológicas, sensores ambientales, invernaderos, acuarios, dispositivos Arduino, ESP32 o micro:bit, y para cualquier servicio web que devuelva datos numéricos en formato JSON.

¿Quién configura cada parte?¶

El profesorado añade el campo Monitor de datos a la categoría y escribe su nombre y descripción.
La persona que crea una observación configura la fuente concreta, los valores que quiere recoger, las unidades y la duración. La frecuencia solo se configura cuando Peneira consulta una fuente web.
Cualquier persona con acceso a la observación publicada puede consultar las gráficas y la tabla.
La dirección de envío y el token de un dispositivo son privados: solo pueden verlos la persona autora de la observación, el profesorado del proyecto y la administración.

¿Cómo llegarán los datos?¶

Al llegar al campo Monitor de datos hay que elegir uno de los dos modos.

Selector del modo del monitor: el dispositivo envía los datos o Peneira consulta una dirección web

Peneira recibe datos de un dispositivo externo (modo push)¶

Elige esta opción para un Arduino, ESP32, micro:bit con una pasarela de Internet u otro dispositivo capaz de hacer peticiones HTTP.

Indica la duración de la captura. El valor 0 significa que no hay fecha de fin.
Define los valores, rutas JSON y unidades que quieres recoger (puedes añadir entre 1 y 12).
Pulsa Obtener URL y token para ver la dirección POST, el token privado y un ejemplo del JSON que debe enviar el dispositivo.
Guarda estos datos en la configuración del dispositivo y crea la observación.

Tres valores configurados: temperatura, ruido y luz, con sus rutas JSON y unidades

Peneira no consulta el dispositivo ni le impone una frecuencia: la dirección queda a la escucha y guarda cada envío cuando llega.

Si tienes dudas sobre el formato, pulsa ¿Cómo funciona? para ver un ejemplo del payload y los pasos exactos.

Diálogo de ayuda del modo push con el ejemplo de payload y los pasos de envío

Cuando pulsas Obtener URL y token, Peneira muestra la dirección POST, el token privado y un ejemplo del cuerpo JSON:

Dirección POST, token privado y ejemplo del cuerpo JSON tras pulsar Obtener URL y token

El token se envía en la cabecera HTTP:

Authorization: Bearer TOKEN_PRIVADO

Credenciales privadas

No compartas el token ni lo publiques en el código fuente. Peneira lo muestra durante la configuración para que puedas guardarlo directamente en el dispositivo. No vuelve a aparecer después de crear la observación.

Peneira se conecta a un servicio web (modo pull)¶

Elige esta opción cuando ya existe una API pública, por ejemplo un servicio meteorológico.

Introduce una dirección https:// que devuelva un objeto JSON.
Elige la frecuencia de consulta (entre 5 minutos y 7 días).
Indica la duración de la captura.
Define los valores que Peneira debe extraer.
Usa Probar conexión para comprobar la respuesta antes de crear la observación.

Por seguridad, la URL no puede apuntar a localhost, a una red privada ni incluir usuario y contraseña. Solo se admite HTTPS y no se siguen redirecciones.

Sugerencias de campos con IA¶

Si la administración ha configurado un proveedor LLM, las personas identificadas verán el botón Detectar campos junto a la prueba de conexión (solo en el modo pull). Peneira consulta primero la fuente, localiza sus valores numéricos y propone nombres, rutas JSON y unidades. Las sugerencias se pueden revisar y seleccionar antes de añadirlas; nunca se aplican automáticamente.

Para proteger la privacidad, Peneira no envía al modelo la URL de la fuente, credenciales, datos de la sesión ni la respuesta JSON completa: solo una lista limitada de rutas numéricas y sus valores de muestra.

Cómo seleccionar valores de un JSON¶

Cada medición tiene tres datos:

Nombre de la medición: etiqueta comprensible que aparecerá en la gráfica, por ejemplo Temperatura.
Ruta JSON: lugar en el que está el número dentro de la respuesta.
Unidad: texto que se mostrará junto al valor, por ejemplo °C, %, ppm o lux.

Las rutas empiezan por $.. Supongamos que la fuente devuelve:

{
  "temperatura": 21.6,
  "ambiente": {
    "humedad": 68
  },
  "sensores": [
    { "nombre": "exterior", "valor": 18.4 },
    { "nombre": "aula", "valor": 22.1 }
  ]
}

Valor deseado	Ruta JSON	Resultado
Temperatura	`$.temperatura`	`21.6`
Humedad dentro de `ambiente`	`$.ambiente.humedad`	`68`
Valor del primer sensor	`$.sensores[0].valor`	`18.4`
Valor del segundo sensor	`$.sensores[1].valor`	`22.1`

Las listas empiezan en cero

En una lista JSON el primer elemento es [0], el segundo es [1], el tercero es [2], etc.

Peneira solo crea puntos en la gráfica para valores numéricos. Si una ruta no existe en una respuesta concreta, esa medición queda vacía en esa muestra y el resto continúa guardándose.

Fecha y hora de las mediciones¶

Peneira usa como fecha y hora el momento en el que recibe o consulta cada medición. Así evita interpretar incorrectamente horas locales, fechas parciales u otros campos temporales de la respuesta.

Consultar los datos¶

Una observación activa muestra:

indicador EN VIVO y frecuencia de actualización;
última medición recibida;
número de muestras;
una gráfica por cada valor, con su unidad y con los valores en los ejes;
vista alternativa en Tabla;
descarga de los datos en CSV para usuarios con acceso.

Vista en gráfica con un monitor en vivo y tres mediciones: temperatura, ruido y luz

Pulsa Tabla para ver todas las muestras en filas, con la fecha y hora de cada una:

Vista en tabla con las muestras ordenadas de la más reciente a la más antigua

El monitor continúa en el servidor aunque se cierre Peneira. Si la observación necesita moderación, la captura comienza cuando el profesorado la aprueba.

Mientras la observación está abierta y visible, los datos se actualizan automáticamente sin pulsar F5: aproximadamente cada 5 segundos en los monitores a los que envía datos un dispositivo y cada 15 segundos en las fuentes web. Si cambias a la vista de tabla, Peneira conserva esa vista al incorporar nuevas muestras.

Ejemplo completo: una micro:bit V2 que envía datos a Peneira¶

En esta guía la micro:bit mide temperatura, ruido y luz y, al pulsar el botón A, las envía a un monitor push de Peneira.

La micro:bit no tiene WiFi

La micro:bit V2 no puede hacer peticiones HTTP por sí sola. Por eso la placa escribe cada medición en el puerto serie USB y un pequeño programa en el ordenador (la pasarela) las reenvía a Peneira con el token privado. Mientras la pasarela esté abierta y la placa conectada por USB, los datos llegan solos al pulsar el botón.

Necesitas:

una placa micro:bit V2 y un cable USB;
un ordenador con Python 3;
los archivos de ejemplo:
- peneira-microbit-v2.hex — el programa listo para grabar en la placa;
- peneira_gateway.py — la pasarela del ordenador;
- main.ts — el código fuente, por si quieres modificarlo en MakeCode.

1. Graba el programa en la micro:bit¶

Conecta la micro:bit al ordenador con un cable USB. Aparecerá como una unidad llamada MICROBIT.
Descarga peneira-microbit-v2.hex y cópialo dentro de esa unidad. La placa parpadea mientras graba y muestra un ♥ al terminar.

El programa hace lo siguiente cada vez que pulsas el botón A:

{ "temperatura": 21.6, "ruido": 62.5, "luz": 508 }

temperatura: temperatura interna del chip, en °C.
ruido: nivel del micrófono convertido a un valor aproximado en dB.
luz: nivel de luz de la matriz de LED convertido a un valor aproximado en lux.

Valores aproximados

La micro:bit no es un sonómetro ni un luxómetro. Los valores de ruido y luz son estimaciones a partir de sus sensores integrados; si necesitas medidas exactas, ajusta la conversión en el código fuente o usa sensores calibrados.

2. Configura el campo Monitor de datos¶

En la observación, elige El dispositivo envía los datos a Peneira y añade estos tres valores:

Nombre	Ruta JSON	Unidad
temperatura	`$.temperatura`	°C
ruido	`$.ruido`	dB
luz	`$.luz`	lux

Pon la duración en 0 (sin fecha de fin), pulsa Obtener URL y token y guarda la dirección POST y el token: los necesitas en el siguiente paso.

3. Ejecuta la pasarela en el ordenador¶

La pasarela lee lo que la placa escribe en el USB y lo reenvía a Peneira.

Instala la dependencia (solo la primera vez):
```
pip install pyserial
```

Descarga peneira_gateway.py e indícale tu dirección y token. Puedes usar variables de entorno:

export PENEIRA_MONITOR_URL="https://peneira.cesga.es/api/web-monitor/TU_ID/readings"
export PENEIRA_MONITOR_TOKEN="TU_TOKEN"
python3 peneira_gateway.py

…o pasarlos como argumentos:

python3 peneira_gateway.py --url "https://peneira.cesga.es/api/web-monitor/TU_ID/readings" --token "TU_TOKEN"

La pasarela detecta la placa automáticamente. Al pulsar el botón A, verás algo así:

Escoitando a micro:bit en /dev/cu.usbmodem1102 a 115200 baudios.
Preme o botón A da placa para enviar unha medición. Ctrl+C para saír.

→ {"temperatura": 22, "ruido": 62.5, "luz": 508}
  ✓ gardada ás 2026-07-30T09:17:47.000Z

En Peneira, la observación mostrará EN VIVO y las nuevas muestras aparecerán en la gráfica sin recargar la página.

Comprueba primero sin enviar nada

Ejecuta python3 peneira_gateway.py --dry-run para ver las mediciones en el terminal sin enviarlas a Peneira. Es útil para confirmar que la placa y el cable funcionan.

Solución de problemas¶

Mensaje	Qué significa	Qué hacer
`Non se atopou ningunha micro:bit`	La pasarela no ve la placa.	Comprueba el cable USB o indica el puerto con `--port /dev/...`.
`Non se puido abrir ...`	Otro programa está usando el puerto.	Cierra el editor de MakeCode o cualquier monitor serie abierto.
`token non válido` (401)	El token no coincide.	Copia de nuevo el token con Obtener URL y token.
`demasiado rápido` (429)	Más de una medición por segundo.	Espera un intervalo entre pulsaciones del botón.
`o monitor xa non acepta medicións` (410)	Terminó la duración de la captura.	Crea una nueva observación o aumenta la duración.

Glosario¶

Monitor de datos: observación que sigue recibiendo mediciones a lo largo del tiempo desde una fuente automática.
push (Peneira recibe datos de un dispositivo externo): el dispositivo hace la petición y envía los datos a Peneira cuando quiere. Peneira solo queda a la escucha.
pull (Peneira se conecta a un servicio web): Peneira se conecta periódicamente a una dirección web y lee los datos.
endpoint: la dirección web a la que el dispositivo envía cada medición mediante una petición HTTP POST.
payload: los datos que el dispositivo envía en cada petición, en formato JSON.
token / Bearer: clave secreta que autentica los envíos del dispositivo; va en la cabecera «Authorization: Bearer». No la compartas.
ruta JSON: indica dónde está cada valor dentro del JSON; empieza por «$.», por ejemplo $.temperatura.
HTTPS: versión segura y cifrada del protocolo web. La dirección que Peneira da para el dispositivo usa siempre HTTPS.
medición / muestra: cada conjunto de valores recibido en un momento concreto.

Recomendaciones¶

Usa nombres cortos y claros: Temperatura, Humedad, CO₂.
Incluye siempre la unidad.
Prueba primero la fuente web (modo pull) o usa --dry-run (modo push).
No consultes una API con más frecuencia de la necesaria.
En los dispositivos, conserva el token fuera del código que publiques.
Comprueba que los valores enviados son números y que el JSON es válido.