LocalSensor.h

Go to the documentation of this file.

#pragma once
 
#pragma region INCLUSIONS
// Libreria per la gestione del sensore utilizzato: DHT22
/*
Libreria di autore "Adafruit" per la gestione LowLevel di un sensore modello "DHT".
Sorgenti necessarie: 
--- DHT sensor library by Adafruit
--- Adafruit Unified Sensor by Adafruit
*/
#include <DHT.h>
#pragma endregion INCLUSIONS
 
/*
E' importante ricordare che le espressioni costanti 'constexpr' equivalgono alla direttiva '#define'.
Questo significa che, durante la fase di compilazione, avviene un REPLACEMENT da parte del compilatore, che, dovunque
trova il nome assegnato alla 'constexpr' lo SOSTITUISCE con il rispettivo valore.
Questo ci fa capire che, in verità, le 'constexpr' sono RVALUE e NON risiedono nel Data Segment come le variabili globali (si/no statiche).
*/
 
// Namespace di protezione dalle inclusioni multiple con nominazione uguale
/*
I valori constexpr, come spiegato appena sopra, equivalgono alla direttiva '#define'. Questo può creare problemi nel momento in cui un singolo file viene incluso
in una gerarchia di molti più file, dove si potrebbe riscontrare la presenza di constexpr appartenenti a file diversi ma con gli stessi nomi! Questa ripetitività dei nomi deriva
dagli standard di nominazione. Per evitare, quindi, conflitti di multipla definizione, andremo ad utilizzare un 'namespace', che, come dice il nome, fornisce uno SPAZIO per i NOMI del nostro 
file in cui il 'namespace' è stato dichiarato ed implementato.
Mantieniamo comunque la specificazione 'static', per evitare errori di linker in caso di inclusioni multiple di questa unità di traslazione [file].
*/
 
namespace LocalSensor__file
{
    // Espressione costante (equivalente della direttiva '#define') per la definizione di un valore di "non-pin".
    // Questo valore rappresenta lo stato delle variabili contenenti valori relativi ai PIN prima dell'inizializzazione.
    /*Lasciare variabili PIN senza inizializzazione potrebbe causare risultati indefiniti.*/
    static constexpr auto _nopin = -1;
 
    // Espressione costante (equivalente della direttiva '#define') per la definizione di un valore di "_invalidvalue".
    // Questo valore rappresenta il valore di assegnazione all'attributo 'm_Invalidator'. Deve essere un valore "impossibile", che non 
    // deve esistere in altri contesti.
    static constexpr float _invalidvalue = -999.9;
}
 
class LocalSensor
{
    /*Blocco trivial*/
    /*
    Stiamo trattando una classe interamente statica. Per la definizione di staticità, descritta successivamente, questa classe fungerà solamente
    da "contenitore astratto" per organizzare più logicamente i dati. In verità, tutto risiederà principalmente nel Data Segment, quindi sarà 
    globale, ma statico (anche questo descritto successivamente). 
    Questa staticità implica la NON necessità di creare istanze di questa classe, che risulterebbero totalmente inutili dato che tutti gli attributi
    e i metodi esistono nell'ambito globale.
    Per evitare, quindi, inutili istanziamenti, verranno bloccati il costruttore trivial (di default generato dal compilatore) e il distruttore, reso
    inutile dalla non-istanziabilità della classe stessa.
    */
private:
    // Blocco attraverso privatizzazione del costruttore trivial
    LocalSensor() = default;
    // Blocco attraverso privatizzazione del distruttore trivial
    ~LocalSensor() = default;
 
    /*Enumerazioni*/
    /*
    Una enumerazione permette una gestione più intelligente degli "switcher" forniti all'utente finale.
    Tramite nomi significativi, si gestiscono gli "switcher" appunto con dei nomi, utilizzati per mascherare i valori di enumerazione meno significativi per l'utente.
    Anche qua si applica la staticità descritta successivamente. Una classe di enumarazione è automaticamente statica.
    */
public:
    enum class TemperatureUnit
    {
        CELSIUS,
        FAHRENHEIT
    };
 
    /*Attributi*/
private:
    // Puntatore al sensore stesso, rappresentato da un oggetto di classe "DHT"
    /*
    Questa variabile conterrà l'istanza dell'oggetto sensore creata durante l'operazione di inizializzazione.
    L'oggetto sarà sottoposto ad allocazione dinamica [heap]. Questo per evitare problemi con la deallocazione mirata all'ambito
    caratteristica della memoria statica [stack]. Una allocazione statica [stack] provocherebbe l'allocazione e successiva deallocazione
    immediata dell'oggetto esistendo solamente nell'ambito di inizializzazione.
    Essendo statica, la variabile (puntatore) verrà allocata nel 'Data Segment' (segmento dei dati) ed "esisterà" fino a termine 
    del programma stesso. Quindi si tratta di una variabile globale, ma statica. Questo la rende esistente solamente in questa unità 
    di traslazione (file).
    */
    static DHT* m_Sensor;
 
    // Valore del PIN utilizzato per la lettura dei valori corrispondenti alla temperatura
    /*
    Questa variabile conterrà il valore che rappresenta il PIN fisico utilizzato per interfacciare il sensore.
    Il tipo di variabile che rappresenta un PIN è un semplice intero [int].
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int m_SensorPin;
 
    // Modello del sensore utilizzato per la lettura dei valori
    /*
    Questa variabile conterrà il modello (codice identificativo) del sensore che verrà utilizzato.
    La variabile è resa necessaria dalla presenza della libreria "DHT", la quale può gestire più sensori e quindi necessità
    del modello del sensore in uso. 
    Anche questa variabile è un tipo intero [int]. Le specificazioni del modello sono solitamente rappresentate da SIGLE
    (e.g. DHT11, DHT22...) le quali sono rappresentano soltano dei nomi, ma in verità sono dei semplici interi.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int m_SensorType;
 
    // Variabile di salvataggio della temperatura rilevata
    /*
    Questa variabile conterrà il valore della temperatura rilevata. Il tipo è un numero decimale [float].
    Esso può rappresentare una temperatura in CELSIUS o FAHRENHEIT. Questa scelta viene fornita dal metodo
    che verrà utilizzato per la lettura stessa.
    La variabile viene continuamente aggiornata ad ogni ricampionamento da parte del sensore.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static float m_Temperature;
 
    // Variabile di salvataggio dell'umidità rilevata
    /*
    Questa variabile conterrà il valore della temperatura rilevata. Il tipo è un numero decimale [float] che rappresenta una 
    PERCENTUALE. La variabile viene continuamente aggiornata ad ogni ricampionamento da parte del sensore.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static float m_Humidity;
 
    /*Init*/
public:
    // Inizializza il sensore tramite il costruttore della classe "DHT"
    /*
    Questo metodo, fondamentale, "dà vita" al sensore. Effettua una allocazione (dinamica [heap]) attraverso un costruttore
    parametrico della classe "DHT". Questo costruttore richiede 2 parametri:
    --- PIN fisico utilizzato per interfacciare il sensore. Parametro -> 't_SensorPin'
    --- Modello (codice identificativo) del sensore utilizzato. Parametro -> 't_SensorType'
    I parametri, per evitare inutili copie, vengono passati per riferimento [reference --> '&'].
    Il passaggio di questi due valori come parametri potrebbe indurre a dubitare l'utilità dei 2 attributi: 'm_SensorPin' e 'm_SensorType'.
    Questo è sbagliato perchè il salvataggio di parametri "vitali" per il corretto funzionamento della classe evita la necessità di "recall"
    per la ripresentazione degli stessi parametri.
    Il metodo ritorna un valore booleano, utilizzato per comunicare eventuali errori durante l'allocazione.
    Inoltre, prima dell'effettiva allocazione, esegue una deallocazione [delete] se necessaria.
    Anche qua ritroviamo la specificazione di staticità. Nel caso di applicazione ad un metodo, dissocia il metodo stesso da qualsiasi possibile istanza
    della classe. Quindi, il metodo sarà richiamabile come se fosse globale (e statico). Sarà solamente necessario anteporre il nome della classe di 
    appartenenza. Ricordiamo anche che i metodi statici possono operare solo su variabili statiche, che anch'esse, essendo globali (e statiche) sono
    totalmente dissociate da possibili istanze della classe stessa (da oggetti).
    */
    static bool Init(const int& t_SensorPin, const int& t_SensorType);
 
    /*Service Management*/
    static bool Begin();
 
    /*LowLevel getters*/
    /*
    I seguenti metodi LowLevel sono supposti soprattutto per uso a scopo di debug e management manuale.
    Forniscono un punto di accesso costante a VALORE MODIFICABILE (quindi dereferenziabile ma non reindirizzabile).
    In release mode, potrebbe risultare efficace cambiare il contrassegno da 'public' a 'private'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
public:
    // Ritorna un puntatore a 'm_SensorPin'
    static int* const get_SensorPin();
 
    // Ritorna un puntatore a 'm_SensorType'
    static int* const get_SensorType();
 
    // Ritorna un puntatore all'oggetto di classe "DHT"
    static DHT* const get_Sensor();
 
    /*LowLevel reallocator*/
    /*
    Il seguente metodo è supposto soprattutto per uso a scopo di debug e management manuale.
    Esegue una riallocazione dell'oggetto sensore costruito con il rispettivo costruttore parametrico (della libreria "DHT") con i valori degli attributi interessati
    della classe.
    Inoltre, prima dell'effettiva riallocazione, esegue una deallocazione [delete] se necessaria.
    Il metodo ritorna un valore booleano, utilizzato per comunicare eventuali errori durante l'allocazione.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
public:
    // Riesegue una operazione di inizializzazione con i valori degli attributi 'm_SensorPin' ed 'm_SensorType'
    static bool ReInit();
 
    /*Metodi*/
public:
    // Ritorna il valore corrispondente alla temperatura rilevata
    // Parametro 't_Switch' per la selezione dell'unità di misura
    /*
        TemperatureUnit::FAHRENHEIT --> FAHRENHEIT ---> maschera: "1" (valore booleano corrispondente --> 'true')
        TemperatureUnit::CELSIUS --> CELSIUS --> maschera_ "0" (valore booleano corrispondente --> 'false')
    */
    /*
    Questo metodo rappresenta la principale ragione dell'esistenza di questa classe. Permette il campionamento del valore della temperatura,
    il quale verrà successivamente restituito.
    E' importante specificare la non possibilità di un ritorno con riferimento [reference --> '&']. Questo a causa della presenza di un rvalue, o 
    comunque di una deallocazione ad ambito.
    Il tipo del valore ritornato è un numero decimale [float]. E' stato reso costante vista la non necessità di modifiche sulla copia in ritorno.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static const float get_Temperature(const TemperatureUnit& t_Switch);
 
    // Ritorna il valore corrispondente all'umidità rilevata
    /*
    Questo metodo rappresenta la seconda principale ragione dell'esistenza di questa classe. Permette il campionamento del valore dell'umidità, il
    quale verrà successivamente restituito.
    Stessa motivazione riguardo il riferimento.
    Il tipo del valore ritornato è un numero decimale [float]. E' stato reso costante vista la non necessità di modifiche sulla copia in ritorno.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static const float get_Humidity();
 
    /*Invalidator*/
    /*
    L'invalidatore consiste in quel valore che viene ritornato ogni qualvolta una chiamata da parte dell'utente ai metodi non produce il risultato atteso.
    E' importante specificare che, l'invalidatore, pur essendo costante, non deve essere dichiarato come 'constexpr' perchè NON deve seguire le regole di 
    comportamento della direttiva '#define'. Il compilatore NON deve sostituire il nome dell'attributo con un valore numerico costante --> i.e. RVALUE!!
    L'invalidatore deve essere un vero e proprio attributo della classe, che però non deve mai appartenere ad uno specifico oggetto. Per questo deve essere sempre
    specificato come statico. Ovviamente, avrà una locazione nel Data Segment, sarà quindi globale ma statico (valido sono in questa unità di traslazione (file)) e utilizzabile
    solamente nell'ambito della classe di dichiarazione.
    */
    /*Attributo*/
private:
    // Valore costante che viene ritornato in caso di invalidità riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato è un valore impossibile, cioè che non potrebbe essere mai rilevato naturalmente dal sensore.
    static const float m_Invalidator;
 
    /*getter*/
public:
    // Metodo per il ritorno del valore dell'Invalidatore. Verrà ritornata una referenza [reference --> '&'] costante, in modo tale da ottimizzare il processo e,
    // allo stesso tempo evitare modifiche inappropriate.
    /*
    Un'altra particolarità di questo metodo sta nel fatto che è definita come 'inline'. Questa keyword comunica al compilatore, ovunque trovi una chiamata
    a questo metodo, di NON effettuare una vera e propria chiamata, ma di sostituire la porzione del codice per la chiamata con il BODY del metodo (la implementazione stessa).
    Questa tecnica risulta molto utile per funzioni che effettuano pochissime operazioni e sono sottoposte a frequenti chiamate.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static inline const float& get_Invalidator();
};
 
// Dichiarazione delle variabili GLOBALI STATICHE 
// Risiederanno nel Data Segment
/*
Essendo statiche in classe, tutti gli attributi non sono altro che variabili GLOBALI STATICHE.
Per questo è richiesta la dichiarazione globale. Non è necessario specificare 'static' essendo già stato specificato nella dichiarazione degli
attributi nella classe stessa.
*/
DHT* LocalSensor::m_Sensor = nullptr;
int LocalSensor::m_SensorPin = LocalSensor__file::_nopin;
int LocalSensor::m_SensorType;
float LocalSensor::m_Temperature;
float LocalSensor::m_Humidity;
const float LocalSensor::m_Invalidator = LocalSensor__file::_invalidvalue;