Technische Artikel

MathWorks Insights

Fünf Möglichkeiten zur Dokumentation Ihres Simulink-Modells


Autor:

  • Emmanouil Tzorakoleftherakis, MathWorks

6 Minuten Lesezeit

Haben Sie schon einmal eines Ihrer älteren Simulink®-Modelle oder ein Modell eines Kollegen geöffnet und konnten nicht nachvollziehen, wie es funktioniert? Eine gute Dokumentation kann hier sehr hilfreich sein. Sie kann außerdem Ihre Produktivität steigern und die teamübergreifende Zusammenarbeit erleichtern.

Es gibt viele verschiedene Möglichkeiten, ein Simulink-Modell zu dokumentieren. Dieser Artikel führt Sie durch fünf Optionen – von allgemeinen Modellbeschreibungen und kurzen Notizen auf der Arbeitsfläche bis hin zu detaillierteren Modell- und Blockdokumentationen. Zur Veranschaulichung der einzelnen Methoden verwenden wir das in Abbildung 1 dargestellte Simulink-Fahrzeugmodell.

Abbildung 1: Ein vollständiges Fahrzeugmodell in Simulink.

Abbildung 1: Ein vollständiges Fahrzeugmodell in Simulink. 

Modellinformationen festlegen und anzeigen

Zunächst bietet es sich an, eine allgemeine Beschreibung hinzuzufügen. Sie können die Eigenschaft „Description“ des Modells im Property Inspector (Abbildung 2) anzeigen und bearbeiten oder mit der rechten Maustaste auf die Arbeitsfläche klicken und Model Properties auswählen. Um die Modellbeschreibung anzuzeigen, geben Sie in der MATLAB®-Eingabeaufforderung help gefolgt vom Modellnamen ein.

Abbildung 2: Property Inspector mit der Modellbeschreibung.

Abbildung 2: Property Inspector mit der Modellbeschreibung.

Die Registerkarte „Info“ im Property Inspector fasst außerdem die Modellhistorie zusammen, einschließlich Änderungen, Version und Datum der letzten Speicherung.

Modell annotieren

Das Hinzufügen von Annotationen ist eine weitere Möglichkeit, die Lesbarkeit und Verständlichkeit Ihres Designs zu verbessern. Annotationen sind visuelle Elemente, mit denen Sie schnell beschreibende Notizen und Erläuterungen hinzufügen können. Wählen Sie in der Palette oder nach einem Doppelklick auf die Arbeitsfläche Create Annotation aus, um beliebige Kombinationen aus Text, Bildern, Gleichungen und Links zu Websites oder zu MATLAB®-Funktionen zu erstellen. Sie können Art und Aussehen Ihrer Annotation ändern und beispielsweise mathematische Gleichungen in LaTeX oder MathML einfügen.

Sie können Verbindungslinien zwischen einer Annotation und einem Block hinzufügen, indem Sie den Cursor über den Umriss der Annotation bewegen und die Verbindungslinie zum gewünschten Block ziehen. Sie können Bereiche Ihres Modells einrahmen, um zusammengehörige Blöcke visuell zu gruppieren und die Lesbarkeit des Modells zu verbessern – entweder über die Palette oder indem Sie einen Rahmen um den gewünschten Bereich ziehen und in der Aktionsleiste Create Area auswählen. Bereiche können beschriftet werden, um die Beziehung zwischen Blöcken anzuzeigen.

Abbildung 3 veranschaulicht diese Annotationstechniken.

Abbildung 3: Modell mit hinzugefügten Annotationen.

Abbildung 3: Modell mit hinzugefügten Annotationen. 

Blöcke und Signale dokumentieren

Im Laufe der Entwicklung Ihres Modells werden Sie wahrscheinlich mit Hunderten oder sogar Tausenden von Blöcken und Signalen arbeiten, was das Lesen des Modells noch schwieriger macht.

Die Übersichtlichkeit des Designs lässt sich sofort verbessern, indem Signale und Blöcke benannt werden (Abbildung 4). Um einen Signalnamen einzugeben oder zu bearbeiten, klicken Sie mit der rechten Maustaste auf das Signal und wählen Properties aus, oder doppelklicken Sie einfach auf das Signal. Um einen Block zu benennen, klicken Sie auf den Standardnamen direkt unterhalb des Blocks.

Erfahren Sie mehr über die Steuerung der Formatierung, des Stils und des Erscheinungsbilds eines Blocks.

Abbildung 4: Annotierte Blöcke und Signale.

Abbildung 4: Annotierte Blöcke und Signale.

Geben Sie Beschreibungen für einen Block oder ein Signal im jeweiligen Feld in den Block- oder Signaleigenschaften ein. Anschließend können Sie die Beschreibung und weitere Blockeigenschaften unterhalb des Blocksymbols oder beim Überfahren des Blocks mit der Maus anzeigen. Die annotierten Blöcke und Signale sind in Abbildung 4 dargestellt. Sie können die Blockbeschreibung auch als Kommentar in den aus Ihrem Modell generierten C/C++-Code aufnehmen.

Wenn Sie Masken verwenden, um benutzerdefinierte Schnittstellen in Ihren Blöcken zu definieren, können Sie trotzdem im Bereich „Documentation“ des Mask Editor eine Beschreibung angeben (Abbildung 5). Im Feld „Help“ desselben Bereichs können Sie Informationen eingeben, die angezeigt werden sollen, wenn der Benutzer des maskierten Blocks im Maskendialogfeld auf die Schaltfläche „Help“ klickt.

Abbildung 5: Dokumentation für maskierte Blöcke.

Abbildung 5: Dokumentation für maskierte Blöcke.

Notizen zu Modellebenen hinzufügen

Wenn Modelle größer werden, kommen immer mehr Ebenen zur Hierarchie hinzu, sodass es schwierig wird, das Gesamtbild zu erfassen. Sie können einzelne Ebenen eines Modells mithilfe von Viewmarks, Notizen und dem DocBlock annotieren.

Viewmarks markieren Teile eines Modells – Sie können sie verwenden, um direkt zu bestimmten Teilen Ihres Modells zu navigieren und Details oder Kommentare zu bestimmten Ansichten bereitzustellen. Um eine Viewmark zu erstellen, klicken Sie in der Palette auf Viewmark This View, während der gewünschte Modellteil angezeigt wird. Klicken Sie auf die Schaltfläche Viewmarks, um Ihre Viewmarks anzuzeigen und mit Beschreibungen oder Kommentaren zu versehen (Abbildung 6).

Abbildung 6: Viewmarks mit Details zu bestimmten Modellansichten.

Abbildung 6: Viewmarks mit Details zu bestimmten Modellansichten. 

Um einer beliebigen Ebene in Ihrer Modellhierarchie Notizen hinzuzufügen, müssen Sie zuerst eine Notizendatei erstellen. Notizen können Bilder und Links sowie URLs enthalten (Abbildung 7). Wenn dem Modell bereits Notizen zugeordnet sind, zeigt der Notizenbereich beim Navigieren durch die Hierarchie den Inhalt der aktuellen Ebene an. 

Abbildung 7: Notizen zu einer bestimmten Ebene der Modellhierarchie.

Abbildung 7: Notizen zu einer bestimmten Ebene der Modellhierarchie.

Mit dem DocBlock haben Sie eine weitere Möglichkeit, Notizen hinzuzufügen. Durch Doppelklicken auf eine Instanz des Blocks wird eine temporäre Datei erstellt, die den zu diesem Block gehörenden Text enthält, und die Datei wird in einem Editor geöffnet (Abbildung 8). Beachten Sie, dass Sie den Kommentartext eines DocBlock als globalen Kommentar verwenden können, der im aus Ihrem Modell generierten Code erscheint.

Abbildung 8: DocBlock mit hinzugefügten Kommentaren.

Abbildung 8: DocBlock mit hinzugefügten Kommentaren.

Busse, Signale und Parameter dokumentieren

Ein Simulink-Modell greift häufig auf Variablen und Daten zurück, die außerhalb des Modells gespeichert sind – beispielsweise werden Bus-, Signal- und Parameterobjekte oft im Basis-Workspace gespeichert. Sie können die Rolle und Funktionalität eines Objekts in seiner Eigenschaft „Description“ beschreiben. Dies kann entweder programmatisch erfolgen:

>> myParam = Simulink.Parameter; myParam.Description = 'Dies ist die Parameterbeschreibung';

oder über das entsprechende Dialogfeld, das Sie im Model Explorer oder per Doppelklick auf das Objekt öffnen (Abbildung 9).

Abbildung 9: Beschreibungsfelder für Bus-, Signal- und Parameterobjekte.

Abbildung 9: Beschreibungsfelder für Bus-, Signal- und Parameterobjekte. 

Wenn Sie Embedded Coder® verwenden, um Code aus Ihrem Modell zu generieren, können Sie die Beschreibungen der Bus-, Signal- und Parameterobjekte als Kommentare zu den Variablendeklarationen im generierten Code hinzufügen (Abbildung 10).

Abbildung 10: Die Beschreibungsfelder für Bus-, Parameter- und Signalobjekte werden als Kommentare im generierten Code verwendet.

Abbildung 10: Die Beschreibungsfelder für Bus-, Parameter- und Signalobjekte werden als Kommentare im generierten Code verwendet.

Erfahren Sie mehr über das Einfügen von Beschreibungen von Simulink-Datenobjekten als Kommentare in den generierten Code und das Hinzufügen benutzerdefinierter Kommentare zum generierten Code.

Nächste Schritte

An dieser Stelle fragen Sie sich vielleicht: Was ist, wenn mein Projekt mehrere Simulink-Modelle enthält? Gibt es Möglichkeiten, das Ganze auf ein komplettes Projekt auszuweiten? MATLAB-Projekte und Produkte wie Simulink Report Generator™ und Requirements Toolbox™ bieten naheliegende Erweiterungen der in diesem Artikel besprochenen Techniken.

Mit Simulink Report Generator können Sie Berichte aus Ihren Modellen gestalten und automatisch in gängigen Formaten wie PDF, Microsoft® Word®, Microsoft PowerPoint® und HTML generieren.

Mit Requirements Toolbox können Sie Rich-Text-Anforderungen erstellen und diese mit Entwürfen, Code und Tests verknüpfen. Sie können den Implementierungs- und Verifizierungsstatus Ihrer Anforderungen überprüfen und so die Vollständigkeit Ihres Projekts beurteilen.

Mit MATLAB-Projekten können Sie Ihre Arbeit organisieren und sowohl eine effiziente Teamarbeit als auch die individuelle Produktivität fördern. Sie können alle Ihre Projektdateien an einem Ort verwalten, Dateien für Peer-Review-Workflows anzeigen und kennzeichnen sowie Ihre Projekte mit externen Versionskontrollsystemen wie Subversion® oder Git™ nachverfolgen und teilen.

Veröffentlicht 2018


Eingesetzte Produkte: Embedded Coder, Stateflow

Über den Autor

Emmanouil Tzorakoleftherakis

Emmanouil Tzorakoleftherakis ist Principal Product Manager bei MathWorks mit Schwerpunkt auf Reinforcement Learning und Steuerungssystemen. Emmanouil besitzt einen Master- und einen Doktortitel in Maschinenbau von der Northwestern University mit Spezialisierung auf Steuerungssysteme und Robotik sowie einen Bachelor-Abschluss in Elektrotechnik und Informatik von der University of Patras in Griechenland.

Mehr entdecken