Programmierschnittstelle für das Soundfield Scanning Drive · Die GAMPT mbH haftet nicht für...

Softwaretools

xyz.dll Programmierschnittstelle für das Soundfield Scanning Drive

Programmierhandbuch

www.gampt.de

Erstausgabe: Version 1.0, Juli 2010

Revision 1: Version 1.1, Dezember 2012

Revision 2: Version 1.2, Mai 2013

Gesellschaft für Angewandte Medizinische Physik und Technik mbH Hallesche Strasse 99F 06217 Merseburg Telefon: +49 3461/278691-0 Fax: +49 3461/278691-101 E-Mail: [email protected]

Besuchen Sie uns im Internet: www.gampt.de

© 2010-2014 GAMPT mbH

Alle Rechte sind der GAMPT mbH vorbehalten. Kein Teil dieses Handbuchs darf in irgendeiner Form ohne die Genehmigung der GAMPT mbH reproduziert oder verarbeitet, vervielfältigt oder verbreitet werden.

Die GAMPT mbH haftet nicht für Schäden infolge von Fehlgebrauch sowie Reparaturen und Abänderungen, die von dritter, nicht von der GAMPT mbH autorisierter Seite vorgenommen werden.

Technische Änderungen vorbehalten. Irrtümer vorbehalten.

Druck: 13. 03. 2014 Version: 1.2 GER

Inhaltsverzeichnis

Inhaltsverzeichnis

1 Einführung..................................................................................................................2 2 Soundfield Scanning Drive..............................................................................................3

2.1 Bedienelemente auf der Vorderseite..........................................................................3 2.2 Anschlüsse auf der Rückseite ....................................................................................4 2.3 3D-Scanner............................................................................................................5

3 xyz.dll und FTD2XX.dll...................................................................................................6 4 Typdefinitionen und -deklarationen ................................................................................7

4.1 Ganzzahl-Parameter ...............................................................................................7 4.2 Logischer Typ.........................................................................................................7 4.3 PChar ...................................................................................................................7 4.4 Wichtige Konstanten, Arrays und Pionter ....................................................................7

5 Funktionen und Prozeduren...........................................................................................8 5.1 USB-Kommunikation ..............................................................................................8

5.1.1 open_usb........................................................................................................8 5.1.2 close_usb........................................................................................................8 5.1.3 is_open...........................................................................................................9 5.1.4 last_error........................................................................................................9 5.1.5 errortxt...........................................................................................................9 5.1.6 errortext .........................................................................................................9

5.2 Test-Prozeduren................................................................................................... 10 5.2.1 dllmessage.................................................................................................... 10 5.2.2 show_resolution ............................................................................................ 11 5.2.3 show_movetest .............................................................................................. 11

5.3 Aktionen ............................................................................................................. 12 5.3.1 move............................................................................................................ 12 5.3.2 set_axes_current ............................................................................................ 12 5.3.3 get_axes_current ........................................................................................... 13 5.3.4 move_to ....................................................................................................... 13 5.3.5 get_pos......................................................................................................... 13 5.3.6 set_zero........................................................................................................ 13

6 Anhang ..................................................................................................................... 14 6.1 Code-Beispiele ..................................................................................................... 14

6.1.1 unit xyz_h.pas für Delphi................................................................................. 14 6.1.2 unit xyz.h für Matlab....................................................................................... 15

xyz.dll für Soundfield Scanning Drive · Programmierhandbuch Version 1.2 GER 1

0BEinführung

2 GAMPT mbH · Hallesche Straße 99F · D-06217 Merseburg · Tel. +49 3461/2786910 · www.gampt.de

1 Einführung

Standardmäßig werden die Geräte der Firma GAMPT mit der entsprechenden Software ausgeliefert. Diese ermöglicht eine direkte Kommunikation der Geräte mit einem angeschlossenem PC oder Notebook über eine USB-Schnittstelle.

Um dem Anwender eine flexiblere Nutzung des 3D-Scanner-Equipments zu ermöglichen, stellen wir zusätzlich eine dynamische Programmbibliothek (DLL) zur Verfügung, mit welcher der Anwender das Soundfield Scannning Drive (xyz-Steuerung) selber ansteuern kann.

Die bereitgestellte DLL wurde mit Borland Delphi (Object Pascal) geschrieben. Die später genannten Definitionen und Typdeklarationen beziehen sich darauf. Für andere Anwendungen müssen die Typen entsprechend angepasst werden.

Um eine möglichst hohe Kompatibilität zu gewährleisten, werden die Parameter als ganzzahlige Werte (byte oder integer) übergeben. Die minimale Schrittweite bei Verwendung der Standardwerte beträt 1,88 µm. Es können immer nur Vielfache dieser minimalen Schrittweite gefahren werden. Um Rundungsfehler, die sich im Lauf der Zeit addieren können, zu vermeiden und die Parameter trotzdem als integer Werte übergeben zu können, werden die Weglängen und Koordinaten in Nanometer angegeben. Dies erscheint sicher etwas übertrieben, vereinfacht aber die Programmierung und vermeidet Abweichungen.

1BSoundfield Scanning Drive

2 Soundfield Scanning Drive

Das Soundfield Scanning Drive dient als Steuerelektronik für eine 3D-Scanvorrichtung. Das Steuergerät kann über eine USB-Schnittstelle von einer Anwendungssoftware auf einem PC oder Notebook aus angesteuert und auch manuell bedient werden.

2.1 Bedienelemente auf der Vorderseite

Abb. 1: Frontansicht des Soundfield Scanning Drive (xyz-Steuerung)

Das Steuergerät ist an der Frontseite mit Elementen zur manuellen Bedienung versehen.

• Über den ON/OFF-Schalter wird das Gerät ein- und ausgeschaltet. • Mit den Schaltern X-AXIS, Y-AXIS und Z-AXIS kann eine Bewegung in der jeweiligen

Achsenrichtung gestartet und beendet werden sowie die jeweilige Fahrtrichtung (LEFT, RIGHT) gewählt werden.

• Über den Schalter SPEED können vier Fahrgeschwindigkeiten (5%, 25%, 50% und 100%) eingestellt werden.



2.2 Anschlüsse auf der Rückseite

Abb. 2: Rückansicht des Soundfield Scanning Drive (xyz-Steuerung)

Auf der Rückseite des Soundfield Scanning Drive befinden sich:

• der Netz-Anschluss des Gerätes (unten links), • die USB-Schittstelle für die Verbindung zum PC (unten rechts) und • die vier Anschlüsse zur Ansteuerung der vier Schrittmotoren des 3D-Scanners.




2.3 3D-Scanner

Mit dem 3D-Scanner kann ein Messsensor (z. B. ein Hydrofon) definiert in einem kartesischen Koordinatensystem bewegt werden. Für die Bewegung in den drei Achsenrichtungen ist die Scanvorrichtung mit Schrittmotoren versehen. Diese Schrittmotoren werden manuell oder per Software über das Soundfield Scanning Drive angesteuert.

Die Motorschlitten sind jeweils mit zwei Endlagenschaltern versehen. Die zugehören Anschläge sind frei auf den Achsen positionierbar.

Sollte ein Verfahren in einer Achsenrichtung nicht möglich sein, obwohl der entsprechende Endlagenschalter seinen Anschlag noch nicht erreicht hat, ist als erstes immer die mechanische Funktionalität des Schalters zu prüfen.

Abb. 3: 3D-Scanvorrichtung mit Steuergerät

Abb. 4: Motorschlitten mit Endlagen-

schaltern (1) und Anschlag (2)

2Bxyz.dll und FTD2XX.dll

3 xyz.dll und FTD2XX.dll

Für die Ansteuerung des Soundfield Scanning Drive von einer Anwendungssoftware aus werden zwei Programmbibliotheken benötigt: xyz.dll (GAMPT) und FTD2XX.dll (FTDI).

Die Programmbibliothek xyz.dll stellt die eigentliche Schnittstelle zum Anwendungsprogramm dar. Ihre Funktionen und Prozeduren werden weiter unten ausführlich beschrieben.

Die Kommunikation zwischen PC und Steuergerät wird mit einem USB-Chip der Firma FTDI realisiert. Um den Chip ansprechen zu können, braucht die xyz.dll die Programmbibliothek FTD2XX.dll. Beide DLLs müssen sich im Programmverzeichnis oder Pfad der Anwendungssoftware befinden. Damit der PC den USB-Chip erkennt, muss dafür zunächst der entsprechende Treiber installiert werden.

Weitere Informationen zum USB-Treiber sind auf der Download-Seite unserer Website unter www.gampt.de zu finden.


3BTypdefinitionen und -deklarationen

4 Typdefinitionen und -deklarationen

4.1 Ganzzahl-Parameter

Typ: Bereich: Format:

integer -2147483648..2147483647 32 Bit (mit Vorzeichen)

byte 0..255 8 Bit (ohne Vorzeichen)

4.2 Logischer Typ

Als logischer Typ wird boolean verwendet (z. B. für den Parameter onoff der Prozedur set_axes_current). Dieser Datentyp kennt nur die beiden Werte true und false.

4.3 PChar

Der Parameter für die Übergabe des USB-ID-Strings ids der Funktion open_usb ist als PChar deklariert. Der Typ PChar bezeichnet einen Zeiger auf eine nullterminierte Zeichenkette.

4.4 Wichtige Konstanten, Arrays und Pionter

const DLL_name = 'xyz.dll'; (Name der DLL)

type int3arr = array[1..3] of integer; pint3arr = ^int3arr; bytearr = array[0..255] of byte; (Byte-Array für Fehlermeldungen) pbytearr = ^bytearr; (Zeiger auf das Byte-Array)


4BFunktionen und Prozeduren


5 Funktionen und Prozeduren

Die Kommunikation verläuft auf zwei Ebenen. Zunächst wird eine Verbindung zum USB-Chip des Soundfield Scanning Drive gesucht. Wird diese gefunden, werden darüber Daten an den Mikrokontroller des Gerätes gesendet, der daraufhin die Messdaten via USB zurückgibt.

5.1 USB-Kommunikation

5.1.1 open_usb

function open_usb(ids:pchar):integer

Die Funktion open_usb stellt die Verbindung vom PC zum USB-Chip des Gerätes her. Damit die DLL weiß, nach welchem Chip gesucht werden soll, wird die USB-Kennung in einem ID-String übergeben. Der Parameter ids zeigt auf die Zeichenkette, die den ID-String enthält. Die DLL sucht jetzt nach einem Chip mit dieser Kennung und versucht die Verbindung zu öffnen. Ist dies erfolgreich, werden einige Testdaten gelesen.

Der Kennung (ID-String) eines Soundfield Scanning Drive (xyz-Steuerung) lautet zur Zeit 'GAFR' (siehe auch Abschnitt 4.2.1)

Der ID-String der Steuerung ist im USB-Chip des Gerät gespeichert. In Zukunft wird dieser

String an die entsprechende Anwendung angepasst.

Der ID-String kann über die Funktion dllmessage ermittelt werden (Abschnitt 5.2.1).

Ist die Aktion erfolgreich, liefert die Funktion als Ergebnis 0, andernfalls einen Fehlercode, welcher die Ursache des Fehlers beschreibt (s. a. procedure errortxt).

5.1.2 close_usb

procedure close_usb

Die Prozedur close_usb schließt die mit open_usb geöffnete USB-Verbindung.

close_usb schließt auch die Formulare move_test und resolution, die mit den Prozeduren show_movetest bzw. show_resolution aufgerufenen werden (s. a. Abschnitt 5.2).



5.1.3 is_open

function is_open:boolean

Die Funktion is_open testet, ob eine gültige Verbindung zum Gerät besteht. Dazu werden Testdaten vom Gerät gelesen. Die Funktion kann hilfreich sein, um zu vermeiden, dass Datenabfragen ins Leere laufen.

5.1.4 last_error

function last_error:integer

Mit die Funktion last_error kann der letzte aufgetretene Fehler abgerufen werden.

Vorsicht! Alle anderen Funktionen der DLL können den letzten Fehlercode wieder zurücksetzen.

5.1.5 errortxt

function errortxt(err:integer):string

Die Funktion errortxt dient dazu, die als Integer-Werte gelieferten Fehlercodes in einen Text umzuwandeln.

5.1.6 errortext

function errortext(err:integer; pba:pbytearr):integer

Die Funktion errortext dient ebenfalls dazu, die als Integer-Werte gelieferten Fehlercodes in einen Text umzuwandeln. Die Funktion greift intern auf errortxt zurück. Die Zeichen des Textes werden in Byte umgewandelt und in das Array bytearr geschrieben, auf welches der Zeiger pba zeigt. Als Ergebnis liefert die Funktion die Anzahl der zurückgegebenen Zeichen. Um den Text anzuzeigen, wird der Inhalt des Byte-Arrays in Zeichen umgewandelt.

!!



5.2 Test-Prozeduren

Im Folgenden werden die Prozeduren zum Testen der Kommunikation beschrieben. Mit diesen kann überprüft werden, ob der Datentransfer zwischen Programm, DLL und Gerät funktioniert. Die Prozeduren können beim Programmieren hilfreich sein, sind aber für den eigentlichen Betrieb nicht notwendig.

Ein Vermischen dieser Testroutinen mit dem eigentlichen Programm sollte vermieden werden. Speziell dann, wenn die USB-Verbindung von show_movetest oder show_resolution aufgebaut wurde, kann dies zu Störungen im Programm führen.

5.2.1 dllmessage

procedure dllmessage

Die Prozedur dllmessage dient dazu die Kommunikation zwischen dem aufrufenden Programm und der DLL zu testen. Das Ergebnis des Tests wird im Meldungsfenster unter USB-Info angezeigt.

Beim Test der Kommunikation wird auch der Pfad inidatpath des aufrufenden Programms ermittelt. Dieser dient als Vorlage zum Speichern der ini-Daten (s. a. show_resolution).

Wenn zum Zeitpunkt des Tests das Gerät angeschlossen und eingeschaltete ist, wird die USB-Kennung ausgelesen und im Meldungsfenster unter USB-Info angezeigt (rechte Abbildung). Die ersten vier Zeichen der Kennung – hier 'GAFR' - dienen als USB-ID-String und werden von der Funktion open_usb benötigt. Die Parameterübergabe erfolgt über den Zeiger ids, der auf den USB-ID-String verweist.

Abb. 5: Negativer Kommunikationstest (Gerät ist nicht angeschlossen oder ausgeschaltet).

Abb. 6: Erfolgreicher Kommunikationstest.



5.2.2 show_resolution

procedure show_resolution(an:boolean)

In der Programmbibliothek xyz.dll sind zwei Formulare integriert.

Die Prozedur show_resolution öffnet ein Formular, in dem die Hardwareparameter der Scannereinheit angepasst werden können.

Achtung! Diese Parameter sollten nur nach Rücksprache mit einem Mitarbeiter von GAMPT geändert werden.

Eine Anpassung der Parameter kann z. B. dann notwendig sein, wenn die Anstiege der Gewindestangen nicht den Standardwerten entsprechen.

Einzig der Wert des USB-ID-Strings kann, wenn notwendig, angepasst werden. Steht hier ein falscher Wert funktioniert die Kommunikation des move_test-Formulars (procedure show_movetest) nicht. Die Funktion open_usb wird davon nicht beeinflusst.

Die Daten des Formulars werden automatisch in einer Datei mit der Erweiterung gin gespeichert. Die Struktur dieser Datei entspricht einer ini-Datei. Pfad und Dateiname hängen davon ab, von welchem Programm die DLL aufgerufen wurde.

5.2.3 show_movetest

procedure show_movetest(an:boolean)

Die Prozedur show_movetest öffnet das Formular move_test. Mit diesem Formular kann die Steuerung interaktiv direkt angesprochen werden, ohne die anderen Funktionen der DLL zu benutzten.

!!



5.3 Aktionen

5.3.1 move

function move(speed,axis:byte;path:integer;pmovedpath:pinteger):integer

Die Funktion move ist die wichtigste Anwendung. Mit ihr wird eine Bewegung realisiert.

Mit dem Parameter speed wird die Fahrgeschwindigkeit in Prozent übergeben.

Der Parameter axis gibt die Fahrtrichtung an. Dabei werden nur folgende drei Werte akzeptiert: 1 für die x-Achse, 2 für die y-Achse und 3 für die z-Achse.

Der Parameter path gibt die Länge des zu fahrenden Weges in Nanometern (nm) an, wobei negative Werte die Richtung umkehren.

Der Zeiger pmovedpath verweist auf eine Integer-Variable. Der Wert der Variablen entspricht dem zurückgelegten Weg in nm.

Normalerweise sollte dieser Weg natürlich gleich der Vorgabe sein, kann aber durch Rundungsfehler, oder wenn z. B. die Endlage erreicht wurde, abweichen.

Als Ergebnis liefert die Funktion move ein Fehlercode, der mit der Funktion last_error abgerufen werden kann.

5.3.2 set_axes_current

procedure set_axes_current(axis:byte;onoff:boolean)

Es gibt für die Achsen drei Stromzustände. Wird das Gerät angeschaltet sind die Achsen stromlos. Beim Fahren haben sie den Zustand full. Nach dem Fahren wird automatisch auf einen reduzierten Zustand geschaltet. Der reduzierte Zustand soll sicherstellen, dass die angefahrene Position gehalten wird, aber vermeiden, dass die gesamte Zeit zuviel Strom durch die Motoren fließt.

Die Schrittmotoren des Scanners werden auch durch den reduzierten Strom erwärmt. Wenn sie nicht benötigt werden, sollte der Strom ganz abgeschaltet werden.

Zum Abschalten des Stroms kann die Prozedur set_axes_current verwendet werden. Über die Parametern axis und onoff wird festgelegt, auf welcher Achse der reduzierte Strom an oder ausgeschaltet wird. Ein Anschalten ist eigentlich nie notwendig, kann aber zum Testen verwendet werden.



5.3.3 get_axes_current

procedure get_axes_current(pac:pint3arr)

Mit der Prozedur get_axes_current kann der Zustand des Stromes abgefragt werden. Der Parameter pac ist ein Zeiger auf ein Integer-Array (siehe Typdefinitionen), wobei 0 = aus und 1 = an bedeutet.

5.3.4 move_to

function move_to(speed:byte;pos:int3arr):integer

Neben der absoluten Bewegung durch die Funktion move, gibt es die Funktion move_to, bei der die Positionierung mittels Koordinaten geschieht.

Als Parameter dienen zum einen wieder speed für die Fahrgeschwindigkeit in Prozent.

Zum anderen wird ein Integer-Array pos mit drei Werten (x,y,z) übergeben, das die anzufahrende Position beinhaltet. Ausgehend von der aktuellen Position werden nacheinander die Änderungen der x-, y- und z-Koordinate abgefahren. Die erreichte Position ist dann als aktuelle Position mit Hilfe der Funktion get_pos abrufbar.

Die Achsen werden immer in der Reihenfolge x - y - z abgefahren. Das bedeutet, wenn man z. B. von (0,0,0) nach (10000,10000,0) fährt und danach wieder zurück zu (0,0,0), wird für den Hinweg und den Rückweg nicht derselbe Weg benutzt. Stellen Sie bitte sicher, dass beide Wege frei sind.

5.3.5 get_pos

procedure get_pos(ppos:pint3arr)

Die Prozedur get_pos liefert die aktuelle Position, wobei die Positionswerte in ein Array mit drei Integerwerten geschrieben werden, auf das der Zeiger ppos verweist.

5.3.6 set_zero

procedure set_zero

Die Prozedur set_zero setzt die aktuelle Position auf (0,0,0).

5BAnhang

6 Anhang

Im Folgenden werden zwei Beispiele gezeigt, wie die Programmbibliothek xyz.dll eingebunden werden kann. Das erste Beispiel demonstriert die Einbindung in Delphi und das zweite eine Einbindung in Matlab. Für andere Programme sind entsprechende Anpassungen vorzunehmen.

6.1 Code-Beispiele

6.1.1 unit xyz_h.pas für Delphi unit xyz_h; interface uses windows,sysutils; type bytearr = array[0..255] of byte; pbytearr = ^bytearr; int3arr = array[1..3] of integer; pint3arr = ^int3arr; const DLL_name = 'xyz.DLL'; function open_usb(ids:pchar):integer;stdcall;External DLL_name; //errorcode procedure close_usb;stdcall;External DLL_name; //close also move_test & resolution function is_open:boolean;stdcall;External DLL_name; //status function last_error:integer;stdcall;External DLL_name; //error number function errortxt(err:integer):string;stdcall;External DLL_name; //error text function errortext(err:integer; pba:pbytearr):integer;stdcall;External DLL_name; //length of pba //‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ procedure dllmessage;stdcall;External DLL_name; procedure show_movetest(an:boolean);stdcall;External DLL_name; procedure show_resolution(an:boolean);stdcall;External DLL_name; //‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ procedure set_axes_current(axis:byte;onoff:boolean);stdcall;External DLL_name; procedure get_axes_current(pac:pint3arr);stdcall;External DLL_name; function move(speed,axis:byte;path:integer;pmovedpath:pinteger):integer;stdcall;External DLL_name; //errorcode //‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ procedure set_zero;stdcall;External DLL_name; procedure get_pos(ppos:pint3arr);stdcall;External DLL_name; function move_to(speed:byte;pos:int3arr):integer;stdcall;External DLL_name; //errorcode //‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ implementation end.


5BAnhang

6.1.2 unit xyz.h für Matlab //Define GAMPT xyz‐API functions #include <stdlib.h> #include <stdio.h> extern "C" int __declspec(dllimport) __stdcall open_usb(char*); //ids = ID string extern "C" void __declspec(dllimport) __stdcall close_usb(); extern "C" bool __declspec(dllimport) __stdcall is_open(); extern "C" int __declspec(dllimport) __stdcall last_error(); extern "C" char* __declspec(dllimport) __stdcall errortxt(int); extern "C" int __declspec(dllimport) __stdcall errortext(int,unsigned char*); extern "C" bool __declspec(dllimport) __stdcall dllmessage(); extern "C" void __declspec(dllimport) __stdcall show_movetest(bool); extern "C" void __declspec(dllimport) __stdcall show_resolution(bool); extern "C" int __declspec(dllimport) __stdcall move(unsigned char,unsigned char,int,int*); //speed, axis,

path, pmovedpath; extern "C" bool __declspec(dllimport) __stdcall set_axes_current(unsigned char,bool); //axis, onoff extern "C" void __declspec(dllimport) __stdcall get_axes_current(int*); // pointer pos array extern "C" void __declspec(dllimport) __stdcall set_zero(); extern "C" void __declspec(dllimport) __stdcall get_pos(int*); //pos array extern "C" int __declspec(dllimport) __stdcall move_to(unsigned char,int*); //byte=speed, ...


Programmierschnittstelle für das Soundfield Scanning Drive · Die GAMPT mbH haftet nicht für...

Documents

Transcript of Programmierschnittstelle für das Soundfield Scanning Drive · Die GAMPT mbH haftet nicht für...