SIMULINK-iFBSpro-Compiler V3.2. zur Integration von Simulink- Modellen in das Funktionsblocksystem ifbspro. Bedienhandbuch

SIMULINK-iFBSpro-Compiler V3.2 zur Integration von Simulink- Modellen in das Funktionsblocksystem ifbspro Bedienhandbuch Bearbeiter: und Dr. J. Alex Dr. T. B. To, ifak, Institut für Automation und Kommunikation e.v. Steinfeldstr. 3 39179 Barleben Dipl.-Ing. J. Nagelmann LTSoft GmbH Brabanterstr. 13 50171 Kerpen März 2000

SIMULINK-iFBSpro-Compiler V3.2 zur Integration von Simulink- Modellen in das Funktionsblocksystem ifbspro Bedienhandbuch 1 Einleitung...3 1.1 Beschreibung:...3 1.2 Eigenschaften:...3 1.3 Voraussetzungen für den Anwender:...3 1.4 Installation...3 2 Modellkonventionen...4 3 Konformitätscheck...5 3.1 Geprüfte Konventionen...5 3.2 Anmerkungen...5 4 Erzeugung eines neuen ifbspro Typen aus Simulink...6 4.1 Aufruf der Funktion simcon...6 4.1 Liste der generierten Dateien:...7 4.2 Anmerkung...7 5 Compilierung des neuen FBS Typen...8 5.1 Dateien kopieren...8 5.2 Typ compilieren...8 6 Verwendung des neuen FBS Typen...9 6.1 Kommandoschnittstelle...9 7 Beispiel...10

1 Einleitung 1.1 Beschreibung: Mit diesem Werkzeug können SIMULINK-Modelle, die in C-Code transformiert wurden, als Funktionsblock in das Funktionsblocksystem ifbspro eingebunden werden. Das SIMULINK- Modell, welches typischerweise als eine Systembeschreibung durch gewöhnliche nichtlineare Differentialgleichungen darstellbar ist, wird zusammen mit einem Integrationsalgorithmus (Runge-Kutta 5. Ordnung) in eine Laufzeitumgebung integriert, die dann eine getaktete Abarbeitung als Funktionsblock ermöglicht. 1.2 Eigenschaften: - Kommandoschnittstelle zum Laden und Speichern des Zustandes, zum Starten und Stoppen der Simulation und zum Setzen von Parametern wie z.b. dem Verhältnis von Real- zu Simulationszeit - Meldungsausgang zur Anzeige von Informationen, Warnungen und Fehlern - Automatische Generierung der Definitionsdatei mit der Deklaration der In- und Outports des Funktionsblocktypen aus dem SIMULINK-Modell - Automatische Generierung des Typen (C-Code) 1.3 Voraussetzungen für den Anwender: - Lizenz MATLAB 5.3 /SIMULINK 3.0 - Lizenz Real-Time Workshop - Lizenz ifbspro 1.4 Installation Auf der Installationsdiskette befindet sich das Verzeichnis /simblocks mit weiteren Unterverzeichnissen. Dieses Verzeichnis muß in das Unterverzeichnis %IFBS_HOME%/server/user kopiert werden. Zur Installlation auf einem Matlab/Simulink Entwicklungsrechner muß ein Suchpfad auf das Verzeichnis mit den m-dateien (%IFBS_HOME%/server/user/simblocks/mfiles) unter Matlab hinzugefügt werden: >>path(path, c:/programme/ifbspro/server/user/simblocks/mfiles ) Das Beispiel steht in Verzeichnis (%IFBS_HOME%/server/user/simblocks/example.

2 Modellkonventionen Um den aus einem Simulink-Modell erzeugten C-Code in das ifbspro-system integrieren zu können, sind die folgenden Modellkonventionen einzuhalten: Der Simulink-Modell des zu erstellenden Funktionsblocks muß sich mit dem RealTimeWorkshop (RTW) in C-Code transformieren lassen. Die entsprechenden Konventionen sind einzuhalten. Das bedeutet insbesondere, daß keine Modellblöcke als m-files definiert sein dürfen (m-s-function) und das für alle C-codierten Blöcke (mex-s- Function) die Quellen vorhanden sein müssen. Das in einen Funktionsblock zu überführende Simulink-Modell muß ein Subsystem darstellen. D.h. es sollte Inport- und muß Outport-Blöcke enthalten. Das betreffende System muß als Subsystem innerhalb des Modells auf oberster Modell-Ebene definiert sein. Für die In- und Outports des in einen Funktionsblock zu überführenden Subsystems sind nur skalare Signale erlaubt. Das heißt, die Eigenschaft Port Width der Ports muß auf den Wert 1 eingestellt werden. Aus den Namen und Kommentaren der In- und Outports werden automatisch die Namen der In- und Outports des FBS Typen generiert. Es ist daher auf eine sorgfältige Wahl der Namen und Kommentare zu achten (Vermeidung von Sonder und Trennzeichen, wie z.b. /_ usw.). Aus dem Parameter AttributesFormatString der In- und Outports wird die Beschreibung des Ports in der OVM-Datei generiert und die Einheit des Ports wird aus dem Parameter Description des Simulink In- oder Outport Blockes entnommen. Aus dem Parameter AttributesFormatString des Blocks wird die Beschreibung des Blocks für die Library-Info generiert. Es dürfen keine Blöcke, die Signale von oder auf die Festplatte transferieren (wie ToFile und FromFile) oder Daten von oder auf den Matlab Workspace schreiben (wie ToWorkspace, FromWorkspace) in dem, in einen Funktionsblock zu überführenden Subsystem, verwendet werden. Die maximale Länge des Namen des Subsystems darf nicht 15 Zeichen überschreiten. Die aktuelle Version des RTW erlaubt nur die Verwendung von Integratoren mit fester Schrittweite um determinierte Laufzeiten zu garantieren. Für die Überführung ins FBS muß der Integrator ODE5, Fixed-Step-Size eingestellt werden. Das Modell muß mindestens einen kontinuierlichen Zustand besitzen, damit der vom RTW erzeugte Code fehlerfrei läuft.

3 Konformitätscheck 3.1 Geprüfte Konventionen Vor der Compilierung wird das Simulink-Modell auf Einhaltung der unter 2 beschriebenen Konventionen getestet: Existenz des Modells bzw. Des Modells mit dem angegebenen Subsystem im MATLAB- Suchpfad. Ein zu transformierendes Subsystem kann sowohl ein normales Subsystem als auch ein Link zu einer Block-Bibliothek darstellen. Im letzten Fall wird die Existenz der Block-Bibliothek im MATLAB-Suchpfad ebenfalls geprüft. Überprüfung aller In- und Outports auf skalare Signale Länge des Subsystem-Namen: Hat ein System den zu langen Namen, generiert der Filter eine Warnung. Integrator-Einstellung: ODE5, Fixed-Step-Size; Es muß betont werden, daß die Wahl der Tastzeit sorgfältig erfolgen muß. Wegen der Genauigkeit und der Stabilität des Integrations-Verfahrens wird empfohlen, für die Tastzeit einen ausreichend kleinen Wert einzustellen. Hinweise hierfür können durch Simulation mit dem ODE45 mit variabler Schrittweite unter Simulink gewonnen werden. Bei der Compilierung wird automatisch eine Warnung über die aktuelle Tastzeit-Einstellung generiert. 3.2 Anmerkungen Zur Prüfung der In- und Outport Dimensionen wird das Simulinkmodell des zu erstellenden Funktionsblocks unter Matlab ausgeführt. Diese Aktion läßt sich allerdings nur dann ausführen, wenn das Modell nicht zufällig die selbe Bezeichnung wie eine buildin Funktion von Matlab, eine im aktuellen Verzeichnis befindliche Funktion oder eine im Workspace vorhandene Variable besitzt. Eine entsprechende Fehlermeldung wird ausgegeben. Werden innerhalb des Modells die Ausdrücke inf oder -inf verwendet, wie z.b. im Block Saturation, werden diese Grenzen in dem erzeugten Code durch 1e38 bzw. -1e38 ersetzt.

4 Erzeugung eines neuen ifbspro Typen aus Simulink 4.1 Aufruf der Funktion simcon Im Matlab Command Window muß zuerst das benötigte Modell geöffnet werden. Das Modell muß das zur Integration in das FBS vorgesehene Subsystem enthalten. Anschließend wird die Generierung des FBS Typen durch die Matlab Funktion oder oder oder oder simcom(name) simcom(name,version) simcom(name,version,newname) simcom(name,version,newname,iter) simcom(name,version,newname,iter,libname) realisiert. In den vier unterschiedlichen Varianten sind folgende Parameter anzugeben 1. simcom(name) Das Variable Name ist der Namen des zu compilierenden Blocks, z.b. simcom( Model_Name/Subsystem_Name ) Für den zu erstellenden Funktionsblocktypen wird lediglich der Name des Subsystems benutzt. Ist das Variable Name beispielsweise Name = Test/simsubblock, erhält der Anwender nach der Compilierung die folgenden Dateien: /source/fbt_simblocks_simsubblock.h /include/fbt_simblocks_simsubblock.ovm /source/simsubblock.h /source/simsubblock.c /source/simsubblock_exports.h /source/simsubblock.reg /source/simsubblock.prm. 2. simcom(name,version) Zusätzlich wird in der Variablen Version ein String für die Versions-Nummer, z.b. Version = 1.2 angegeben. Dieser String wird in Kommentaren zum Typen verwendet. 3. simcom(name,version,newname) Bei dieser Variante erhält der FBS Tyo einen zum Simulink Modell abweichenden Namen. Die Variable NewName gibt den Namen des FBS-Typen an. Nach dem Aufruf des Filters erhält der Anwender die folgenden Dateien /source/fbt_simblocks_ NewName.h /include/fbt_simblocks_ NewName.ovm /source/newname.h /source/newname.c /source/newname _exports.h /source/newname.reg

/source/newname.prm. 4. simcom(name,version,newname,iter) In dieser Variante wird in der Variablen Iter die Anzahl von Simulationschritten je Aufruf im FBS eingestellt. Wird diese Variable nicht angegeben, wird als Voreinstellung: Iter = 1; verwendet. Für eine Realzeit-Simulation muß das Produkt Iter*FixedStepsize gleich der Tastzeit des FBS Blocks sein. Die Einstellung dieser Variablen beeinflußt maßgeblich die Rechenzeit des FBS Blocks. Es ist darauf zu achten, daß die Rechenzeit des Blocks deutlich kleiner bleibt als die Tastzeit des Blocks. Der Eingangsparameter Iter gibt eine Grundeinstellung vor. Zur Laufzeit kann dieser Wert mit dem entsprechenden Kommando (SI) neu gesetzt werden. 5. simcom(name,version,newname,iter,libname) Bei dieser Aufrufvariante wird abweichend zum Namen der Standardbibliothek simblocks der als Zeichenkette angegebene Name verwendet. Sind alle Voraussetzungen (Konventionen) erfüllt, generiert die Funktion simcon alle notwendigen Dateien, die zur Erstellung des FBS Typen benötigt werden. 4.1 Liste der generierten Dateien: Die folgenden Dateien werden im Lauf der Compilierung automatisch erzeugt: Im Verzeichnis /source: fbt_libname_name.c - Typ-Quelle name.c - Modell-Quelle name.h - Modell-Header name _exports.h - Modell-Header Include name.prm - Modell-Header Include name.reg - Modell-Header Include Im Verzeichnis /include: fbt_ libname_name.ovm - Typ-Definition wobei name der Name des FBS-Block Typen und libname der Name der Typbibliothek (Standard: simblocks) ist. Die Dateien aus denverzeichnissen /source und /include müssen in die entsprechenden Unterverzeichnisse der zu compilierenden Library verschoben werden. 4.2 Anmerkung In einigen Fällen sind die unter Windows generierten Dateien (C-Codes) nicht problemlos unter Unix/Linux-Systemen zu übersetzen. Zur Vermeidung dieses Problems ist mit dem Programm dos2unix eine Umwandlung dieser C-Code in für Unix/Linux geeignete ASCII- Dateien notwendig: dos2unix *

5 Compilierung des neuen FBS Typen 5.1 Dateien kopieren Die Dateien aus denverzeichnissen /source und /include müssen in die entsprechenden Unterverzeichnisse der zu compilierenden Library verschoben werden. 5.2 Typ compilieren Das Makefile der Library (z.b. (%IFBS_HOME%/server/user/simblocks/build/generic.mk) muß editiert werden, um die Erstellung des neuen Typen zu veranlassen. ############################################################################### # Anwender-Bibliothek # # ------------------- # # (Bibliothek-Name angeben, z.b. sinblocks) # # (Klassen-Namen angeben, z.b. pt1 pt2) # # (evt. zusätzliche Library und Include-Pfad angeben) # ############################################################################### # Library Name # (simblocks) LIBRARY = simblocks # Definierte Klassen # (pt1 pt2) USERCLASSES = exfb # Zusätzliche Includes und Bibliotheken PLUS_LIB =../../libs/simulinklib/lib/simulinklib$(lib) PLUS_INCLUDE =../../libs/simulinklib/include ############################################################################### # (ENDE) # ############################################################################## Unter USERCLASSES muß der Name des neuen Typen mit Leerzeichen getrennt eingefügt werden. In der OVM Datei der Library %IFBS_HOME%/server/user/simblocks/include/simblocks.ovm muß die OVM Datei des neuen Typen include -ed werden: /* * simblocks.ovm */ #include "fb.ovm" LIBRARY simblocks VERSION = "1.0"; AUTHOR = "Joachim Nagelmann, Jens Alex, mailto: nagelmann@ltsoft.de"; COPYRIGHT = " 2000, LTSoft GmbH, ifak e.v."; COMMENT = "Simulink Library"; /* Fuer jeden Typ ein Include: */ #include "fbt_simblocks_exfb.ovm" END_LIBRARY; Zur Erstellung der neuen Library müssen im entsprechenden Verzeichnis z.b. %IFBS_HOME%/server/user/simblocks/build/nt make Funktioen aufgerufen werden: make clean make make install Der letzte Aufruf kopiert die neue Library in das Library-Verzeichnis von ifbspro. Die Library kann nun mit dem ifbspro Engineering-Werkzeug geladen werden.

6 Verwendung des neuen FBS Typen 6.1 Kommandoschnittstelle Der generierte FBS Typ besitzt einige Besonderheiten. Zunächst besitzt der Block immer einen automatisch generierten Zeichenketten-Eingang mit dem Namen Command, der zur Übermittlung von Kommandos an den Funktionsblock dient. Als Reaktion auf dieses Kommando wird in dem ebenfalls automatisch angelegten Ausgangs-Port CommandMsg eine Information über den Erfolg des gewünschten Kommandos geliefert. Es werden die folgenden Kommandos realisiert: Kommando Parameter Antwort Beschreibung? Liste Hilfe, Liste alle möglichen Kommandos St Status Zeit Status Information Abfragen, in der Variablen Status wird eine zweistellige Error Zahl zurückgegeben, die Einer-Stell signalisiert ob das Modell initialisiert ist, die Zehner-Stelle gibt an ob das Modell läuft. S Error Simulation stoppen Fehler: F: Nicht Initialisiert F: Läuft nicht LS [Datei-Name] Error Zustand laden, ohne Angabe eines Dateinames wird der im Hiddenport States gespeichert Zustand verwendet Fehler: F: beim Datei oeffnen F: Kein Zustand WS Datei-Name Error Zustand schreiben SI I ter dt Fehler: F: beim Datei oeffnen F: Nicht Initialisiert Error Integrator setzen, I ter Anzahl der Simulationsschritte pro Abtastung des Blocks, dt Schrittweite des Integrators Fehler: F: I, dt erwarted: Parsen der Parameter fehlgeschlagen F: dt<=0: Schrittweite muß ein Wert größer Null sein F: I<=0 F: Nicht Initialisiert F: Läuft bereits Zusätzlich existieren die zwei Eingangsports StartupCMD und ShutdownCMD in die eine Liste von Kommandos, die automatisch beim Laden bzw. Beenden der Blockinstanz ausgeführt werden sollen. Die Kommandos sind mit einem Semikolon zu trennen.

7 Beispiel Im Verzeichnis simblocks/example befindet sich ein einfaches Beispiel eines in Simulink erstellten Funktionsblock. Das Modell heißt example.mdl. In diesem Beispiel existiert ein Subsystem mit dem Namen exfb, welches als Funktionsblock in FBS realisiert werden soll. Step 1 Constant u1 u2 y exfb Ein PT2 - Block Clock Scope t To Workspace Abbildung 1: Simulink-Modell example.mdl Der Funktionsblock besteht aus einem Summationsblock und einer Übertragungsfunktion. 1 u1 Eingang 1 2 Sum 1 18s 2+9s+1 Transferfcn 1 y Ausgang 1 u2 Eingang 2 Abbildung 2: Block example/exfb Die In- und Outports dieses Blocks bilden für den zu erstellenden Funktionsblock die Ei- und Ausgänge. Hierbei wird der Name der Ports ins FBS übernommen. Bei der Generierung der FBS-OVM Datei werden die Beschreibungen und Einheiten der In- und Outports ebenfalls aus dem Simulink Modell ausgelesen. Hierzu werden bestimmte Eigenschaften der In- Outport Blöcke ausgelesen, die über ein mit der rechten Maustaste/Properties zu öffnendes Dialogfenster eingeben werden können: Abbildung 3: Properties Dialog für Inport u2 In diesem Properties-Dialog wird der Eintrag Description zur Erzeugung der Einheit und der Eintrag Attributes format string zur Erzeugung des Kommentares verwendet.

Zur Erzeugung einer Blockbeschreibung in der Library-Info-Anzeige kann der Eintrag Attributes format string des zu kompilierenden Blocks verwendet werden. Vor der Erstellung des FBS Blocktypen müssen die Integratoreinstellungen modifiziert werden. Abbildung 4: Simulations-Parameter Als Integrator muß Fixed-step, ode5 gewählt werden. Die feste Schrittweite dieses Integrators muß sorgfältig gewählt werden. Durch Testläufe ist sicherzustellen, daß mit dieser Schrittweite unter allen Umständen (Anregungssituation/ Arbeitspunkt) eine stabile Integration möglich ist. Bei zu großer Schrittweite ist es prinzipiell möglich, das es zu numerischen Instabilitäten kommt, die zu einem Absturz des Typen führen können! Diese Gefahr besteht im übrigen auch dann, wenn unter bestimmten Umständen illegale arithmetische Operationen ausgeführt werden, wie z.b. Division durch Null oder die Berechnung einer Potenz mit Überschreitung des darstellbaren Zahlenbereiches. Zur Sicherstellung einer stabilen Abarbeitung sind daher im Modell entsprechende Vorkehrungen zu treffen. So sollte jeder Divisor mit einem Saturation-Block nach unten auf einen größeren Wert als Null begrenzt werden. Durch Aufruf des Simulink-iFBSpro-Compiler werden die zur Typgenerierung erforderlichen Quellen generiert. Bei diesem Aufruf ist als wichtigster Parameter der Name des zu transformierenden Blocks anzugeben: simcom( example/exfb ) Mit drei weiteren optionalen Parametern können weitere Eigenschaften beeinflußt werden. Mit dem Aufruf simcom( example/exfb, 1.1, exfb,10) beispielsweise, wird die Versionsnummer des neuen Typen auf 1.1 gesetzt, als Typname wird die Blockbezeichnung exfb im FBS verwendet und die Variable Iter des Blocks wird auf 10 gesetzt. Die Variable Iter definiert, um wieviel Schritte das Modell je Abtastung im FBS weitergerechnet werden soll. Mit den diesen Einstellungen würde die folgende OVM-Datei erstellt werden:

// fbt_simblocks_exfb.ovm Typdeklaration für ifbspro-type: "exfb" // fbt_simblocks_exfb.ovm Typdeklaration für ifbspro-type: "exfb" // (c) ifak, LTSoft // Automatisch generiert am 23-Mar-2000, um 13:45:38 // Integratorschrittweite dt=0.1, Anzahl Iterationen pro Abtastung=1 // //Version: 1.0 CLASS exfb : CLASS fb/functionblock IS_INSTANTIABLE; FLAGS = "i"; COMMENT = "Ein PT2 - Block"; VARIABLES Command : STRING FLAGS = "i" UNIT = "-" COMMENT = "Kommando-Schnittstelle"; StartupCMD : STRING FLAGS = "i" UNIT = "-" COMMENT = "Startup-Kommandos"; ShutdownCMD : STRING FLAGS = "i" UNIT = "-" COMMENT = "Shutdown-Kommandos"; OldCMD : STRING FLAGS = "n" UNIT = "-" COMMENT = "Altes Kommando"; InitFlag : INT FLAGS = "n" UNIT = "bool" COMMENT = "Block initialisiert"; RunFlag : INT FLAGS = "n" UNIT = "bool" COMMENT = "Block run"; Iteration : INT FLAGS = "n" UNIT = "-" COMMENT = "Anzahl Schritte pro Aufruf"; Stepsize : DOUBLE FLAGS = "n" UNIT = "-" COMMENT = "Integrations-Schrittweite"; States[2] : DOUBLE FLAGS = "n" UNIT = "-" COMMENT = "Zustands-Vektor"; Simstruct : INT FLAGS = "n" UNIT = "-" COMMENT = "Simstruct-Zeiger"; CommandMsg : STRING FLAGS = "o" UNIT = "-" COMMENT = "Kommandoantwort"; y : DOUBLE FLAGS = "o" UNIT = "V" COMMENT = "Ausgang"; u1 : DOUBLE FLAGS = "i" UNIT = "V" COMMENT = "Eingang 1"; u2 : DOUBLE FLAGS = "i" UNIT = "mv" COMMENT = "Eingang 2"; END_VARIABLES; OPERATIONS startup : C_FUNCTION <OV_FNC_STARTUP>; shutdown : C_FUNCTION <OV_FNC_SHUTDOWN>; typemethod : C_FUNCTION <FB_FNC_TYPEMETHOD>; END_OPERATIONS; END_CLASS;