Documentazione libreria Master - GregoSwe/pluviometroI2c GitHub Wiki

#Descrizione

Questa libreria dovrà essere aggiunta al modulo che si intende utilizzare come nodo Master per effettuare interrogazioni con la scheda Slave connessa al pluviometro. Per l'utilizzo della libreria viene fornita un oggetto precreato (esattamente come avviene per la libreria Wire) denominato SlaveInterface, il quale fornisce dei metodi per potersi interfacciare tramite protocollo I2C con la scheda Slave.

##Esempio utilizzo libreria:

Esempio utilizzo libreria Master:

int numberOfNewTimestamp = SlaveInterface.newTimestamp(); // recupero il numero di nuovi timestamp
if(numberOfNewTimestamp() > 0) // verifico che ci siano nuovi timestamp da richiedere
{
    for(int j =0; j<numberOfNewTimestamp;j = j+900) \*
    {
        TimestampContainer container = SlaveInterface.requireTimestamp() // recupero i nuovi                                              timestamp dallo Slave
        for(int i = 0; i < container.size(); i++) // scorro tutti i Timestamp contenuti dentro il container
       {
         Timestamp tmstmp = container.value(i); // recupero il Timestamp i-esimo dal container
         Serial.println(tmstmp.day());   // stampo il giorno del mese
         Serial.println(tmstmp.month()); // stampo il mese dell'anno
         Serial.println(tmstmp.year());  // stampo l'anno
         Serial.println(tmstmp.hour());  // stampo l'ora del giorno
         Serial.println(tmstmp.minute());// stampo i minuti dell'ora
         Serial.println(tmstmp.second());// stampo i secondi del minuto
         Serial.println(tmstmp.counter());// stampo il contatore del Timestamp
         Serial.print(***);
       }
 
       container.clear(); // rilascio la memoria occupata dal TimestampContainer
  }

* Poiché le schede Arduino possiedono capacità limitate di RAM, se ci sono più di 900 byte di dati da inviare, devono essere effettuate più richieste, perché ogni richiesta invia al massimo 900byte. Due richieste successive inviano i byte corretti: i primi 900 + i byte restanti.

#Indice

Componenti Software

• SlaveInterfaceClass - SIC
• Attributi
  • Descrizione Attributi
• Metodi
  • Descrizione Metodi
    • Pubblici
      • SlaveIntefaceClass(byte _slaveAddress)
      • TimestampContainer requireTimestamp()
      • int resetMemory()
      • int newTimestamp()
    • Privati
• SlaveComunicationHandler - SCH
  • Attributi
    • Descrizione Attributi
  • Metodi
    • Descrizione Metodi
      • Pubblici
        • SlaveComunicationHandler()
        • int requireNewTimestamp(byte _slaveAddress)
        • int requireUsedMemory(byte _slaveAddress)
        • int requireDeleteMemory(byte _slaveAddress)
        • byte* getNewTimestamp(byte _slaveAddress, bool _letUnread)
        • byte* getUsedMemory(byte _slaveAddress)
      • Privati
        • void prepareSlaveRequest(byte _slaveAddress, byte _requestType)
        • byte* requireBytes(byte _slaveAddress, byte _requestType, int _howManyBytes)
        • int requireInteger(byte _slaveAddress, byte _requestType)
• TimestampContainer - TsC
  • Attributi
    • Descrizione Attributi
  • Metodi
    • Descrizione Metodi
      • Pubblici
        • TimestampContainer(byte * _rawByte, int _size)
        • Timestamp value(int i)
        • Timestamp &get(int i)
        • int size()
        • void clear()
      • Privati
• Timestamp - Ts
• Attributi
  • Descrizione Attributi
• Metodi
  • Descrizione Metodi
    • Pubblici
      • Timestamp(byte _d,byte _m,int _y,byte _h,byte _mm,byte _s,int _c)
      • Timestamp()
      • byte day()
      • byte month()
      • int year()
      • byte hour()
      • byte minute()
      • byte second()
      • int counter()
    • Privati
• Converter - Cnv
• Attributi
  • Descrizione Attributi
• Metodi
  • Descrizione Metodi
    • Pubblici
    • Protetti
      • int get_info(byte* _byteArray,int _type)
      • void decompress(byte * _compressedByte, int * _integerArray)

#Componenti Software

Di seguito vengono elencate le componenti software che compongono la libreria, i loro attributi e metodi con relative descrizioni.

SlaveInterfaceClass - SIC

torna su

Classe principale della libreria, che permette di interfacciarsi con la scheda Slave connessa al pluviometro tramite i suoi metodi pubblici.

SIC Attributi

Pubblici:

public:

Privati:

private:
    SlaveComunicationHandler SCH;
    byte slaveAddress;

SIC Descrizione Attributi

torna su

Pubblici:

Privati:

• SlaveComuncationHandler SCH: Riferimento alla classe SlaveComunicationHandler, componente per l'interfaccia con la scheda Slave tramite protocollo I2C.
• byte slaveAddress: indirizzo della scheda Slave indispensabile per l'utilizzo della libreria Wire

SIC Metodi

torna su

Pubblici:

public:
    SlaveInterfaceClass(byte _slaveAddress);
    TimestampContainer requireTimestamp();
    int resetMemory();
    int newTimestamp();
    void setSlaveAddress(byte _newAdd);

Private:

private:

SIC Descrizione Metodi

• Pubblici
  • SlaveIntefaceClass(byte _slaveAddress)
  • TimestampContainer requireTimestamp()
  • int resetMemory()
  • int newTimestamp()
• Privati

Pubblici:

SlaveInterfaceClass(byte _slaveAddress)

torna su

Costruttore della classe;

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave connessa al pluviometro;
• Variabili direttamente modificate:
  • byte slaveAddress;

TimestampContainer requireTimestamp()

torna su

Metodo che ritorna un oggetto di tipo TimestampContainer contenente tutti i nuovi timestamp salvati dalla scheda Slave.

• Metodi utilizzati:
  • SCH.requireNewTimestamp(slaveAddress): ritorna il numero di byte di nuovi timestamp presenti in memoria;
  • SCH.getNewTimestamp(slaveAddress,false): ritorna i byte dei timestamp compressi;

int resetMemory()

torna su

Metodo che richiede alla scheda Slave connessa al pluviometro di cancellare i dati salvati all'interno della memoria EEPROM esterna e di ripristinare i contatori. Infine ritorna il numero di byte che sono stati cancellati.

• Metodi utilizzati:
  • SCH.requireDeleteMemory(slaveAddress): metodo che ritorna il numero di byte cancellati e richiede alla scheda Slave di cancellare la memoria.

int newTimestamp()

torna su

Metodo che ritorna il numero di timestamp presenti nella memoria della scheda Slave ancora da leggere.

• Metodi utilizzati:
  • SCH.requireNewTimestamp(slaveAddress): ritorna il numero di byte di nuovi timestamp presenti in memoria;

SlaveComunicationHandler - SCH

torna su

Componente software adibita alla comunicazione con la scheda Slave connessa al pluviometro tramite protocollo I2C.

SCH Attributi

torna su

Pubblici:

public:

Privati:

private:
    byte BYTERATE;

SCH Descrizione Attributi

torna su

Pubblici:

Privati:

• byte BYTERATE: corrisponde al numero di byte da inviare al massimo nel bus I2C.

SCH Metodi

Pubblici:

public:
    SlaveComunicationHandler();
    int requireNewTimestamp(byte _slaveAddress);
    int requireUsedMemory(byte _slaveAddress);
    int requireDeleteMemory(byte _slaveAddress);
    byte* getNewTimestamp(byte _slaveAddress, bool _letUnread);
    byte* getUsedMemory(byte _slaveAddress);

Privati:

private:
    void prepareSlaveRequest(byte _slaveAddress, byte _requestType);
    byte* requireBytes(byte _slaveAddress, byte _requestType, int _howManyBytes);
    int requireInteger(byte _slaveAddress, byte _requestType);

SCH Descrizione Metodi

torna su

• Pubblici
  • SlaveComunicationHandler()
  • int requireNewTimestamp(byte _slaveAddress)
  • int requireUsedMemory(byte _slaveAddress)
  • int requireDeleteMemory(byte _slaveAddress)
  • byte* getNewTimestamp(byte _slaveAddress, bool _letUnread)
  • byte* getUsedMemory(byte _slaveAddress)
• Privati
  • void prepareSlaveRequest(byte _slaveAddress, byte _requestType)
  • byte* requireBytes(byte _slaveAddress, byte _requestType, int _howManyBytes)
  • int requireInteger(byte _slaveAddress, byte _requestType)

Pubblici:

SlaveComunicationHandler()

torna su

Costruttore della classe

• Parametri direttamente modificati:
  • byte BYTERATE: viene impostato a 30 di default. 32 byte è il limite fisico supportato dal bus I2C, portato a 30 per poter inviare facilmente 5 timestamp alla volta da 6 byte ciascuno.

int requireNewTimestamp(byte _slaveAddress)

torna su

Metodo che ritorna il numero di timestamp presenti nella memoria della scheda Slave connessa al pluviometro ancora da leggere.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare
• Metodi utilizzati:
  • requireInteger(_slaveAddress,0): metodo che richiede tramite protocollo I2C il numero di timestamp presenti nella memoria che devono ancora essere letti.

int requireUsedMemory(byte _slaveAddress)

torna su

Metodo che ritorna il numero di byte totali occupati nella memoria EEPROM della scheda Slave. Questa richiesta viene effettuata tramite protocollo I2C.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
• Metodo usati:
• requireInteger(_slaveAddress,1): metodo che richiede tramite protocollo I2C il numero byte totali usati per salvare i timestamp nella memoria EEPROM.

int requireDeleteMemory(byte _slaveAddress)

torna su

Metodo che richiede alla scheda Slave che vengano cancellati i byte presenti in memoria e che vengano ripristinati i contatori al valore di default. In oltre ritorna il numero di byte che sono stati in questo modo cancellati.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
• Metodo usati:
• requireInteger(_slaveAddress,5): metodo che richiede tramite protocollo I2C il numero byte che sono stati cancellati dalla memoria EEPROM della scheda Slave.

byte* getNewTimestamp(byte _slaveAddress, bool _letUnread)

torna su

Metodo che richiede alla scheda Slave tramite protocollo I2C di ricevere i byte contenenti i Timestamp ancora non letti, lasciandoli poi non letti oppure contrassegnandoli come letti.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
  • bool _letUnread: booleano che identifica se i byte che sono stati ricevuti devono essere considerati letti (_letUnread == false) oppure come non letti (_letUnread == true).
• Metodi utilizzati:
  • int requireNewTimestamp(_slaveAddress): metodo che richiede il numero di byte da leggere
  • byte* requireBytes(_slaveAddress,requestType,howManyByte): metodo che richiede tramite protocollo I2C un numero preciso di byte (howManyByte) alla scheda Slave a seconda del tipo di richiesta da effettuare:
    • requestType == 3: i byte che si ricevono vengono contrassegnati come letti;
    • requestType == 2: i byte che si ricevono non vengono contrassegnati come letti

byte* getUsedMemory(byte _slaveAddress)

torna su

Metodo che richiede alla scheda Slave tramite protocollo I2C che venga trasmessa tutta la memoria contenente Timestamp.

• Parametri:
  • byte _slaveAddress`: indirizzo della scheda Slave da interrogare;
• Metodi utilizzati:
  • int requireNewTimestamp(_slaveAddress): metodo che richiede il numero di byte da leggere
  • byte* requireBytes(_slaveAddress,requestType,howManyByte): metodo che richiede tramite protocollo I2C un numero preciso di byte (howManyByte) alla scheda Slave a seconda del tipo di richiesta da effettuare:
    • requestType == 4: richiede tutti i byte che sono presenti in memoria utilizzati per salvare Timestamp;

Privati:

void prepareSlaveRequest(byte _slaveAddress, byte _requestType)

torna su

Metodo che informa la scheda Slave tramite protocollo I2C di preparare i dati che serviranno per la richiesta da effettuare.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
  • byte _requestType: variabile che identifica il tipo di richiesta che la scheda Slave deve preparare ad accogliere.
• Note: viene utilizzata la libreria Wire per la comunicazione con la scheda Master.

byte* requireBytes(byte _slaveAddress, byte _requestType, int _howManyBytes)

torna su

Metodo che ritorna i byte richiesti attraverso protocollo I2C alla scheda Slave a seconda della richiesta effettuata.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
  • byte _requestType: variabile che identifica il tipo di richiesta che la scheda Slave deve preparare ad accogliere;
  • int _howManyBytes: numero di Byte che devono essere richiesti alla scheda Slave.
• Metodi utilizzati:
  • prepareSlaveRequest(_slaveAddress,_requestType): metodo utilizzato per preparare la scheda Slave ad inviare i dati richiesti a seconda del _requestType.
• Note: in questo metodo vengono effettuate più richieste tramite protocollo I2C, poiché non è possibile richiedere più di 30 byte alla volta. Quindi nel caso in cui si richiedono più di 30 byte, all'interno del metodo vengono effettuate il numero adeguato di richieste su protocollo I2C alla scheda Slave, la quale, a sua volta, è programmata per rispondere con i byte corretti.

int requireInteger(byte _slaveAddress, byte _requestType)

torna su

Metodo che ritorna un intero richiesto tramite protocollo I2C alla scheda Slave a seconda del tipo di richieste effettuato.

• Parametri:
  • byte _slaveAddress: indirizzo della scheda Slave da interrogare;
  • byte _requestType: variabile che identifica il tipo di richiesta che la scheda Slave deve preparare ad accogliere;
• Metodi usati:
  • prepareSlaveRequest(_slaveAddress,_requestType);
• Note : in questo metodo viene utilizzata la libreria Wire per la comunicazione I2C con la scheda Slave.

TimestampContainer - TsC

torna su

Classe adibita per convertire i byte compressi contenenti le informazioni dei timestamp, ricevuti tramite protocollo I2C dalla scheda Slave, in un formato più facile da utilizzabile. Oltre a convertire i byte, questa classe è progettata per funzionare da collezione di oggetti di tipo Timestamp e fornire un'interfaccia per potervi accedere.

Ereditarietà: questa classe è sottoclasse della classe Converter

NOTE: Questa classe occupa memoria nello heap, ricordarsi di utilizzare .clear() quando non si intende più utilizzare l'oggetto, così da liberare memoria RAM.

TsC Attributi

torna su

Pubblici:

Privati:

Timestamp* timestampArray;
int sizeOf; 

TsC Descrizione Attributi

torna su

• Timestamp * timestampArray: puntatore all'array di Timestamp. Alla creazione dell'oggetti, l'arra viene inizializzato a seconda del numero di byte compressi che l'oggetto della classe riceverà nel costruttore. Ogni 6 byte (numero di byte per un timestamp), verrà creato un oggetto di tipo Timestamp con le informazioni decodificate nel formato corretto.
• int sizeOf: intero che rappresenta il numero dei Timestamp che si trovano in timestampArray

TsC Metodi

torna su

Pubblici:

TimestampContainer(byte * _rawByte, int _size);
Timestamp value(int i);
Timestamp &get(int i);
int size();
void clear();

Privati:

TsC Descrizione Metodi

torna su

• Pubblici
  • TimestampContainer(byte * _rawByte, int _size)
  • Timestamp value(int i)
  • Timestamp &get(int i)
  • int size()
  • void clear()

Pubblici:

TimestampContainer(byte * _rawByte, int _size)

torna su

Costruttore della classe, nella quale viene costruito tramite operatore new un array contenente oggetti della classe Timestamp

• Parametri:
  • byte _rawByte: array di byte contenenti le informazioni compresse;
  • int _size: intero raffigurante la grandezza dell'array di byte.
• Metodi utilizzati:
  • decompress(int*,byte*): metodo della superclasse Converter che converte le informazioni compresse in 6 byte nelle informazioni corrispondenti nel formato corretto. Vedi Ottimizzazione memoria.
• Variabili direttamente modificate:
  • Timestamp* timestampArray;
  • int sizeOf.
• Note: l'array di byte _rawByte, concluso il costruttore, verrà eliminato tramite l'operatore delete [], così da liberare la memoria da informazioni ridondanti, in quanto i parametri contenuti nei byte compressi, ora sono memorizzati in un formato più compressibile ed accessibile nell'array di Timestamp.

Timestamp value(int i)

torna su

Metodo che ritorna l'oggetto Timestamp nella posizione i-esima per valore

• Parametri:
  • int i : indice del Timestamp che si vuole recuperare ( i [0,size()-1])

Timestamp &get(int i)

torna su

Metodo che ritorna un riferimento all'oggetto Timestamp nella posizione i-esima

• Parametri:
  • int i : indice del Timestamp che si vuole recuperare ( i [0,size()-1])

int size()

torna su

Metodo che ritorna il numero dei Timestamp contenuti all'interno dell'oggetto TimestampContainer

void clear()

torna su

Metodo utilizzato per pulire dalla memoria i dati contenuti all'interno dell'oggetto TimestampContainer tramite l'operazione delete []

• Variabili direttamente modificate:
  • Timestamp* timestampArray: viene effettuata la delete[] dell'intero array.

Timestamp - Ts

torna su

Classe adibita alla rappresentazione in chiaro delle informazioni costituenti un timestamp : giorno, mese, anno, ora, minuti, secondi e contatore. Questa classe rende semplice l'utilizzo di queste informazioni

Ts Attributi

torna su

Pubblici:

Privati:

private:
    byte _day;
    byte _month;
    int _year;
    byte _hour;
    byte _minute;
    byte _second;
    int _counter;

Ts Descrizione Attributi

torna su

Pubblici:

Privati:

• byte _day: byte rappresentante il giorno del mese (valore compreso tra 1 e 31);
• byte _month: byte rappresentante il mese dell'anno (valore compreso tra 1 e 12);
• int _year: byte rappresentante l'anno (valore compreso tra 0 e 99);
• byte _hour: byte rappresentante l'ora del giorno (valore compreso tra 0 e 23);
• byte _minute: byte rappresentante i minuti dell'ora (valore compreso tra 0 e 59);
• byte _second: byte rappresentante i secondi dei minuti (valore compreso tra 0 e 59);
• int _counter: intero rappresentante il numero del timestamp memorizzato dall'ultima lettura.

Ts Metodi

torna su

Pubblici:

public:
 Timestamp(byte _d,byte _m,int _y,byte _h,byte _mm,byte _s,int _c);
 Timestamp();
 byte day();
 byte month();
 int year();
 byte hour();
 byte minute();
 byte second();
 int counter();

Privati:

Ts Descrizione Metodi

torna su

• Pubblici
  • Timestamp(byte _d,byte _m,int _y,byte _h,byte _mm,byte _s,int _c)
  • Timestamp()
  • byte day()
  • byte month()
  • int year()
  • byte hour()
  • byte minute()
  • byte second()
  • int counter()

Timestamp(byte _d,byte _m,int _y,byte _h,byte _mm,byte _s,int _c)

torna su

Costruttore della classe; vengono inizializzate le variabili.

• Variabili direttamente modificate:
  • byte _day;
  • byte _month;
  • int _year;
  • byte _hour;
  • byte _minute;
  • byte _second;
  • int _counter;

Timestamp()

torna su

Costruttore della classe di default. Necessario in Arduino perché non è possibile immettere valori di default alle variabili.

• Variabili direttamente modificate:
  • byte _day;
  • byte _month;
  • int _year;
  • byte _hour;
  • byte _minute;
  • byte _second;
  • int _counter;

byte day()

torna su

Metodo che ritorna il valore del giorno del mese.

byte month()

torna su

Metodo che ritorna il valore del mese dell'anno.

int year()

torna su

Metodo che ritorna il valore dell'anno.

byte hour()

torna su

Metodo che ritorna il valore dell'ora del giorno.

byte minute()

torna su

Metodo che ritorna il valore dei minuti dell'ora.

byte second()

torna su

Metodo che ritorna il valore dei secondi del minuto.

int counter()

torna su

Metodo che ritorna il valore dei contatore del timestamp.

Converter - Cnv

torna su

Questa classe è stata creata per fornire tutti i metodi di necessari per la conversione dei byte compressi di un timestamp in un formato più facilmente utilizzabile.

Cnv Attributi

torna su

none

Cnv Descrizione Attributi

torna su

none

Cnv Metodi

torna su

Pubblici:

Protetti:

protected:
  int get_info(byte* _byteArray,int _type);
  void  decompress(byte * _compressedByte, int * _integerArray);

Note: i metodi in questione sono stati implementati protetti e non privati per poter essere utilizzati dalle classi che derivano da questa.

Cnv Descrizione Metodi

torna su

• Protetti
  • int get_info(byte* _byteArray,int _type)
  • void decompress(byte * _compressedByte, int * _integerArray)

Protetti:

torna su

int get_info(byte* _byteArray,int _type)

torna su

Metodo che ritorna il valore intero di una informazione compressa contenuta all'interno dell'array di byte contenente i valori compressi del timestamp.

• Parametri:
  • byte* _byteArray: array di byte contenente le informazioni del timestamp in un formato compresso;
  • int _type: intero che rappresenta il tipo di informazione che si desidera ricevere:
    • _type == 0: ritorna il valore del giorno ;
    • _type == 1: ritorna il valore del mese;
    • _type == 2: ritorna il valore dell'anno;
    • _type == 3: ritorna il valore dell'ora;
    • _type == 4: ritorna il valore dei minuti;
    • _type == 5: ritorna il valore dei secondi;
    • _type == 6: ritorna il valore del contatore;

void decompress(byte * _compressedByte, int * _integerArray)

torna su

Metodo che inserisce nell'array di interi _integerArray i byte di un timestamp compressi in _compressedByte

• Parametri:
  • byte * _compressedByte: array di byte contenente i byte compressi del timestamp (dimensione: 6 byte);
  • int * _integerArray: array di interi nel quale verranno inseriti i valori decompressi del timestamp (dimensione 7 int).
• Metodi utilizzati:
  • int get_info(byte* _byteArray,int _type): metodo per il recupero delle informazioni decompresse.
• Note: il chiamante del metodo dovrà inizializzare un array di interi int x[7] e passarlo come parametro. Dopo aver utilizzato il metodo l'array conterrà:
  • x[0]: valore del giorno;
  • x[1]: valore del mese;
  • x[2]: valore dell'anno;
  • x[3]: valore dell'ora;
  • x[4]: valore dei minuti;
  • x[5]: valore dei secondi;
  • x[6]: valore del contatore;