Monitores de datos

O campo Monitor de datos crea un tipo especial de observación que recolle datos de xeito automático a partir dunha fonte —un sensor, un dispositivo ou un servizo web— que envía información de forma periódica e recorrente. Peneira garda o histórico de todas as medicións e amósao nunha gráfica ou nunha táboa, mesmo despois de pechar a aplicación.

É útil para estacións meteorolóxicas, sensores ambientais, invernadoiros, acuarios, dispositivos Arduino, ESP32 ou micro:bit, e para calquera servizo web que devolva datos numéricos en formato JSON.

Quen configura cada parte?

• O profesorado engade o campo Monitor de datos á categoría e escribe o seu nome e descrición.
• A persoa que crea unha observación configura a fonte concreta, os valores que quere recoller, as unidades e a duración. A frecuencia só se configura cando Peneira consulta unha fonte web.
• Calquera persoa con acceso á observación publicada pode consultar as gráficas e a táboa.
• O enderezo de envío e o token dun dispositivo son privados: só pode velos a persoa autora da observación, o profesorado do proxecto e a administración.

Como chegarán os datos?

Ao chegar ao campo Monitor de datos hai que escoller un dos dous modos.

Peneira recibe datos dun dispositivo externo (modo push)

Escolle esta opción para un Arduino, ESP32, micro:bit cunha pasarela de Internet ou outro dispositivo capaz de facer peticións HTTP.

1. Indica a duración da captura. O valor 0 significa que non hai unha data de fin.
2. Define os valores, rutas JSON e unidades que quere recoller (podes engadir entre 1 e 12).
3. Preme Obter URL e token para ver o enderezo POST, o token privado e un exemplo do JSON que debe enviar o dispositivo.
4. Garda estes datos na configuración do dispositivo e crea a observación.

Peneira non consulta o dispositivo nin lle impón unha frecuencia: o enderezo queda á escoita e garda cada envío cando chega.

Se tes dúbidas sobre o formato, preme Como funciona? para ver un exemplo do payload e os pasos exactos.

Cando premes Obter URL e token, Peneira amosa o enderezo POST, o token privado e un exemplo do corpo JSON:

O token envíase no cabezallo HTTP:

Authorization: Bearer TOKEN_PRIVADO

Credenciais privadas

Non compartas o token nin o publiques no código fonte. Peneira amósao durante a configuración para que poidas gardalo directamente no dispositivo. Non volve aparecer despois de crear a observación.

Peneira conéctase a un servizo web (modo pull)

Escolle esta opción cando xa existe unha API pública, por exemplo un servizo meteorolóxico.

1. Introduce un enderezo https:// que devolva un obxecto JSON.
2. Escolle a frecuencia de consulta (entre 5 minutos e 7 días).
3. Indica a duración da captura.
4. Define os valores que Peneira debe extraer.
5. Usa Probar conexión para comprobar a resposta antes de crear a observación.

Por seguridade, a URL non pode apuntar a localhost, a unha rede privada nin incluír usuario e contrasinal. Só se admite HTTPS e non se seguen redireccións.

Suxestións de campos con IA

Se a administración configurou un provedor LLM, as persoas identificadas verán o botón Detectar campos xunto á proba de conexión (só no modo pull). Peneira consulta primeiro a fonte, localiza os seus valores numéricos e propón nomes, rutas JSON e unidades. As suxestións pódense revisar e seleccionar antes de engadilas; nunca se aplican automaticamente.

Para protexer a privacidade, Peneira non envía ao modelo a URL da fonte, credenciais, datos da sesión nin a resposta JSON completa: só unha lista limitada de rutas numéricas e os seus valores de mostra.

Como seleccionar valores dun JSON

Cada medición ten tres datos:

• Nome da medición: etiqueta comprensible que aparecerá na gráfica, por exemplo Temperatura.
• Ruta JSON: lugar no que está o número dentro da resposta.
• Unidade: texto que se amosará xunto ao valor, por exemplo °C, %, ppm ou lux.

As rutas comezan por $.. Supoñamos que a fonte devolve:

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

Valor desexado	Ruta JSON	Resultado
Temperatura	$.temperatura	21.6
Humidade dentro de ambiente	$.ambiente.humidade	68
Valor do primeiro sensor	$.sensores[0].valor	18.4
Valor do segundo sensor	$.sensores[1].valor	22.1

As listas comezan en cero

Nunha lista JSON o primeiro elemento é [0], o segundo é [1], o terceiro é [2], etc.

Peneira só crea puntos na gráfica para valores numéricos. Se unha ruta non existe nunha resposta concreta, esa medición queda baleira nesa mostra e o resto continúa gardándose.

Data e hora das medicións

Peneira usa como data e hora o momento no que recibe ou consulta cada medición. Así evita interpretar incorrectamente horas locais, datas parciais ou outros campos temporais da resposta.

Consultar os datos

Unha observación activa mostra:

• indicador EN VIVO e frecuencia de actualización;
• última medición recibida;
• número de mostras;
• unha gráfica por cada valor, coa súa unidade, cos valores nos eixos;
• vista alternativa en Táboa;
• descarga dos datos en CSV para usuarios con acceso.

Preme Táboa para ver todas as mostras en filas, coa data e hora de cada unha:

O monitor continúa no servidor aínda que se peche Peneira. Se a observación necesita moderación, a captura comeza cando o profesorado a aproba.

Mentres a observación está aberta e visible, os datos actualízanse automaticamente sen premer F5: aproximadamente cada 5 segundos nos monitores aos que envía datos un dispositivo e cada 15 segundos nas fontes web. Se cambias á vista de táboa, Peneira conserva esa vista ao incorporar novas mostras.

Exemplo completo: unha micro:bit V2 que envía datos a Peneira

Nesta guía a micro:bit mide temperatura, ruído e luz e, ao premer o botón A, envíaas a un monitor push de Peneira.

A micro:bit non ten WiFi

A micro:bit V2 non pode facer peticións HTTP por si soa. Por iso a placa escribe cada medición no porto serie USB e un pequeno programa no ordenador (a pasarela) reenvíaas a Peneira co token privado. Mentres a pasarela estea aberta e a placa conectada por USB, os datos chegan sós ao premer o botón.

Necesitas:

• unha placa micro:bit V2 e un cable USB;
• un ordenador con Python 3;
• os dous ficheiros de exemplo:
• peneira-microbit-v2.hex — o programa listo para gravar na placa;
• peneira_gateway.py — a pasarela do ordenador;
• main.ts — o código fonte, por se queres modificalo en MakeCode.

1. Grava o programa na micro:bit

1. Conecta a micro:bit ao ordenador cun cable USB. Aparecerá como unha unidade chamada MICROBIT.
2. Descarga peneira-microbit-v2.hex e cópiao dentro desa unidade. A placa parpadea mentres grava e amosa un ♥ ao rematar.

O programa fai o seguinte cada vez que premes o botón A:

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

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

Valores aproximados

A micro:bit non é un sonómetro nin un luxómetro. Os valores de ruido e luz son estimacións a partir dos seus sensores integrados; se necesitas medidas exactas, axusta a conversión no código fonte ou usa sensores calibrados.

2. Configura o campo Monitor de datos

Na observación, escolle O dispositivo envía os datos a Peneira e engade estes tres valores:

Nome	Ruta JSON	Unidade
temperatura	$.temperatura	°C
ruido	$.ruido	dB
luz	$.luz	lux

Pon a duración en 0 (sen data de fin), preme Obter URL e token e garda o enderezo POST e o token: necesitalos no seguinte paso.

3. Executa a pasarela no ordenador

A pasarela le o que a placa escribe no USB e reenvíao a Peneira.

1. Instala a dependencia (só a primeira vez):

   pip install pyserial
   

2. Descarga peneira_gateway.py e indícalle o teu enderezo e token. Podes usar variables de contorno:

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

   …ou pasalos como argumentos:

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

3. A pasarela detecta a placa automaticamente. Ao premer o 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, a observación amosará EN VIVO e as novas mostras aparecerán na gráfica sen recargar a páxina.

Comproba primeiro sen enviar nada

Executa python3 peneira_gateway.py --dry-run para ver as medicións no terminal sen envialas a Peneira. É útil para confirmar que a placa e o cable funcionan.

Solución de problemas

Mensaxe	Que significa	Que facer
Non se atopou ningunha micro:bit	A pasarela non ve a placa.	Comproba o cable USB ou indica o porto con --port /dev/....
Non se puido abrir ...	Outro programa está usando o porto.	Pecha o editor de MakeCode ou calquera monitor serie aberto.
token non válido (401)	O token non coincide.	Copia de novo o token con Obter URL e token.
demasiado rápido (429)	Máis dunha medición por segundo.	Agarda un intervalo entre pulsacións do botón.
o monitor xa non acepta medicións (410)	Rematou a duración da captura.	Crea unha nova observación ou aumenta a duración.

Glosario

• Monitor de datos: observación que segue recibindo medicións ao longo do tempo desde unha fonte automática.
• push (Peneira recibe datos dun dispositivo externo): o dispositivo fai a petición e envía os datos a Peneira cando quere. Peneira só queda á escoita.
• pull (Peneira conéctase a un servizo web): Peneira conéctase periodicamente a un enderezo web e le os datos.
• endpoint: o enderezo web ao que o dispositivo envía cada medición cunha petición HTTP POST.
• payload: os datos que o dispositivo envía en cada petición, en formato JSON.
• token / Bearer: clave secreta que autentica os envíos do dispositivo; vai na cabeceira «Authorization: Bearer». Non a compartas.
• ruta JSON: indica onde está cada valor dentro do JSON; comeza por «$.», por exemplo $.temperatura.
• HTTPS: versión segura e cifrada do protocolo web. O enderezo que Peneira dá para o dispositivo usa sempre HTTPS.
• medición / mostra: cada conxunto de valores recibido nun momento concreto.

Recomendacións

• Usa nomes curtos e claros: Temperatura, Humidade, CO₂.
• Inclúe sempre a unidade.
• Proba primeiro a fonte web (modo pull) ou usa --dry-run (modo push).
• Non consultes unha API con máis frecuencia da necesaria.
• Nos dispositivos, conserva o token fóra do código que publiques.
• Comproba que os valores enviados son números e que o JSON é válido.