inserimento immagini

relazione/relazione.md

@@ -5,55 +5,63 @@ Le funzionalità sviluppate e implementate nei microservizi sono le seguenti:
 - Controllo remoto delle luci
 - Sistema di antifurto
 - Metodo di deterrenza delle intrusioni
-
-Inoltre sono state implementate le seguenti … collaterali:
-- Sistema di autenticazione per l'accesso ai servizi basato su token JWT
-- Webserver e la relativa Webapp per l'interfaccia utente
-- Domain Manager (DM) per la gestione dei domini e dei relativi servizi
-- Broker MQTT per la comunicazione tra i servizi (in bridging con smartcity-challenge)
 # 1. Specifiche funzionali
 ## 1.1. Controllo tramite sensori ed attuatori
 Il sistema nella LAN è costituito da una BeagleBone (BB), con attuatori e led; e un arduino, che presenta un sensore di luminosità.
 
 Gli attuatori simulano gli interruttori e i sensori di movimento. I sensori di movimento permettono il controllo dell'allarme dell'antifurto e, assieme agli interruttori e al sensore di luminosità, dello stato delle luci.
 ## 1.2. Accessibilità via internet
-I servizi in cloud consistono di un server che fornisce una webapp, con la quale è possibile controllare gli elementi della LAN; il servizio di autenticazione con Keycloak; il DM, responsabile di mantenere la consistenza dei dati; e il Cloud App Manager (CAM), il quale s'interfaccia con il broker mosquitto che è connesso in bridge con la BB della LAN.
+I servizi in Cloud consistono nei seguenti servizi:
+- Sistema di autenticazione per l'accesso ai servizi basato su token JWT (JSON Web Token)
+- Webserver che fornisce una Webapp, con la quale è possibile controllare gli elementi nella LAN
+- Domain Manager (DM) per la gestione dei domini e dei relativi servizi e responsabile di mantenere la consistenza dei dati
+- Cloud App Manager (CAM), che s'interfaccia con il broker mosquitto connesso in bridge con la BB nella LAN.
+- Broker MQTT per la comunicazione tra i servizi (in bridging con smartcity-challenge)
 
-I servizi sono stati resi sicuri con l'implementazione di HTTPS e per il broker con TLS (e WSS).
+Questi servizi sono stati resi sicuri con l'implementazione di HTTPS e WSS usando dei certificati self-signed.
+<!-- DA FARE elisa spiega i certificati che hai fatto, se vuoi -->
 # 2. Analisi
 ## 2.1. Installazione del sistema in reti private
-L'installazione del sistema avviene senza configurazioni particolari poiché l'uso di mosquitto, con la configurazione da noi impostata, rende il sistema plug-n-play, ovvero è sufficiente collegarlo alla rete domestica per avere le funzionalità richieste disponibili.
+L'installazione del sistema avviene senza configurazioni particolari poiché utilizzando mosquitto con la configurazione da noi impostata, è sufficiente collegare il sistema alla rete internet per avere le funzionalità richieste disponibili.
 ## 2.2. Accessibilità da rete pubblica e da rete privata
-La connettibilità è indistintamente garantita sia all'interno della LAN sia al suo esterno grazie all'impiego di brokers Mosquitto, tutti connessi grazie all'utilizzo del bridging. Questo permette ai microservizi di comunicare come se fossero nella stessa LAN.
+La connettibilità è indistintamente garantita sia all'interno della LAN sia al suo esterno grazie all'impiego di brokers Mosquitto, tutti connessi insieme grazie all'utilizzo del bridging. Questo permette ai microservizi, alla Webapp ed al CAM di comunicare come se fossero nella stessa LAN.
 
-In ogni caso, per accedere al servizio, l'utente deve autenticarsi sia per osservare lo stato dei microservizi che per inviare comandi. Il login è gestito grazie a Keycloak che autorizza l'accesso alla webapp, interfacciata al resto del sistema.
-Grazie a questa caratteristica, l'accesso può avvenire sia dalla rete pubblica che da quella privata, senza distinzioni.
-<!--L'architettura che ne garantisce il funzionamento è la seguente: un broker è posizionato in remoto con IP pubblico e statico (smartcity) al quale si connettono il broker della LAN, della webApp ed il CloudAppManager. In questo modo, con il bridging effettuato a smartcity, siamo in grado di inviare e ricevere messaggi su ogni microservizio che lo richieda. => magari nel capitolo 4?-->
+In ogni caso, per accedere al servizio l'utente deve autenticarsi sia per osservare lo stato dei microservizi che per inviare comandi. Il login è gestito grazie a Keycloak che autorizza l'accesso alla Webapp, interfacciata al resto del sistema come appena spiegato.
 ## 2.3. Caratteristiche del traffico dati da sostenere e vincoli in tempo reale
-Essendo un sistema di domotica, è necessario che i comandi impartiti dall'utente vengano attutati una ed una sola volta ed in tempo utile, in modo tale da non inficiare l'esperienza dell'utente che risulta quindi al pari o migliore della sua esperienza analogica.
+Essendo un sistema di domotica, è necessario che i comandi impartiti dall'utente vengano attutati una ed una sola volta ed in tempo utile, in modo tale da non inficiare l'esperienza dell'utente che deve risultare al pari o migliore dell'esperienza analogica.
 
-La quantità di traffico da gestire non è eccessiva, poiché le uniche 2 fonti di produzione di messaggi (oltre a quella umana) sono il servizio della GPIO, che pubblica a tempo costante di 10s; ed il microservizio dell'antifurto, che pubblica ogni 8s.
-La componente umana non è precisamente quantificabile, ma proporzionale nella quantità di messaggi prodotti rispetto al numero di lampadine, sensori e interruttori utilizzati da ogni dominio.
+La quantità di traffico da gestire non è eccessiva poiché le uniche 2 fonti di produzione di messaggi del sistema <!--(oltre a quella umana)--> sono il servizio della GPIO, che pubblica a tempo costante di 10s; ed il microservizio dell'antifurto, che pubblica ogni 8s.
+La componente umana non è precisamente quantificabile, ma proporzionale nella quantità di messaggi prodotti rispetto al numero di lampadine, sensori e interruttori utilizzati da ogni dominio in un determinato momento.
 ## 2.4. Tecniche viste a lezione con cui soddisfare i requisiti
 Per soddisfare i requisiti, è possibile usare delle chiamate REST o il protocollo MQTT. Entrambe queste modalità sono utilizzabili poiché permettono la comunicazione tra servizi diversi.
 
-L'implementazione di microservizi riduce il tempo di installazione grazie alla dimensione inferiore dei file che ogni microservizio richiede. Inoltre la scalabilità del sistema viene semplificata di molto perché tutti i microservizi sono connessi e ognuno counica su un topic differente almeno per dominio e sottodominio.
+L'implementazione di microservizi riduce il tempo di installazione grazie alla dimensione inferiore dei file che ogni microservizio richiede.
 # 3. Approccio tecnologico
 ## 3.1. Vantaggi dell'uso di un message broker e come lo giudichiamo rispetto alle altre scelte
-Il message broker risulta fondamentale nello sviluppo di un'applicazione formata da vari microservizi, poiché permette a questi di registrarsi all'ascolto di topic specifici dai quali ricevere i messaggi degli altri microservizi. In questo modo il lavoro svolto da ogni microservizio è inferiore rispetto ad un progetto dello stesso tipo che non si avvale dell'utilizzo di mqtt.
+Il message broker risulta fondamentale nello sviluppo di un'applicazione formata da vari microservizi, poiché permette a questi di registrarsi all'ascolto di topic specifici dai quali ricevere i messaggi degli altri microservizi. In questo modo il lavoro svolto da ogni microservizio è inferiore rispetto ad un progetto dello stesso tipo che non si avvale dell'utilizzo di MQTT.
 
-L'utilizzo di mosquitto assicura il recapito di oggi messaggio nel numero a noi necessario.
+La scelta effettuata risulta migliore rispetto all'uso di chiamate REST per la sua scalabilità. Volendo rappresentare il sistema con un grafo non orientato in cui i nodi sono i microservizi e gli archi rappresentanti delle connessioni tra di essi, grazie al message broker otteniamo un grafo molto più sparso, in cui i microservizi comunicano con il message broker centrale, anzichè istanziare una connessione per ogni altro microservizio.
 
-La scelta effettuata risulta migliore rispetto all'uso di chiamate REST per la sua scalabilità. Volendo rappresentare il sistmea con un grafo non orientato in cui i nodi sono i microservizi e gli archi rappresentanti delle connessioni tra di essi, grazie al message broker otteniamo un grafo molto più sparso, in cui i microservizi comunicano con il message broker centrale, anzichè istanziare una connessione per ogni altro microservizio.
-Anche la manutenibilità migliora. <!-- => spiegare -->
+L'utilizzo di mosquitto assicura il recapito di oggi messaggio nel numero a noi necessario. La scelta di utilizzare il protocollo MQTT è dovuta al fatto che è un protocollo molto semplice e leggero, che permette di inviare messaggi in modo molto veloce e sicuro; inoltre poiché tutto il sistema dev'essere connesso, questo protocollo permette di evitare l'invio di messaggi a tutti i microservizi, ma solo a quelli che sono interessati al messaggio, poiché ognuno comunica su un topic diverso, differente almeno per dominio e sottodominio.
+
+Anche la manutenibilità migliora: infatti, se si volesse modificare un microservizio, non sarebbe necessaria la modifica del codice di tutti il sistema, ma solo quello del microservizio in questione ed eventualmente del message broker.
 # 4. Architettura del software
 ## 4.1. Organizzazione del software (evidenziandone i moduli)
+Il sistema si suddivide in 4 parti:
+- La LAN domestica
+- Il Cloud
+- Un Webserver
+- L'istanza di Keycloak per l'autenticazione.
+
+Nella LAN è presente la porzione di sistema che si occupa di comandare le luci, l'allarme e gli scenari.
+Essa è composta da una BB sulla quale operano il broker Mosquitto, i microservizi (Luci, Allarme e Scenari) e da un'Arduino che espone un sensore di luminosità.
 
-Il sistema si suddivide in due parti principali: la LAN domestica ed il cloud, oltre ad un webserver ed un'istanza di KeyCloak per l'autenticazione.
-Nella LAN è presente la porzione di sistema che si occupa di comandare le luci, l'allarme e l'apprendimento degli scenari di simulazione. Esso è composto da un BeagleBone sulla quale operano il broker Mosquitto, i microservizi Luci, Allarme e Scenari, e da un'Arduino che espone un sensore di luminosità.
-In cloud invece sono presenti il DomainManager ed il CloudAppManager che servono ad interrogare il DB e a gestire i microservizi in lan. Inoltre è presente un broker Mosquitto a cui sono connessi in bridging quello della BeagleBone e quello della WebApp.
+In Cloud sono presenti il DM che interroga il Database (DB) ed il CAM che gestisce i microservizi in LAN.
+Inoltre è presente un broker Mosquitto a cui sono connessi in bridging quello presente sulla BB e quello a cui si affaccia la Webapp.
 
+Il Webserver …
 
+L'istanza di Keycloak si occupa di gestire l'autenticazione degli utenti.
 ### 4.1.1. Webserver e Webapp
 Il Webserver, configurato per usare HTTPS, fornisce la Webapp al client grazie all'uso di API REST. Il Webserver è in grado di gestire molteplici sessioni allo stesso tempo grazie all'implementazione di Threads.
 
@@ -61,7 +69,7 @@ La Webapp può comunicare con il Message Broker grazie al protocollo MQTT, con i
 ### 4.1.2. Keycloak
 <!--DA FARE elisa-->
 ### 4.1.3. Domain Manager
-Il DM è un microservizio che opera in cloud, con funzionalità da server REST ed interagisce con il database (DB) dell'intero sistema. Si occupa di soddisfare le richieste HTTPS provenienti dalla Webapp, controllandone la validità e la consistenza col DB e inoltrarle al CloudAppManager richiamando degli URI esposti da quest'ultimo. Dopo aver verificato l'autorizzazione tramite il token fornito da Keycloak, il DM interagisce con il DB ed effettua la chiamata al CloudAppManager. Terminate queste due interazioni, viene servita la risposta alla Webapp.
+Il DM è un microservizio che opera in Cloud, con funzionalità da server REST ed interagisce con il DB dell'intero sistema. Si occupa di soddisfare le richieste HTTPS provenienti dalla Webapp, controllandone la validità e la consistenza col DB e inoltrarle al CAM richiamando degli URI esposti da quest'ultimo. Dopo aver verificato l'autorizzazione tramite il token fornito da Keycloak, il DM interagisce con il DB ed effettua la chiamata al CAM. Terminate queste due interazioni, viene servita la risposta alla Webapp.
 => poco chiaro (Alfredo)
 ### 4.1.4. BeagleBone
 - Luci
@@ -90,6 +98,7 @@ Questo componente della LAN scrive sul broker Mosquitto della BB i valori del se
 ## 5.1. UML delle classi implementate
 - Domain Manager
 
+![Domain Manager](./UML/domainManager.jpg)
 La classe principale del DM è Domain.java. Essa funge da server REST su Https.
 Espone le rotte che vengono richiamate dalla WebApp per avviare, installare, creare ed eliminare i domini, oltre a fornire servizi per la corretta  visualizazione degli elementi in app.
 Prima di operare da server esso effettua una chiamata al nostro repository gitlab per popolare la tabella dei moduli del DB.
@@ -102,6 +111,7 @@ La persistenza del sistema è affidata ad un DB SQLite locale.
 
 - Luci
 
+![Luci](./UML/luciMicroservizio.jpg)
 Il microservizio Luci opera in LAN e serve a gestire l'accensione e spegnimento delle lampade nella casa.
 la classe principale è Luci.java che opera su un ArrayList di oggetti di tipo Luce, che è la struttura dati fondamentale per il funzionamento del microservizio.
 L'oggetto Luce è definito dal quartetto input, output, stato e nome.
@@ -117,10 +127,12 @@ Ad ogni modifica dello stato delle luci corrisponde una modifica del file di sta
 
 - Webserver <!--DA FARE elisa integra con la tua parte (keycloak)-->
 
-Come il DM, anche il webserver espone delle API REST su HTTPS. Queste API sono richiamate dalla WebApp per ottenere i dati necessari per la visualizzazione delle pagine; in particolare restituiscono le pagine HTML, le immagini, i file CSS e JavaScript. Ogni richiesta viene gestita da un nuovo Thread, che legge il file e lo restituisce; una volta che il Thread ha terminato di rispondere ad una richiesta, viene eliminato; in questo modo il webserver non occupa risorse inutilmente ed è in grado di gestire molte richieste contemporaneamente. È anche presente la classe Helper, che permette di inviare le risposte HTTPS alla Webapp e di fare controlli ripetuti in varie altre classi.
+![Webserver](./UML/webserver.jpg)
+Come il DM, anche il Webserver espone delle API REST su HTTPS. Queste API sono richiamate dalla WebApp per ottenere i dati necessari per la visualizzazione delle pagine; in particolare restituiscono le pagine HTML, le immagini, i file CSS e JavaScript. Ogni richiesta viene gestita da un nuovo Thread, che legge il file e lo restituisce; una volta che il Thread ha terminato di rispondere ad una richiesta, viene eliminato; in questo modo il Webserver non occupa risorse inutilmente ed è in grado di gestire molte richieste contemporaneamente. È anche presente la classe Helper, che permette di inviare le risposte HTTPS alla Webapp e di fare controlli ripetuti in varie altre classi.
 
 - Scenari
 
+![Scenari](./UML/scenariMicroservizio.jpg)
 Il microservizio degli scenari contiene 4 classi fondamentali: Scenari, Automa, SubscribeCallback ed Esecutore.
 Scenari è la classe principale: fa partire il microservizio ed espone alle altre classi il metodo per l'invio dei messaggi MQTT, il path delle cartelle di configurazione e di risorse (nella quale si trova la cartella in cui sono salvati gli scenari) e gli IN e OUT in uso sulla GPIO.
 L'automa gestisce lo stato in cui si trova il microservizio, che può essere uno dei seguenti: spento, in fase di apprendimento e in fase di esecuzione. Questa classe espone i getter e setter dello stato, permettendo alle altre classi d'interfacciarsi. Per salvaguardare la persistenza, l'automa salva lo stato in cui si trova in un file di testo.
@@ -131,14 +143,17 @@ Sono inoltre presenti 2 classi di utilità: UserChangeSync ed Helper. La prima p
 <!--DA FARE elisa la tua parte-->
 ## 5.2. Descrizione della UI
 ### 5.2.1. Autenticazione
+![Login](./WebappPics/login.png)
 La prima pagina che viene fornita serve per ridirigere l'utente alla pagina di login su Keycloak; per questo motivo è interamente vuota.
 ### 5.2.2. Lista di domini
-In questa pagina vengono mostrati tutti i domini appartenenti all'utente autenticato. Nel caso in cui questi sia amministratore di un dominio, a destra dello stato viene mostrato un cestino, per poterlo eliminare; inoltre il bottone dello stato e' cliccabile, consentento la sua attivazione/spegnimento. Al contrario, se non e' un amministratore e il dominio e' attualmente attivo, egli puo' solamente accedere alla pagina d'interazione.
+![Lista di domini](./WebappPics/paginaDomini.png)
+In questa pagina vengono mostrati tutti i domini appartenenti all'utente autenticato. Nel caso in cui questi sia amministratore di un dominio, a destra dello stato viene mostrato un cestino, per poterlo eliminare; inoltre il bottone dello stato è cliccabile, consentento la sua attivazione/spegnimento. Al contrario, se non è un amministratore e il dominio è attualmente attivo, egli può solamente accedere alla pagina d'interazione.
 ### 5.2.3. Interazione con il proprio dominio
 Questa è la pagina principale del progetto, in cui si possono vedere tutti i dettagli del dominio installato. In alto si trovano fino a 3 bottoni che rappresentano i microservizi installati nel dominio scelto. Alla loro pressione, mostrano la UI relativa al loro microservizio, con la quale interagire per apportare modifiche.
 
 - Visione d'insieme
 
+![Visione d'insieme](./WebappPics/homepage.png)
 La pagina principale della Webapp permette l'interazione completa con il sistema. Questo significa che il suo utilizzo permette di avere sia una visione real-time di ciò che accade nella LAN, sia di comandare da remoto gli attuatori connessi.
 
 All'avvio della Webapp, viene fatta una RPC ad ogni microservizio installato nel dominio per mostrare correttamente tutti i dati disponibili all'utente; inoltre viene richiesto al server se l'utente è in realtà l'amministratore del dominio, per mostrare funzionalità aggiuntive.