Cinque modi per documentare il proprio modello Simulink

Hai mai aperto uno dei tuoi vecchi modelli Simulink^® o un modello sviluppato da un collega e hai scoperto di non riuscire a capire come funzionava? Una documentazione adeguata può essere molto utile in questa situazione. Può inoltre aumentare la produttività e facilitare la collaborazione tra i team.

Esistono molti modi diversi per documentare un modello Simulink. Questo articolo illustra cinque opzioni, dalle descrizioni di alto livello del modello e dalle brevi note sull’area di disegno, fino alla documentazione più dettagliata del modello e dei blocchi. Per illustrare ciascun metodo, utilizzeremo il modello di veicolo Simulink mostrato nella Figura 1.

Specifica e visualizzazione delle informazioni del modello

La prima operazione da eseguire potrebbe essere fornire una descrizione di alto livello. È possibile visualizzare e modificare la proprietà Description del modello nella vista Property Inspector (Figura 2) oppure facendo clic con il pulsante destro del mouse sull’area di disegno e selezionando Model Properties. Per visualizzare la descrizione del modello, inserire help seguito dal nome del modello al prompt dei comandi di MATLAB^®.

La scheda Info nel Property Inspector riassume anche la cronologia del modello, incluse le modifiche, la versione e la data dell’ultimo salvataggio.

Annotazione del modello

L'aggiunta di annotazioni è un altro modo per migliorare la leggibilità e la chiarezza del progetto. Le annotazioni sono elementi visivi che consentono di aggiungere rapidamente note descrittive e richiami. Utilizza la tavolozza oppure fai doppio clic sull’area di disegno e selezionare Create Annotation per creare qualsiasi combinazione di testo, immagini, equazioni e collegamenti a siti web o a funzioni MATLAB^®. È possibile modificare il tipo e l’aspetto dell’annotazione; ad esempio, è possibile aggiungere equazioni matematiche in LaTeX o MathML.

È possibile aggiungere linee di collegamento tra un'annotazione e un blocco posizionando il cursore sul contorno dell'annotazione e trascinando la linea di collegamento fino al blocco desiderato. È possibile racchiudere aree del modello in riquadri per raggruppare visivamente blocchi correlati e migliorare la leggibilità del modello, utilizzando la tavolozza, oppure trascinando un riquadro attorno all'area di interesse e selezionando Create Area dalla barra delle azioni. È possibile etichettare le aree per indicare la relazione tra i blocchi.

La Figura 3 illustra queste tecniche di annotazione.

Documentazione di blocchi e segnali

Man mano che il progetto procede, probabilmente ci si troverà a lavorare con centinaia o addirittura migliaia di blocchi e segnali, il che renderà il modello ancora più difficile da interpretare.

È possibile migliorare immediatamente la chiarezza del progetto assegnando un nome ai segnali e ai blocchi (Figura 4). Per immettere o modificare il nome di un segnale, fai clic con il pulsante destro del mouse sul segnale e selezionare Properties oppure fai semplicemente doppio clic sul segnale. Per assegnare un nome a un blocco, fai clic sul nome predefinito che si trova immediatamente sotto il blocco.

Scopri di più su come controllare la formattazione, lo stile e l’aspetto di un blocco.

Inserisci le descrizioni di un blocco o di un segnale utilizzando il campo corrispondente nelle proprietà del blocco o del segnale. È quindi possibile visualizzare la descrizione e altre proprietà del blocco sotto l’icona del blocco o passando il mouse sopra il blocco. Nella Figura 4 sono illustrati i blocchi e i segnali annotati. È anche possibile includere la descrizione del blocco come commento nel codice C/C++ generato dal modello.

Se si utilizzano maschere per definire interfacce personalizzate nei blocchi, è comunque possibile fornire una descrizione nel riquadro Documentation in Mask Editor (Figura 5). Il campo Help nello stesso riquadro consente di inserire le informazioni che si desidera vengano visualizzate quando l'utente del blocco mascherato fa clic sul pulsante Help nella finestra di dialogo della maschera.

Aggiunta di note ai livelli del modello

Man mano che i modelli diventano più grandi, si aggiungono ulteriori livelli alla gerarchia, rendendo difficile avere una visione d’insieme. È possibile annotare i singoli livelli di un modello utilizzando i viewmark, le note e il blocco DocBlock.

I viewmark fungono da segnalibri per parti di un modello: è possibile utilizzarli per passare direttamente a parti specifiche del modello e per fornire dettagli o commenti su viste specifiche. Per creare un viewmark, seleziona il pulsante Viewmark This View nella tavolozza, sulla parte del modello che si desidera acquisire. Fai clic sul pulsante Viewmarks per visualizzare i viewmark e aggiungervi descrizioni o commenti (Figura 6).

Per aggiungere note a qualsiasi livello della gerarchia del modello, è necessario innanzitutto creare un file di note. Le note possono includere immagini e collegamenti, nonché URL (Figura 7). Se al modello sono già associate delle note, il riquadro Note visualizza il contenuto del livello corrente durante la navigazione nella gerarchia. 

Il blocco DocBlock offre un altro modo per aggiungere note. Facendo doppio clic su un’istanza del blocco, si crea un file temporaneo contenente il testo associato al blocco, che viene aperto in un editor (Figura 8). Si noti che è possibile utilizzare il testo del commento di un blocco DocBlock come commento globale nel codice generato dal modello.

Documentazione di bus, segnali e parametri

Un modello Simulink spesso si basa su variabili e dati archiviati all'esterno del modello; ad esempio, gli oggetti bus, segnale e parametro sono spesso memorizzati nell'area di lavoro di base. È possibile specificare il ruolo e la funzionalità di un oggetto utilizzando la sua proprietà Description. Questa operazione può essere eseguita in modo programmatico:

>> myParam = Simulink.Parameter; myParam.Description = 'This is the parameter description';

oppure dalla corrispondente finestra di dialogo, accessibile da Model Explorer o facendo doppio clic sull'oggetto (Figura 9).

Se si utilizza Embedded Coder^® per generare il codice dal modello, è possibile aggiungere le descrizioni degli oggetti bus, segnale e parametro come commenti per le dichiarazioni delle variabili nel codice generato (Figura 10).

Scopri di più sull’inserimento delle descrizioni degli oggetti dati Simulink nel codice generato sotto forma di commenti e sull’aggiunta di commenti personalizzati al codice generato.

Prossimi passi

A questo punto, ci si potrebbe chiedere: cosa succede se il mio progetto include più modelli Simulink? Esistono modi per estendere queste tecniche a un intero progetto? I progetti e prodotti come Simulink Report Generator™ e Requirements Toolbox™ forniscono estensioni naturali alle tecniche descritte in questo articolo.

Con Simulink Report Generator è possibile progettare e generare automaticamente report dai modelli in formati comuni come PDF, Microsoft^® Word^®, Microsoft PowerPoint^® e HTML.

Requirements Toolbox consente di creare requisiti in formato rich text e di collegarli a progetti, codice e test. È possibile controllare lo stato di implementazione e verifica dei requisiti, consentendo così di valutare la completezza del progetto.

I progetti aiutano a organizzare il lavoro e a favorire sia un lavoro di squadra efficiente sia la produttività individuale. Puoi gestire tutti i file del progetto da un'unica posizione, visualizzarli e assegnare loro etichette per i flussi di lavoro di revisione tra colleghi, nonché tenere traccia dei progetti e condividerli tramite strumenti esterni di controllo del codice sorgente, come Subversion^® o Git™.