Diplomarbeit B37.10 AMX Netlinx SourceCode Inspector Projektbezeichnung SWS Diplomarbeit # B37.10 NDS Klasse B37 AMX Netlinx SourceCode Inspector Diplomand Thomas Jud Zelgweg 3 3110 Muensingen thomas.jud@datacomm.ch Mobile +41 79 422 75 66 Experte Gilles Maitre Zielweg 9 3014 Bern gilles.maitre@bluewin.ch Priv. +41 31 333 47 81 Betreuer Max Kleiner Kasernenstrasse 19 3003 Bern max.kleiner@armasuisse.ch Gesch. +41 31 322 00 55 Mobile +41 79 366 30 08 Erstellt am 18.02.2007 Zuletzt geändert am 16.03.2007 Bearbeitungszustand Dokumentablage V-Modell-XT Version x In Bearbeitung Vorgelegt Fertig gestellt..\diplomsws\organisation_original\.doc Version 1.2bw Abstract: Kunden sowie Programmierer, die mit dem AMX System und dessen Netlinx Sprache eine Multimedia Anlage betreiben oder programmieren, verlangen nach einer erweiterten Dokumentation. Diese soll mit einem Dokumentationstool erstellt werden. Die Dokumentation soll einerseits den Source Code und seine verwendeten Schnittstellen beschreiben, sowie andererseits nach bestimmten nichtfunktionalen Fehlern suchen. Dies sichert einen professionellen Standard der Programmierung und garantiert eine höhere Robustheit sowie Flexibilität an den Code..doc 19.03.2007 Seite 1 von 15
Änderungsverzeichnis Änderung Geänderte Kapitel Beschreibung der Änderung Autor Zustand Nr. Datum Version 1 19. Feb. 07 0.1 Alle Initiale Produkterstellung Th. Jud Bearbeitung 2 10. Mrz. 2007 0.2 -Einleitung -Funktionale Anforderungen -Audits / Metriken -generierte Gem. Anmerkungen Version 0.1 Th. Jud Bearbeitung Dokumantation -Lizenzbestimmungen -Glossar 3 16. Mrz. 2007 0.3 -Funktionale Anforderungen (EBNF, Parser ) Gem. Anmerkungen Version 0.2 Th. Jud Bearbeitung Glossar 4 19. Mrz. 2007 1.0 Finales Pfilchtenheft Version 1.0 Th. Jud Fertig gestellt Prüfverzeichnis Datum Geprüfte Version Anmerkung Prüfer Neuer Produktzustand 09. Mrz. 2007 0.1 Gesamtkontrolle Audits und Metrics Details Max Kleiner 0.2 Lizenz 13. Mrz. 2007 0.2 Gesamtkontrolle Glossar nach A-Z ordnen Kapitel EBNF durch visuelles Beispiel ersetzen. Dies wird neu unter Gilles Maitre 0.3 Unterkapitel generierte Dokumentation angelegt 16. Mrz. 2007 1.0 Freigegeben Gilles Maitre 1.0.doc 19.03.2007 Seite 2 von 15
Inhalt: 1 Einleitung 4 1.1 Sinn der Gesamtspezifikation () 4 1.2 Benutzerkreis / Einsatzgebiet 4 1.3 Vorgesehene Erweiterungen 4 2 Ausgangssituation und Zielsetzung 4 2.1 Ist Zustand 4 2.2 Programmierung heute 4 2.3 Zielsetzung 4 3 Funktionale Anforderungen 5 3.1 Voraussetzungen 5 3.2 Use Case Overview 5 3.3 Benutzerinterface (GUI) 5 3.4 Device Liste 6 3.5 Parser / Translator 6 3.6 Audits und Metriken 7 3.7 Generierte Dokumentation 7 4 Nicht funktionale Anforderungen 9 4.1 Q-Anforderungen (nach FURBS* Schema) 9 4.2 Plattform 9 5 Gesamtsystemarchitektur 10 6 Lieferumfang 10 6.1 Software 10 6.2 Dokumentation 10 7 Lizenz 10 8 Abkürzungsverzeichnis / Glossar 10 9 Literaturverzeichnis 11 10 Abbildungsverzeichnis 11 11 Anhang 12 11.1 Treenodes definition 12 11.2 Projektplan 13 11.3 V Modell Chart 15.doc 19.03.2007 Seite 3 von 15
1 Einleitung 1.1 Sinn der Gesamtspezifikation () Dieses Dokument beschreibt die Anforderungen an die Diplomarbeit B37.10 AMX Netlinx SourceCode Inspector an der Software Schule Schweiz (SWS). Der Initiant und realisierende Person ist Thomas Jud. 1.2 Benutzerkreis / Einsatzgebiet Da die AMX Netlinx Sprache nicht sehr verbreitet ist, wird sich der Benutzerkreis stark begrenzen. Dies sind vor allem Programmierer und Fachpersonen. Diese Applikation soll dem einzelnen Programmierer, der ausführenden Firma sowie dem Endkunden eine Hilfe bieten, die Übersicht sowie die Qualität des Codes sicher zu stellen. Das Einsatzgebiet spielt sich vorwiegend in der professionellen Multimedia Technik ab. 1.3 Vorgesehene Erweiterungen Dieses Produkt stellt einen Grundbaustein zum Weiterausbau neuer definierter Audits und Metriken dar. Es soll und muss für den zeitgemässen Einsatz erweitert werden können. Auch Firmenspezifische Eigenheiten sollen nachprogrammiert werden können. 2 Ausgangssituation und Zielsetzung 2.1 Ist Zustand Das AMX System ist ein grosser Bruder der bekannten SPS Steuerung. Programmiert wird aber textorientiert. Es gibt bislang keine oder nur unbefriedigte Möglichkeiten einer visuellen Programmierung. Die Textprogrammierung bietet dem Programmierer mehr Freiheiten, kann aber wie in allen Programmiersprachen auch gewisse Risiken bergen. AMX Systeme werden vielfach von Personen programmiert die nicht direkt einen Abschluss als Software Engineer oder einen IT-Fachausweis besitzen. Es ist sogar üblich, dass Fachkräfte aus der professionellen Multimedia-Technik sowie Telematik als Programmierer weiter ausgebildet werden. Industrie- sowie auch besser gestellte Privatkunden sind Abnehmer solcher Systeme. Vor allem bei Sicherheitsrelevanten Anlagen werden die Stimmen nach einer Dokumentation immer lauter. Diese bleibt aber aus Zeitgründen und mangels Tools auf der Strecke liegen. Dokumentationen existieren höchstens in Form von Kommentaren im programmierten Code. 2.2 Programmierung heute Die angesprochene teilweise mangelhafte Fachkompetenz der Programmierer führt vielfach zu langem Spaghetticode. Unübersichtliche Files entstehen. Gliederungen sind schwer zuerkennen. Fehler schwer zu finden. Vereinzelt kommt es durch Erweiterungen zu nicht erreichten Codefragmenten. (Dead Code). 2.3 Zielsetzung In Zukunft sollen definierte nichtfunktionale Fehler (weiter auch Warnings genannt) durch dieses Tool erkannt werden. Diese sollen nicht behoben werden, sondern dem Programmierer soll bekannt gemacht werden, dass er sich mit den aufgezeigten Punkten ein Problem einhandeln könnte. Einem Endkunden kann eine Dokumentation mit Schnittstellenbeschreibung abgegeben werden. Diese wird einer Fachperson Auskunft geben z.b. welche Geräte mit welchen Treibern gesteuert werden. Einem Laien wird die Dokumentation nicht in Prosa den ganzen Sourcecode erklären, aber einiges zur Qualitätssicherung und Wartbarkeit seiner eingekauften Software beitragen..doc 19.03.2007 Seite 4 von 15
3 Funktionale Anforderungen In diesem Kapitel werden die funktionalen Anforderungen an die Software beschrieben 3.1 Voraussetzungen Die Voraussetzung für den Parser ist ein fehlerfrei kompilierbares.axs File. Dieses bildet mit allfälligen.axi Files ein lauffähiges AMX Programm. 3.2 Use Case Overview USE CASE DIAGRAM: Overview 1 Add new.axs File <<include>> Scan.axs /.axi File <<extends>> Device List Documentation <<extends>> Reviewer Add new Device List Source Code Documentation <<extends>> 1 Programmer Save Entry Add New Device <<extends>> <<include>> Edit Entry <<extends>> Entry Manipulations <<extends>> Delete Entry Metric Documentation 1 generierte Dokumentation Abbildung 3.2 3.3 Benutzerinterface (GUI) Das GUI bildet die Schnittstelle zwischen Bediener und Tool. Sämtliche erforderlichen Eingaben werden über dieses definiert. Ser. No. Konzept Katalog 3.3.1 Taskliste / Statusliste 3.3.2 Pfadangabe der vorhandenen.axs Datei 3.3.3 Liste mit Vorlagenauswahl (Device Liste) 3.3.4 Add, Edit, Delete, Save Button für Listeneinträge 3.3.5 Der Benutzer kann jedes der drei Dokumente unabhängig voneinander erstellen. 1. Source Code Documentation 2. Device Liste Documentation 3. Warnings Documentation.doc 19.03.2007 Seite 5 von 15
3.4 Device Liste Die Device und IP Liste beschreibt sämtliche Hardware Schnittstellen des AMX Zentralrechners. Diese Liste soll Aufschluss über die ID Vergabe (AMX interne Adressen) sowie über Details wie MAC Adresse, Software Version usw. der angeschlossenen Geräte geben. Als Vorlage dient das bewährte Excel File mit dem die Device und IP Listen aktuell erstellt werden. Abbildung 3.4 Ser. No. Konzept Katalog 3.4.1 Die vorhandene Datei IP_Device.xls dient als verbindliche Vorlage zur Erstellung einer kompletten Liste 3.4.2 Der Benutzer kann aus einer Vorlage, Devices auswählen und in die Liste einfügen 3.4.3 Der Benutzer kann jeden Eintrag vor der Erstellung der Dokumentation modifizieren 3.4.4 Der Benutzer kann jeden Eintrag vor der Erstellung der Dokumentation löschen 3.5 Parser / Translator Ser. No. Konzept Katalog 3.5.1 Parser: speichert relevante Informationen in einem abstract syntax tree 3.5.2 Parser: Verifiziert und behandelt Audits und Metriken nach ihrer Definition 3.5.3 Parser: Der Parser wird mit dem Tool JavaCC entwickelt. 3.5.4 Translator: Erstellung der generierten Dokumentation Translator: Erstellung dynamischer Files aus abstract synatx tree 1. Source Code Documentation 3.5.5 2. Device Liste Documentation 3. Warnings Documentation.doc 19.03.2007 Seite 6 von 15
3.6 Audits und Metriken Der Source Code wird nach den unten definierten Regeln durchsucht. In einem eigenen Dokument werden allfällige Warnungen ausgegeben. Die nichtfunktionalen Fehler werden im Dokument Warnings aufgezeigt, nicht aber korrigiert. Ser. No. Konzept Katalog Audit / Metrik 3.6.1 Dead code (unused var, CALL s, functions usw.) Audit 3.6.2 Undefined type var Audit 3.6.3 very long.axi files Metric 3.6.4 Long DEFINE_PROGRAM section (Mainline) Metric 3.6.5 Naming (Devices only) Audit 3.6.6 Duplicated timelines Audit 3.6.7 Duplicated Module includes Audit 3.6.8 Global var in functions, calls Audit 3.6.9 Global var as a parameter in functions Audit 3.6.10 IP devices check (format & unique) Audit 3.6.11 Nesting depth (brace), warning starting from the 8 th brace Metric 3.6.12 Nesting include files Audit 3.6.13 Duplicated BAUD rate definition on same device Audit 3.6.14 Duplicated virtual devices Audit 3.6.15 Check system number (more than one system) Audit 3.6.16 Defined file extention of include files Audit 3.7 Generierte Dokumentation Die generierte Dokumentation bildet das visuelle Resultat des AMX Netlinx SourceCode Inspectors Ser. No. Konzept Katalog 3.7.1 Browserfähig 3.7.2 Indexpage (verlinkt auf die drei unten genannten Dokumente) 3.7.3 Menüführungs-Sprache: English 3.7.4 Dokument: Source Code (siehe Abbildung 3.7) Dynamisches JavaScript Dokument Baumstruktur nach Art Windows Explorer Nach Sections unterteilt Sections entsprechen den Regeln der Treenode definition (Anhang 11.1) Der Inhalt der Sections entspricht genau den Regeln der Treenode definition (Anhang 11.1) Nicht benutzte Sections sollen ersichtlich sein aber kein Inhalt enthalten Benutzte Sections, resp. deren Inhalt sollen mit einem Link ins Root Verzeichnis den entsprechenden original Source Code im Browser darstellen 3.7.5 Dokument: Device List Statisches HTML Dokument Tabellenform gem. Excel Vorlage Inhalt: gemäss Device List 3.4 3.7.6 Dokument: Warnings Dynamisches JavaScript Dokument Baumstruktur nach Art Windows Explorer Sections nach Verstoss gegen definierte Regeln gemässe Punkt 3.6 unterteilt Inhalt: Filenamen mit Zeilennummer Kommentar und Bemerkungsfelder.doc 19.03.2007 Seite 7 von 15
Als visuelles Beispiel gilt dieser Print Screen des Prototyps Source Code Documentation. Wie die einzelnen Ordner gegliedert sind und welche Inhalte sie besitzen, ist im Anhangkapitel 11.1 Treenodes definition ersichtlich. Dieselbe Struktur wird für die Warning Documentation verwendet. Die Gliederung richtet sich nach der Tabelle 3.6 Abbildung 3.7.doc 19.03.2007 Seite 8 von 15
4 Nicht funktionale Anforderungen 4.1 Q-Anforderungen (nach FURBS* Schema) *FURPS = Functionality, Usability, Reliability, Performance, Supportability Qualitätskriterien Funktionalität Durch ein geführtes Testdrehbuch wird die Funktionalität laufend geprüft und festgehalten. Ein Prüfprotokoll ist das Ergebnis erfolgter Test s. Produkt: Ein kompilierbares AMX Netlinx Projekt kann jederzeit die Funktionalität des entwickelten Tools in Anspruch nehmen. Dies dient der Steigerung des Programmierniveaus des einzelnen Programmierers Benutzbarkeit Es wird ein Systemhandbuch, Benutzerhandbuch erstellt, sowie eine Versionsliste und Change Requests geführt. Zuverlässigkeit Das Produkt hat die funktionellen Anforderungen jederzeit zu erfüllen Effizienz Auf das Zeitverhalten sowie auf das Verhalten gegenüber der Verwendung von Speicher werden keine Regeln gesetzt. Der Prozess ist weder Zeitkritisch noch Speicheraufwändig. Wart- und Änderbarkeit Neue Metriken sollen nachprogrammiert werden können. Auch Erweiterungen am AMX Netlinx Language Sprachumfang können im Parser nach der EBNF Erweiterung implementiert werden. Durch die automatisch generierten Files nach JavaCC wird der gesamte Parser- und Translator-Teil in einem Package zu finden sein. Dies ist ein Nachteil in der Übersicht dient aber der Änderbarkeit. Es kann jederzeit eine neue Node eingefügt werden ohne dass manuell eine Package-Angabe erweitert werden muss. Übertragbarkeit Das Produkt wird unter Programmierern ausgetauscht. Durch das Systemhandbuch werden die Anforderungen an Hardware definiert und im Benutzerhandbuch dokumentiert. Die empfohlene jdk und jre Version wird ebenfalls ausgewiesen. 4.2 Plattform Die Arbeit wird in Eclipse3.2 entwickelt. Dazu werden folgende Plug-Ins benötigt. - Remi Koutcherawy JavaCC Plug-In 1.5.6 - Omondo EclipseUML Free Edition 2.1.0 - Eclipse.org Java Visual Editor 1.2.1.doc 19.03.2007 Seite 9 von 15
5 Gesamtsystemarchitektur Definition Use Case Overview unter Punkt 3.2 6 Lieferumfang 6.1 Software AMX Netlinx SourceCode Inspector (als Gesamtlösung) 6.2 Dokumentation Projektdokumentation Systemhandbuch Benutzerhandbuch Testdrehbuch mit Prüfprotokoll 7 Lizenz Nach GNU General Public License Auszug aus deutscher Übersetzung http://www.gnu.de/documents/gpl.de.html Copyright (C) [Jahr] [Name des Autors] Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 2 der Lizenz oder (nach Ihrer Option) jeder späteren Version. Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, daß es Ihnen von Nutzen sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN ZWECK. Details finden Sie in der GNU General Public License. Sie sollten ein Exemplar der GNU General Public License zusammen mit diesem Programm erhalten haben. Falls nicht, schreiben Sie an die Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA. 8 Abkürzungsverzeichnis / Glossar Begriff AMX Audits apw axs axi Device EBNF FURPS GNU GPL GUI HTTP HTML IDE JavaCC MAC Metrics Netlinx tkn UML Warnings XML Bedeutung Markenname des Produktes (Home USA Texas) Audits oder Prüfer überwachen die Richtlinienkonformität, Wartbarkeit und Robustheit des Codes AMX Project File-Extention AMX Master File-Extention AMX Incude File-Extention Als Device wird ein Hardware Gerät bezeichnet das an einer Schnittstelle am AMX Controller angeschlossen, und in der DEFINE_DEVICE Sectoin definiert ist. Extended Backus Naur Form Functionality, Usability, Reliability, Performance, Supportability Free Software Foundation General Public License Graphical User Interface HyperText Transfer Protocol HyperText Markup Language Integrated Development Environment Java Compiler Compiler Media Access Control Metrics oder Metriken dienen zur Berechnung der Komplexität des Codes Zweite AMX Generation AMX Compiled File-Extention (Netlinx) Unified Modeling Language Nichtfunktionale Fehler die aus den Audits und Metriken entstehen extensible Markup Language.doc 19.03.2007 Seite 10 von 15
9 Literaturverzeichnis Begriff V-Modell V-Modell AMX GNU Literatur http://ftp.uni-kl.de http://www.informatik.uni-bremen.de/gdpa/vmodel_d/i-gral.htm http://www.amx.com http://www.gnu.de/documents/gpl.de.html 10 Abbildungsverzeichnis Abbildung Quelle / File 3.2 Th. Jud / Overview.sdr 3.4 Kilchenmann AG / IP_Device.xls 3.7 Th. Jud / Prototype Source Code Documentation auf IE 7.0 Browser.doc 19.03.2007 Seite 11 von 15
11 Anhang 11.1 Treenodes definition Ser. No. 11.1.1 11.1.2 11.1.3 11.1.4 11.1.5 11.1.6 11.1.7 11.1.8 11.1.9 11.1.10 11.1.11 11.1.12 11.1.13 11.1.14 11.1.15 11.1.16 11.1.17 11.1.18 Konzept Katalog PROGRAM_NAME [Name] DEFINE_DEVICES [Name][Device Number][Defined Section(Line)] DEFINE_COMBINE [Combined Device Name or Number][Defined Section(Line)] DEFINE_CONSTANT [Name][Defined Section(Line)] DEFINE_VARIABLE (globale Variabeln) [Name][Type][Defined Section(Line)] DEFINE_VARIABLE (lokale Variabeln) [Name][Type][Defined Section(Line)] DEFINE_TYPE [Name][Defined Section(Line)] DEFINE_START [Defined Sections(Line)]* DEFINE_MUTALLY_EXCLUSIVE [Defined Sections(Line)]* DEFINE_EVENT (Data Event) [Device Name or Number][Defined Section(Line)] DEFINE_EVENT (Button Event) [Device Name or Number][Defined Section(Line)] DEFINE_EVENT (Level Event) [Device Name or Number][Defined Section(Line)] DEFINE_EVENT (Channel Event) [Device Name or Number][Defined Section(Line)] DEFINE_FUNCTION [Function Name][Return Type][Defined Section(Line)] DEFINE_CALL [Call Name][Defined Section(Line)] DEFINE_MODULE (Module und System Calls) [System Call or Module Name][Defined Section(Line)] DEFINE_PROGRAM (Push) [Device Name or Number][Defined Section(Line)] DEFINE_PROGRAM (Release) [Device Name or Number][Defined Section(Line)].doc 19.03.2007 Seite 12 von 15
11.2 Projektplan Februar - März.doc 19.03.2007 Seite 13 von 15
April Mai - Juni.doc 19.03.2007 Seite 14 von 15
11.3 V Modell Chart.doc 19.03.2007 Seite 15 von 15