El flux s'importa a la instància Node-RED accedint a:
"Menú hamburguesa -> Import -> Clipboard" i marquem l'opció "Import to new flow".
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:
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]
Documentació de la sessió de Formació, veure enllaç [4]
Des d'Octubre 2024 aquesta integració de les estacions de la XEMA de Meteocat es realitza de forma agrupada des de Smart Region: si esteu interessats en integrar aquestes dades sobre la vosta instància de la Plataforma Smart Region, envieu un correu a smartregion@diba.cat [5] i us activarem aquesta integració de dades directa.
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:
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:
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.
Des de Novembre 2024 aquesta integració de les estacions de la XPVCA de dades obertes es realitza de forma agrupada des de Smart Region: si esteu interessats en integrar aquestes dades sobre la vosta instància de la Plataforma Smart Region, envieu un correu a smartregion@diba.cat i us activarem aquesta integració de dades directa."
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 fluxos que utilitzen aquests nodes, caldrà fer una petita intervenció.
A continuació es detalla com cal actuar per tal d'adaptar els fluxos a la nova versió si és necessari.
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):
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:
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ó.
Per tal d'adaptar els nostres fluxos 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:
Un cop finalitzat aquest procediment, ja hauríem de poder tornar a fer servir el nostre fluxe normalment:
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 fluxos estiguin fent servir un node de subscripció):
És un missatge totalment normal, i ens indica que, en algun dels nostres fluxos, 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ó
El flux global és una plantilla d'inici per a proveïdors que necessitin començar de forma ràpida i amb l'aplicació de bones pràctiques assolides durant el desenvolupament dels fluxes transversals.
En aquest flux mostrarem una petita col·lecció de sub-fluxes que podrem fer servir per a dur a terme tasques rutinàries i que sovint es repeteixen en els nostres fluxes:
I un petit flux principal que mostra el seu ús:
Finalment donarem un seguit de pautes que cal seguir per tal de desenvolupar de forma estandarditzada dintre de l'ecosistema Node-RED d'SmartRegion.
A continuació es detallen tots els recursos que composen un flux estandarditzat segons les bones pràctiques propossades.
globals.getFlowConfig: obtenció de la configuració del flux
Injecta automàticament l'objecte msg.flowConfig en el contexte, cada cop que es desplega el flux, i conté tota la configuració inicial, necessària per a poder executar el flux.
Estructura base:
flowConfig.sentilo: configuració base de Sentilo
flowConfig.sentilo.api.host: host de l'API de SentiloflowConfig.sentilo.api.token: token mestre, o per defecte, per acreditar-se contra l'API de SentiloflowConfig.sentilo.catalog.ens: llistat d'objectes amb les dades dels ens que es faran servir a l'execució
flowConfig.sentilo.catalog.component: descripció de les dades del component (formen part dels paràmetres del sensors Sentilo)
flowConfig.sentilo.catalog.sensors: llistat de sensors amb els que treballarem durant l'execució del flux
En general podem afegir qualsevol altre configuració que creiem oportuna, i la podrem fer servir sempre que cridem aquest sub-flux des del flux principal o altres sub-fluxos.
globals.getCatalog: Obtenir dades del catàleg
Aquest sub-flux rep com a entrada un objecte reqParams amb les dades necessàries per fer la crida a l'API de Sentilo.
La sortida serà el resultat de la crida al servei catalog de Sentilo [7] per a la recuperació del catalog del proveïdor (en cas de que el token sigui d'un proveïdor) o bé de tot el catàleg (si el token és el mestre).
reqParams
El sub-flux espera l'objecte msg.reqParams a l'entrada, o fallarà si no es troba correctament definit:
{
ens: <ENS_ID>,
provider: <PROVIDER_ID>,
token: <PROVIDER_TOKEN>
}
Si no s'informa el paràmetre token s'agafarà el token mestre per defecte (si està informat). Sinò, el sub-flux donarà un error i es pararà l'execució.
Filtres
componentType: si tenim definit el valor flowConfig.sentilo.catalog.component.componentType es farà servir com a filtre de la crida a Sentilo filtrant per tipus de componentResposta
La resposta es recupera al msg.payload i és la que ofereix el servei catalog de Sentilo quan es cerca per credencials.
globals.addCatalog: Afegir sensors al catàleg
Amb aquest sub-flux podrem afegir sensors al catàleg segons el servei catalog de Sentilo [8].
reqParams
El sub-flux espera l'objecte msg.reqParams a l'entrada, o fallarà si no es troba correctament definit:
{
ens: <ENS_ID>,
provider: <PROVIDER_ID>,
token: <PROVIDER_TOKEN>,
sensorsToCreate: [SENSORS_ARRAY]
}
Si no s'informa el paràmetre token s'agafarà el token mestre per defecte (si està informat). Sinò, el sub-flux donarà un error i es pararà l'execució.
El paràmetre reqParams.sensorsToCreate ha de contenir el llistat de sensors a crear, segons la documetació del servei catalog de Sentilo [9] per a afegir diversos sensors d'un proveïdor (és el llistat del camp sensors).
Resposta
La resposta es recupera al msg.payload i és la que ofereix el servei catalog de Sentilo [10] quan s'afegeixen diversos sensors per un proveïdor.
globals.publishObservations: Publicar observacions
Aquest sub-flux permet afegir publicar observacions per a diversos sensors, segons la documentació del servei data de Sentilo [11].
reqParams
El sub-flux espera l'objecte msg.reqParams a l'entrada, o fallarà si no es troba correctament definit:
{
ens: <ENS_ID>,
provider: <PROVIDER_ID>,
token: <PROVIDER_TOKEN>
}
Com a body passarem dintre de l'objecte msg.payload un objecte json amb el llistat d'observacions a publicar, tal i com s'especifica pel servei data de Sentilo [12].
Resposta
La resposta es recupera al msg.payload i és la que ofereix el servei data de Sentilo [11] quan es publiquen observacions per a diversos sensors d'un proveïdor.
globals.getLastObservations: Obtenir les darreres observacions
Aquest sub-flux permet recuperar observacions dels sensors d'un proveïdor, segons la documentació del servei data de Sentilo [13].
reqParams
El sub-flux espera l'objecte msg.reqParams a l'entrada, o fallarà si no es troba correctament definit:
{
ens: <ENS_ID>,
provider: <PROVIDER_ID>,
token: <PROVIDER_TOKEN>,
filters: {
from: <FROM_DATE>,
to: <TO_DATE>,
limit: <LIMIT>
}
}
Si no s'informa el paràmetre token s'agafarà el token mestre per defecte (si està informat). Sinò, el sub-flux donarà un error i es pararà l'execució.
El paràmetre reqParams.filters és opcional, i pot contenir dades de filtrat per a realitzar la crida al servei de recuperació de d'observacions, amb els posibles paràmetres segons el servei data de Sentilo [14].
Exemple
filters: {
from: "27/03/2025T14:00:00",
to: "27/03/2025T14:59:59",
limit: 100
}
Amb aquests filtres podrem obtenir les 100 darreres observacions dels sensors del proveïdor pel temps comprès entre 27/03/2025T14:00:00 i 27/03/2025T14:59:59.
Tots els paràmetres de filtrat són opcionals.
Resposta
La resposta serà un json que serà retornat en l'objecte msg.payload i que contindrà l'estructura de dades segons el servei data de Sentilo [15].
Tota la paremetrització del flux ha d'anar definida en l'objecte json msg.flowConfig per conveniència. Qualsevol dada addicional hauria d'estar inclosa dintre d'ell, de forma que segueixi l'arquitectura documentada. D'aquesta forma assegurarem que sempre podrem trobar i configurar la parametrització del flux de forma senzilla i ordenada.
Exemple:
msg.flowConfig = {
sentilo: {
api: {
host: "<HOST_SENTILO_API>",
token: "<MASTER_TOKEN>"
},
catalog: {
ens: [
{
ens: "myEns",
provider: "myEns@TEST_GLOBAL_FLOWS",
token: "<PROVIDER_TOKEN>"
}
],
component: {
"component": "test_global",
"componentType": "generic",
"componentDesc": "Component de test pels fluxos globals",
"componentPublicAccess": "false",
},
sensors: {
"global001": {
"sensor": "global001",
"description": "Test sensor for global flows",
"type": "status",
"dataType": "boolean",
"unit": "",
"publicAccess": "false",
"location":"41.4123488 2.2076235",
},
"global002": {
"sensor": "global002",
"description": "Test sensor for global flows",
"type": "temperature",
"dataType": "number",
"unit": "ºC",
"publicAccess": "false",
"location":"41.4123488 2.2076235",
},
"global003": {
"sensor": "global003",
"description": "Test sensor for global flows",
"type": "battery",
"dataType": "number",
"unit": "%",
"publicAccess": "false",
"location":"41.4123488 2.2076235",
}
}
}
}
}El pas de paràmetres entre nodes es fa a través de l'objecte msg.reqParams i ha de contenit, al menys, les dades de l'ens amb el que estem treballant. Addicionalment podrem passar tota aquella parametrització que sigui necessària, sempre assegurant una convenció segura i senzilla de recordar.
IMPORTANT: donat que aquest objecte viatga en el contexte msg del flux, és molt important mantenir-lo durant tota l'execució, fet que si modifiquem o destruïm el msg en algun node, hem de saber que pedrem aquesta parametrització i el flux fallarà en cridar els sub-fluxos.
Per tal de demostrar el funcionament dels sub-fluxos globals, i donar un exemple d'ús i bones pràctiques, a continuació podreu trobar un flux de test que els fa servir de forma linial.
El flux llegeix la configuració, genera el catàleg que no existeix, i hi publica dades d'observacions aleatòries.
Aquest flux de proves demostra com fer servir les diferents funcionalitats globals:
Iniciglobals.getFlowConfigmsg.ensListens informa de les dades de l'ens que actualment estem tractant (contingut del msg.payload)end informa quan acabem totes les iteracions (mostrarà el contingut de msg.payload)
El node funcional prepareReqParams recupera les dades de l'ens, que venen en msg.payload i les integra en msg.reqParams, que serà l'objecte de parametrització que farem servir durant tot el flux.
El primer pas de la iteració recupera les dades del cataleg:
globals.getCatalogsensorsToCreate
msg.reqParams.sensorsToExist, i la mostra el node de debug sensorsToExistmsg.reqParams.sensorsToCreate, i la mostra el node de debug sensorsToCreate
Es processa la llista msg.reqParams.sensorsToCreate, i si no es buida es crida a globals.addCatalog, passant-la com a body de la crida a Sentilo:
crearSensors? decideix si cal o no crear sensors (verifica msg.reqParams.sensorsToCreate)
globals.addCatalog i es fa una pausa de 5 segons (temps de sincronització del catàleg de Sentilo, caldrà validar segons el cas si augmentar aquest temps)
crearSensors? decideix que no cal crear sensors (verifica msg.reqParams.sensorsToCreate), continuem per la segona sortidaprepareGetLastObservations prepara la crida per obtenir les darreres observacions del catàleg
msg.reqParams.filters.from, msg.reqParams.filters.to i msg.reqParams.filters.limit (totalment opcionals, veieu els exemples [16]de la documentació oficial de Sentilo per a més informació)globals.getLastObservations, per tal d'obtenir les observacions que resultin d'aplicar els diferents filtres
getLastObservations mostra les dades obtingudes
Si cal fer algun processament o interpretació de les dades ho farem al node funcional processLastObservations, que les tindrem disponibles al msg.payload (el format és el que es defineix a la documentació oficial de Sentilo [16])
El flux d'exemple conté una implementació parcial d'aquest node per a poder treballar amb les dades d'entrada.
Finalment, un cop hem obtingut les dades de sentilo, i si ha calgut tractar-les, podrem preparar les possibles publicacions al node funcional preparePublishObservatiosn.
Aquest node del flux de test implementa la generació de dades aletòries pels diferents sensors de test. És en aquest punt on caldrà afegir la lògica de creació de les possibles observacions que volem publicar a Sentilo.
L'objecte msg.payload haurà de contenir les observacions que enviarem en el body de la crida a Sentilo (veieu el format en la documentació oficial de Sentilo [17]). Aquestes dades les podrem revisar gràcies al node de debug preparePublishObservations.
La publicació es fa amb la posterior crida al sub-flux globals.publishObservations, que publicarà les dades que li passem pel msg.payload com a body de la crida. El node de debug publishObaservations mostrarà el resultat de la crida.
Podeu trobar el codi font d'aquest flux en aquest link [18], per tal de poder-lo fer servir com a base inicial.
Els fluxos tenen un espai de disc reservat per a poder escriure de forma segura. Aquest espai roman dintre del contexte de la instància Node-RED, i només podrem escriure les nostres dades dintre del mateix.
Aquest espai es troba al path absolut /data.
Es recomanda, doncs, fer servir sempre aquesta adreça com a base del path del fitxer que volguem escriure (o llegir), per tal d'accedir correctament i sense problemes al seu contingut.
Exemple d'escriptura a /data/fluxes/global/flowConfig.json
| Adjunt | Mida |
|---|---|
| Flux Meteocat [3] | 6.45 KB |
| Flux Loxone [6] | 5.37 KB |
| Flux Lorawan - sensors qualitat aire [1] | 29.64 KB |
| Fluxos globals [18] | 30.2 KB |
Enllaços:
[1] https://smartregion.diba.cat/sites/smartregion.diba.cat/files/sensors_de_qualitat_de_laire.json_.txt
[2] mailto:xoic@femprocomuns.coop
[3] https://smartregion.diba.cat/sites/smartregion.diba.cat/files/meteocatsimple.json__0.txt
[4] https://smartregion.diba.cat/documents/sessio-4-exemple-practic-integracio-estacio-meteorologica-meteocat
[5] mailto:smartregion@diba.cat
[6] https://smartregion.diba.cat/sites/smartregion.diba.cat/files/flux-loxone-sentilo-node-red.json_.txt
[7] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/retrieve_provider_sensor_data.html
[8] https://sentilo.readthedocs.io/en/latest/api_docs/services/catalog/create_sensors.html
[9] https://sentilo.readthedocs.io/en/latest/api_docs/services/catalog/create_sensors.html#adding-several-sensors
[10] https://sentilo.readthedocs.io/en/latest/api_docs/services/catalog/create_sensors.html#response-data
[11] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/publish_provider_sensor_data.html
[12] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/publish_provider_sensor_data.html#request-to-send-multiple-observations-of-several-sensors-setting-a-ltc-timezone
[13] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/retrieve_sensor_data.html
[14] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/retrieve_sensor_data.html#parameters
[15] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/retrieve_sensor_data.html#request-to-retrieve-the-latest-observations-of-a-sensor-based-on-a-date
[16] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/retrieve_provider_sensor_data.html#examples
[17] https://sentilo.readthedocs.io/en/latest/api_docs/services/data/publish_provider_sensor_data.html#examples
[18] https://smartregion.diba.cat/sites/smartregion.diba.cat/files/global-flows.json_.txt