PROGETTI CLUSTER TOP DOWN - R.3.1 - Specifiche Software
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
Sardegna FESR 2014/2020 - ASSE PRIORITARIO I “RICERCA SCIENTIFICA, SVILUPPO TECNOLOGICO E INNOVAZIONE” Azione 1.1.4 Sostegno alle attività collaborative di R&S per lo sviluppo di nuove tecnologie sostenibili, di nuovi prodotti e servizi PROGETTI CLUSTER TOP DOWN R.3.1 – Specifiche Software VIRTUALENERGY 1/52
Sommario 1. Introduzione ......................................................................................................................................... 4 2. Requisiti Funzionali............................................................................................................................... 5 3. Soluzione Realizzata ............................................................................................................................. 6 3.1 Architettura .................................................................................................................................. 6 3.1 Backend ........................................................................................................................................ 7 3.1.1 Django................................................................................................................................... 7 3.1.2 Django REST Framework ...................................................................................................... 8 3.1.3 django-allauth ...................................................................................................................... 8 3.1.4 Docker .................................................................................................................................. 8 3.1.5 uWsgi .................................................................................................................................... 8 3.1.6 Postgres ................................................................................................................................ 8 3.2 Frontend ....................................................................................................................................... 8 3.3.1 Vue.js .................................................................................................................................... 9 3.3.2 Yarn....................................................................................................................................... 9 3.3.3 Webpack ............................................................................................................................... 9 3.3.4 Nginx ..................................................................................................................................... 9 3.3.5 Docker .................................................................................................................................. 9 3.3 Gateway........................................................................................................................................ 9 3.4 Client............................................................................................................................................. 9 3.5 Interfacce di comunicazione ...................................................................................................... 10 4. Dettagli di implementazione .............................................................................................................. 11 4.1 Backend ...................................................................................................................................... 11 4.1.1 ER Diagram ......................................................................................................................... 11 4.1.2 Discovery ............................................................................................................................ 16 4.1.3 Sensing................................................................................................................................ 17 4.1.4 Experiment ......................................................................................................................... 18 4.2 Frontend ..................................................................................................................................... 18 2/52
4.2.1 Login ................................................................................................................................... 19 4.2.2 Gestione dei dispositivi ...................................................................................................... 19 4.2.3 Gestione degli esperimenti ................................................................................................ 20 5. Installazione........................................................................................................................................ 28 5.1 Pacchetti software...................................................................................................................... 28 5.2 Download e avvio del server: ..................................................................................................... 28 5.3 Download e avvio del client ....................................................................................................... 28 5.4 Funzionamento predefinito........................................................................................................ 29 5.5 Personalizzare il funzionamento ................................................................................................ 29 6. REST APIs ............................................................................................................................................ 31 6.1 Autenticazione............................................................................................................................ 31 6.1.1 Registrazione utente .......................................................................................................... 31 6.1.2 Login utente........................................................................................................................ 32 6.1.3 Logout utente ..................................................................................................................... 32 6.2 Dispositivi ................................................................................................................................... 33 6.2.1 Lista Nodi ............................................................................................................................ 33 6.2.2 Istanza di un Nodo .............................................................................................................. 35 6.2.3 Lista Devices con stato ON ................................................................................................. 37 6.2.4 Toggle di un Device ............................................................................................................ 38 6.3 Esperimenti ................................................................................................................................ 39 6.3.1 Creazione esperimento ...................................................................................................... 39 6.3.2 Risultati di un esperimento (grafici e statistiche)............................................................... 40 7. Algoritmo di stima associato ad uno scaldacqua elettrico ................................................................. 46 7.1 Descrizione ................................................................................................................................. 46 7.2 Implementazione........................................................................................................................ 49 7.2.1 Codice dell’algoritmo ......................................................................................................... 49 7.2.2 Funzioni ausiliarie ............................................................................................................... 51 3/52
1. Introduzione Il progetto VIRTUALENERGY è uno dei tanti progetti collaborativi promossi da Sardegna Ricerche attraverso il programma “Azioni Cluster Top-Down”, finanziato grazie al fondo di sviluppo regionale POR- FESR Sardegna 2014-2020. La finalità principale che accomuna queste iniziative è quella di svolgere attività di trasferimento tecnologico nei confronti delle aziende partecipanti, attraverso la risoluzione di problematiche condivise, mediante l’applicazione di competenze e risultati frutto dell’attività di ricerca. L’obiettivo del progetto VIRTUALENERGY è quello di implementare un prototipo di Virtual Power Plant (VPP), ovvero una centrale elettrica virtuale, costituita dall’integrazione e coordinamento di sistemi eterogenei (potenza, controllo e comunicazione) in grado di interfacciarsi con la rete elettrica ed i vari stakeholders che operano sul mercato elettrico per il dispacciamento di energia e la fornitura di servizi ancillari. Questo documento descrive l’architettura del software realizzato dal DIEE nell’ambito del progetto VIRTUALENERGY. Questa piattaforma, è stata studiata per consentire in generale il controllo remoto di risorse elettriche distribuite, ed offrire un ambiente di verifica dei risultati idoneo all’esecuzione di alcune campagne sperimentali in linea con le specifiche definite nel piano dei test. L’attuale implementazione del software consente in particolare la gestione remota di carichi elettrici connessi a prese intelligenti ad uso domestico. Questa scelta è stata indotta dalla disponibilità dei componenti hardware con cui gli sviluppatori del sistema hanno avuto modo di interagire in maniera diretta. Tuttavia, la struttura del software è idonea ad integrare il controllo e la gestione di ulteriori risorse hardware. La piattaforma realizzata risulta essere uno degli elementi che concorrono all’implementazione delle funzionalità previste per il prototipo di VPP oggetto di studio, in particolare per quanto riguarda il testing e la validazione di logiche per il Demand Side Management basate sul controllo di carichi elettrici. La piattaforma abilita la trasmissione e ricezione distribuita di opportune sequenze segnali di controllo da e verso il campo, con relativo monitoraggio delle prestazioni in termini di qualità della comunicazione, esponendo opportuni meccanismi di interfacciamento con applicativi di terze parti focalizzati sulle logiche di funzionamento del VPP. La piattaforma risulta essere uno strumento di prototipazione utile per le imprese che intendono avviare o hanno già in corso investimenti per la realizzazione di sistemi che richiedono il controllo e la supervisione remota dei carichi elettrici domestici. 4/52
2. Requisiti Funzionali In questo capitolo è riportato l’elenco dei principali requisiti funzionali che l’attuale implementazione del software è in grado di soddisfare: ✓ Login: l’operatore deve poter accedere al sistema tramite le sue credenziali; ✓ Discovery dei Nodi e dei Dispositivi presenti in ogni nodo: il sistema deve automaticamente rilevare i nodi ed i dispositivi connessi. Il sistema deve anche rilevare automaticamente la disconnessione dei nodi e dei dispositivi; ✓ Sensing dei dispositivi: il sistema deve continuamente ed automaticamente ricevere l’aggiornamento dello stato dei dispositivi (es. potenza assorbita, accensione o spegnimento, etc…); ✓ Visualizzazione lista nodi e dispositivi su ogni nodo: il sistema deve consentire ad un operatore di monitorare i nodi connessi e lo stato dei dispositivi al loro interno; ✓ Visualizzazione dettaglio dispositivi: il sistema deve consentire all’operatore di visualizzare i dettagli di ogni dispositivo connesso (es. modello, numero di serie, stato di funzionamento corrente, etc…); ✓ Controllo dei dispositivi: il sistema deve consentire all’operatore di controllare i dispositivi connessi (es. accensione, spegnimento); ✓ Setup di un esperimento: il sistema deve consentire all’operatore di organizzare un esperimento che coinvolge uno o più dispositivi; ✓ Lista storico esperimenti: il sistema deve consentire all’operatore di visualizzare lo storico degli esperimenti; ✓ Visualizzazione risultato esperimento: il sistema deve consentire all’operatore di visualizzare i risultati di ogni singolo esperimento (es. grafici e statistiche, export CSV). 5/52
3. Soluzione Realizzata Per soddisfare le specifiche funzionali descritte nel capitolo 2, è stato implementato un sistema web-based in grado di gestire nodi e dispositivi, composto dai seguenti componenti: ✓ Un Backend basato su Django e Postgres, per l’implementazione della logica applicativa; ✓ Un Frontend basato su Vue.JS, per offrire un'interfaccia grafica all’operatore; ✓ Un Node Client basato sulla libreria open source PyWeMo, per il controllo ed il discovery dei dispositivi all’interno di una rete locale; ✓ Un Real Time Gateway basato sulla libreria open source Socket.io, per consentire un collegamento real time bidirezionale fra i nodi ed il backend. Il capitolo descrive gli ambienti software utilizzati per la realizzazione della piattaforma, ed ogni singolo componente con cui la piattaforma è in grado di interagire. 3.1 Architettura In Figura 1 sono riportati i vari componenti che costituiscono l'architettura del sistema realizzato. In particolare, l’applicazione è strutturata su quattro differenti layer: 1. Frontend Layer: è il layer di presentazione, che implementa l’interfaccia grafica tramite la quale gli utenti interagiscono con il sistema; 2. Backend Layer: rappresenta il cuore del sistema, fornisce le funzionalità di autenticazione, autorizzazione, gestione degli esperimenti, memorizzazione dei dati; 3. Gateway Layer: implementa un gateway che consente una comunicazione bidirezionale real time tra i web client e i server; 4. Client Layer: è la parte software che si occupa di ricevere i comandi generati dal backend e di eseguirli sui dispositivi WeMo. Nelle sezioni seguenti vengono forniti ulteriori dettagli su ognuno di questi livelli. 6/52
Figura 1: Architettura del sistema 3.1 Backend Il backend consiste in una web application scritta utilizzando il linguaggio di programmazione Python ed il Web Framework Django. In particolare, le principali tecnologie utilizzate sono quelle di seguito descritte. 3.1.1 Django Django è un framework per applicazioni web gratuito e open source, scritto in Python. Le principali caratteristiche e funzionalità che caratterizzano questo framework, sono di seguito elencate: ✓ Pattern Model-View-Controller; ✓ Possibilità di installare funzionalità attraverso plugin; ✓ Astrazione del database relazionale ad oggetti; ✓ Robusta API per la gestione del database; ✓ Sistema di template basato su tag con ereditarietà dei template; ✓ Gestore di URL basate su espressioni regolari; ✓ Sistema di gestione degli utenti e loro autenticazione nell'applicazione We ✓ Sistema di componenti "middleware" per lo sviluppo di funzionalità aggiuntive, come ad esempio la protezione CSRF e il supporto per la sessione; ✓ Può essere usato con Apache nginx e qualsiasi web server che supporta lo standard WSGI. 7/52
3.1.2 Django REST Framework Django REST Framework è stato utilizzato per sviluppare e per documentare le API REST in ambiente Django. Tale framework consente di implementare API e relativa documentazione, impostare adeguate politiche di autenticazione e autorizzazione, e fornisce strumenti per il supporto alla serializzazione ed alla validazione degli input. 3.1.3 django-allauth La libreria django-allauth è stata utilizzata per implementare gli endpoint e la logica necessari per aggiungere autenticazione in un progetto Django. 3.1.4 Docker Docker è una piattaforma software che permette di creare, testare e distribuire applicazioni, raccogliendo il software in unità standardizzate chiamate container, che offrono tutto il necessario per la loro corretta esecuzione, incluse librerie, strumenti di sistema, codice e runtime. 3.1.5 uWsgi uWSGI è un'implementazione del server WSGI (Web Server Gateway Interface) che consente di eseguire applicazioni web Python. uWSGI consente inoltre di servire files statici, gestire la terminazione SSL, ed effettuare Caching e Task Queuing. 3.1.6 Postgres PostgreSQL è un completo DBMS ad oggetti rilasciato con licenza libera. PostgreSQL offre caratteristiche che lo pongono per alcuni aspetti all'avanguardia nel settore dei database. 3.2 Frontend E’ stato scelto di implementare l’interfaccia utente tramite una Single Page Application. Con il termine Single Page Application (SPA) si intende un'applicazione web, o un sito web, che può essere usato o consultato su una singola pagina web, con l'obiettivo di fornire un'esperienza utente più fluida e simile alle applicazioni desktop dei sistemi operativi tradizionali. In un'applicazione su singola pagina, tutto il codice necessario (HTML, JavaScript e CSS) è recuperato in un singolo caricamento della pagina, e le risorse appropriate sono caricate dinamicamente e aggiunte alla pagina quando necessario, di solito in risposta ad azioni dell'utente. Le principali tecnologie utilizzate sono quelle di seguito descritte. 8/52
3.3.1 Vue.js Vue.js è un framework JavaScript open-source per la creazione di interfacce utente e single-page applications. Vue.js presenta un'architettura adottabile in modo incrementale, che si concentra sul rendering dichiarativo e sulla composizione dei componenti. 3.3.2 Yarn Yarn è un package manager open source per Javascript. Il suo scopo è quello di gestire la complessità relativa alla gestione dei pacchetti Javascript e relative dipendenze. 3.3.3 Webpack Webpack è module bundler open source per applicazioni Javascript. La sua funzione è quella di unire un insieme di moduli Javascript in un singolo file, o più files, nell’ordine corretto, ma può trasformare risorse front-end come HTML, CSS e immagini, se sono inclusi i caricatori corrispondenti. 3.3.4 Nginx Nginx è un web server/reverse proxy leggero ad alte prestazioni. Il suo scopo è quello di fornire rapidamente i contenuti statici con un utilizzo efficiente delle risorse di sistema. 3.3.5 Docker Docker è una piattaforma software che permette di creare, testare e distribuire applicazioni, raccogliendo il software in unità standardizzate chiamate container che offrono tutto il necessario per la loro corretta esecuzione, incluse librerie, strumenti di sistema, codice e runtime. 3.3 Gateway Il Gateway è stato implementato utilizzando la tecnologia Socket.io, per consentire una comunicazione bidirezionale real time orientata agli eventi tra Backend e Client. Socket.IO usa principalmente il protocollo WebSocket. Il Gateway è un breve script implementato in Python. 3.4 Client Il client è costituito da un semplice script Python, ed in particolare utilizza le librerie python-socketio per la comunicazione real time con il Gateway, e PyWeMo per la comunicazione con le smart socket. 9/52
3.5 Interfacce di comunicazione Per comprendere meglio il funzionamento del sistema, risulta utile dare una definizione delle interfacce di comunicazione utilizzate per connettere tra loro i vari elementi architetturali illustrati in Figura 2. L'interazione tra il frontend e il backend avviene tramite un'interfaccia REST, attraverso la quale le risorse messe a disposizione dal server sono identificate mediante URI. La connessione utilizza il protocollo HTTPS. La comunicazione tra backend e client PostgreSQL utilizza un protocollo message-based. Il protocollo è supportato sia su TCP/IP che su Unix-domain sockets. La comunicazione tra backend e client avviene grazie al gateway, che consente di instaurare un canale di comunicazione real time bidirezionale tra i due componenti. La comunicazione tra client e dispositivi Wemo avviene via HTTP tramite le API Wemo, controllate dalla libreria PyWeMo. Figura 2: Interfacce di comunicazione 10/52
4. Dettagli di implementazione Questo capitolo fornisce ulteriori dettagli relativi all’implementazione dei due principali elementi che caratterizzano l’applicazione. 4.1 Backend Il cuore del sistema è il backend, che implementa le seguenti funzionalità: ✓ Autenticazione e accounting ✓ Discovery dei dispositivi e dei nodi ✓ Sensing dei dispositivi ✓ Controllo dei dispositivi all’interno di uno o più nodi ✓ Gestione degli esperimenti ✓ Generazione delle statistiche relative agli esperimenti Il backend espone tutte queste funzionalità al frontend tramite delle REST API. La sezione successiva illustra il diagramma ER che rappresenta l’organizzazione interna del database progettato per il corretto funzionamento dell’applicazione. Le sezioni che seguono descrivono, mediante diagrammi UML, le sequenze di azioni effettuate dai vari componenti del sistema relativamente ai tre scenari principali implementati dall’applicazione: discovery, sensing ed experiment. 4.1.1 ER Diagram Il diagramma ER riportato in Figura 3, illustra le principali tabelle del database e le relative relazioni. Per semplicità sono state omesse le tabelle “accessorie” generate dal framework Django e dagli ulteriori framework utilizzati durante la realizzazione del backend. 11/52
Figura 3: Diagramma ER Le tabelle principali sono: ✓ Device: rappresenta il dispositivo WeMo. Lo stato del record nel DB viene tenuto aggiornato allo stato attuale dalla procedura di sensing e discovery. Campo Descrizione id Id univoco autogenerato address Indirizzo IP privato nella rete locale color Il colore che identifica il device nei risultati grafici dei tests (autogenerato) is_active specifica se il device è attivo (connesso) o meno last_update ultima volta che è stato aggiornato lo stato o il valore mW del dispositivo name nome assegnato al device 12/52
porta di comunicazione attraverso la quale avviene la comunicazione tra il client a port cui è connesso il device ed il backend mac MAC address del device model modello e versione del device model_name nome modello del device serial_number numero di serie del device value valore della grandezza elettrica misurata dal device ✓ Node: rappresenta il nodo remoto. Lo stato del record nel DB viene tenuto aggiornato allo stato attuale dalla procedura di sensing e discovery. Campo Descrizione id Id univoco autogenerato is_active Specifica se il nodo è attivo (connesso) o meno last_update Data dell’ultimo aggiornamento, rilevato name Nome assegnato al nodo owner Utente proprietario del nodo sid Identificativo univoco del nodo (viene utilizzato nel Realtime Gateway per la comunicazione tra backend e frontend) ✓ Experiment: modello dell’esperimento, che contiene i dati necessari all’esecuzione dell’esperimento. Campo Descrizione uuid uuid autogenerato univoco auto_run specifica se l’esperimento deve partire subito dopo la sua creazione start momento in cui l’esperimento è stato avviato (autogenerato) end momento in cui l’esperimento è terminato (autogenerato) 13/52
name nome dato all’esperimento (opzionale) riferimento alla tabella ExperimentSettings che specifica i tempi e il tipo setting dell’esperimento status Specifica se l’esperimento è in fase di creazione, in corso o concluso ✓ ExperimentSetting: contiene il tipo di esperimento e i dati temporali per l’esecuzione dell’esperimento stesso (è chiave esterna del modello esperimento). Campo Descrizione id Id univoco autogenerato start_experiment specifica quando l’esperimento dovrà essere avviato experiment_type specifica il tipo di esperimento che verrà condotto duration durata dell’esperimento impulse frequenza di esecuzione comandi durante l’esperimento ✓ SetExperiment: contiene il device su cui dovrà essere eseguito l’esperimento (fa riferimento al modello Experiment). Campo Descrizione id Id univoco autogenerato experiment riferimento alla tabella Experiment device device coinvolto nell’esperimento (foreignKey alla tabella device) 14/52
✓ Sample: singolo campione dei dati di un esperimento. Campo Descrizione id Id univoco autogenerato created momento di scrittura del dato sul DB finished Momento di fine scrittura del sample (tutte le operazioni e tutte le misurazioni previste per il sample sono state eseguite) experiment Riferimento alla tabella experiment (identifica l’esperimento di cui fa parte il sample) device Riferimento alla tabella device (identifica il device i cui dati sono scritti nel sample) time_sent Momento in cui il il client invia il comando al device (nel diagramma delle azioni effettuate durante l’esperimento corrisponde a Time start cmd) time_received Momento in cui il device risponde al client che ha eseguito il comando (nel diagramma delle azioni effettuate durante l’esperimento corrisponde a Time start cmd) time_start_cmd Momento in cui il backend invia il messaggio node_command(data) al client passando per il Realtime Gateway (nel diagramma delle azioni effettuate durante l’esperimento corrisponde a Time server start cmd) time_end_cmd Momento in cui il backend riceve dal Realtime Gateway la risposta che il device ha eseguito il comando (nel diagramma delle azioni effettuate durante l’esperimento corrisponde a Time server end cmd ) status Stato del device (ON/OFF) value valore della grandezza elettrica misurata dal device 15/52
✓ Statistics: memorizza i dati statistici dei risultati di un esperimento per un device. Campo Descrizione id Id univoco autogenerato experiment Riferimento alla tabella experiment (identifica l’esperimento oggetto della statistica) device Riferimento alla tabella device (identifica il device oggetto della statistica) value Oggetto contenente tutti i dati statistici dell’esperimento ✓ Chart: memorizza i dati necessari per la rappresentazione grafica dei risultati di un esperimento Campo Descrizione id Id univoco autogenerato experiment riferimento alla tabella Experiment device device coinvolto nell’esperimento (foreignKey alla tabella device) 4.1.2 Discovery Il meccanismo di discovery, illustrato in Figura 4, si occupa di rilevare automaticamente i nodi ed i dispositivi connessi al sistema, o la disconnessione degli stessi. Lo stato dei nodi e dei dispositivi viene memorizzato all’interno del DB. La procedura di connessione viene inizializzata dal client ed avviene automaticamente, sfruttando il meccanismo fornito automaticamente da Socket.io. Appena possibile, il client si connette automaticamente al real time gateway. Il real time gateway riceve il messaggio connect(data), che contiene un identificativo univoco del nodo ed il suo nome. Il real time gateway invia al backend il messaggio node_connected(data), informando in questo modo quest’ultimo sul fatto che tale nodo si è connesso. Il backend memorizza i dati del nodo e richiede immediatamente a quest’ultimo, tramite il real time gateway, un aggiornamento sui dispositivi presenti al suo interno, tramite il comando node_command(data). Il real time gateway riceve il comando e lo inoltra al client. Il client invia al 16/52
backend un messaggio node_update(data), che contiene l’aggiornamento di tutti i dispositivi ad esso connessi, con relativo stato associato. Figura 4: Diagramma UML - scenario discovery 4.1.3 Sensing Il meccanismo di sensing, illustrato in Figura 5, si occupa di effettuare continue misurazioni dei devices, allo scopo di tenere aggiornati tutti i relativi parametri. Lo stato dei devices aggiornati sarà memorizzato all’interno del DB. Figura 5: Diagramma UML - scenario sensing 17/52
La procedura di connessione avviene sfruttando il meccanismo di connessione fornito automaticamente da Socket.io. Appena possibile, il client si connette automaticamente al real time gateway. Il real time gateway riceve il messaggio node_update(data), che contiene un identificativo univoco del nodo ed il suo nome.Il real time gateway invia al backend il messaggio node_update(data), che contiene al suo interno i dati aggiornati del nodo. Se è necessario, il backend aggiorna i dati del nodo, e memorizza i dati aggiornati nel DB. 4.1.4 Experiment Il diagramma illustrato in Figura 6 descrive la sequenza di azioni effettuate durante lo svolgimento di un esperimento. Figura 6: Diagramma UML - scenario experiment Il frontend, tramite REST API, invia al backend i dati necessari per la creazione di un esperimento. Al tempo time_server_start_cmd, il backend invia al real time gateway un messaggio node_command(data) che contiene i dati necessari all’esecuzione dell’esperimento. Il real time gateway invia al client, tramite messaggio node_command(data) i dati necessari all’esperimento. Al tempo time_start_cmd , il client, interfacciato con i devices, esegue i comandi e legge i parametri degli stessi. Al tempo time_end_cmd, il client invia i parametri ottenuti al real time gateway. Al tempo time_server_end_cmd, il backend riceve dal real time gateway il messaggio che il device ha eseguito il comando. Il backend memorizza nei samples i parametri ottenuti dai devices. 4.2 Frontend Le sezioni che seguono illustrano i dettagli relativi alle diverse schermate che caratterizzano l’interfaccia utente dell’applicazione. 18/52
4.2.1 Login In particolare, la Figura 7 fa riferimento alla schermata attraverso cui l’operatore accede all’applicazione. I parametri di default sono: Username: admin Password: admin Figura 7: Schermata di login 4.2.2 Gestione dei dispositivi La Figura 8 mostra la schermata attraverso cui l’utente ha la possibilità di visualizzare l’elenco dei dispositivi connessi al sistema. Per ogni dispositivo viene mostrato il relativo identificativo, l’attuale stato di funzionamento, che nel caso delle smart socket corrisponde allo stato di attivazione del relay integrato all’interno della presa, i cui stati sono rappresentati in base al differente colore della lampadina (verde: acceso, bianco: spento), e l’elenco delle grandezze elettriche acquisite dal dispositivo, che in questo caso corrispondono alla sola potenza assorbita. 19/52
Figura 8: Elenco dei dispositivi connessi La Figura 9 mostra la parte della schermata di visualizzazione attraverso cui l’utente accede alle informazioni di dettaglio relative al singolo dispositivo. Nel caso delle smart socket, queste informazioni sono relative in particolare a: indirizzo ip del dispositivo, porta di comunicazione attraverso cui il sistema scambia i dati con il dispositivo, mac address, serial number e modello del dispositivo, ed infine, stato di funzionamento attuale del dispositivo. Figura 9: Lista dispositivi con informazioni relative al singolo device 4.2.3 Gestione degli esperimenti La Figura 10 illustra invece la schermata attraverso cui l’operatore ha la possibilità di impostare un nuovo esperimento. Il sistema implementa due distinte tipologie di esperimento: una modalità di “sola lettura”, ovvero in cui non è previsto l’invio di alcun segnale di controllo da parte del sistema, che si limita in questo caso a registrare secondo la frequenza impostata dall’operatore le misure di potenza assorbita acquisite dal dispositivo; una modalità di “lettura e scrittura”, in cui invece, oltre al campionamento dei parametri elettrici, è previsto anche l’invio di un certo numero di segnali di accensione/spegnimento, con frequenza impostabile dall’operatore. L’operatore può selezionare i dispositivi che dovranno essere coinvolti in un 20/52
determinato esperimento. Un dispositivo può essere coinvolto in più esperimenti. Questa flessibilità consente all’operatore di impostare campagne di test che consentono di validare svariati scenari. Per ogni esperimento, l’operatore può impostare: la relativa durata, la frequenza, ossia l’intervallo di tempo che dovrà intercorrere tra due azioni successive (acquisizione del dato ed eventuale modifica dello stato di funzionamento). ed infine, la data e l’orario di avvio dell’attività. In particolare, un esperimento potrà essere avviato immediatamente, selezionando l’opzione ‘Adesso’ dal menù a tendina, oppure in un secondo momento selezionando l’opzione ‘Posticipa’. Figura 10: Schermata relativa alla creazione di un nuovo esperimento Nel caso in cui si scegliesse di posticipare l’avvio, la data e l’orario potrà essere scelto per mezzo del date- picker che apparirà subito dopo la selezione di esperimento posticipato, così come mostrato in Figura 11. L’interfaccia utente offre all’operatore la possibilità di gestire sia gli esperimenti in corso, sia quelli ad avvio programmato, oltre che naturalmente visualizzare i risultati degli esperimenti conclusi. 21/52
Figura 11: Schermata relativa all'impostazione della data di avvio dell'esperimento La Figura 12 mostra in particolare le due opzioni che l’operatore ha a disposizione per gestire un determinato esperimento in esecuzione. La prima, è quella di poter arrestare l’attività in qualsiasi momento, tramite il tasto (icona verde con il quadrato blu all’interno); la seconda, è quella di visualizzare i risultati parziali, grafici e statistici, attraverso il tasto (icona verde con l’occhio blu all’interno). Figura 12: Schermata relativa alla gestione degli esperimenti in corso La Figura 13 invece, mostra la schermata attraverso cui l’operatore visualizza l’elenco degli esperimenti da lui programmati, ma non ancora mandati in esecuzione dal sistema. 22/52
Figura 13: Schermata relativa alla gestione degli esperimenti posticipati La Figura 14, mostra la schermata attraverso cui l’operatore accede alla gestione degli esperimenti conclusi. In particolare, per ogni attività conclusa, l’operatore ha la possibilità di consultare i principali indicatori statistici e grafici attraverso l’interfaccia utente, oppure effettuare l’esportazione dei dati grezzi tramite in formato .csv per eventuali ulteriori attività di elaborazione off-line. Figura 14: Schermata relativa alla gestione degli esperimenti conclusi La Figura 15 rappresenta la pagina attraverso cui l’operatore ha modo di consultare a livello grafico l’andamento di un determinato esperimento. In particolare, per ogni singola smart socket analizzata, l’interfaccia utente mostra l’andamento della potenza assorbita e del delta_t. Quest’ultima grandezza rappresenta il principale indicatore, il cui grafico consente all’operatore di valutare la qualità della comunicazione nel corso dell’intero esperimento. L’interfaccia utente rende facilmente distinguibili i segnali relativi ad ogni singolo dispositivo, differenziandoli dagli altri sulla base del colore associato al particolare id. 23/52
Figura 15: Schermata relativa alla visualizzazione grafica dei risultati ottenuti nell’esperimento
La Figura 16 rappresenta la schermata attraverso cui l’operatore ha modo di consultare i vari indicatori
statistici determinati dal sistema una volta concluso l’esperimento. Le grandezze in questione vengono
calcolate come di seguito descritto:
Quantificazione misure acquisite
Numero totale di misure aventi timestamp
= all’interno della finestra temporale di logging
considerata registrate nel database
Numero di misure CORROTTE all’interno del
= ∑ ( )
totale nella finestra temporale considerata
=1
Numero di misure CORRETTE rispetto al totale
= −
nella finestra temporale considerata
Quantificazione durate temporali
Durata complessiva della finestra temporale di
= −
logging presa in esame.
Intervallo di tempo, all’interno della finestra
= ∑ ( ) temporale di logging considerata, calcolato
=1 come somma degli intervalli di trasmissione
( ) ( ) = 0 relativi alle MISURE CORRETTE registrate sul
( ) = {
0 ( ) = 1 database.
24/52
Intervallo di tempo, all’interno della finestra
= ∑ ( ) temporale di logging considerata, calcolato
=1 come somma degli intervalli di trasmissione
| ( )| ( ) = 1 relativi al numero di MISURE CORROTTE
( ) = {
0 ( ) = 0 registrate sul database.
Intervallo di tempo, all’interno della finestra
= − ( + ) temporale di logging considerata, in cui il
dispositivo è risultato disconnesso.
Statistiche relative alla trasmissione corretta delle misure
Massimo intervallo di tempo in cui è avvenuta
= { ( ) ∀ = 1: }
correttamente la trasmissione di una misura
Minimo intervallo di tempo in cui è avvenuta
= { ( ) ∀ = 1: }
correttamente la trasmissione di una misura
1 Intervallo di tempo medio in cui è avvenuta
= ∑ ( )
correttamente la trasmissione di una misura
=1
Varianza degli intervalli di tempo con cui sono
1 2
= ∑( ( ) − ) avvenute correttamente le trasmissioni delle
misure
=1
Deviazione standard degli intervalli di tempo con
1 2
= √ ∑( ( ) − ) cui sono avvenute correttamente le trasmissioni
−1 delle misure
=1
Valore stimato delle tempistiche associate alle misure (totali, trasmesse, perse)
Stima dell’intervallo di tempo, all’interno della
finestra temporale di logging considerata,
= ⋅
corrispondente al numero di misure registrate nel
database.
Stima dell’intervallo di tempo, all’interno della
finestra temporale di logging considerata,
= ⋅
corrispondente al numero di misure corrotte
presenti nel database.
Stima dell’intervallo di tempo, all’interno della
finestra temporale di logging considerata,
= ⋅
corrispondente al numero di misure registrate
correttamente nel database.
25/52Figura 16: Schermata relativa alla visualizzazione degli indicatori statistici associati all'esperimento In Figura 17 è riportato un esempio di dati relativi ad un esperimento concluso, che l’operatore ha l’opportunità di esportare tramite interfaccia utente, in formato CSV, qualora fosse necessario effettuare eventuali ulteriori elaborazioni offline, mediante applicativi di terze parti. Il significato dei singoli campi che costituiscono i record del file csv estratto dal sistema è di seguito riportato: ✓ N: numero progressivo (univoco) del sample. ✓ Sample Id: identificativo (univoco) del sample all’interno del DB. ✓ Created: timestamp di avvio del processo di creazione del sample. ✓ Finished: timestamp di fine del processo di creazione del sample. ✓ Experiment: uuid dell’esperimento all’interno del DB. ✓ Device: nome del device coinvolto nell’esperimento. ✓ Time start cmd: timestamp dell’istante in cui il client invia il comando al device. ✓ Time end cmd: timestamp dell’istante in cui il comando viene ricevuto (ed eseguito) dal device. ✓ Time server start cmd: timestamp dell’istante in cui il server (all’interno del ciclo dell’esperimento) invia al client il comando da far eseguire al device. ✓ Time server end cmd: timestamp dell’istante in cui il server riceve dal client la conferma di comando eseguito da parte del device. ✓ Status: stato del device (ON/OFF). ✓ Current power mW: potenza assorbita dal dispositivo. 26/52
Figura 17: Esempio di dati esportati in formato CSV In Figura 18 è riportato un diagramma UML che mostra la sequenza di operazioni che caratterizzano il processo di invio e ricezione dei messaggi dal server (backend) al singolo attuatore (WeMo device), e viceversa, in cui si trovano evidenziati anche i quattro differenti timestamp che il sistema registra per ogni singolo campionamento. Figura 18: diagramma UML relativo al processo di registrazione dei vari timestamp per ogni sample 27/52
5. Installazione In questo capitolo vengono fornite le indicazioni che è opportuno seguire per realizzare una corretta installazione della piattaforma. 5.1 Pacchetti software Per il corretto funzionamento del sistema, occorre anzitutto installare i seguenti software, che costituiscono prerequisito essenziale per poter completare la messa in servizio del sistema: ✓ Git: scaricabile su http://git-scm.com/downloads o utilizzando il gestore di pacchetti del sistema operativo ✓ Docker: è possibile scaricare e installare il software su diverse piattaforme. Per ulteriori dettagli è opportuno fare riferimento alla seguente documentazione: https://docs.docker.com/get-docker 5.2 Download e avvio del server: Occorre quindi creare la directory in cui verrà salvato il progetto, e digitare i seguenti comandi: git clone https://github.com/VirtualEnergy-Project/virtualenergy-backend-app-configuration.git --recurse- submodules cd virtualenergy-backend-app-configuration docker-compose -f production.yml build docker-compose -f production.yml up 5.3 Download e avvio del client Nel dispositivo su cui andrà installato il modulo per la gestione del nodo, creare una directory e, una volta entrati all’interno di quest’ultima, digitare i seguenti comandi: ✓ Effettuare il download del progetto git clone https://github.com/VirtualEnergy-Project/virtualEnergyNode.git ✓ Installare le dipendenze necessarie pip3 install pywemo==0.4.43 pip3 install python-socketio==4.6.0 pip3 install python-engineio==3.13.0 28/52
pip3 install six==1.10.0 pip3 install eventlet==0.25.2 pip3 install requests==2.24.0 ✓ Per avviare il client, all’interno della directory creata è sufficiente digitare il comando: python3 node_client.py A questo punto, una volta che il sistema è avviato, è possibile accedere al frontend, collegandosi al link: http://0.0.0.0:8081 5.4 Funzionamento predefinito Ogni secondo il client, invia al Server Django la lista dei devices presenti al suo interno. Il server a sua volta, riceve la lista e la aggiorna nei seguenti casi: ✓ un eventuale nuovo device aggiunto viene memorizzato nel DB con tutti i relativi parametri; ✓ un device precedentemente esistente che non viene rilevato per un certo intervallo di tempo superiore ad una certa soglia (di default impostata ad un valore pari a 120 secondi), viene disabilitato e non sarà più fruibile fino a nuova rilevazione da parte del nodo; ✓ l’eventuale variazione di stato (es: ON/OFF) comporterà l’aggiornamento del device stesso Il Frontend interagisce con le API esposte dal backend all’indirizzo http://0.0.0.0:8000 5.5 Personalizzare il funzionamento All’interno della directory in cui risulta installato il modulo virtualenergy-backend-app-configuration, nel path /.envs/.production/.django, possiamo personalizzare i parametri di default del server, riportati in Figura 19. Figura 19: Parametri di configurazione del server 29/52
Il significato di ognuno di questi parametri è di seguito riportato: ✓ SERVER_URL specifica l’indirizzo pubblico, attraverso il quale, verrà esposto il modulo websockets realtime gateway. ✓ TIME_OUT indica il numero dei secondi oltre i quali, un device non rilevato dal nodo viene disabilitato. ✓ DEFAULT_ADMIN_USER e DEFAULT_ADMIN_PASSWORD: specificano l’utente di default che verrà creato al primo avvio del progetto. Sono altresì fondamentali le variabili d’ambiente che si trovano nel client, all’interno del file constants.py, il cui contenuto è riportato in Figura 20 Figura 20: Parametri di configurazione del client Il significato di ognuno di questi parametri è di seguito riportato: ✓ SERVER_URL: specifica l’indirizzo pubblico, attraverso il quale, verrà esposto il modulo websockets realtime gateway (dev’essere obbligatoriamente il medesimo specificato nel server in /.envs/.production/.django). ✓ DEVICES_REFRESH_TIME: specifica ogni quanti secondi il client deve inviare al server la lista aggiornata dei devices. In /.envs/.production/.dashboard, per mezzo della variabile d’ambiente VUE_APP_BASE_URL è possibile personalizzare l’indirizzo attraverso cui il frontend si interfaccia alle API esposte dal server, così come mostrato in Figura 21. Figura 21: Parametri per interfacciamento tra frontend ed API 30/52
6. REST APIs
In questo capitolo vengono descritte in maniera dettagliata le API REST implementate nel Backend.
Le API sono divise in tre gruppi principali:
✓ Autenticazione
✓ Dispositivi
✓ Esperimenti
6.1 Autenticazione
6.1.1 Registrazione utente
Metodo Metodo/Formato Formato
Input Output
/rest-auth/registration/ POST JSON
Parametri POST
username Username identificativo dell'utente
email Email dell’utente
password1 Password
password2 Ripeti la password
Risposta di successo (otteniamo il token di accesso
{
"key": "51e85b9e851ecaa76227556db947033d9deb418c"
}
31/526.1.2 Login utente
Metodo Metodo/Formato Formato
Input Output
/rest-auth/login/ POST JSON
Headers
Authorization Token
Parametri POST
username Username identificativo dell'utente
password Password
Risposta di successo (restituisce il token d’accesso)
{
"key": "51e85b9e851ecaa76227556db947033d9deb418c"
}
Risposta Errore
{
"detail": "Invalid token.",
"status_code": 401
}
6.1.3 Logout utente
Metodo Metodo/Formato Formato
Input Output
/rest-auth/logout/ POST JSON
Risposta di successo
{
"detail": "Successfully logged out."
}
32/526.2 Dispositivi
6.2.1 Lista Nodi
Metodo Metodo/Formato Formato
Input Output
/api/v1/nodes GET JSON
Headers
Authorization Token
Risposte di esempio
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"node": {
"id": 1,
"owner": {
"username": "admin",
"email": ""
},
"created": "2020-10-13T16:01:18.715702",
"modified": "2020-10-15T09:59:13.415276",
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"name": "Office",
"sid": "4d7dd1abba5941ff85e731967d30cc75"
},
"device": [
[
{
"id": 2,
"created": "2020-10-13T16:08:24.111882",
"modified": "2020-10-15T09:59:13.418559",
33/52"status": false,
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"color": "#5DE4D2",
"name": "103",
"address": "192.168.5.5",
"port": 49153,
"mac": "6038E01B97F4",
"model": "Belkin Insight 1.0",
"model_name": "Insight",
"serial_number": "221714K12000FF",
"value": "0"
},
{
"id": 1,
"created": "2020-10-13T16:08:19.761872",
"modified": "2020-10-15T09:59:13.421564",
"status": true,
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"color": "#F793FC",
"name": "104",
"address": "192.168.5.88",
"port": 49153,
"mac": "6038E01B94E8",
"model": "Belkin Insight 1.0",
"model_name": "Insight",
"serial_number": "221714K120003C",
"value": "0"
}
]
]
}
]
}
34/526.2.2 Istanza di un Nodo
Metodo Metodo/Formato Formato
Input Output
/api/v1/nodes/ GET JSON
Headers
Authorization Token
Risposte di esempio
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"node": {
"id": 1,
"owner": {
"username": "admin",
"email": ""
},
"created": "2020-10-13T16:01:18.715702",
"modified": "2020-10-15T09:59:13.415276",
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"name": "Office",
"sid": "4d7dd1abba5941ff85e731967d30cc75"
},
"device": [
[
{
"id": 2,
"created": "2020-10-13T16:08:24.111882",
"modified": "2020-10-15T09:59:13.418559",
"status": false,
"is_active": true,
35/52"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"color": "#5DE4D2",
"name": "103",
"address": "192.168.5.5",
"port": 49153,
"mac": "6038E01B97F4",
"model": "Belkin Insight 1.0",
"model_name": "Insight",
"serial_number": "221714K12000FF",
"value": "0"
},
{
"id": 1,
"created": "2020-10-13T16:08:19.761872",
"modified": "2020-10-15T09:59:13.421564",
"status": true,
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T09:59:13.404546",
"color": "#F793FC",
"name": "104",
"address": "192.168.5.88",
"port": 49153,
"mac": "6038E01B94E8",
"model": "Belkin Insight 1.0",
"model_name": "Insight",
"serial_number": "221714K120003C",
"value": "0"
}
]
]
}
]
}
36/526.2.3 Lista Devices con stato ON
Metodo Metodo/Formato Formato
Input Output
/api/v1/devices/?status=true GET JSON
analogamente con status= false otterremo la lista dei devices con stato OFF
Headers
Authorization Token
Risposta di esempio
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"created": "2020-10-13T16:08:19.761872",
"modified": "2020-10-15T10:35:49.007650",
"status": true,
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T10:35:48.988256",
"color": "#65E15B",
"name": "104",
"address": "192.168.5.88",
"port": 49153,
"mac": "6038E01B94E8",
"model": "Belkin Insight 1.0",
"model_name": "Insight",
"serial_number": "221714K120003C",
"value": "0",
"node": {
"id": 1,
37/52"created": "2020-10-13T16:01:18.715702",
"modified": "2020-10-15T10:35:56.095090",
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T10:35:48.988256",
"name": "Office",
"sid": "4d7dd1abba5941ff85e731967d30cc75",
"owner": 1
}
}
]
}
6.2.4 Toggle di un Device
Metodo Metodo/Formato Formato
Input Output
/api/v1/devices//toggle GET JSON
analogamente con status= false otterremo la lista dei devices con stato OFF
Headers
Authorization Token
Risposta di esempio
{
"id": 1,
"created": "2020-10-13T16:08:19.761872",
"modified": "2020-10-15T12:07:08.041545",
"status": false,
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T12:07:07.470466",
"color": "#CA10C0",
"name": "104",
"address": "192.168.5.88",
"port": 49153,
"mac": "6038E01B94E8",
"model": "Belkin Insight 1.0",
38/52"model_name": "Insight",
"serial_number": "221714K120003C",
"value": "0",
"node": {
"id": 1,
"created": "2020-10-13T16:01:18.715702",
"modified": "2020-10-15T12:07:07.480607",
"is_active": true,
"is_simulated": false,
"last_update": "2020-10-15T12:07:07.470466",
"name": "Office",
"sid": "4d7dd1abba5941ff85e731967d30cc75",
"owner": 1
}
}
6.3 Esperimenti
6.3.1 Creazione esperimento
Metodo Metodo/Formato Formato
Input Output
/api/v1/experiment POST JSON
Headers
Authorization Token
Parametri POST
auto_run true
start_experiment Timestamp di inizio esperimento (se nullo l’esperimento partirà subito dopo la
sua creazione)
name Nome da assegnare all’esperimento, può essere null
experiment_type Tipo esperimento: TOGGLE_DEVICE (esperimento con accesione e
spegnimento dei devices) o READ_DEVICE_STATUS (sola lettura dello stato
dei devices)
39/52duration Durata esperimento in secondi
impulse Frequenza esperimento lettura stato o impulso di toggle dei devices
device_ids Array id dei device coinvolti nell’esperimento, può essere null e in questo caso
verranno considerati tutti i devices
es:[{"id": 1},{"id": 2}]
Risposta di esempio (otteniamo l’uuid dell’esperimento)
{
"uuid": "50d3bbf1-3320-40b6-9614-ae7c0e3da651"
}
6.3.2 Risultati di un esperimento (grafici e statistiche)
Può essere eventualmente eseguito durante l’esecuzione di un esperimento, in modo da ottenere i risultati
parziali
Metodo Metodo/Formato Formato
Input Output
/api/v1/experiment//results POST JSON
Headers
Authorization Token
Parametri POST
device_ids Array id dei device dei quali vogliamo vedere i risultati, può essere null e in
questo caso verranno considerati tutti i devices
es:[{"id": 1},{"id": 2}]
Risposta di esempio
{
"experiment": {
"experiment_type": "TOGGLE_DEVICE",
“Start_experiment”: null,
"duration": 10,
40/52Puoi anche leggere
