FlashMat master
===============

Example program to control multiple FlashMat cells from a custom master board.

Each FlashMat module (called "cell") is made of an electronic board mounting
a microcontroller and the integrated circuits to drive the RGB led matrix.
Each cell is connected to an I2C bus, from which it receives the commands to draw
the desired images (each cell must have a unique address).
Commands are sent on I2C by a device ("commander" or "master"), which can be
an Arduino, a PC or any other suitable device.

This example software has been wrote for Arduino (ATmega328P or ATmega2560,
hence Arduino Uno, Arduino Mega, Arduino Nano, ...).
The main program is contained in FlashMat_master.ino.
There the software waits for serial commands to arrive (numbers sent by the user;
the baud rate must be 9600), with which it selects the test/example to be executed.
All the tests are inside the .ino file, and inside the loop() function it is
possible to see which tests are available, and the relative numbers.

To be able to control FlashMat cells, it is necessary to understand which commands
obtain which graphic effect, and how to combine commands. The various tests
show step-by-step all the available commands, together with notes
to avoid errors and combine commands in the proper way.
In this project a Commander class has already been created, which deals with the
lowest level in the transmission of the commands.
You can study its functions' implementation to be able to replicate it on
other devices (to understand how to transmit the commands byte-by-byte, how
to deal with errors, re-transmission, addressing, etc.).
Among the classes useful for the communication are:
+ Commander: creates the packets corresponding to each command and sends them
+ Packets: identifies the packet type. In this file it is defined the byte-by-byte
  format of each packet, too.
+ CellStatus/PacketStatus: codes information about the status of the cells
+ I2C: implements the communication at the physical level.
  It is easier to use a library already implemented for your specific device.
  I2C is more complex than the subset used in this projet, and complex to implement.
Among the classes useful to create commands are:
+ Text: to change the text parameters
+ Font/Fonts: to represent a font (in particular to know how much space a Text will take
  once drawn)
+ Gradient: to select the type of color gradient to be drawn (with the dedicated command)
+ Point: to represent a pixel/a position on the whole matrix (the global matrix made up by
  all the used cells). Point is used by various commands.
+ fmatdef: contains some fixed parameters of the cell, like the height/width in pixels.
+ ImgChunker/ImgDepthConverter: to convert bitmap images in a format supported by the cells.

For an understanding of FlashMat enough to create images/animations/custom effects
it should be enough to understand FlashMat_master and Commander (the other functionalities
can easily be used/ported on other platforms without paying much attention to their details).

To realize a master on a platform different from Arduino Uno/Mega, it is necessary to:
+ Re-implement Commander's functionalities
+ Use a suitable I2C library (on which Commander can rely)
+ In Commander, use the same numerical values for the parameter contained in Fonts (the FontId),
  Gradient, CellStatus, PacketStatus, fmatdef.
+ Re-implementing Font and Text (and the .cpp files of each font) is only necessary
  to be able to know the space occupied by the text.
+ Realize a custom software to create the desired effects/texts/images, by combining the base commands


To connect the cells: seen from above, with the socket and the microprocessor on the left,
the connections are:

    VCC  + socket
    GND  - socket
    
    VCC -- \
    VCC -- |
    GND -- | male strip 6pin, angled
    GND -- |
    SDA -- |
    SCL -- /

Note: this library can be used to control standard FlashMat cells. Custom cells programmed
with the FlashMat_lite library cannot be controlled this way.

================================================================================
================================================================================

Programma di esempio per comandare le celle FlashMat da un master personalizzato.

Ogni modulo FlashMat (chiamato "cella") e' costituito da una scheda elettronica
che monta un processore e i circuiti integrati per comandare la matrice a led RGB.
Ogni cella e' connessa ad un bus I2C, da cui riceve i comandi per disegnare
le immagini desiderate (ogni cella deve avere un indirizzo univoco).
I comandi sono inviati su I2C da un dispositivo ("commander" o "master"), che puo'
essere un Arduino, un PC o qualunque altro dispositivo.

Questo software di esempio e' realizzato per Arduino (ATmega328P o ATmega2560,
quindi Arduino Uno, Arduino Mega, Arduino Nano, ...).
Il programma principale e' contenuto in FlashMat_master.ino.
Qui il software attende che arrivino dei comandi in seriale (dei numeri inseriti
dall'utente; il baud rate deve essere 9600), con cui seleziona il test/esempio
da eseguire.
Tutti i test sono all'interno del file .ino, e all'interno della funzione loop()
e' possibile vedere quali test sono disponibili, e i relativi numeri.

Per poter comandare le celle FlashMat, e' necessario capire quali comandi
ottengono quale effetto grafico, e come combinare i comandi. I vari test
mostrano passo-passo tutti i comandi disponibili, oltre a varie osservazioni
per evitare errori e combinare i comandi in modo corretto.
In questo progetto e' gia' stata realizzata una classe Commander che si occupa
del livello pi basso della trasmissione dei comandi.
Si puo' analizzare l'implementazione delle sue funzioni per poterla replicare
su altri dispositivi (per capire come costruire i comandi byte-a-byte, come
gestire gli errori, la ritrasmissione, l'indirizzamento, ecc.).
Tra le classi utili per la comunicazione ci sono:
+ Commander: crea i pacchetti corrispondenti a ciascun comando e li invia
+ Packets: identifica il tipo di pacchetto. In questo file e' definito anche il
  formato byte-per-byte di ciascun pacchetto
+ CellStatus/PacketStatus: codifica informazioni riguardo allo stato delle celle
+ I2C: implementa la comunicazione a livello fisico. E' pi semplice usare
  una libreria I2C gia' implementata per un certo dispositivo; l'I2C e' molto
  pi complessa di quanto viene utilizzato in questo progetto, e complessa
  da implementare.
Tra le classi utili per creare i comandi ci sono:
+ Text: per variare i parametri del testo
+ Font/Fonts: per rappresentare un font (in particolare, per prevedere quanto
  spazio occupa un Text una volta disegnato)
+ Gradient: per selezionare il tipo di sfumatura da disegnare (con l'apposito
  comando)
+ Point: per rappresentare un pixel/una posizione sulla matrice intera (la matrice globale
  formata da tutte le celle utilizzate). Point e' usato da vari comandi.
+ fmatdef: contiene alcuni parametri fissi della cella, come il numero di pixel
  di altezza/larghezza.
+ ImgChunker/ImgDepthConverter: per convertire immagini bitmap in un formato
  supportato dalle celle.

Per una comprensione di FlashMat sufficiente a creare immagini/animazioni/effetti
personalizzati dovrebbe essere sufficiente comprendere FlashMat_master e
Commander (le altre funzionalita' si possono facilmente usare/portare su altre
piattaforme senza particolare attenzione ai loro dettagli).

Per realizzare un master su una piattaforma diversa da Arduino Uno/Mega, e' necessario:
+ Re-implementare le funzionalita' di Commander
+ Usare una libreria I2C opportuna (su cui Commander puo' appoggiarsi)
+ Usare in Commander gli stessi valori numerici per i parametri contenuti in
  Fonts (il FontId), Gradient, CellStatus, PacketStatus, fmatdef.
+ Re-implementare Font e Text (e i file .cpp dei singoli font) e' necessario solamente
  per poter prevedere lo spazio occupato dal testo.
+ Realizzare un software personalizzato per creare gli effetti/testi/immagini desiderati,
  combinando i comandi di base.


Per il collegamento delle celle: vista da sopra, con la morsettiera e il microprocessore
sulla sinistra, i collegamenti sono:

    VCC  + morsettiera
    GND  - morsettiera
    
    VCC -- \
    VCC -- |
    GND -- | strip maschio 6 poli, 90gradi
    GND -- |
    SDA -- |
    SCL -- /
    
Nota: questa libreria puo' essere usata per controllare celle FlashMat standard.
Celle personalizzate programmate con la libreria FlashMat_lite non possono essere controllate
in questo modo.