Article de wiki

Fluxos Node-RED

Publicat per Ainhoa Pascualena Lasa el 04/02/2022 - 12:22 | Última modificació: 03/05/2023 - 17:30

1. Importar fluxos Node-RED de la Wiki

El flux s'importa a la instància Node-RED accedint a:

"Menú hamburguesa -> Import -> Clipboard" i marquem l'opció "Import to new flow".

 

2. Sostenibilitat i medi ambient

2.1. LoraWan - Flux d'integració de dades de sensors de qualitat de l'aire (descarrega)

Agraïr l'aportació desinteresada de l'Ajuntament d'Arenys de Munt amb aquest flux. En concret s'integren dades de dispositius dels fabricants DecentLab i Dragino.

Amb la col·laboració de Femprocomuns han fet un esforç d’adaptació important del flux per a que sigui reutilitzable per altres municipis i altres dispositius de diferents fabricants.

El flux està dividit en 5 etapes:

  1. Configuració, s'injecta la configuració amb els dispositius que es volen monitorar. Per cada dispositiu es registra l'identificador, tipus de dispositiu, proveïdor associat a Sentilo i un "mapeig" de camps entre els que torna el dispositiu i com es diuen els sensors associats a Sentilo. 
  2. Entrada de dades. Es reben les dades des del servidor LoraWAN, es filtren per processar només els dispositius que volem i preprocessa l'entrada de dades per tenir un "buffer" de bytes.
  3. Descodificació. En funció del tipus de dispositiu es fa passar el "buffer" de bytes per un descodificador o un altre. Aquests descodificadors són els proporcionats pel fabricant del dispositiu (en el codi s'inclou la referència) però modificats per tal que la sortida sigui homogènia entre diferents fabricants. A aquestes alçades tindrem un llistat de camps i valors.
  4. Es "mapegen" els camps que torna el descodificador del dispositiu a sensors a Sentilo basant-nos en la informació de configuració. La sortida es passa per una plantilla i es neteja per obtenir un missatge preparat pel node de publicació de Sentilo.
  5. S'ingereixen les dades a Sentilo en funció del proveïdor associat en aquest. Un únic missatge genera una única crida al node "publish" de Sentilo amb dades dels N sensors associats a aquell dispositiu.

S'ha dissenyat modularment amb l'objectiu de homogeneïtzar els fluxos per afavorir la replicació i manteniment del codi.
Permet identificar quins són els nodes i variables específics per cada sensor i fabricant.

Autoria: xoic@femprocomuns.coop

 

2.2. Meteocat - Flux d'integració de dades (descarrega)

Documentació de la sessió de Formació, veure enllaç

2.3. PLC's Loxonne - Flux d'integració de dades (descarrega)

2.3.1. Descripció del funcionament 

El flux utilitza l’API de Miniserver de Loxone per obtenir les dades actuals d’un sensor concret. Existeix un servei de núvol de Loxone que ofereix accés al Miniserver sense necessitat de conèixer la IP de Miniserver prèviament - només és necessari saber el ID de Miniserver.

Bàsicament, el flux segueix aquests passos:

  1. Llegeix la configuració dels sensors, cada hora o una vegada al día
  2. Per cada sensor fa una crida a l’API de Loxone i recupera la dada actual del sensor en format XML
  3. Si la connexió en el punt anterior falla, torna a provar
  4. Parseja la resposta XML i obté el valor
  5. Publica el valor a Sentilo.

2.3.2. Configuració del flux

Configuració de la connexió a Sentilo

Si fem un doble clic sobre el node "Publica a Sentilo", podem escollir una connexió a Sentilo de les existents o configurar una nova.

Alternativament, podem esborrar la connexió importada i crear o reutilitzar una connexió que ja tenim dins de la nostra instància de Node-RED.

 

Configuració dels sensors a importar

Dins dels nodes Function "Configuració dels sensors amb lectura horària" i "Configuració dels sensors amb lectura diària" hi ha una array javascript SENSORS.

Cada element de la array és una configuració de sensor amb les següents atributs:

  • Miniserver: ID de Miniserver Loxone
  • Sensor: ID de Sensor Loxone
  • Usr: Usuari d'accés a Miniserver
  • Pass: Contrasenya d'accés a Miniserver
  • sSensor: ID de sensor de Sentilo

Per exemple, la definició de sensor seria:

  {
    "lMiniserver":"504F94A050B0",
    "lSensor":"08213ENS001_MV_BMC1_ENER",
    "lUsr":"x",
    "lPass":"x",
    "sSensor":"08213ENS001_MV_BMC1_ENER" 
  }

El flux processarà tots els elements de la array SENSORS, si està activat el seu Inject Node (veure el següent apartat).

 

Programació periódica de l'execució

Dins del flux hi ha 2 injectors, cadascun pensat per planificar l’execució amb una freqüència different. Per defecte estan desactivats. Si volem activar la execució de cada hora, hem de accedir a la configuració d’Inject Node "Cada hora" i configurar-ho d’aquesta forma:

Desplegament del flux

Finalment publiquem les nostres canvis amb el botó "Deploy".

En cas d'incidència, podem activar els nodes "Debug" i revisar el contingut dels missatges en la pestanya log.

2.4. Qualitat de l'aire - Flux d'integració de dades de Qualitat de l'Aire (descàrrega)

El flux d'integració de dades de Qualitat de l'Aire del portal de Dades Obertes de Catalunya permet consultar, decarregar i, posteriorment, publicar les dades d'estaciones de mesura de qualitat de l'aire en la plataforma Sentilo per a un grup d'ens determinat.

2.4.1. Descripció del fluxe

El fluxe consta de 4 parts:

2.4.2. Dependències

Aquest fluxe fa servir la llibreria node-red-contrib-loop-processing, que caldrà tenir instal·lada prèviament:

2.4.3. Configuració

El node principal del fluxe és el node que injecta la configuració necessària per al correcte funcionament, tant a nivell d'obtenció de les dades com de publicació.

Els camps que cal configurar en aquest node són:

  • msg.ensList: llistat en format json amb les dades dels ens i la configuació necessària per obtenir i publicar les dades​​ (veieu l'annex per a més informació)​:
    • ENS: identificador de l'ens
    • nomEstacio: nom identificador de l'estació a la que es consultarà les dades (veieu la definició del servei per a més informació)
    • prefixComponent: el prefix que es farà servir per a crear el component al que s'annexaran els sensors de les dades obtingudes, el format final serà <prefixComponent>_AIR_QUALITY (el sufix és configurable amb el paràmetre msg.sufixComponent)
    • provider: el proveïdor al qual pertany el component que rebrà les dades
    • token: token d'autorització del proveïdor per tal de poder crear el component, sensors i publicar les dades
  • msg.sentiloEndPoint: enpoint de l'api de Sentilo a la qual es publicarà les dades
  • msg.sufixComponent: sufix per defecte de tots els components que crearà aquest fluxe (es fa servir al punt d'ensList)
  • msg.tipusComponent: tipus del component que es crearà (cal que existeixi prèviament al Catàleg de Sentilo)
  • msg.tipologies: llistat de tipologies que es farà servir per crear els sensors segons el seu contaminant (les tipologies han d'existir prèviament al Catàleg de Sentilo)

Finalment, l'execució del fluxe està marcada per a que s'executi de forma automàtica cada dia a les 6:00 del matí, tot i que tambè és possible l'execució manual, fent click en aquest node, o bé configurar el mètode automàtic al mateix node:

2.4.4. Funcionament

El fluxe s'executa diàriament a les 6:00h del matí de forma automàtica, com ja em vist, o bé de forma manual (fent click al node d'inici). És totalment configurable segons les nostres necessitats.

L'execució itera tots els ens existents al llistat de configuració d'ens, per a cadascún, obté les dades de l'estació associada, verifica l'existència del component i els sensors a Sentilo i, si escau, publica les dades als sensors de la tipologia associada a cada contaminant.

En cas que el component / sensors no existeixin es creen prèviament a la publicacio de les dades (en aquest cas el fluxe farà una espera d'un minut abans de la publicació de les dades, per tal que el Catàleg de Sentilo pugui recarregar la caxé de components convenientment).

Les dades consultades sempre son les darreres obtingudes pel servei (dia anterior). En cas que el fluxe detecti que no existeixi el component, els sensors o bé que aquests no tinguin dades actualitzades, es demanarà pels darrers 30 dies, per tal de poder dispossar d'un històric de dades suficientment gran per a poder fer l'explotació de les mateixes.

Finalment el fluxe mostra per la barra de logs l'estat de finalització. Cal tenir els nodes de log actius.

Per defecte es mostren els següents logs:

  • API data url: mostra la URL que es fa servir per demanar les dades de l'estació actual
  • Resultat crear sensors: indica l'estat després d'haver creat els sensors
  • Finalitza error creació sensors: informa la finalització de l'execució per error en crear sensor
  • Resultat publicar observations: mostra el resultat de publicar les observacions
  • Finalitza error publicació observacions: informa la finalització de l'execució per error en publicar observacions

Les dades apareixeran als sensors del component associat a l'ens.

2.4.5. Annex

2.4.5.1. Configuració principal - Ens / Estacions

Aquest és un exemple de configuració bàsica dels ens i les estaciones relacionades:

[
    {
        "ENS": "DIBA",
        "nomEstacio": "Barcelona (Sants)",
        "prefixComponent": "BARCELONA_SANTS",
        "provider": "diba@POLLUTION_PROVIDER",
        "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" 
    }
]

Aquesta configuració esdevindrà en una consulta a l'estació "Barcelona (Sants)", i publicarà les dades als sensors associats al component BARCELONA_SANTS_AIR_QUALITY del proveïdor diba@POLLUTION_PROVIDER. El token en aquest exemple és ocult, cal emplenar-lo amb les dades correctes.

2.4.5.2. Configuració de contaminants - Dades mestres

Aquest és un exemple de configuració de contaminants, que relacionen la dada de l'estació amb la tipologia de sensors, que cal que existeixin prèviament a Sentilo (aquestes dades en format json estan configurades per defecte al node de configuració i només cal canviar-les si hi ha nous contaminants, o es vol canviar la relació entre contaminants i tipologies de sensors):

{
    "1": {
        "magnitud": "1",
        "contaminant": "SO2",
        "unitats": "µg/m3",
        "typology": "air_quality_so2" 
    },
    "6": {
        "magnitud": "6",
        "contaminant": "CO",
        "unitats": "mg/m3",
        "typology": "air_quality_co" 
    },
    "7": {
        "magnitud": "7",
        "contaminant": "NO",
        "unitats": "µg/m3",
        "typology": "air_quality_no" 
    },
    "8": {
        "magnitud": "8",
        "contaminant": "NO2",
        "unitats": "µg/m3",
        "typology": "air_quality_no2" 
    },
    "9": {
        "magnitud": "9",
        "contaminant": "PM2.5",
        "unitats": "µg/m3",
        "typology": "air_quality_pm25" 
    },
    "10": {
        "magnitud": "10",
        "contaminant": "PM10",
        "unitats": "µg/m3",
        "typology": "air_quality_pm10" 
    },
    "12": {
        "magnitud": "12",
        "contaminant": "NOX",
        "unitats": "µg/m3",
        "typology": "air_quality_nox" 
    },
    "14": {
        "magnitud": "14",
        "contaminant": "O3",
        "unitats": "µg/m3",
        "typology": "air_quality_o3" 
    },
    "30": {
        "magnitud": "30",
        "contaminant": "C6H6",
        "unitats": "µg/m3",
        "typology": "air_quality_c6h6" 
    },
    "65": {
        "magnitud": "65",
        "contaminant": "H2S",
        "unitats": "µg/m3",
        "typology": "air_pollutant" 
    }
}
2.4.5.3. Informació sobre el servei - Qualitat de l’aire als punts de mesurament automàtics de la Xarxa de Vigilància i Previsió de la Contaminació Atmosfèrica

Podeu consultar la descripció de serviei de dades obertes de Catalunya "Qualitat de l’aire als punts de mesurament automàtics de la Xarxa de Vigilància i Previsió de la Contaminació Atmosfèrica" a la següent url: 

A més, la descripció de l'api que hem fet servir per a construir aquest fluxe la podeu trobar a:

La crida que el fluxe fa a l'api és del tipus:

https://analisi.transparenciacatalunya.cat/resource/tasf-thgu.json?nom_estacio=Manlleu&data=2023-04-13

on:

  • nom_estacio: correspon al paràmetre nomEstacio configurat per a cada ens
  • data: data de consulta

Per tal de fer una consulta online de forma visual, podeu fer servir aquesta utilitat:

3. Adaptacions necessàries dels fluxos per actualització de la versió del Node-Red a v0.5.1

L'actualització de Node-RED a la versió 2.2.2, també ha aportat actualitzacions d'alguns nodes, com és el cas dels de Sentilo, que passen de la versió v0.1.5 a la v0.5.1.

Per tal de poder continuar fent servir els nostres fluxes que utilitzen aquests nodes, caldrà fer una petita intervenció.

A continuació es detalla com cal actuar per tal d'adaptar els fluxes a la nova versió si és necessari.

3.1. Detalls de la versió v0.1.5

Si recordem els nodes de la versió anterior, teníem la següent col·lecció:

que estava formada per 3 nodes funcionals i un de configuració del servidor (node intern):

  • retrieve: permet obtenir dades de Sentilo, i les ofereix a la seva sortida
  • publish: permet publicar dades a Sentilo, injectades com a entrada en format observation
  • subscribe: permet subscriure's a un recurs de Sentilo (en el moment del desplegament del fluxe), i ens ofereix la dada publicada a la seva sortida, en format observació
  • server: ofereix un espai de configuració per a la connexió a Sentilo, que es pot fet servir a la resta de nodes del fluxe

3.2. Detalls de la versió v0.5.1

La nova versió de nodes de Sentilo, la v0.5.1, ofereix els mateixos nodes funcionals, i el node de servidor. A part, s'ha introduït un nou node de subscripció:

un cop més tenim:

  • retrieve: permet obtenir dades de Sentilo, i ofereix dos dades de sortida
    • sortida 1: resposta de l'api de Sentilo, amb la dada sol·licitada
    • sortida 2: codi http de resposta del servidor de Sentilo
  • publish: permet publicar dades a Sentilo, injectades com a entrada en format observation, i ofereix dos sortides:
    • sortida 1: només en cas d'error, emetrà el missatge retornat per l'api de Sentilo, o un missatge buit si tot ha anat bé
    • sortida 2: codi http de resposta del servidor de Sentilo
  • subscribe with endpoint: permet subscriure's a un recurs de Sentilo (en el moment del desplegament del fluxe) i rebre la dada al mateix node, tenim 3 sortides:
    • sortida 1: ofereix la dada a la qual estem subscrits en el moment de la seva publicació (actua com a endpoint)
    • sortida 2: ofereix la resposta de Sentilo a l'event de subscripció (només un cop, quan fem el desplegament del fluxe)
    • sortida 3: ofereix el codi de resposta http que ens retorna el servidor en el moment de fer la subscripció
  • subscribe without endpoint: aquest node és una modificació del node subscription with endpoint de anterior, però amb la particularitat que accepta dades d'entrada (de configuració), i no genera dades de sortida quan es publica una dada a la que estem subscrits (no crea un endpoint), sinò que les reenvia cap a una adreça remota (de fet, el que fa és generar una subscripció cap a la url que informarem a la dada Callback URL de la seva configuració).
    El funcionament segueix sent molt semblant al cas anterior, però com a sortida disposem de dos canals que podem explotar:
    • sortida 1: ofereix la resposta de Sentilo a l'event de subscripció (només un cop, quan fem el desplegament del fluxe)
    • sortida 2: ofereix el codi de resposta http que ens retorna el servidor en el moment de fer la subscripció
  • server: ofereix un espai de configuració per a la connexió a Sentilo, que es pot fet servir a la resta de nodes del fluxe

Com veiem, els nodes publish i retrieve mantenen la seva funcionalitat, i afegeixen una nova sortida informativa.

Per contra, els dos nodes de subscripció han canviat. El primer, subscribe with endpoint és l'equivalent a l'original de la versió anterior, mentres que el subscribe without endpoint és un node nou que afegeix una nova funcionalitat.

A continuació es mostra un conjunt d'imatges amb l'estructura funcional de cadascun d'ells, i com explotar la seva sortida:

Retrieve

Publish

Subscribe with endpoint

Subscribe without endpoint

En aquest darrer cas cal tenir en compte el node function anomenat Prepara subscripció que és l'encarregat d'injectar les dades de configuració del node de subscripció.

3.3. Com adaptar fluxes a la nova versió dels nodes de Sentilo

Per tal d'adaptar els nostres fluxes a la nova versió de Sentilo v0.5.1, cal seguir unes passes molt senzilles que tot seguit explicarem.

Prendrem com a referència el fluxe de test Meteocat Simple:

Com podem veure, el node publish està connectat a un node funcional que li prepara les dades a enviar (node Prepare Sentilo msg).

En arrencar la instància normalment detectarà que aquest node ha estat actualitzat, i el substituirà per la nova versió. En aquest cas no caldrà fer res més (si no fos així, només cal esborrar el node i tornar a insertar el node de la nova versió al seu lloc).

Per tant, ens trobem amb aquest escenari:

  1. Arrenquem la nova instància i accedim al nostre fluxe
  2. Revisem els nodes de Sentilo existents (en l'exemple, és el node publish) i mirem que hagin estat correctament actualitzats (verificar que el node no està en format transparent i no tenim cap error per pantalla, indicaria que cal substituir el node manualment)
    • si hi ha incompatibilitats, esborrem el node, i el tornem a inserir, aquesta vegada amb la versió actual (actualització del node de forma manual)
  3. Cal tornar a configurar el node Server que estem fent servir per a les nostres connexions
    • és possible que Node-RED ens indiqui que hi ha errors de configuració al node (icona vermella o missatge d'error que diu SETTINGS ERROR!)
    • cal revisar i inserir les dades de connexió a Sentilo, en especial el token, que per seguretat haurà estat esborrat del node server
  4. Un cop hem actualitzat el node, podem fer servir les sortides segons ens convingui
    • en l'exemple que estem explicant (veure imatge inferior) hem fet servir les sortides a mode de debug
      • sortida 1: debug de resposta de Sentilo
      • sortida 2: debug de codi d'estat http de Sentilo

Un cop finalitzat aquest procediment, ja hauríem de poder tornar a fer servir el nostre fluxe normalment:

3.3.1. Casos d'incompatibilitat

Un cop arranquem i entrem per primer cop a la nova instància de Node-RED, és molt probable que ens trobem amb aquest missatge per pantalla (en el cas que algun dels nostres fluxes estiguin fent servir un node de subscripció):

És un missatge totalment normal, i ens indica que, en algun dels nostres fluxes, estem fent servir un node que ja no existeix.

Ens trobarem una situació com aquesta:

En aquest cas, és el node subscribe que no existeix. Com ja hem dit abans, ha canviat de nom i ara hi ha dos tipus de node de subscripció.

El que correspon a la versió anterior de forma directa seria el subscribe with enpoint, que podríem substituir-lo sense més problemes, tot seguint les passes comentades anteriorment.

Per fer-ho, cal esborrar el node antic (marcat en vermell) i inserir el nou node, tot tornant a configurar les seves dades de connexió com s'ha explicat anteriorment.

Finalment, el fluxe quedaria així:

NOTA: les indicacions i errors ens avisen que cal configurar novament el node, ja que hem fet una substitució

  • Versió per a imprimir
  • 6251 lectures
  • Versió en PDF