USB2.DLL
Version 1.3

Ein einfaches Programmierinterface für den Cypress Cy7c68013 USB2.0 Controller.

Available Languages:

• English (File: Usb2Dll_help_en.html)

• German (File: Usb2Dll_help.html)

• Was ist USB2.DLL?
• Zum USB HighSpeed Interface Modul V2.0 & V2.5 von Braintechnology
• Installation
• Generelles zur DLL
• Beispiele
• Header und Includes für diverse Programmiersprachen
• Latenzzeiten und Geschwindigkeit
• Funktionen der DLL
  • Allgemeine Funktionen
    • UsbInit
    • UsbGetError
    • UsbGetErrorStringByNr
    • UsbSetLicense
    • UsbCheckSpeed
    • UsbOpen
    • UsbClose
    • UsbGetVersion <Neu>
  • IO Funktionen
    • UsbSetIOState
    • UsbSetIODir
    • UsbGetIOState
  • Port Funktionen
    • UsbSetPortState
    • UsbSetPortDir
    • UsbGetPortState
• i²c-Bus Funktionen
  • UsbI2CSetSpeed
  • UsbI2CWriteByte
  • UsbI2CWriteBytes
  • UsbI2CReadByte
  • UsbI2CReadBytes
  • UsbI2CWriteAndReadBytes
• i²c-EEProm Funktion
  • UsbEEpWriteByte
  • UsbEEpWriteBytes
  • UsbEEpReadByte
  • UsbEEpReadBytes
  • UsbEEpSetAddr <Neu>
• Parallelport-Funktionen
  • Generelle Informationen zum Parallelbus
  • UsbParInit
  • Mode 0-3
  • Mode 4-7
  • Mode 8-9
  • UsbParInitUsingArray
  • UsbParOut  
  • UsbParIn
  • UsbGetRdyState <Neu>
• Problemlösungen
• Geplante Erweiterungen
• Versionsgeschichte
• Kontakt

Das Produkt befindet sich momentan noch in der Entwicklung, weswegen im Moment noch nicht alle geplanten Funktionen realisiert sind. Das bringt andererseits den Vorteil, dass sie noch in den Entwicklungsprozess eingreifen und sinnvolle Funktionen vorschlagen können, die Ihnen fehlen.

Die Usb2Dll wird mit Hilfe des Usb2.0 Interfaces von Braintechnology entwickelt. Dieses Interface ist Ideal um eigene Entwicklungen im USB2.0 Sektor zu realisieren. 

Pinbelegung des Modules:
 

Version 2.0		Version 2.5

Anschlüsse:

Die Dll muß sich in dem Suchpfad für ddls befinden. Das ist entweder das Systemverzeichnis des Rechners, oder das Verzeichnis, in dem sich das Programm befindet, das die dll nutzt.

Eine Registrierung mit Hilfe von regsvr32 ist nicht nötig, da es sich nicht um eine activex-dll handelt.

Fast jede Funktion besitzt DevNum als Aufrufparameter. Er muß die Nummer des anzusprechenden USB-Interfaces beinhalten. Das erste angeschlossene Interface besitzt die Nummer 0, das zweite die Nummer 1, ...

Ist nur ein Interface angeschlossen, so muß man 0 übergeben.

Im Moment gibt es 2 Beispiele, die den Zugriff auf die Funktionen verdeutlichen:

pardemo:

Dieses Programm demonstriert die Programmierung des Parallel-interfaces. Nach dem Start muss der Button Initialize Parallel Interface gedrückt werden. Ein Klick auf den Button Write! schreibt die in dem Edit-Feld angegebene Anzahl von Bytes auf dem Parallel Interface.

Hinweis: Das Demo arbeitet mit Parallelmodus 4.

i²cdemo:

Hiermit können Werte in das interne EEProm gelesen und geschrieben werden. Außerdem kann die Geschwindigkeit des i²c-Busses gewählt werden. 

Zum Schreiben eines Wertes muß man die Felder Address und Value füllen und auf Write klicken.

Zum Lesen eines Wertes aus dem EEProm trägt man die Adresse der Speicherzelle in das Feld Address ein und klickt auf Read. Der gelesene Wert wird dann im Feld Value angezeigt.

iodemo:

Mit Hilfe des Programms können sie sich die Zustände der IO-Leitungen anzeigen
lassen und manipulieren.
Dazu wird jede IO-Leitung durch 3 Elemente visualisiert:

• Eine "Zahl", die bei jedem anklicken zwischen 0 und 1 wechselt. Sie dient dazu den logischen Zustand der IO-Leitung zu setzen. Änderungen wirken sich lediglich aus, wenn die Portleitung als Ausgang geschaltet ist.
• Einen Pfeil, der die aktuelle Richtung der jeweiligen IO-Leitung anzeigt. Zeigt der Pfeil nach links, so ist die IO-Leitung ein Eingang, zeigt er nach rechts, so ist sie ein Ausgang.
• Eine "Leuchtdiode", die den aktuellen Zustand der IO-Leitung anzeigt.

Der Ordner Includes enthält Includes und teilweise Beispiele für Programmiersprachen wie Microsoft Visual Basic, Delphi und Microsoft Visual C++

Wer die DLL in andere Programmiersprachen einbinden will, zu denen keine Includes vorliegen findet hier die Beschreibung der für Aufruf- und Rückgabeparameter verwendeten Datentypen:

Datentyp	Grösse in Byte	signed/unsigned	Beschreibung
boolean	1	-	Ein boolean enthält den Wert 1 (=true) oder 0 (=false)
byte	1	unsigned	Ein vorzeichenloser Wert mit dem Wertebereich 0-255
word	2	unsigned	Ein vorzeichenloser Wert mit dem Wertebereich 0-65535
pchar	4	-	Zeiger auf einen Nullterminierten String (wie in C verwendet)
pointer	4	-	Ein untypisierter Zeiger

Befindet sich das Schlüsselwort "Var" vor einem Parameter, so wird ein Zeiger auf den Wert übergeben. Es entspricht dem Operator "*" in C, bzw. dem Schlüsselwort "byRef" in Visual Basic.

Initialisiert das durch DevNum spezifizierte USB-Interface. Der Initialisierungsvorgang programmiert die aktuellste Firmware in den Controller und ist somit zur weitergehenden Kommunikation zwingend notwendig. Die Routine wartet so lange, bis das Gerät neu enumeriert wurde (normalerweise ca. 1.5 Sekunden). Dies vermeidet Fehler, die durch zu frühe Ansteuerung des Interfaces auftreten können.

Das Interface wird nicht exklusiv geöffnet, das heisst mehrere Programme können gleichzeitig auf den USB-Controller zugreifen. Deswegen ist auch kein "Schliessen" der DLL nötig.

Ist ein Fehler während der Kommunikation mit dem Interface aufgetreten, so liefert diese Funktion die Fehlernummer zurück. Ist der zurückgegebene Wert 0, so ist kein Fehler aufgetreten. Nach dem Auslesen des Fehlerspeichers, wird er zurückgesetzt. 

Wird in ErrNr die durch UsbGetError übermittelte Fehlernummer übergeben, so wird in PString ein Zeiger auf die Fehlermeldung in Klartext zurückgegeben. Aus Kompatibilitätsgründen wird hier mit PChars gearbeitet und nicht mit Strings. Ein PChar ist ein Nullterminierter String, wie er z.B. in C benutzt wird.

function UsbSetLicense(Filename : PChar) : boolean;

Wird diese Funktion nicht ausgeführt und in dem Parameter Filename kein Dateiname einer gültigen Lizenzdatei angegeben, handelt es sich nur um eine Demoversion. In der Demoversion erscheint etwa alle 10 Minuten ein Fenster.

function UsbCheckSpeed(DevNum : Byte; var Speed : Byte) : boolean;

Gibt in Speed den Wert 0 oder 1 zurück. Speed = 0 wird zurückgegeben, wenn der USB-Controller an einem USB1.1, Speed = 1, wenn der Controller an einem USB2 Bus betrieben wird.

function UsbOpen(DevNum : Byte) : boolean;

Normalerweise wird beim Ausführen jeder Funktion das Gerät automatisch geöffnet und geschlossen. Dies bringt natürlich einen kleinen Geschwindigkeitsverlust, allerdings auch den Vorteil, das mehrere Applikationen gleichzeitig auf das Gerät zugreifen können.
Mittels dieser Funktion lässt sich das Gerät exklusiv öffnen. Dadurch entfällt der erwähnte (minimale) Geschwindigkeitsverlust. Allerdings muss nach dem Beenden der Applikation dafür gesorgt werden, dass die Funktion UsbClose aufgerufen wird.

Wer diese Funktion einsetzt, sollte sie direkt nach der Funktion UsbInit aufrufen.

function UsbClose(DevNum : Byte) : boolean;

Schliesst das Gerät, wenn es mittels UsbOpen geöffnet wurde. Wird UsbOpen nicht benutzt, so ist auch der Aufruf von UsbClose nicht erforderlich.

function UsbCheckSpeed(DevNum : Byte; var Speed : Byte) : boolean;

Gibt in Speed den Wert 0 oder 1 zurück. Speed = 0 wird zurückgegeben, wenn der USB-Controller an einem USB1.1, Speed = 1, wenn der Controller an einer USB2 Schnittstelle betrieben wird.

procedure UsbGetVersion(VersionStr : PChar);

Gibt in VersionStr die Versionsnummer der aktuell benutzten DLL zurück. VersionStr muss auf einen Speicherbereich von 16 Byte oder mehr zeigen.

Setzt eine einzelne IO-Leitung auf High (State=1) oder Low (State=0). An LineNum muß die Nummer der IO-Leitung übergeben werden. Die Zuordnung ist folgendermassen:

Damit sich diese Änderung auch an der IO-Leitung auswirkt, muss mittels UsbSetIODir oder UsbSetPortDir die IO-Leitung als Ausgang programmiert werden.

Setzt die Richtung einer IO-Leitung auf Ausgang (State=1) oder Eingang (State=0). Nach dem Initialisieren des Interfaces sind alle IO-Leitungen als Eingang geschaltet. 

Die Zuordnung von LineNum zu den IO-Leitungen entspricht der von UsbSetIOState.

Liefert in State den Zustand einer IO-Leitung zurück. Ist er High, so wird State=1, ist er Low, so wird State=0 zurückgeliefert. 

Die Zuordnung von LineNum zu den IO-Leitungen entspricht der von UsbSetIOState.

Setzt einen der 3 Ports auf den durch State übergebenen Zustand. An PortNum muß die Nummer der Portleitung übergeben werden. Die Zuordnung ist folgendermassen:

Ist ein Bit von State 1, so wird der entsprechende Port-Pin High geschaltet. 

Damit sich diese Änderung auch an den IO-Leitungen auswirkt, müssen mittels UsbSetIODir oder UsbSetPortDir  die relevanten Portleitungen als Ausgang programmiert werden.

Setzt die Richtungen der Portleitungen des durch Portnum ausgewählten Ports. 

Ist ein Bit High, so wird die entsprechende IO-Leitung zu einem Ausgang, sonst ein Eingang.

Die Zuordnung von PortNum zu den IO-Leitungen entspricht der von UsbSetPortState

Liefert den Zustand des durch Portnum spezifizierten Ports zurück. 

Die Zuordnung von PortNum zu den IO-Leitungen entspricht der von UsbSetPortState.

Setzt die Geschwindigkeit des i²c-interfaces. Wird Speed=0 übergeben, so arbeitet das i²c-interface mit 100khz. Speed=1 schaltet das i²c-Interface auf 400khz.

Schreibt das Byte Data an das i²c-Device mit der Slaveadresse SlaveAddr.

Bitte beachten: Hat das anzusprechende i²c-device z.B. die Adresse 0xA0, so müssen Sie an diese und sämtliche andere i²c-Funktionen 0x50 übergeben, d.h. eine um 1 bit nach rechts verschobene Adresse (SlaveAddr >> 1).

Schreibt den Datenblock, auf den der Pointer P zeigt mit der Länge Length an das i²c-Device mit der Slaveadresse SlaveAddr.

Ließt ein einzelnes Byte von dem i²c-Device mit der Slaveadresse SlaveAddr. Der gelesene Wert wird an Data übergeben.

Ließt einen Datenblock mit der Länge von Length Bytes von dem i²c-Device mit der Slaveadresse SlaveAddr.

Schreibt den Datenblock, auf den der Pointer PWrite zeigt mit der Länge WriteLen an das i²c-Device mit der Slaveadresse SlaveAddr. Nach dem Schreibvorgang wird direkt eine Anzahl von ReadLen Bytes von dem selben i²c-Device gelesen. Die gelesenen Daten werden in den Buffer auf den der Pointer PRead zeigt abgelegt.

Schreibt das Datenbyte Data an Adresse Addr des internen EEProms.

Schreibt den Datenblock auf den der Pointer PData zeigt mit der Länge von Length Bytes an Adresse Addr des internen EEProms.

Ließt ein einzelnes Datenbytes von Adresse Addr des internen EEProms. Der gelesene Wert wird in Data zurückgegeben.

Ließt einen Datenblock mit der Länge von Length Bytes von dem Internen EEProm. Die gelesenen Daten  werden in den Speicher geschrieben, auf den PData zeigt.

function UsbEEpSetAddr(DevNum, SlaveAddr : Byte) : boolean;

Setzt die zu benutzende i2c-slaveadresse des internen EEProms.

Die Adressen der 2 verschiedenen USB2-Module von Braintechnology sind:

Sollten Sie das neue Modul von Braintechnology (V2.5) einsetzen, müssen Sie vor Benutzung von EEprom-Funktionen die Funktion folgendermassen aufrufen:

UsbEEpSetAddr(0, $51);

Das Parallelinterface ist recht flexibel. Das geht so weit, dass man als Firmware-Programmierer den Ablauf von Schreib- und Lesezyklen mit seinen Steuerleitungen geradezu "malen" kann.
Zukünftige Versionen werden ein Programm enthalten mit dem sie die Funktionsweise des Parallelbusses selber definieren können. Es erstellt einen Datenblock den sie mit Hilfe der Funktion UsbParInitUsingArray an den USB Controller übermitteln. Das Programm befindet sich momentan in der Testphase. Sollten sie Interesse an einem Test haben, melden Sie sich (siehe Kontakt)!
Ansonsten können Sie einen der 10 vordefinieren Parallelbus-Modi nutzen.

Mit Hilfe des Parallelbusses sind Sie in der Lage grosse Datenmengen schnell zu übertragen. Unabhängig von dem gewählten Modus unterliegt er gewissen Eigenschaften. Im Detail sind dies:

• Werden mehr als 512 Byte mittels UsbParOut() oder UsbParIn() übertragen, so werden die Daten in maximal 512 Byte grossen Blöcken übertragen. Beispiel:
  UsbParOut(0, @Buffer, 25); // Überträgt einen zusammenhängenden 25 Byte grossen Datenblock
UsbParOut(0, @Buffer, 512); // Überträgt einen zusammenhängenden 512 Byte grossen Datenblock
UsbParOut(0, @Buffer, 1500); // Überträgt zwei 512 Byte grosse Datenblöcke und einen 476 Byte grossen Datenblock
• Wird die USB2DLL in Zusammenhang mit einer USB1.1 Schnittstelle benutzt, so werden die Daten zu 64 Byte (statt 512 Byte) grossen Datenblöcken zusammengefasst und übertragen.
• Auch der Parallelbus unterliegt den im Abschnitt Latenzzeiten und Geschwindigkeit erwähnten Latenzzeiten. UsbParOut und UsbParIn besitzen eine Latenzzeit von ca. 1/8ms (USB1.1: 1ms).

Innerhalb von Datenblöcken werden die einzelnen Datenworte zeitlich äquidistant übertragen. Die Abstände zwischen den Datenblöcken, in denen keine Daten übertragen werden, hängen von dem verwendeten Parallelbusmodus ab.

Deshalb werden Anwendungen die auf äquidistante Datenübertragung >512 Byte angewiesen sind einen FIFO benötigen.

function UsbParInit(DevNum, mode :Byte) : boolean;

Initialisiert das Parallelinterface mit einem der vordefinierten Modi (mode). Eine Initialisierung ist zwingend notwendig um Daten über das Parallelinterface ein- oder auszugeben. 

Folgende Modi sind implementiert:

mode	Taktquelle	Busbreite	Max. Übertragungsgeschwindigkeit (Burst Datenrate)
0	Intern	8 Bit	48 MB/s
1	Intern	16 Bit	96 MB/s
2	Extern	8 Bit	=IFCLK
3	Extern	16 Bit	=IFCLK*2
4	Intern	8 Bit	4.8 MB/s
5	Intern	16 Bit	9.6 MB/s
6	Extern	8 Bit	IFCLK/10
7	Extern	16 Bit	IFCLK/5
8	-	8 Bit	Aufgrund des Handshakings abhängig von der angeschlosenen Hardware
9	-	16 Bit	Aufgrund des Handshakings abhängig von der angeschlosenen Hardware

function UsbParInitUsingArray(DevNum, Data : Pointer) : boolean; 

Initialisiert das Parallelinterface mit Hilfe eines 152 Byte großen Arrays. Falls Sie spezielle Anforderungen an den Parallelbus haben, die durch die oben beschriebenen Standard-Modi nicht abgedeckt sind, so können wir den Bus nach Ihren Anforderungen gestalten und schicken Ihnen einen 152 Byte großen Datenblock zu, den Sie mit Hilfe dieser Funktion aktivieren. Ein zusätzlicher Aufruf der Funktion UsbParInit darf dann nicht erfolgen.

Momentan wird eine Anwendung entwickelt, mit der Sie selber die Funktionsweise des Parallelbusses definieren und diesen Datenblock erstellen können. Sie befindet sich momentan in der Testphase und wird vorraussichtlich in der nächsten Version enthalten sein.

Unter "normalen" Bedingungen werden Sie diesen Befehl jedoch nicht aufrufen müssen.

function UsbParOut(DevNum : Byte; Data : Pointer; Len : Word) : boolean; 

Gibt eine Anzahl von Len Datenworte auf dem Parallelbus aus. Data ist ein Zeiger auf einen Datenblock der die zu übermittelnden Daten enthält.

Beispiele:

Befindet sich das Parallelinterface im 8 Bit Modus und es sollen 768 Bytes übermittelt werden:

UsbParOut(0, @Daten, 768);

Befindet sich das Parallelinterface im 16 Bit Modus und es sollen 768 Bytes (=384 Words) übermittelt werden:

UsbParOut(0, @Daten, 384);

function UsbParIn(DevNum : Byte; Data : Pointer; Len : Word) : boolean; 

Liesst Len Datenworte von dem Parallelbus ein. Data ist ein Zeiger auf einen Datenblock, der mit den gelesenen Daten gefüllt wird.

Beispiele:

Befindet sich das Parallelinterface im 8 Bit Modus und es sollen 768 Bytes gelesen werden:

UsbParIn(0, @Daten, 768);

Befindet sich das Parallelinterface im 16 Bit Modus und es sollen 768 Bytes (=384 Words) gelesen werden:

UsbParIn(0, @Daten, 384);

function UsbGetRdyState(DevNum : Byte; var Rdy : Byte) : boolean; stdcall;

Liefert in Rdy den Zustand der RDYx-Leitungen Zurück (RDY0, RDY1, etc.).

Der Zustand von Bit 0 entspricht dem von RDY0, Bit1 RDY1, ...

• Programmierung von Beispielen und Includes für Visual C++, LabView und Java
• Programmierung von Eventsteuerung, die bestimmte Programmteile nach dem Auftreten von Hardwareinterrupts ausführt (z.B. Drücken eines an dem Interface angeschlossenen Tasters)
• ...und vieles anderes