Ripasso di inizio anno – appunti per la classe.

In elettronica e automazione, un errore concettuale spesso costa più tempo di un errore di cablaggio. I diagrammi di flusso aiutano a scomporre il problema in passi elementari, chiarire condizioni e cicli, progettare la logica prima di scrivere il codice. Questo riduce la probabilità di “scrivere e sperare” e mette gli studenti nella condizione di ragionare per stati, condizioni e transizioni: esattamente ciò che serve per gestire sensori (LDR, potenziometri), attuatori (LED, buzzer) e sequenze temporizzate su Arduino.

In classe, partire dal diagramma rende trasparente il legame tra:

• Analisi del problema > (diagramma);
• Progettazione > (pseudocodice);
• Implementazione > (sketch Arduino).

Questa filiera abitua a un metodo di lavoro replicabile, valutabile e condivisibile.

Che cos’è Mermaid

Mermaid è uno strumento open-source che trasforma descrizioni testuali (uno specifico linguaggio “simile al Markdown”) in diagrammi resi automaticamente nel browser. È scritto in JavaScript ed è pensato proprio per “diagrammare come si scrive”: poche righe leggibili, risultato grafico immediato.

Nato come progetto open-source nel 2014 per semplificare la creazione di diagrammi nelle documentazioni tecniche, Mermaid è sviluppato dalla comunità (MIT license) e supporta diversi tipi di diagramma: flowchart, sequence diagram, state diagram, Gantt, ER, class diagram e altri.

Dove funziona (integrazioni utili a scuola)

Mermaid è integrato o supportato nativamente in molte piattaforme usate anche in ambito didattico e progettuale (editor Markdown, wiki, ambienti di sviluppo, appunti digitali). Questo significa che studenti e docenti possono scrivere il diagramma nello stesso file in cui documentano, e vederlo renderizzato senza strumenti pesanti.

Un vantaggio pratico importante: GitHub permette di includere i diagrammi Mermaid direttamente dentro i file Markdown del repository. Per noi significa versionare codice e diagrammi nello stesso posto.

Perché Mermaid è più interessante rispetto ai tool grafici tradizionali

Molti software di disegno (Visio, draw.io, ecc.) producono file binari o complessi da confrontare e unire. Mermaid, invece, produce testo:

• che viene integrato nella versione con Git insieme allo sketch (storia delle modifiche, differenze riga-per-riga, revisioni);
• si integra nei flussi “docs-as-code”, cioè il trattare la versione e gli aggiornamenti della  documentazione di progetto come si fa per il codice (documentazione e progetto nello stesso repository);
• è più veloce da modificare: cambiare una logica significa aggiornare due righe, non ridisegnare frecce e box;
• è adatto all’automazione (generare diagrammi da script o dati).

Inoltre, per gli studenti è inclusivo: chi fatica con strumenti grafici complessi oppure non è particolarmente allenato nello scrivere codice, può concentrarsi sulla logica invece che sulla formattazione.

Tipi di diagrammi utili nel laboratorio di sistemi con Arduino

• Flowchart (diagrammi di flusso): progettano il comportamento dello sketch (lettura sensore > confronto con soglia > azione). Perfetti per attività didattiche laboratoriali, come ad esempio con la gestione di: LDR, potenziometri, PWM su LED/buzzer.
• State diagram (diagrammi di stati): modellano macchine a stati finiti, utili per sistemi reattivi (allarmi luminosi/acustici, sequenze a tempo e molto altro).
• Sequence diagram: descrivono interazioni nel tempo (Utente > Arduino > Sensore >  Attuatore), utili per chiarire responsabilità e tempi (debounce, ritardi, feedback).
• Gantt: pianificano attività di laboratorio (ricerca componenti, prototipazione, test, consegna), favorendo un’organizzazione realistica del progetto.
• ER diagram: modellano dati (es. datalogger con tabelle misure, sensori), utile quando il progetto prevede salvataggi su SD/PC e successiva analisi.

Un flusso di lavoro consigliato (didattico e “versionabile”)

Di seguito trovate il flusso di lavoro che bisognerebbe adottare nello sviluppo di un sistema con Arduino e non solo, ovviamente è suscettibile di modifiche, ma percorrendo i 6 punti molto probabilmente il vostro progetto funzionerà, o come diceva un mio caro amico probabilmente “funzionicchierà” 🙂

1. Definisci il comportamento atteso del sistema (requisiti minimi e soglie).
2. Scrivi il flowchart in Mermaid (anche direttamente nel README del progetto).
3. Aggiungi lo state diagram se il comportamento è meglio descritto per stati.
4. Deriva lo pseudocodice riga-per-riga dal diagramma.
5. Implementa lo sketch Arduino e committa insieme a diagrammi e note.
6. Versiona su GitHub e usa pull request per rivedere sia codice che diagrammi (il diff testuale evidenzia le modifiche di logica).

Esempio pratico

Vediamo ora un esempio minimale pratico che conduce dal diagramma di flusso allo sketch

flowchart TD
A[Start] --> B[Leggi LDR A0]
B --> C{v < soglia?}
C -- Si --> D[LED ON]
C -- No  --> E[LED OFF]
D --> B
E --> B

Lettura della LDR, confronto a soglia, attivazione LED: lo schema diventa facilmente uno sketch con analogRead(), confronto, digitalWrite(). Questo ponte chiaro tra diagramma e codice rende la progettazione più rigorosa e la correzione più rapida.

Strumenti gratuiti per generare il diagramma di flusso

E’ possibile utilizzare diversi software gratuiti o semi-gratuiti che vi consentono di scrivere la descrizione del diagramma e lo traducono immediatamente in un grafico, vi segnalo due software

Mermaid Live Editor

Mermaid Live Editor (browser, nessuna installazione). Accedendo all’applicativo web scriverete sulla sinistra della pagina e se la descrizione del grafico è ben scritta e formatta, vedrete il diagramma a destra della pagina. Sarà possibile esporta in PNG/SVG. Ottimo per le prime esercitazioni.
Per la documentazione ufficiale di Mermaid Live Editor seguite il link.

Drawio

Un altro software credo già molto impiegato nella scuola è draw.io che può essere integrato all’intero degli applicativi Google come estensione oppure potete utilizzare direttamente collegandovi al sito di riferimento drawio.com.
Utilizzare l’applicativo è estremamente semplice e l’importazione di un grafico Mermaid potete farlo seguendo il percorso: Organizza > Inserisci > Mermaid… si aprirà un pannello in cui inserire il testo Mermaid.
L’uso di drawio facilita maggiormente l’editing, in quanto le modifiche avvengono su un editor grafico, pertanto l’orientamento delle frecce di collegamento tra i blocchi, spessori di linee, aggiunte di blocchi ed altro sono probabilmente più semplici, quindi probabilmente potrebbe essere utile insegnare a scrivere il testo Mermaid e poi rielaborarlo in drawio.

Nella prossima lezione vedremo come passare dal diagramma di flusso allo pseudocodice su problemi della vita comune.

Buona progettazione a tutti 🙂