.. note::

    Ciao, benvenuto nella community di SunFounder Raspberry Pi & Arduino & ESP32 su Facebook! Approfondisci la tua esperienza con Raspberry Pi, Arduino ed ESP32 insieme ad altri appassionati.

    **Perché unirti a noi?**

    - **Supporto Esperto**: Risolvi i problemi post-vendita e le sfide tecniche con l'aiuto della nostra comunità e del nostro team.
    - **Impara e Condividi**: Scambia suggerimenti e tutorial per migliorare le tue competenze.
    - **Anteprime Esclusive**: Ottieni accesso anticipato agli annunci di nuovi prodotti e alle anteprime.
    - **Sconti Speciali**: Approfitta di sconti esclusivi sui nostri prodotti più recenti.
    - **Promozioni Festive e Giveaway**: Partecipa a concorsi e promozioni festive.

    👉 Pronto a esplorare e creare con noi? Clicca su [|link_sf_facebook|] e unisciti subito!

.. _1.1.6_c:

1.1.6 Modulo Matrice LED
==================================

Introduzione
--------------------

In questo progetto, imparerai a conoscere il Modulo Matrice LED. Il modulo utilizza il driver MAX7219 per gestire la matrice LED 8 x 8.

Componenti Necessari
------------------------------

In questo progetto, abbiamo bisogno dei seguenti componenti. 

.. image:: ../img/list_dot.png

È sicuramente conveniente acquistare un kit completo, ecco il link: 

.. list-table::
    :widths: 20 20 20
    :header-rows: 1

    *   - Nome	
        - COMPONENTI NEL KIT
        - LINK
    *   - Raphael Kit
        - 337
        - |link_Raphael_kit|

Puoi anche acquistarli separatamente dai seguenti link.

.. list-table::
    :widths: 30 20
    :header-rows: 1

    *   - INTRODUZIONE AI COMPONENTI
        - LINK PER L'ACQUISTO

    *   - :ref:`cpn_gpio_extension_board`
        - |link_gpio_board_buy|
    *   - :ref:`cpn_breadboard`
        - |link_breadboard_buy|
    *   - :ref:`cpn_wires`
        - |link_wires_buy|
    *   - :ref:`cpn_dot_matrix`
        - |link_led_matrix_buy|

Schema Elettrico
-----------------------

============ ======== ======== ====
T-Board Name physical wiringPi BCM
SPIMOSI      Pin 19   12       MOSI
SPICE0       pin 24   10       CE0
SPISCLK      Pin 23   14       SCLK
============ ======== ======== ====

.. image:: ../img/schematic_dot.png

Procedure Sperimentali
----------------------------

**Passo 1:** Costruisci il circuito. 

.. image:: ../img/1.1.6fritzing.png

**Passo 2:** Accendi il SPI prima di iniziare l'esperimento, fai riferimento a :ref:`spi_configuration` per i dettagli.

**Passo 3:** Vai alla cartella del codice.

.. raw:: html

   <run></run>

.. code-block:: 

    cd ~/raphael-kit/c/1.1.6/

**Passo 4:** Compila il codice.

.. raw:: html

   <run></run>

.. code-block:: 

    make

**Passo 5:**: Esegui il file eseguibile.

.. raw:: html

   <run></run>

.. code-block:: 

    sudo ./1.1.6_LedMatrix

Dopo aver eseguito il codice, la matrice LED mostrerà in sequenza i numeri da 0 a 9 e le lettere da A a Z.

.. note::

    Se non funziona dopo l'esecuzione, o appare un messaggio di errore: \"wiringPi.h: No such file or directory\", fai riferimento a :ref:`install_wiringpi`.

**Codice**

.. code-block:: c

    #include <wiringPi.h>
    #include <wiringPiSPI.h>
    #include <stdio.h>

    #define SPI_CHANNEL    0           // Define SPI channel (0 or 1)
    #define SPI_SPEED      1000000     // SPI speed set to 1 MHz

    // Function to write data to a MAX7219 register
    void max7219_write(unsigned char address, unsigned char data) {
        unsigned char buffer[2];
        buffer[0] = address;   // Register address to write to
        buffer[1] = data;      // Data to write into the register
        wiringPiSPIDataRW(SPI_CHANNEL, buffer, 2);  // Send data via SPI
    }

    // Function to initialize the MAX7219 display module
    void max7219_init() {
        max7219_write(0x09, 0x00); // Decode Mode: No decoding for digits (useful for 7-segment displays)
        max7219_write(0x0A, 0x03); // Intensity: Set brightness level (0x00 to 0x0F)
        max7219_write(0x0B, 0x07); // Scan Limit: Display digits 0-7 (all 8 digits)
        max7219_write(0x0C, 0x01); // Shutdown Register: Normal operation (not in shutdown mode)
        max7219_write(0x0F, 0x00); // Display Test: Normal operation (no test mode)

        // Clear all digits on the display
        for (int i = 1; i <= 8; i++) {
            max7219_write(i, 0x00); // Write 0 to each digit register
        }
    }

    // Function to display a pattern on the MAX7219
    void max7219_display(unsigned char *data) {
        for (int i = 1; i <= 8; i++) {
            max7219_write(i, data[i - 1]); // Write each row of the pattern to the display
        }
    }

    // Function to display a pattern for a specified duration
    void display_pattern(const unsigned char pattern[8], int delay_ms) {
        max7219_display((unsigned char *)pattern); // Display the pattern
        delay(delay_ms);                           // Wait for the specified time in milliseconds
    }

    // Array of patterns to display
    const unsigned char patterns[][8] = {
        // Square pattern
        {
            0b11111111, // Row 1
            0b10000001, // Row 2
            0b10000001, // Row 3
            0b10000001, // Row 4
            0b10000001, // Row 5
            0b10000001, // Row 6
            0b10000001, // Row 7
            0b11111111  // Row 8
        },
        // Heart pattern
        {
            0b01100110, // Row 1
            0b11111111, // Row 2
            0b11111111, // Row 3
            0b11111111, // Row 4
            0b01111110, // Row 5
            0b00111100, // Row 6
            0b00011000, // Row 7
            0b00000000  // Row 8
        },
        // Number 0
        {
            0b00111100, // Row 1
            0b01100110, // Row 2
            0b11000011, // Row 3
            0b11000011, // Row 4
            0b11000011, // Row 5
            0b11000011, // Row 6
            0b01100110, // Row 7
            0b00111100  // Row 8
        },
        // Number 1
        {
            0b00011000, // Row 1
            0b00111000, // Row 2
            0b01111000, // Row 3
            0b00011000, // Row 4
            0b00011000, // Row 5
            0b00011000, // Row 6
            0b01111110, // Row 7
            0b01111110  // Row 8
        },
        // Number 2
        {
            0b01111110, // Row 1
            0b11000011, // Row 2
            0b00000011, // Row 3
            0b00001110, // Row 4
            0b00110000, // Row 5
            0b11000000, // Row 6
            0b11111111, // Row 7
            0b00000000  // Row 8
        },
        // Number 3
        {
            0b01111110, // Row 1
            0b11000011, // Row 2
            0b00000011, // Row 3
            0b00111110, // Row 4
            0b00000011, // Row 5
            0b11000011, // Row 6
            0b01111110, // Row 7
            0b00000000  // Row 8
        },
        // Number 4
        {
            0b00001110, // Row 1
            0b00011110, // Row 2
            0b00110110, // Row 3
            0b01100110, // Row 4
            0b11111111, // Row 5
            0b00000110, // Row 6
            0b00000110, // Row 7
            0b00000000  // Row 8
        },
        // Number 5
        {
            0b11111111, // Row 1
            0b11000000, // Row 2
            0b11111110, // Row 3
            0b00000011, // Row 4
            0b00000011, // Row 5
            0b11000011, // Row 6
            0b01111110, // Row 7
            0b00000000  // Row 8
        },
        // Number 6
        {
            0b00111110, // Row 1
            0b01100000, // Row 2
            0b11000000, // Row 3
            0b11111110, // Row 4
            0b11000011, // Row 5
            0b11000011, // Row 6
            0b01111110, // Row 7
            0b00000000  // Row 8
        },
        // Number 7
        {
            0b11111111, // Row 1
            0b11000011, // Row 2
            0b00000110, // Row 3
            0b00001100, // Row 4
            0b00011000, // Row 5
            0b00110000, // Row 6
            0b00110000, // Row 7
            0b00000000  // Row 8
        },
        // Number 8
        {
            0b01111110, // Row 1
            0b11000011, // Row 2
            0b11000011, // Row 3
            0b01111110, // Row 4
            0b11000011, // Row 5
            0b11000011, // Row 6
            0b01111110, // Row 7
            0b00000000  // Row 8
        },
        // Number 9
        {
            0b01111110, // Row 1
            0b11000011, // Row 2
            0b11000011, // Row 3
            0b01111111, // Row 4
            0b00000011, // Row 5
            0b00000110, // Row 6
            0b01111100, // Row 7
            0b00000000  // Row 8
        },
    };

    int main() {
        if (wiringPiSetup() == -1) {
            printf("Failed to initialize WiringPi\n");
            return 1;
        }

        if (wiringPiSPISetup(SPI_CHANNEL, SPI_SPEED) == -1) {
            printf("Failed to initialize SPI\n");
            return 1;
        }

        max7219_init();  // Initialize the MAX7219 module

        // Display patterns in a loop
        while (1) {
            // Display the square pattern
            display_pattern(patterns[0], 1000);  // Display for 1000 milliseconds

            // Display the heart pattern
            display_pattern(patterns[1], 1000);

            // Display numbers 0-9
            for (int i = 2; i <= 11; i++) {
                display_pattern(patterns[i], 1000);
            }
        }

        return 0;
    }

**Spiegazione del Codice**
#. File di intestazione:

   * ``wiringPi.h``: Fornisce funzioni per il controllo dei GPIO.
   * ``wiringPiSPI.h``: Fornisce funzioni per la comunicazione SPI.
   * ``stdio.h``: Libreria di input/output standard per funzioni come printf.

#. Definizioni:

   * ``SPI_CHANNEL``: Specifica il canale SPI (0 o 1) usato per la comunicazione.
   * ``SPI_SPEED``: Imposta la velocità della comunicazione SPI a 1 MHz.

   .. code-block:: c

        #define SPI_CHANNEL    0           // Definisce il canale SPI (0 o 1)
        #define SPI_SPEED      1000000     // Velocità SPI impostata a 1 MHz

#. Funzione ``max7219_write``: Invia dati a un registro specifico del driver del display MAX7219.

   * ``address``: Indirizzo del registro a cui scrivere.
   * ``data``: Dati da scrivere nel registro.
   * Crea un buffer contenente indirizzo e dati.
   * Utilizza ``wiringPiSPIDataRW`` per inviare il buffer via SPI.

   .. code-block:: c

        void max7219_write(unsigned char address, unsigned char data) {
            unsigned char buffer[2];
            buffer[0] = address;   // Indirizzo del registro a cui scrivere
            buffer[1] = data;      // Dati da scrivere nel registro
            wiringPiSPIDataRW(SPI_CHANNEL, buffer, 2);  // Invia i dati tramite SPI
        }

#. Funzione ``max7219_init``: Inizializza il modulo display MAX7219 con le impostazioni necessarie.

   * Imposta il modo di decodifica su "no decode" poiché stiamo controllando direttamente i LED.
   * Imposta l'intensità (luminosità) a un livello medio (0x03).
   * Imposta il limite di scansione a 7 per abilitare tutte le 8 cifre (righe) del display.
   * Esce dalla modalità di spegnimento per accendere il display.
   * Disattiva la modalità di test del display.
   * Pulisce il display scrivendo 0x00 su tutti i registri delle cifre.

   .. code-block:: c

        void max7219_init() {
            max7219_write(0x09, 0x00); // Modo di decodifica: Nessuna decodifica per le cifre (utile per display a 7 segmenti)
            max7219_write(0x0A, 0x03); // Intensità: Imposta il livello di luminosità (0x00 a 0x0F)
            max7219_write(0x0B, 0x07); // Limite di scansione: Visualizza cifre 0-7 (tutte le 8 cifre)
            max7219_write(0x0C, 0x01); // Registro di spegnimento: Operazione normale (non in modalità spegnimento)
            max7219_write(0x0F, 0x00); // Test del display: Operazione normale (nessuna modalità di test)

            // Pulisce tutte le cifre sul display
            for (int i = 1; i <= 8; i++) {
                max7219_write(i, 0x00); // Scrive 0 su ogni registro delle cifre
            }
        }

#. Funzione ``max7219_display``: Aggiorna il display con un pattern di 8 byte.

   * ``data``: Un array contenente il pattern da visualizzare.
   * Itera attraverso ciascuna delle 8 righe (cifre) e scrive i dati corrispondenti.

   .. code-block:: c

        void max7219_display(unsigned char *data) {
            for (int i = 1; i <= 8; i++) {
                max7219_write(i, data[i - 1]); // Scrive ogni riga del pattern sul display
            }
        }

#. Funzione ``display_pattern``: Visualizza un pattern per un tempo specificato.

   * ``pattern``: Il pattern da visualizzare (array di 8 byte).
   * ``delay_ms``: Durata di visualizzazione del pattern in millisecondi.
   * Chiama ``max7219_display`` per mostrare il pattern.
   * Usa ``delay`` per attendere la durata specificata.

   .. code-block:: c

        void display_pattern(const unsigned char pattern[8], int delay_ms) {
            max7219_display((unsigned char *)pattern); // Visualizza il pattern
            delay(delay_ms);                           // Attende il tempo specificato in millisecondi
        }

#. Array patterns:

   * Contiene pattern predefiniti per il quadrato, cuore e numeri da 0 a 9.
   * Ogni pattern è un array di 8 byte, che rappresenta 8 righe della matrice LED 8x8.
   * Ogni byte usa la notazione binaria dove ogni bit rappresenta un LED (1 per acceso, 0 per spento).
   
   .. code-block:: c

        const unsigned char patterns[][8] = {
            // Pattern del quadrato
            {
                0b11111111, // Riga 1
                0b10000001, // Riga 2
                0b10000001, // Riga 3
                0b10000001, // Riga 4
                0b10000001, // Riga 5
                0b10000001, // Riga 6
                0b10000001, // Riga 7
                0b11111111  // Riga 8
            },
            ...
            // Numero 9
            {
                ...
            },
        };    

#. Funzione main:

   * Inizializza ``WiringPi`` e l'interfaccia ``SPI``.
   
     .. code-block:: c

        if (wiringPiSetup() == -1) {
            printf("Errore nell'inizializzazione di WiringPi\n");
            return 1;
        }

        if (wiringPiSPISetup(SPI_CHANNEL, SPI_SPEED) == -1) {
            printf("Errore nell'inizializzazione di SPI\n");
            return 1;
        }
   
   * Chiama ``max7219_init`` per configurare il modulo MAX7219.
   
     .. code-block:: c

        max7219_init();  // Inizializza il modulo MAX7219
      
   * Entra in un ciclo infinito per visualizzare continuamente i pattern. Mostra ogni pattern per 1 secondo prima di passare al successivo.

     .. code-block:: c

        while (1) {
            // Visualizza il pattern del quadrato
            display_pattern(patterns[0], 1000);  // Visualizza per 1000 millisecondi

            // Visualizza il pattern del cuore
            display_pattern(patterns[1], 1000);

            // Visualizza i numeri da 0 a 9
            for (int i = 2; i <= 11; i++) {
                display_pattern(patterns[i], 1000);
            }
        }

**Comprensione dei pattern**

* Rappresentazione binaria:

  * Ogni pattern è definito utilizzando letterali binari (prefisso 0b).
  * Ogni byte corrisponde a una riga della matrice LED 8x8.
  * Ogni bit all'interno del byte rappresenta una colonna (LED) in quella riga.
  * Il bit più significativo (a sinistra) corrisponde al primo LED a sinistra.

* Creazione di pattern personalizzati:

  * È possibile creare nuovi pattern definendo nuovi array di 8 byte.
  * Ogni pattern può essere aggiunto all'array patterns.
  * Aggiorna il ciclo di visualizzazione nel main per includere i nuovi pattern.


**Regolazioni e personalizzazione**

* Cambiare la luminosità: Modificare il livello di intensità in ``max7219_init``:

   .. code-block:: c

        max7219_write(0x0A, brightness_level); // brightness_level compreso tra 0x00 e 0x0F

* Modificare il tempo di visualizzazione: Cambia il parametro ``delay_ms`` nelle chiamate a ``display_pattern`` per regolare quanto tempo viene visualizzato ogni pattern.


Immagine del Fenomeno
--------------------------

.. image:: ../img/1.1.6led_dot_matrix.JPG