SmartRegion Barcelona

1. Antecedents

La Direcció de Serveis de Tecnologies i Sistemes Corporatius (en endavant DSTSC), en el marc de l’estratègia Barcelona Smart Region, ofereix com a recurs de catàleg una Plataforma Smart Region als Ajuntaments dels Municipis de més de 2.500 habitants i als Consells Comarcals de la demarcació.

La Plataforma Smart Region s'ofereix en la modalitat plataforma com a servei, consulteu-ne aquí les condicions de prestació.

La Plataforma Smart Region té com a objectius principals:

• Aïllar les aplicacions de gestió de la capa de sensors desplegats a territori.

• Interconnectar les funcionalitats específiques de les diferents aplicacions verticals, per a la gestió dels serveis urbans concrets (enllumenat, mobilitat, gestió de residus, eficiència energètica, reducció de les emissions contaminants...).

• Proporcionar compatibilitat entre proveïdors de sensors independentment de les tecnologies utilitzades.

• Disposar d’un únic repositori d’informació normalitzada a nivell sintàctic i semàntic.

• Permetre que diferents aplicacions de gestió de les administracions públiques usuàries puguin explotar les dades dels diferents sensors, independentment del seu origen.

Actualment hi ha més de 50 organitzacions usuàries de la Plataforma Smart Region, entre Ajuntaments, Consells Comarcals i la pròpia Diputació de Barcelona. Es preveu que tant el nombre d’organitzacions usuàries com el de proveïdors de sensorització o aplicacions subscrites a la informació augmenti.

A continuació es recullen els manuals d'usuari dels perfils que interaccionen amb la Plataforma Smart Region.

2. Administrador d’organització

Aquest perfil l’ocupen tècnics dels ens locals usuàris de la Plataforma Smart Region. Les seves funcions seran les d’administració de dades pròpies de la organització.

2.1. Accés a la Plataforma Smart Region

El catàleg de Sentilo és la consola d'administració de la Plataforma Smart Region, que permet configurar i personalitzar certs aspectes del sistema.

Des de la zona pública, els administradors de l’organització poden accedir a l'àrea d'administració pròpia, per tal de gestionar el seu àmbit d'actuació.

2.1.1. Ja sou usuaris

Connecteu-vos mitjançant http://sentilo.diba.cat/sentilo-catalog-web/<ens>

On <ens> és l’identificador d’ens que els administradors de la plataforma us van facilitar per correu electrònic. Si no recordeu la ruta envieu un missatge de correu electrònic a smartregion@diba.cat, es comprovarà que l’adreça de correu remitent està autoritzada i se us informarà del que calgui.

2.1.2. No sou usuari però ja existeix instància a la vostra organització

Demaneu a l’administrador de l’organització que us doni d’alta com a usuari. Si no sabeu qui és, contacteu per correu electrònic amb smartregion@diba.cat i se us facilitarà el nom de la persona responsable de la vostra organització.

2.1.3. Sol·licitar instància per a la vostra organització

Cal formalitzar la sol·licitud mitjançant la petició des de la seu electrònica de la Diputació del producte de catàleg "Plataforma tecnològica per a la gestió urbana”.

Al donar d’alta la instància caldrà saber qui de l’organització serà l’encarregat d’administrar la plataforma i quines persones voldran rebre les comunicacions de les actuacions i notícies rellevants que es publiquin a la comunitat d’Smart Region. 

2.2. Parametrització d’organització

En accedir a la pestanya “organització”, es mostren les dades bàsiques de l'Ens, que podrem editar, excepte el camp identificador, que es mostrarà bloquejat.

En accedir a la pestanya “Paràmetres de configuració”, es mostren aspectes configurables a nivell d’Ens, en concret:

2.2.1. Cessió d’accés a tercers

Com a organització, podem cedir les nostres dades a altres ens locals accedint a la pestanya “Permisos a tercers”, això es fa sempre a nivell de proveïdor, el que donarà accés a tots els components/sensors que hi pertanyen.

Un cop cedim accés a tercers, els administradors de les organitzacions a les que hem cedit accés podran visualitzar el nou permís a la pestanya “Permisos de tercers”.

2.2.2. Visualització de dades de tercers

La cessió d'accés a les dades d'un proveïdor per part d'un tercer, ens permet:

• Indicar, dintre de la pestanya “Permisos de tercers”, si volem que els components i sensors associats es mostrin dintre del mapa públic.

• Visualitzar el proveïdor així com els seus components i sensors al catàleg, sempre en mode lectura.

• Permetre afegir permisos a les nostres “Aplicacions” per que accedeixin a dades de proveïdors sobre els que ens han cedit accés.​

​

2.3. Personalització visual

Inicialment, l'aspecte visual, tant de la zona pública com de l'àrea d'administració, serà el existent per defecte de la plataforma.

Per tal de personalitzar l'aspecte visual, existeixen certs aspectes que els administradors dels Ens locals poden modificar de forma autònoma via el Catàleg d'Administració, i d'altres que impliquen certa programació i un desplegament posterior per part de tècnics de la Diputació.

Des de l'aplicació de catàleg és possible modificar els valors de configuració per personalitzar alguns aspectes visual, com ara el color de fons del mapa principal, el seu centre i el zoom inicial. Aquestes modificacions només podran ser realitzades per un administrador de l'organització i no caldrà la intervenció d'un tècnic de sistemes o súper administrador.

Cal estar identificat com a tal i accedir a l'opció Organització del menú d'administració o el menú lateral.

A continuació es mostra la pantalla principal d'una organització, en el seu estat inicial, la qual encara no ha estat configurada. Podem observar que el mapa principal no té un centre ni un estil específic, així com la presentació del logotipus per defecte de la plataforma Sentilo.

Per a modificar els paràmetres accedim a l'apartat Organització com a administrador de l'organització que es vol configurar:

Posteriorment cliquem sobre Editar organització, i accedim a la pestanya Paràmetres de configuració:

En aquest apartat es troben els següents paràmetres configurables:

• Nivell de zoom: indica el nivell de zoom del mapa de la pantalla principal (de 0 a 21+, sent 0 el nivell mínim en el que es veu el mapa del món sencer, i 21 el màxim possible, a nivell de carrer)

• Latitud: latitud del centre del mapa(en Graus Decimals).

• Longitud: longitud del centre del mapa(en Graus Decimals).

• Color de fons del mapa: indica el color del fons del mapa, en format CSS Color. Per a més comoditat és possible fer servir el seleccionador de color integrat, fent clic en el requadre de la dreta del camp de text:

Un cop configurats tots els paràmetres, desem els canvis i ja tenim disponible la nova configuració de la pantalla principal.

Des de l'equip SmartRegion inclourem a la capçalera l'escut que es disposa a https://www.diba.cat/en/web/municipis , si no és correcte agrairíem ho notifiqueu a smartregion@diba.cat  enviant l’arxiu en format imatge de qualitat i tamany uniforme.

2.4. Administració d’usuaris

Des de la pestanya “Usuaris”, serem capaços d'administrar els nostres usuaris de forma totalment autònoma. Disposem del llistat d'usuaris dal nostre Ens i un manteniment CRUD estàndard.

Per més informació, podem consultar l'apartat específic de la web Sentilo. 

2.4.1. Informar la contrasenya d'un usuari

Al crear un usuari no apareix l'opció per introduir la contrasenya, cal guardar primer les dades de l'usuari i després editar-lo per a que aparegui el botó de modificar i per poder-la informar.

2.4.2. Bones pràctiques en l’administració d’usuaris

Cada organització té la seva instància independent però el mòdul d’administració d’usuaris i proveïdors és compartit per a totes les instàncies. Per tal de no col·lisionar amb noms d’usuaris s’ha establert que els noms d’usuari estinguin precedits pel nom del domini de l’organització, un subguió i el nom d’usuari que utilitzen en aquesta.

Exemple alta empleat de la Diputació de Barcelona

Email: username@diba.cat

Nom d’usuari a la plataforma Sentilo:  diba_<username>

2.5. Administració de proveïdors

Accedint a la pestanya de Proveïdors, visualitzem un llistat dels proveïdors sobre els que tenim accés. Tindrem accés de lectura sobre proveïdors de tercers i d'escriptura sobre els nostres proveïdors(sempre que tinguem rol d'administrador).

Podem accedir a un proveïdor concret per veure els seus detalls i/o editar-los.

Al accedir al proveïdor visualitzem altres dades d'interès:

• Sensors/actuadors associats al proveïdors

• Components associats al proveïdors

• Subscripcions actives del proveïdors

• Documentació d'interès (no implementat) 

​Per més informació podem consultar el apartat corresponent de web Sentilo.

2.6. Administració de components

Accedint a la pestanya “Components”, visualitzem un llistat dels components sobre els que tenim accés. Tindrem accés de lectura sobre components de tercers i d'escriptura sobre els nostres components (sempre que tinguem rol d'administrador).

Al accedir a un component es visualitzen diverses pestanyes amb informació significativa:

• Detalls

• Detalls tècnics

• Informació addicional

• Darreres dades

Normalment, la creació de sensors és responsabilitat del proveïdor que ho fa de forma totalment autònoma, el que allibera de feina als administradors de l’organització. Per tant, no descriurem en detall en aquest manteniment, en cas necessari es pot consultar l'informació específica a la web de Sentilo.

2.7. Administració de sensors

Accedint a la pestanya “Sensors”, visualitzem un llistat dels sensors sobre els que tenim accés. Tindrem accés de lectura sobre sensors de tercers i d'escriptura sobre els nostres components (sempre que tinguem rol d'administrador).

Al accedir a un component es visualitzen diverses pestanyes amb informació significativa:

• Detalls

• Detalls tècnics

• Informació addicional

• Components relacionats

• Sensors/actuadors

Normalment, la creació de components és responsabilitat del proveïdor que ho fa de forma totalment autònoma, el que allibera de feina als administradors de l’organització. Per tant, no descriurem en detall en aquest manteniment, en cas necessari es pot consultar l'informació específica a la web de Sentilo. 

2.8. Administració d’aplicacions

Accedint a la pestanya de Aplicacions, visualitzem un llistat de les nostres aplicacions.

Podem accedir a una aplicació concreta per veure els seus detalls i/o editar-los, en cas de que siguem administradors. 

Al accedir una aplicació visualitzem altres dades d'interès:

• Permisos, a on podrem afegir permisos sobre altres aplicacions o proveïdors als que tenim accés, bé perquè siguin nostres o perquè ens han cedit permís.

• Subscripcions actives de l'aplicació.

​Per més informació podem consultar el apartat corresponent de web Sentilo.

2.9. Administració d’alertes

La pestanya d'alertes permet gestionar alertes dintre de Sentilo:

Per més informació, podem consultar l'apartat específic de la web Sentilo.

2.9.1. Cas pràctic: Subscripció a alertes amb enviament d'emails

Les alertes de Sentilo accepten subscripcions (vegeu apartat Subscripcions actives més a baix) i podem rebre informació de l'alarma que Sentilo envia, en cas que la regla de l'alerta es verifiqui.

A continuació es detalla un fluxe de Node-RED que mostra com enviar emails en cas de verificar-se l'alerta que valida un llindar de valor sobre un sensor.

2.9.1.1. Premisses

Aquest exemple necessita de les següents entitats creades a Sentilo:

• sensor amb dada de tipus numèric (nivell de bateria en %)
• alerta de validació de nivell de bateria (verifica valor del sensor inferior al 60%)

Per exemple:

Per a aquest exemple, el valor del sensor battery_level és verificat per l'alerta test_alertes_battery_level, on el llindar mínim és del 60%. Per sota d'aquest valor, Sentilo llençarà una alarma associada a l'alerta.

2.9.1.2. Fluxe

Finalment, definim el fluxe de Node-RED segons el següent esquema:

On tenim: 

• Node de Sentilo de subscripció a ALARM
• Node de processament de les dades de la subscripció (node funcional)
  • gestiona el missatge d'entrada de la subscripció a alertes
  • extreu les dades
  • crea el missatge de sortida que enviarà el node de correu electrònic
• Node d'enviament de correus electrònics
  • fa l'enviament del correu amb les dades de l'alerta

2.9.1.2.1. Configuració del node de subscripció

A continuació es dona la configuració del node de subscripcions, per a l'exemple donat:

2.9.1.2.2. Contingut del node funcional

Aquest és el contingut del node funcional, el qual, en primera instància, recupera les dades del missatge de subscripció i crea el cos del correu electrònic (el body es desa en msg.payload).

NOTA: El format del missatge de subscripció el podreu trobar en la documentació oficial de Sentilo (https://sentilo.readthedocs.io/en/latest/api_docs/services/subscription/subscription.html#notifications)

Finalment, informa les dades d'enviament del correu electrònic, que el node d'enviament farà servir (denoteu els camps to, que cal informar degudament, i els cc, bcc, que són opcionals).

2.9.1.2.3. Configuració del node email

Finalment, la configuració del node email és molt senzilla, en la que només cal informar l'adreça i port del servidor SMTP que farem servir:

2.9.1.3. Contingut del correu electrònic

Finalment, el destinatari obtindrà un correu electrònic semblant a aquest de mostra:

2.10. Regles de creació d'alertes

Mitjançant aquesta opció podrem crear una alertes internes sobre diversos sensors en una única operació, filtrant per proveïdor i tipologia de component o sensor.

Abans de l’execució, el sistema ens mostrarà un avís indicant el número d’alertes que es crearan amb l’acció i ens requerirà confirmació.

Un cop executada la regla, les alertes s’hauran creat i les trobarem com entitats autònomes al manteniment corresponent, on podrem editar-les o esborrar-les.

Les regles no es poden editar, només es poden esborrar o re-executar.

Per més informació, podem consultar l'apartat específic de la web Sentilo.

2.11. Subscripcions actives

Mitjançant aquesta opció podem consultar les subscipcions actives associades al nostre Ens, sempre en mode lectura, doncs es gestionen via API per part de proveïdorso aplicacions.

2.12. Tipologies de components i sensors

Les tipologies de components i sensors es defineixen globalment per la Plataforma Smart Region.

Com a usuaris d'un ens, podem visualitzar la relació de tipologies disponibles a la plataforma accedint a “Tipologies de components” i “Tipologies de sensors/actuadors”, però sempre en mode lectura.

2.13. Preguntes freqüents

2.13.1. Com canviar el password de la Plataforma Smart Region (tant pel propi usuari com per d'altres usuaris - en cas d'usuaris administradors)

El següent procediment és útil per a que un usuari pugui canviar-se el password per defecte o en casos de directrius de seguretat. També pot canviar el password d'un usuari qualsevol altre usuari que tingui rol d'administrador de l'organització, cosa molt útil per quan algun usuari oblida el seu password i llavors l'administrador li pot resetejar directament.

• Accedir a la plataforma mitjançant l’enllaç corresponent.
• Prémer Accedir al menú superior.
• Introduir el codi d’usuari i contrasenya actual
• Un cop connectats, accedir, en el menú superior clicant sobre el desplegable del nom d’usuari i seleccionar la opció “Usuaris”
• Un cop dins de l’opció de menú Usuaris, buscar el codi d’usuari a la taula i clicar a sobre de la fila (es pot emprar el buscador amb el camp “Filtre”)
• Un cop dins, seleccionar l’opció Editar usuari
• Clicar “Change Password”
• Indicar la nova contrasenya als camps Contrasenya i Repetir
• Prémer Desar.
• A la pantalla anterior, tornar a clicar Desar per guardar els canvis
• Comprovar que es té accés amb la nova contrasenya, sortint de l’aplicació (menú desplegable sobre el nom d’usuari – Sortir)

2.13.2. Com fer que un tercer publiqui dades a Sentilo

Per a que una empresa proveïdora publiqui dades a Sentilo cal donar-la d’alta com a proveïdor. En el moment de donar-la d’alta, el sistema generarà un token d’autorització únic.

Aquest token se li haurà de facilitar a l’empresa proveïdora junt amb la documentació de l’API per a que pugui interconnectar els sensors amb Sentilo.

Plantilla missatge

Benvolgut/da,

Ens posem en contacte per informar-vos  que heu estat donat d’alta com a proveïdor de la Plataforma Smart Region que disposa <nom ens local>, a continuació facilitem les credencials d’accés per l’entorn de <proves>/<producció>.

id de proveïdor: <idOrganitzacio>@<idProveidor>

token: <idToken>

Els vostres components/sensors generats de caràcter públic i dades associades seran visibles a <incloure url de sentilo de la vostra organització, consultar aquí> 

L’adreça url per comunicar-se mitjançant l’API és:

• Entorn de proves:  http://pre-api-sentilo.diba.cat/ 
• Entorn de producció: http://api-sentilo.diba.cat/

A https://smartregion.diba.cat/ disposeu dels manuals de referència:

• 1. Plataforma Smart Region
• 2. Guies d'usuari i documentació API
• 3. Ontologies definides
• 4. Conceptes i recomanacions per a l'elaboració de clàusules

Al tercer manual es recullen nomenclatures consensuades per a la definició de components i sensors a la Plataforma Smart Region.

En cas de no trobar referència al tipus de solució que teniu intenció d’integrar, contacteu amb smartregion@diba.cat per validar la proposta d’integració.

Recordar-vos la necessitat de fer un ús responsable de la plataforma donat que la Diputació de Barcelona limita l’ús i el servei als següents paràmetres en total:

• un màxim de 10 accessos per segon a l’API,
• enviament d’un màxim de 10MB d’informació per dia a Sentilo.

Atentament,

2.13.3. Com fer que un tercer consumeixi dades de Sentilo

Per a que un sistema d’informació extern pugui consultar dades cal donar-lo d’alta com a aplicació. En el moment de donar-lo d’alta s’hauran de determinar els proveïdors als que tindrà accés, segons components i sensors que hagi de poder consultar. El sistema generarà un token d’autorització únic.

Aquest token se li haurà de facilitar a l’empresa proveïdora del sistema d’informació junt amb la documentació de l’API per a que pugui consultar la informació que interessi.

2.13.4. Com donar d’alta noves tipologies de components i/o sensors

Les tipologies de components i sensors es defineixen globalment per la Plataforma Smart Region.

Com  a usuaris d'un ens, podreu visualitzar la relació de tipologies disponibles a la plataforma accedint a “Tipologies de components” i “Tipologies de sensors/actuadors”, però sempre en mode lectura.

Si necessiteu alguna tipologia no contemplada a la plataforma, envieu-nos un correu electrònic a smartregion@diba.cat, detallant la necessitat.

2.13.5. Com donar d’alta nous sensors i/o components

Normalment, la creació de sensors i/o components és responsabilitat del proveïdor que ho fa de forma totalment autònoma utilitzant l’API, el que allibera de feina als administradors de les organitzacions.

2.13.6. A qui m’he d’adreçar per altres consultes

Enviar un correu electrònic a smartregion@diba.cat l’Equip Smart Region de la Direcció de Serveis de Tecnologies i Sistemes Corporatius de Diputació de Barcelona.

3. Proveïdor i/o consumidor de dades

3.1. Proveïdor de dades

Seran les persones físiques o jurídiques que envien informació a la Plataforma Smart Region dels fenòmens físics que succeeixen al territori.

3.2. Consumidor de dades

Seran les persones físiques o jurídiques que capten la informació proporcionada per la Plataforma Smart Region per a treure’n profit, incloent profit lucratiu.

Poden ser aplicacions subscrites a informació específica, o qualsevol ciutadà subscrit a dades obertes

3.3. Documentació API

3.3.1. Introducció

Sentilo ofereix una interfície de programació d’aplicacions (API) on es defineix un conjunt d'ordres, funcions i protocols a seguir per qui vulgui interactuar amb la plataforma des de sistemes externs, com ara sensors / actuadors o aplicacions.

Utilitzant aquesta interfície es podrà:

• Registrar aplicacions, proveïdors i sensors a la plataforma.

• Permetre que les aplicacions i sensors puguin publicar i subscriure’s als serveis definits.

• Enviar informació de sensors a aplicacions.

• Enviar ordres des de les aplicacions als sensors.

3.3.2. Model de comunicació

L’API utilitza arquitectura REST  i el protocol HTTP per a establir la comunicació des d’elements externs amb Sentilo.

El format de dades que suporta la plataforma és JSON.

En concret Sentilo utilitza els següents conceptes de terminologia REST:

• Recursos: elements del sistema d'informació.

• Identificadors: nom únic que identifica un recurs dins del sistema.

• Representacions: format de les dades intercanviades.

• Operacions: accions que es poden realitzar en un recurs.

• Codis de resposta: resultat de l'operació.
   

3.3.2.1. Recursos

Els recursos o informació de la plataforma Sentilo són:

• Sensor: element de maquinari o programari amb capacitat de generar una observació (dades).

• Component: corresponent a un element de maquinari o programari, amb ubicació geoespacial (fix o mòbil) que podria estar compost per 1 o més sensors.

• Proveïdor: entitat que representa un grup de components i els permet comunicar-se amb Sentilo per enviar dades i rebre ordres.

• Aplicació client: entitat que consumeix les dades processades per la plataforma.

Els sensors i els components sempre tenen una tipologia associada, definida prèviament a la plataforma. Les accions que es poden dur a terme pels recursos són:

3.3.2.1.1. Proveïdors i sensors

• Registre a la plataforma.

• Subscriure's als esdeveniments del sistema.

• Publicar dades.

3.3.2.1.2. Aplicacions

• Registre a la plataforma, però sempre des de la consola d'administració.

• Enviar ordres a proveïdors / sensors.

• Rebre dades de proveïdors / sensors.

• Subscriure's als esdeveniments del sistema.

3.3.2.2. Identificadors

En el cas de Sentilo, el nom que identifica unívocament un recurs es tracta d'una URL que es compon de la següent manera:

protocol: // domini: port / servei

i consta de les següents parts:

• Protocols de comunicació: HTTP o HTTPS.

• domini: domini API del servidor de plataforma  (api-sentilo.diba.cat).

• port: Port definit per a les comunicacions amb l'API del servidor.

• servei: catàleg, dades, ordre, etc.

Cada servei té una URL específica.

3.3.2.3. Operacions

Les operacions utilitzades per la plataforma Sentilo es corresponen als mètodes HTTP.

• GET: Sol·licitud d’informació.

• POST: Enviament de dades noves.

• PUT: Actualització de dades existents.

• DELETE: Esborrament de dades.

La plataforma discrimina l'acció que es vol realitzar a partir del mètode utilitzat i del servei, proveïdor o sensor especificat a la URL.

3.3.2.4. Codis de resposta

La resposta a una sol·licitud es gestiona a través dels codis d'estat HTTP següents:

En cas d'error, el cos de resposta inclou una descripció del problema detectat.

3.3.3. Seguretat

3.3.3.1. Seguretat en les sol·licituds API

La plataforma valida qualsevol sol·licitud rebuda pel sistema seguint la terminologia AAA (Autenticació, Autorització, Anotació) realitzant les següents accions:

• Autenticació: Identifican el peticionari.

• Autorització: Validant que l'acció sol·licitada en el recurs es pot realitzar.

• Anotació (traçabilitat): Auditant l’acció i el peticionari.

Així, per qualsevol sol·licitud rebuda, la plataforma realitza les següents accions:

• Identifica el peticionari a través de l'encapçalament HTTP.

• Comprova que pot fer l'acció sol·licitada al recurs indicat.

• Registra l'acció realitzada.

Quan sigui necessari, la plataforma comprova que la integritat i la confidencialitat de les comunicacions es garanteix mitjançant el protocol HTTPS.

3.3.3.1.1. Autenticació

Per identificar el peticionari, la plataforma utilitza un mecanisme d'autenticació basat en tokens.

És necessari establir un mecanisme de distribució segura, extern a la plataforma, per enviar els tokens als diferents usuaris de la plataforma. Versions futures de Sentilo inclouran aquesta funcionalitat.

Cal incloure el token a la sol·licitud afegint a l’encapçalament la clau IDENTITY_KEY.

Un exemple de solicitud utilitzant la eina curl:

curl --request GET --header "IDENTITY_KEY: <YOUR_KEY>" http://<your_api_server.com>/resource

En el cas de token incorrecte o no vàlid, la plataforma respondrà amb el codi d'error 401.

3.3.3.1.2. Autorització

La plataforma utilitza un sistema de permisos per verificar si l'entitat sol·licitant (proveïdor o aplicació) pot administrar, escriure o llegir en el recurs d’interès.

Aquests permisos es defineixen a través de la consola d’administració. Aquesta consola la gestiona l’entitat propietària de la informació.

Si es fa una acció sobre un recurs sense el permís adequat, la plataforma retornarà un error 403.

3.3.3.2. Seguretat en les retro-trucades

Per garantir que les sol·licituds han estat enviades per la plataforma, Sentilo proporciona un mecanisme d’autenticació basat en codi hash del tipus HMAC. Aquest mecanisme garanteix:

• Que el missatge l'ha enviat la plataforma

• Que el missatge no s’ha modificat després d'enviar-lo

• Que el missatge encara és vigent

Com a algorisme de hash el sistema utilitza SHA-512. Accepta claus de qualsevol mida i produeix una seqüència hash de 512 bits de longitud.

El sistema destinatari hauria d'activar la seguretat en les retro-trucades quan es crea la subscripció especificant la clau secreta. Aquesta subscripció s'ha de fer mitjançant el protocol HTTPS per evitar comprometre la clau.

Un cop creada la subscripció, totes les sol·licituds relacionades han d'incloure dos nous encapçalaments, un amb el hash  (Sentilo-Content-Hmac) i un altre amb la marca de temps (Sentilo-Data), com a mostra el següent exemple:

Sentilo-Content-Hmac: j1OQ+fU667GQoHYHWzLBpigRjLJmRvYn53KHZhApTbrcphYWBlRPSBHkntODuqsqx11Vj8rsc7DDziiutTq/5g==

Sentilo-Date: 10/06/2014T15:27:22

La responsabilitat de validar els encapçalaments serà sempre del sistema destinatari.

El pseudocodi per generar el token HMAC és el següent:

var md5Body = MD5(body)

var endpoint = endpoint_configured_in_subscription

var secretKey = secret_key_configured_in_subscription

var currentDate = value_http_header_Sentilo-Date

var contentToSign = concatenate('POST',md5Body, 'application/json',currentDate, endpoint)

var signature = HmacSHA512(contentToSign)

return base64UrlEncode(signature)

3.3.4. Serveis

3.3.4.1. Alarma

El servei d'alarmes permet gravar i recuperar les alarmes associades a una alerta emmagatzemada al catàleg del sistema.

Totes les sol·licituds d'aquest servei tindran el següent format:

http://api-sentilo.diba.cat /alarm/<id_alert>

on id_alert identifica l'alerta per la qual es vol realitzar l'acció.

L'alerta sempre s'ha de definir abans de llançar l'alarma mitjançant el Catàleg o el servei Alerta.

Les accions disponibles d’aquest servei són:

3.3.4.1.1. Publicar alarma

El següent exemple mostra com enviar una sol·licitud a la plataforma per publicar una nova alarma associada a una alerta amb l'identificador 43. Mètode POST:

http://api-sentilo.diba.cat/alarm/43

Cos del missatge:

{"message": "El límit màxim ha superat: 32"}

Si l'alerta no està activa, el servidor rebutjarà la publicació

3.3.4.1.2. Recuperar alarmes

Els següents exemples mostren el format de les sol·licituds per recuperar les alarmes associades a una alerta amb l'identificador 43. Mètode GET:

• Recuperar la última alarma:

http://api-sentilo.diba.cat /alarm/43

• Recuperar les 3 últimes alarmes:

http://api-sentilo.diba.cat /alarm/43?limit=3

• Recuperar les 3 últimes alarmes d’un dia concret:

http://api-sentilo.diba.cat/alarm/43?limit=3&from=08/04/2013T00:00:00&to=08/04/2013T23:59:59

3.3.4.2. Alerta

El servei d'alertes permet gravar, editar, recuperar i esborrar definicions d’alertes.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /catalog/alert/<entity_id>

on l'entity_id és opcional i s'ha d'incloure en funció de l'operació. entity_id pot identificar una aplicació o un proveïdor.

Hi ha dos tipus d'alertes:

Les alertes internes estan relacionades amb sensors específics i la seva lògica es defineix amb regles bàsiques. Han de definir-se a través de la consola del catàleg o de l'API utilitzant el token del catàleg corresponent.

La plataforma Sentilo llançarà una alarma quan es produeix la lògica definida per l’alerta.

Les alertes externes estan definides per entitats de tercers, que seran responsables de calcular la seva lògica i llançar les alarmes relacionades quan s'apliqui.

En ambdós casos, la plataforma Sentilo s'encarrega de publicar l'alarma de totes les entitats subscrites a l'alerta relacionada.

Totes les alertes tenen la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• L’ID ha d’identificar unívocament una alerta, per tant, 2 alertes no haurien de tenir mai el mateix ID.

• l’ID ha de tenir només caràcters alfanumèrics i guions, mai espais.

• Els valors possibles de tipus d’alerta són: EXTERNAL o INTERNAL.

• El paràmetre entitat no és obligatori, si està buit l’alerta s’associarà a l'entitat especificada a la URL.

• Els tipus de trigger interns estan limitats als definits a continuació.

Tipus de trigger interns

Les accions disponibles d’aquest servei són:

3.3.4.2.1. Crear alerta

Els següents exemples mostren com enviar sol·licituds a la plataforma per publicar noves alertes. Mètode POST.

Alerta externa

Si l’entitat rec vol registrar una nova alerta externa personalitzada amb l’identificador REC_ALERT_001, per monitoritzar que la majoria de valors diaris del sensor REC_001 es troben compresos al rang 60-80, la sol·licitud seria:

http://api-sentilo.diba.cat/catalog/alert/rec

I el cos del missatge:

{"alerts":[

   {"id":"REC_ALERT_001",

    "name":"REC_ALERT_001",

    "description":"Alarma personalitzada per monitoritzar que la majoria de valors diaris del sensor REC_001 es troben compresos al rang 60-80",

    "type":"EXTERNAL"

  }

]}

Alerta interna

Una alerta interna s’hauria de definir a través de la consola del catàleg o fent la crida corresponent a l’API utilitzant el token de catàleg.

Si es vol registrar una nova alerta interna amb ID REC_GT_45_ALERT_001, per monitoritzar els valors del sensor REC_001 que són majors de 45, la sol·licitud seria:

http://api-sentilo.diba.cat/catalog/alert/rec

I el cos del missatge:

{"alerts":[

   {"id":"REC_GT_45_ALERT_001",

    "name":"REC_GT_45_ALERT_001",

    "description":"Internal alert to monitorize that values for sensor's rec REC_001 are greater than 45",

    "type":"INTERNAL",

    "trigger":"GT",

    "expression":"45",

    "component":"REC_COMP_001",

    "sensor":"REC_001"

   }

]}

3.3.4.2.2. Modificar alerta

Els següents exemples mostren com enviar sol·licituds a la plataforma per modificar alertes. Mètode PUT.

Alerta externa

Si l’entitat rec vol modificar el nom de l’alerta REC_ALERT_001, la sol·licitud seria:

http://api-sentilo.diba.cat/catalog/alert/rec

I el cos del missatge:

{"alerts":[

   {"id":"REC_ALERT_001",

    "name":"REC_EXTERNAL_ALERT_001",

    "type":"EXTERNAL"

   }

]}

Alerta interna

Si volem modificar la descripció de l’alerta interna REC_GT_45_ALERT_001, la sol·licitud seria:

http://api-sentilo.diba.cat/catalog/alert/rec

I el cos del missatge:

{"alerts":[

   {"id":"REC_GT_45_ALERT_001",

    "type":"INTERNAL",

    "description":"New description"

   }

]}

3.3.4.2.3. Recuperar alertes

Els següents exemples mostren com recuperar alertes sobre les que una entity_id està subscrita, alertes que pertanyen a una entity_id o alertes sobre les que una entity_id té permisos de lectura del seu propietari. El servei permet especificar criteris de reca per filtrar les alertes a recuperar, tant filtrant pel tipus d’alerta com pel tipus de trigger. Mètode GET.

http://api-sentilo.diba.cat/catalog/alert/<entity_id>?<parameter>=<value>

L’entity_id és opcional i pot ser l’id d’una aplicació o un proveïdor.

Recuperar totes les alertes autoritzades

Per recuperar totes les alertes autoritzades, la sol·licitud seria:

http://api-sentilo.diba.cat/catalog/alert/rec

I la resposta:

{

  "alerts" : [

    {

      "id" : "REC_ALERT_001",

      "name" : "REC_EXTERNAL_ALERT_001",

      "description" : "Alarma personalitzada per monitoritzar que la majoria de valors diaris del sensor REC_001 es troben compresos al rang 60-80",

          "type" : "EXTERNAL"

    },

    {

      "id" : "REC_GT_45_ALERT_001",

      "name" : "REC_GT_45_ALERT_001",

      "description" : "Internal alert to monitorize that values for sensor's rec REC_001 are greater than 45",

      "type" : "INTERNAL",

      "trigger" : "GT",

      "expression" : "45",

      "component" : "S00020114",

      "sensor" : "S00020114-0"

    }

  ]

}

3.3.4.2.4. Esborrar alertes

Els següents exemples mostren com enviar sol·licituds a la plataforma per eliminar alertes. Mètode PUT o DELETE.

Aquesta acció es pot invocar utilitzant els mètodes HTTP PUT i DELETE.

• S’utilitzarà DELETE per esborrar totes les alertes. Aquesta operació no contempla el contingut del BODY.

• S’utilitzarà PUT per esborrar un grup d’alertes. Caldrà que al BODY s’especifiqui el paràmetre de filtratge. 

Esborrar totes les alertes

Si l’entitat rec vol eliminar totes les alertes, la sol·licitud DELETE seria:

http://api-sentilo.diba.cat/catalog/alert/rec

Esborra totes les alertes que estan autoritzades per l’entity rec. Si s’utilitza el token_id esborra totes les alertes internes associades.

Esborrar un conjunt d’alertes

Si l’entitat rec vol eliminar un conjunt d’alertes, la sol·licitud PUT seria:

http://api-sentilo.diba.cat/catalog/alert /rec?method=delete

I la resposta:

{"alertsIds":["REC_ALERT_001","REC_GT_45_ALERT_001"]}

3.3.4.3. Catàleg

El servei catalog permet registrar o modificar els sensors/components propis o consultar les característiques d’un sensor o proveïdor.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /catalog/alert/<provider_id>

on l'provider_id és opcional i s'ha d'incloure en funció de l'operació. 

Totes les sol·licituds tenen la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• L’estat i sub-estat del sensor no es pot canviar via API, només a partir del catàleg. El valor per defecte de l’estat és ‘online’, i el valor per defecte del sub-estat és buit.

• L’identificador ha d’identificar de manera unívoca el proveïdor del sensor, és a dir, dos sensors del mateix proveïdor no poden tenir el mateix ID.

• L’identificador ha de ser alfanumèric (nombres i lletres) amb guionets i sense espais.

• La llista de tipus de sensors està pre-configurada a la plataforma. Si es necessita un de nou cal contactar amb l’administrador supra-municipal per correu electrònic a smartregion@diba.cat.

• El valors possibles de tipus de dada d’un sensor també estan definits per configuració a la plataforma. Els possibles valors són: number, text o boolean. El valor per defecte és numèric.

• Si l’atribut component no es passa per paràmetres, la plataforma crearà un component al catàleg amb el mateix nom que el sensor (si no existeix prèviament).

• Si l’atribut componentType no s’especifica i el component no existeix prèviament al sistema, el component es definirà com del tipus generic.

• Si no s’especifica l’atribut location, el component es definirà com a tipus mòbil (sense localització fixe). En cas contrari es definirà com tipus static i es localitzarà a les coordenades especificades. Si l’element té diferent localitzacions, s’haurien d’informar separades per coma.

• Si no es configuren els atributs type i/o componentType al catàleg, el sistema retorna error 400 indicant que el paràmetre rebut és invàlid.

• El paràmetre publicAcces es refereix a la visibilitat del sensor a la pàgina pública. El valor per defecte és false.

• El paràmetre componentPublicAccess es refereix a la visibilitat del component al mapa públic. El valor per defecte és false.

• El paràmetre additionalInfo s’estructura amb <clau,valor> i permet guardar informació addicional del sensor. Aquesta informació no segueix cap tipus de normativa interna.

• El paràmetre componentAdditionalInfo s’estructura amb <clau,valor> i permet guardar informació addicional del component. Aquesta informació no segueix cap tipus de normativa interna.

• El paràmetre technicalDetaitls s’estructura amb <clau,valor> i permet guardar informació addicional del sensor. Les claus disponibles i els seus possibles valors són:

3.3.4.3.1. Afegir components / sensors

Els següents exemples mostren com enviar sol·licituds a la plataforma per afegir un o més components o sensors al catàleg. Mètode POST.

La sol·licitud seria:

http://api-sentilo.diba.cat/catalog/<id_Provider>

i el cos del missatge:

Afegir un sensor

Si es vol registrar un nou sensor d'humitat amb identificar RE0025 associat al component d’identificador METEO-1:

{"sensors":[

   {"sensor":"RE0025",

    "description":"sensor d’humitat 25",

    "type":"humidity",

    "dataType":"number",

    "unit":"%",

    "component":"METEO-1",

    "componentType":"meteo",

    "componentDesc":"Test componente",

    "location":"41.39479 2.148768",

"publicAccess":"true",

    "timeZone":"CET"

   }

]}

IMPORTANT: per a que el component sigui visible des del visor cal indicar "publicAccess":"true"

Afegir diferents sensors

{"sensors":[

   {"sensor":"tt01_REC013",

    "description":"sensor12",

    "type":"humidity",

    "dataType":"number",

    "unit":"grams",

    "component":"METEO-1",

    "componentType":"meteo",

    "location":"41.39479 2.148768"

   },

   {"sensor":"tt01_REC014",

    "description":"sensor12",

    "type":"humidity",

    "dataType":"number",

    "unit":"grams",

    "component":"METEO-1",

    "componentType":"estaciometeo",

    "location":"41.39479 2.148768"

   }

]}

Afegir un sensor amb informació addicional

{"sensors":[

   {"sensor":"RE0025",

    "description":"sensor d’humitat 25",

    "type":"humidity",

    "dataType":"number",

    "unit":"%",

    "component":"METEO-1",

    "componentType":"meteo",

    "componentDesc":"Test componente",

    "location":"41.39479 2.148768",

    "additionalInfo":{"accuracy":"4.5%","voltage":"2.1-3.6"},

    "componentAdditionalInfo":{"altitude":"525 m."}

    "timeZone":"CET"

   }

]}

3.3.4.3.2. Modificar components / sensors

Els següents exemples mostren com enviar sol·licituds a la plataforma per modificar un o més components o sensors al catàleg. Mètode PUT.

La sol·licitud seria:

http://api-sentilo.diba.cat/catalog/rec

i el cos del missatge:

Per modificar dades de sensors

{"sensors":[

   {"sensor":"REC012","description":"sensor 12"},

   {"sensor":"REC013","description":"sensor 13"}

]}

Si un sensor es vol canviar de component s’haurà d’esborrar i tornar a crear al component destí.

Per modificar dades de components

{"components":[

   {"component":"COMP-2","location":"41.4051143 2.1320120","componentAdditionalInfo":{"altitude":"530 m."}}

]}

3.3.4.3.3. Recuperar llista de proveïdors / sensors

Els següents exemples mostren com enviar sol·licituds a la plataforma per recuperar un o més proveïdors o sensors al catàleg. Mètode GET.

Recuperar tots els proveïdors i sensors

La sol·licitud GET seria:

http://api-sentilo.diba.cat/catalog

I la resposta:

   "providers": [{

        "provider": "A",

        "permission": "WRITE",

        "sensors": [{

            "sensor": "MAR_01_00_SN001_1010",

            "description": "Sound Sensor MODI 001",

            "dataType": "NUMBER",

            "type": "noise",

            "unit": "dBa",

            "state": "online",

            "component": "MAR_01_00_SN001_1010",

            "componentType": "generic",

            "timeZone": "CET"

        }]

    }, {

        "provider": "C",

        "permission": "READ",

        "sensors": [{

            "sensor": "MAR_02_20_PM001_1010",

            "description": "PM10 Sensor IMI 001",

            "dataType": "NUMBER",

            "type": "air_quality_pm10",

            "unit": "ug/m3",

            "state": "online",

            "component": "air_quality",

            "componentType": "generic"

        }, {

            "sensor": "MAR_02_20_PM001_1012",

            "description": "PM10 Sensor IMI 002",

            "dataType": "NUMBER",

            "type": "air_quality_pm10",

            "unit": "ug/m3",

            "state": "online",

            "component": "air_quality",

            "componentType": "generic",

            "additionalInfo": {

                "supportMail": "support@imi.com"

            },

            "technicalDetails": {

                "producer": "xxxx",

                "model": "x-1",

                "serialNumber": "9999",

                "energy": "220VAC"

            },

            "componentTechnicalDetails": {

                "producer": "XXXX",

                "model": "X-1",

                "serialNumber": "9999",

                "macAddress": "00:17:4F:08:5F:61",

                "energy": "12_24_VDC",

                "connectivity": "WIFI"

            }

        }]

    }]

}

Recuperar tots els sensors d’una tipologia

La sol·licitud GET seria:

http://api-sentilo.diba.cat/catalog?type=air_quality_pm10

I la resposta:

   "providers": [{

     "provider":"C","permission":"READ",

     "sensors":

     [{

       "sensor":"MAR_02_20_PM001_1010",

       "description":"PM10 Sensor IMI 001",

       "dataType":"NUMBER",

       "type":"air_quality_pm10",

       "unit":"ug/m3",

       "component":"air_quality",

       "componentType":"generic"

      },{

       "sensor":"MAR_02_20_PM001_1012",

       "description":"PM10 Sensor IMI 002",

       "dataType":"NUMBER",

       "type":"air_quality_pm10",

       "unit":"ug/m3",

       "component":"air_quality",

       "componentType":"generic",

       "additionalInfo":{"field1":"value1","field2":"value2"}

      }

     ]

    }

]}

Altres exemples

http://api-sentilo.diba.cat/catalog?component=comp_demo&type=air_quality_pm10

http://api-sentilo.diba.cat/catalog?componentType=air_quality&type=air_quality_pm10

3.3.4.3.4. Esborrar components / sensors

Els següents exemples mostren com enviar sol·licituds a la plataforma per esborrar un o més components o sensors al catàleg. Mètode DELETE o PUT.

PRECAUCIÓ: Aquesta operació esborra en cascada i un cop esborrat no es pot tornar enrere i desfer la operació.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /<provider_id>?<parameter>=<value>

Aquesta acció es pot invocar utilitzant els mètodes HTTP PUT i DELETE.

• S’utilitzarà DELETE per esborrar tots els sensors i components d’un proveïdor. Aquesta operació no contempla el contingut del BODY.

• S’utilitzarà PUT per esborrar un grup de sensors o components. Caldrà que al BODY s’especifiqui el paràmetre de filtratge. 

Esborrar tots els components i sensors d’un proveïdor

Per un proveïdor anomenat rec, la sol·licitud DELETE seria:

http://api-sentilo.diba.cat/catalog/rec

Esborrar un conjunt de components d’un proveïdor

Per un proveïdor anomenat rec, la sol·licitud PUT seria:

http://api-sentilo.diba.cat/catalog/rec?method=delete

I amb cos del missatge:

{"components":["COMP-3","COMP-4"]}

Esborrar un conjunt de sensors d’un proveïdor

Per un proveïdor anomenat rec, la sol·licitud PUT seria:

http://api-sentilo.diba.cat/catalog/rec?method=delete

I amb cos del missatge:

{"sensors":["RE001","RE002","RE003"]}

3.3.4.4. Dades

El servei data permet llegir, gravar i esborrar observacions dels sensors registrats.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /data/<provider_id>/<sensor_id>

on l'provider_id i sensor_id identifiquen al proveïdor i sensor sobre els que volem realitzar l'operació.

Totes les sol·licituds tenen la següent estructura:

Cada observació tindrà la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• Si s’envia una observació sense especificar timestamp, la plataforma utilitzarà el timestamp actual com a mesura de temps.

• La localització de les observacions és opcional. Si es vol gravar es pot fer globalment per a totes les observacions realitzades i/o de forma individual a cadascuna. La localització informada a cada observació preval sobre la localització global.

• Especificar el TimeZone (Z) al timestamp és opcional. El valor per defecte és UTC.

• Si el sensor té especificat state offline, el servidor rebutja la publicació.

3.3.4.4.1. Publicar observacions d’un sensor

Els següents exemples mostren com enviar sol·licituds a la plataforma per publicar observacions d’un sensor. Mètode POST.

Sol·licitud abreujada

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec/RE0012/12.3

On 12’3 és el valor observat.

Sol·licitud normal

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec/RE0012

I amb cos del missatge:

{"observations":[{

   "value":"12.3",

   "timestamp":"17/09/2012T12:34:45"}

]}

Publicar varies observacions d’un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec/RE0012

I amb cos del missatge:

{"observations":[{

    "value":"10.1"

   },{

    "value":"11.2",

    "timestamp":"17/09/2012T12:34:45"

   },{

    "value":"12.3",

    "timestamp":"17/09/2012T10:34:45"

   }

]}

3.3.4.4.2. Publicar observacions de diferents sensors

Per enviar sol·licituds a la plataforma per publicar observacions de diferents sensors utilitzarem també el mètode POST.

A la sol·licitud caldrà incloure la següent informació:

I per cada sensor:

Enviar dades de varies observacions de diferents sensors

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec

I amb cos del missatge:

{"sensors":[

   {

    "sensor":"RE0012",

    "observations":[

      {"value":"1.1"},

      {"value":"1.2",

       "timestamp":"17/09/2012T12:34:45CET"},

      {"value":"1.3",

       "timestamp":"17/09/2012T10:34:45CET"}

    ]

   },{

    "sensor":"RE0013",

    "location":"41.12345 2.12354",

    "observations":[

      {"value":"2.1"},

      {"value":"2.2",

       "timestamp":"16/09/2012T15:43:21CET"},

      {"value":"2.3",

       "timestamp":"16/09/2012T10:43:21CET"}

    ]

   }

]}

3.3.4.4.3. Esborrar observacions

Els següents exemples mostren com enviar sol·licituds a la plataforma per esborrar observacions d’un sensor. Mètode DELETE.

Esborrar la última observació d’un sensor

http://api-sentilo.diba.cat/data/rec/RE0012

Esborrar la última observació de tots els sensors d’un component

http://api-sentilo.diba.cat/data/rec

3.3.4.4.4. Llegir observacions d’un sensor

Les sol·licituds per llegir observacions d’un sensor tindran el següent format. Mètode GET.

 http://api-sentilo.diba.cat /catalog/data/<provider_id>/<sensor_id>?<parameter>=<value>

Amb la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• El nombre màxim de registres a retornar es fixarà per configuració a la plataforma. Si el paràmetre limit indica un valor superior, el nombre de registres a retornar serà igual al valor màxim configurat a la plataforma.

• Si no s’especifica el paràmetre limit, només retornarà una observació.

• Totes les dates han de tenir el format: dd/MM/yyyyTHH:mm:ssZ on Z es opcional, valor per defecte UTC.

Llegir les últimes observacions d’un sensor a partir d’una data

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec/RE0012?limit=20&from=10/01/2013T10:00:00

La resposta seria:

{"observations":[

   {

      "value":"28.61132406103821",

      "timestamp":"13/11/2017T09:00:00",

      "time":1510563600000

   },{

      "value":"20.795568440010314",

      "timestamp":"13/11/2017T08:30:00",

      "time":1510561800000

   },{

      "value":"91.01094902496055",

      "timestamp":"13/11/2017T08:30:00",

      "time":1510561800000

   },{

      "value":"62.22915604583776",

      "timestamp":"11/01/2013T08:16:38",

      "time":1510561800000

   },{

      "value":"99.96065618303348",

      "timestamp":"11/01/2013T07:16:38",

      "time":1510561800000

   },{

      "value":"94.95685904585568",

      "timestamp":"11/01/2013T06:16:38",

      "time":1510561800000

   },{

      "value":"51.26506022800391",

      "timestamp":"11/01/2013T05:16:38",

      "time":1510561800000

   },{

      "value":"21.43303677241535",

      "timestamp":"11/01/2013T04:16:38",

      "time":1510561800000

   },{

      "value":"55.6601921120059",

      "timestamp":"11/01/2013T03:16:38",

      "time":1510561800000

   },{

      "value":"56.692086830598996",

      "timestamp":"11/01/2013T02:16:38",

      "time":1510561800000

   }

]}

Llegir la última observació d’un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec/RE0012

La resposta seria:

{"observations":[{

   "value":"11.5",

   "timestamp":"18/09/2012T17:20:00",

   "time":1510561800000}

]}

3.3.4.4.5. Llegir observacions de sensors d’un proveïdor

Les sol·licituds per llegir observacions de sensors d’un proveïdor tindran el següent format. Mètode GET.

 http://api-sentilo.diba.cat /catalog/data/<provider_id>?<parameter>=<value>

Amb la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• El nombre màxim de registres a retornar es fixarà per configuració a la plataforma. Si el paràmetre limit indica un valor superior, el nombre de registres a retornar serà igual al valor màxim configurat a la plataforma.

• Si no s’especifica el paràmetre limit, només retornarà una observació.

• Totes les dates han de tenir el format: dd/MM/yyyyTHH:mm:ssZ on Z es opcional, valor per defecte UTC.

Cada sensor tindrà la següent estructura:

I cada observació tindrà la següent estructura:

Llegir les últimes observacions d’un proveïdor a partir d’una data

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec?from=10/09/2012T10:00:00

La resposta seria:

{"sensors":[

   {

      "sensor":"RE0012",

      "observations":

      [{

         "value":"1",

         "timestamp":"10/09/2012T10:05:00",

         "time":1510561800000

      },{

         "value":"1.2",

         "timestamp":"10/09/2012T07:05:00",

         "time":1510561800000

      }]

   },{

      "sensor":"RE0013",

      "observations":

      [{

         "value":"24",

         "timestamp":"10/09/2012T10:06:10",

         "time":1510561800000

      }]

   }

]}

Llegir les últimes observacions d’un proveïdor

La sol·licitud seria:

http://api-sentilo.diba.cat/data/rec

La resposta seria:

{"sensors":[

  {

      "sensor":"RE0012",

      "observations":

      [{

         "value":"1",

         "timestamp":"10/09/2012T10:05:00",

         "time":1510561800000

      }]

   },{

      "sensor":"RE0013",

      "observations":

      [{

         "value":"24",

         "timestamp":"10/09/2012T10:06:10",

         "time":1510561800000

      }]

   }

]}

3.3.4.5. Ordre

El servei ordre permet enviar i recuperar ordres de sensors/actuadors.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /order/<provider_id>/<sensor_id>

L’identificador de sensor sensor_id és opcional i s'ha d'incloure en funció de l'operació. 

3.3.4.5.1. Publicar ordres

Publicar una ordre a un sensor/actuador

La sol·licitud seria:

http://api-sentilo.diba.cat/order/rec/RE0012

I al cos del missatge:

{"order":"Stop"}

Publicar una ordre a tots els sensors/actuadors d’un proveïdor

La sol·licitud seria:

http://api-sentilo.diba.cat/order/rec

I al cos del missatge:

{"order":"Start RE0012, RE0013"}

3.3.4.5.2. Recuperar ordres

Aquesta acció permet recuperar ordres associades a un sensor i/o proveïdor. Addicionalment es pot especificar un criteri de cerca per recuperar ordres: el filtre indicarà un període de temps i/o el màxim nombre d’ordres a recuperar. Mètode GET.

Totes les sol·licituds tindran el següent format:

 http://api-sentilo.diba.cat /order/<provider_id>/<sensor_id>?<parameter>=<value>

Amb la següent estructura:

En relació als paràmetres anteriors, cal tenir present:

• El nombre màxim de registres a retornar es fixarà per configuració a la plataforma. Si el paràmetre limit indica un valor superior, el nombre de registres a retornar serà igual al valor màxim configurat a la plataforma.

• Si no s’especifica el paràmetre limit, només retornarà un registre.

• Totes les dates han de tenir el format: dd/MM/yyyyTHH:mm:ssZ on Z es opcional, valor per defecte UTC.

Si no s’especifica per paràmetres el sensor_id la resposta inclou una llista de sensors. 

Per cada sensor la resposta inclou una llista d’ordres i cada ordre tindrà la següent estructura:

Recuperar la última ordre associada a un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/order/rec/RE0012

La resposta seria:

{"orders":[{

   "order":"Shutdown",

   "timestamp":"21/03/2013T14:25:39",

   "sender":"app_demo_provider"}]

}

Recuperar les N últimes ordres associades a un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/order/rec/RE0012?limit=3

La resposta seria:

{"orders":

   [{

      "order":"Shutdown",

      "timestamp":"21/03/2013T14:25:39",

      "sender":"app_demo_provider",

      "time":1510570798597

   },{

      "order":"Start",

      "timestamp":"20/03/2013T23:59:59",

      "sender":"app_demo_provider",

      "time":1510570798597

   },{

      "order":"Shutdown",

      "timestamp":"20/03/2013T14:25:39",

      "sender":"app_demo_provider",

      "time":1510570798597

   }

]}

Recuperar les N últimes ordres associades a un sensor especificant  un període de temps

La sol·licitud seria:

http://api-sentilo.diba.cat/order/rec/RE0012?limit=3&from=19/03/2013T00:00:00&to=20/03/2013T23:59:59

La resposta seria:

{"orders":

   [{

      "order":"Start",

      "timestamp":"20/03/2013T23:59:59",

      "sender":"app_demo_provider",

      "time":1510570798597

   },{

      "order":"Shutdown",

      "timestamp":"20/03/2013T14:25:39",

      "sender":"app_demo_provider",

      "time":1510570798597

   }

]}

3.3.4.6. Subscripció

El servei subscripció permet als clients de la plataforma (proveïdors i consumidors de dades) subscriure’s a events del sistema associats a:

• Dades: Relatius a observacions rebudes a la plataforma.

• Ordres: Relatius a ordres rebudes a la plataforma.

• Relatius a alarmes rebudes a la plataforma.

També és possible recuperar una llista de subscripcions actives i/o cancelar-les.

Totes les sol·licituds d’aquest servei tindran el següent format:

 http://api-sentilo.diba.cat /subscribe/<event_type>/<resource_id>

L’identificador de resource_id identifica el recurs del sistema sobre el que es fa la subscripció.

El missatge de subscripció segueix la següent estructura:

3.3.4.6.1. Reintents

En cas de que el sistema remot finalista no respongui amb un missatge d’èxit amb codi HTTP 2xx, Sentilo pot reenviar la informació més endavant. En els reintents Sentilo aplica un sistema de retard exponencial en el re-enviament (delay (N) = delay * 2^(N-1)).

Per exemple, si hi ha una subscripció amb una configuració de 5 reintents i 10 minuts, el primer reintent es realitzarà als 10 minuts, el segon als 20 minuts del primer, el tercer als 30 minuts del segon… Al cinquè reintent es farà a 10+20+40+80+160=310 minuts després del primer intent.

3.3.4.6.2. Notificacions

Quan es subscriu a un event del sistema, la plataforma enviarà una notificació (per procés push), si l’event es produeix, a través d’una crida HTTP POST a una URL preconfigurada a la subscripció.

El missatge de notificació segueix la següent estructura:

A continuació es recullen diferents exemples de notificació:

{

   "message":"8",

   "timestamp":"26/10/2016T08:50:33",

   "topic":"/data/app_demo_provider/appdemo_sensor_test",

   "type":"DATA",

   "provider":"app_demo_provider",

   "sensor":"appdemo_sensor_test",

   "retryAttempt": 1,

   "publisher":"app_demo_provider",

   "time":1477471833000,

   "publishedAt":1477471833000

}

{

   "message":"Stop",

   "timestamp":"16/10/2013T15:39:11",

   "topic":"/order/app_demo_provider",

   "type":"ORDER",

   "provider":"app_demo_provider",

   "publisher":"app_demo_provider",

   "time":1477471833000,

   "publishedAt":1477471833000

}

{

   "message":"Value greater than 34",

   "timestamp":"16/10/2013T15:40:57",

   "topic":"/alarm/internalAlarmProve",

   "type":"ALARM",

   "sensor":"app_demo",

   "alert":"ALERT_GT14",

   "alertType":"INTERNAL",

   "publisher": :"sentilo"

   "time":1477471833000,

   "publishedAt":1477471833000

}

Si la subscripció inclou una clau secreta, els missatges anteriors inclouen capçaleres securitzades.

3.3.4.6.3. Notificacions a HTTPS amb certificats en els que no es confia

En cas que el sistema remot utilitza certificats propis en el que no es confia, cal affegir en le fitxer config.properties del servidor de Sentilo:

#Allows Sentilo to send notifications to untrusted servers, i.e., servers with self signed certificates or signed by unknown CAs

api.subs.ssl.no-validate-certificates=false

3.3.4.6.4. Subscripció a sensors/proveïdors

Aquesta acció permet la subscripció a una observació d’un sensor. Mètode PUT.

Només es pot subscriure a sensors dels que s’és propietari o es té permís de lectura.

Subscripció a dades d’un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/data/rec/RE0012

I al cos del missatge:

{"endpoint":"http://<your_endpoint_notification_server.com>"}

Subscripció a dades d’un proveïdor

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/data/rec

I al cos del missatge:

{"endpoint":"http://<your_endpoint_notification_server.com>"}

3.3.4.6.5. Subscripció a ordres

Aquesta acció permet la subscripció a ordres associades a un sensor. Mètode PUT.

Només es pot subscriure a sensors dels que s’és propietari o es té permís de lectura.

Subscripció a ordres d’un sensor

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/order/rec/RE0012

I al cos del missatge:

{"endpoint":"http://<your_endpoint_notification_server.com>"}

Subscripció a ordres d’un proveïdor

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/order/rec

I al cos del missatge:

{"endpoint":"http://<your_endpoint_notification_server.com>"}

3.3.4.6.6. Subscripció a alertes

Aquesta acció permet la subscripció a alertes associades a un sensor. Mètode PUT.

Només es pot subscriure a sensors dels que s’és propietari o es té permís de lectura.

Subscripció a alarmes d’alertes

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/alarm/<alert_id>

I al cos del missatge:

{"endpoint":"http://<your_endpoint_notification_server.com>"}

3.3.4.6.7. Recuperar subscripcions actives

Aquesta acció permet recuperar la llista de subscripcions actives. Mètode GET.

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/alarm/<event_type>

On <event_type> és opcional i permet filtrar per tipus de subscripció

Recuperar totes les subscripcions actives

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe

I al cos del missatge:

{

   "subscriptions":

   [{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"ALARM",

      "alert":"alerta1"

   },{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"DATA",

      "provider":"app_demo_provider",

      "sensor":"appdemo_sensor5_test"

   },{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"DATA",

      "provider":"app_demo_provider",

      "sensor":"appdemo_sensor_test"

   },{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"ALARM","alert":"11"

   }]

}

Recuperar totes les subscripcions actives a alarmes

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/alarm

I al cos del missatge:

{

   "subscriptions":

   [{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"ALARM",

      "alert":"alerta1"

    },{

      "endpoint":"http://<your_endpoint_notification_server.com>",

      "type":"ALARM","alert":"11"

   }]

}

3.3.4.6.8. Cancelar subscripcions

Aquesta acció permet cancelar les subscripcions actives. Mètode DELETE.

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/alarm/<event_type>/<resource_id>

On <event_type> i <resource_id> són opcionals i permeten filtrar per tipus d’event o recurs.

Cancelar totes les subscripcions actives

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe

Cancelar totes les subscripcions actives associades a ordres

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/orders

Cancelar totes les subscripcions actives associades a un recurs concret

La sol·licitud seria:

http://api-sentilo.diba.cat/subscribe/data/rec/RE0012

4. Sessions de formació

8 de novembre de 2019 -  Introducció a Sentilo i al mon Smart

29 de novembre de 2019 - Emmagatzemament i visualització de dades

13 de desembre de 2019 - Gestió de regles amb Node-RED

25 de novembre de 2020 - Exemple pràctic integració estació meteorològica MeteoCat

4 d'abril de 2023 - Ús del Grafana per l'anàlisi de dades històriques de la Plataforma Smart Region

1 de Juny de 2023 - Sessió d'introducció a la Plataforma Smart Region i suport a la integació de dispositius