VORLÄUFIGE Beschreibung
Version: 1.00 vom 07.04.01
Name: jnutl.dll (DOWNLOAD)
OS: Win95/98/NT (32 bit
Windows)
Autor: Josef Neulinger, Ingenieurbüro
Josef Neulinger
Inhalt:
Allgemeines: ................ Kap. 1
Kommunikation: .............. Kap. 2
API: ........................ Kap. 3
Datenstrukturen: ............ Kap. 4
Kodierung und Konstanten: ... Kap. 5
Links: ...................... Kap. 6
Die DLL verwendet ausschließlich Routinen mit der
Aufrufkonvention
Standardcall. Die DLL unterstützt den Anschluß von
mehreren
Racecontrol Sensorboxen (maximal 4), ist also multiplexfähig.
In dieser Version ist noch keine Synchronisierfunktion zwischen
einzelnen Sensorboxen realisiert. D.h. eine eventuelle
Synchronisation
mehrerer Sensorboxen muß noch durch das Anwenderprogramm
erfolgen.
Um universell einsetzbar zu sein, wird die gesamte Low-Level
Kommunikation mit der Sensorbox dem Anwenderprogramm
überlassen.
Wie das Anwenderprogramm mit der Sensorbox kommuniziert ist im
Abschnitt "Kommunikation" beschrieben.
2. Kommunikation
================
Die Kommunikation zwischen PC und Sensorbox erfolgt über
eine
Standard PC Seriellschnittstelle (COM-Schnittstelle). Es erfolgt
der Datenaustausch über eine normale asynchrone
Übertragung
von
Binärdaten. Die Schnittstelle der Sensorbox unterstützt
eine
bidirektionale halbduplex Datenübertragung. Die Datenrichtung
wird dabei durch das RS232 Handshake Signal DTR umgeschalten.
Die Schnittstelle muß wie folgt eingestellt werden:
Baudrate: 4800
Zeichenlänge: 8 bit
Parität: keine
2.1 Empfangen von Daten:
========================
Bei DTR = True sendet die Sensorbox ständig Daten an den PC.
Der PC muß diese Daten 1:1 entgegen nehmen und zur Auswertung
einfach an die DLL weiterreichen (Empfangsroutine: _RX_data@8).
2.2 Senden von Daten:
=====================
Ein Senden von Daten an die Sensorbox ist erforderlich, wenn
die Einstellung der Sensorbox geändert werden muß.
Insbesondere
wenn die Links-/Rechts-Zuordnung der Kanäle, die
Empfindlichkeit
oder die Signalfilterfunktionen verändert werden müssen.
Für
den Fall, daß die Sensorbox in der Grundeinstellung betrieben
wird, könnte auch auf ein Senden von Daten zur Sensorbox
gänzlich verzichtet werden. Dies wird jedoch NICHT empfohlen,
da wichtige Leistungsmerkmale der Sensorbox erst durch
entsprechende Einstellungen wirksam werden! Das Senden ist ein
relativ komplizierter Ablauf, deshalb wird die Aufbereitung
der Sendedaten auch durch die DLL übernommen. Das Senden darf
nämlich nicht zu jedem beliebigen Zeitpunkt eingeleitet werden,
sondern muß auf den Empfangsdatenstrom aufsynchronisiert
werden.
Auch diese Synchronisierfunktion wird in der DLL mit erledigt.
Das Anwenderprogramm muß dazu lediglich dafür sorgen,
daß die Empfangsdaten ohne größere
Zeitverzögerungen
an die
DLL durchgereicht und die Sendedaten möglichst ohne
grössere
Zeitverzögerungen an die Sensorbox übertragen werden.
Sollte (da Windows nicht Echtzeitfähig ist) das Sendetelegramm
zu spät oder mit zu großen Verzögerungen ausgegeben
werden,
so ignoriert die Sensorbox diese Einstelldaten. Das Anwender-
programm braucht sich jedoch nicht darum zu kümmern. Die
DLL prüft selbständig, ob die Box richtig eingestellt
ist
und erzeugt automatisch eine weitere Sendedatenübertragung,
wenn die letzte nicht korrekt empfangen wurde. Durch diese
Technik ist es auch möglich, daß die Sensorbox im
laufenden
Betrieb umgesteckt, ausgeschaltet oder an andere PCs
angeschlossen werden kann. Sie wird bei Wiederaufnahme der
Kommunikation automatisch immer richtig eingestellt, ohne
daß sich das Anwenderprogramm direkt darum kümmern
muß!
3. API (Application Program Interface)
======================================
In der DLL stehen folgende API Routinen zur Verfügung:
Kap. 3.1: _InitBoxes@0 : ......
Initialisierung
der DLL
Kap. 3.2: _OpenBox@8 : ........
Anmelden
einer Sensorbox
Kap. 3.3: _RX_data@8 : ........
Übertragung
der Sensorboxdaten
Kap. 3.4: _Get_Event@4 : ......
Nachricht abholen
Kap. 3.5: _Get_TStamp@4 : .....
aktuellen Time Stamp lesen
Kap. 3.6: _Get_TXDat@4 : ......
Sendedaten
lesen
Kap. 3.7: _Timeout_Check@0 :
.. Timeout Überwachung
Kap. 3.8: _JNLongAdd@8 : ......
Utility 2 Long-Werte addieren
Kap. 3.8: _JNLongSub@8 : ......
Utility 2 Long-Werte subtrahieren
3.1 _InitBoxes@0 (Initialisierung der DLL)
==========================================
Prototyp: word _InitBoxes@0 (void)
Diese Routine initialisiert die komplette DLL, schliesst
alle angemeldeten Sensorboxen. Diese Routine MUSS als
erste Aktion der RACECONTROL API DLL aufgerufen werden.
Der Rückgabewert der Funktion ist die Versionsnummer
der DLL. Im High-Byte befindet sich die Versionsnummer
vor dem Punkt, im Low Byte die Versionsnummer nach dem
Punkt. Die Version 1.31 würde also als 0x11f übergeben.
3.2 _OpenBox@8 (Anmelden einer Sensorbox)
==========================================
Prototyp:
word _OpenBox@8 (word boxnum, struct BOXCONFIGURATION
*p);
Mit dieser Funktion wird eine Sensorbox angemeldet. Dazu
wird eine Boxnummer (boxnum) angegeben. Diese kann zwischen
0 und 3 liegen. Wenn nur eine einzige Sensorbox vorhanden
ist, dann sollte diese die Nummer 0 bekommen. Weitere
Sensorboxen erhalten dann die Nummern 1, 2 bis 3. In dieser
Version des API ist die Zuteilung der Boxnummern noch beliebig,
für Kompatibilität zu späteren Versionen mit
Synchronisation
zwischen den Sensorboxen soll jedoch eine fortlaufende
Reihenfolge eingehalten werden. Im 2. Parameter wird ein
Pointer auf die Datenstruktur BOXCONFIGURATION
(siehe Kapitel
4) übergeben. In dieser Struktur werden der DLL die
Einstellwerte für die Sensorbox übergeben. Diese
können
auch
nachträglich geändert werden, Dazu wird einfach eine
bereits
angemeldete Sensorbox erneut mit dieser Funkion angemeldet.
Es ist zu beachten, daß ein neues Anmelden zu einer
Rücksetzung
der Zeitparameter führt. Deshalb sollte dieses neue Anmelden
nicht innerhalb eines Rennens erfolgen, da sonst Zeitwerte
nicht mehr zueinander passen.
Die Funktion gibt den Wert 0 zurück, wenn alles o.k. ist,
oder eine Fehlernummer.
3.3: _RX_data@8 (Übertragung der Sensorboxdaten)
=================================================
Prototyp:
word _RX_data@8 (word boxnum, byte rxdata);
Mit dieser Funktion werden die von der Sensorbox empfangenen
seriellen Datenbytes der DLL übergeben. Dazu wird der Funktion
die Boxnummer (siehe _OpenBox@8) übergeben. Im 2. Parameter
wird das empfangene Byte übergeben.
Die Funktion gibt entweder 0, die EVENT_AVAILABLE-Kennung
oder
eine Fehlernummer zurück. Gibt die Funktion eine 0
zurück,
so
sind keine neuen Informationen verfügbar. Wenn die
EVENT_AVAILABLE-Kennung zurückgegeben wird, dann liegen eine
oder mehrere Nachrichten im Nachrichtenpuffer zur Abholung
bereit.
3.4: _Get_Event@4 (Nachricht abholen)
=====================================
Prototyp:
word Get_Event (struct EVENT *P)
Mit dieser Funktion kann eine Nachricht aus dem Nachrichtenpuffer
abgeholt werden. Dazu muß der Routine ein Pointer auf eine
Struktur übergeben werden, in der diese dann die nächste
Nachricht
aus dem Nachrichtenpuffer überträgt. Die Funktion liefert
den
Wert 0 zurück, wenn eine Nachricht ausgelesen wurde bzw.
ungleich
0, wenn keine Nachricht vorhanden war. War keine Nachricht
vorhanden, so enthält die EVENT Struktur den Eintrag EVENT_NOP.
3.5: _Get_TStamp@4 (Nachricht abholen)
======================================
Prototyp:
long _Get_TStamp@4 (word boxnum);
Mit dieser Funktion kann der aktuelle Zeitstempel der
entsprechenden
Sensorbox abgefragt werden. Dies ist zum Beispiel dann erforderlich,
wenn das Anwenderprogramm ein Rennen startet. Der Zeitpunkt von
Sensor-EVENTS werden dann auf diesen mit _Get_TStamp@4 ermittelten
Zeitpunkt bezogen. Siehe auch Kap. 5.1
(Zeitwerte)
3.6: _Get_TXDat@4 (Sendedaten lesen)
====================================
Prototyp:
int _Get_TXDat@4 (word boxnum);
Mit dieser Funktion werden Sendedatenbytes von der DLL
ausgelesen.
Ist ein Byte vorhanden, so wird dieses Byte zurückgegeben.
Ist
kein weiteres Byte vorhanden, gibt die Routine -1 zurück.
Diese Funktion soll nach einem EVENT_TX der entsprechenden
Sensorbox benutzt werden, um die von der DLL gebildeten Daten
zur Sensorbox zu senden. Vor dem Senden ist die COM-Steuerleitung
DTR auf FALSE zu schalten. Nach dem das letzte Byte gesendet
wurde, ist die Leitung DTR wieder auf TRUE zu setzen.
Wenn ein EVENT_TX von einer Sensorbox ausgelöst wurde, so
soll
das Anwenderprogramm die Sensorbox wieder in den Status offline
schalten. D.h. nach dem die Sensorbox den Sendestring erhalten
hat, liefert sie erneut Daten an den PC und die DLL generiert
einen neuen EVENT_BOXfound, so bald die Kommunikation wieder
aufgebaut ist.
3.7: _Timeout_Check@0 (Timeout Kontrolle)
=========================================
Prototyp:
word _Timeout_Check@0 (void);
Diese Funktion dient zur Überwachung des Datenempfangs von
einer
Sensorbox. Sie sollte periodisch aufgerufen werden, aber nicht
öfters als ca. 1000 mal pro Sekunde. Wenn längere Zeit
eine
aktive Sensorbox keine Zeichen mehr empfangen hat, so wird
durch diese Funktion ein EVENT_BOXlost erzeugt.
3.8: _JNLongAdd@8 und _JNLongSub@8 (Long Arithmetik)
====================================================
Prototyp:
long _JNLongAdd@0 (long a, long b);
long _JNLongSub@0 (long a, long b);
Diese Funktionen dienen zum Addieren bzw. zum Subtrahieren von
2 long-Werten. Sie sind hauptsächlich für Visual Basic
Programmierer
gedacht, da in Visual Basic ein arithmetischer Überlauf zu
einem
Fehler führen würde.
4. Datenstrukturen
==================
In diesem Kapitel sind die Strukturen und Inhalte von
Datenfeldern beschrieben, die zum Betrieb des Racecontrol
API erforderlich sind.
verwendete Datentypen:
byte: vorzeichenlose 8 Bit Zahl
(0...255)
int: 15 Bit Zahl mit Vorzeichen
(-32768 ... 32767)
word: vorzeichenlose 16 Bit Zahl
(0...65535)
bool: 16 Bit Boolean (0 = false,
<> 0: true)
long: 31 Bit Zahl mit Vorzeichen
(0x80000000 ... 0x7fffffff)
dword: vorzeichenlose 32 Bit Zahl
(0...0xffffffff)
ACHTUNG C-PROGRAMMIERER: Der Datentyp int des Racecontrol API
entspricht nicht dem Datentyp int beim 32 Bit C, sondern dem
Typ short!
4.1 Struktur BOXCONFIGURATION
=============================
struct BOXCONFIGURATION
{
word res0; // reserviert
word res1; // reserviert
word level; // Empfindlichkeit (0...130)
word verz; // Verzögerung in ms
(0...50)
word nachl; // Nachlauf (0...15)
bool zzx; // Zwischenzeitsensor
R/L getauscht
bool szx; // Start-/Zielsensor R/L
getauscht
bool enable; // Überwachung der Box-Parameter
};
Bedeutung der einzelnen Parameter:
Mit dem Parameter enable wird eingestellt, ob die DLL
automatisch die Boxkonfiguration zur Sensorbox überwacht (true)
oder nicht (false). Es wird dringend empfohlen, die
Einstellung false nur zum Testen zu verwenden, da die
Sensorbox wichtige Funktionsmerkmale nicht unterstützt,
wenn sie nur in der Grundeinstellung betrieben wird!!!
4.2 Struktur EVENT
==================
struct EVENT
{
long comm;
long wcnt;
};
Das Element comm enthält den Typ
der
Nachricht. Siehe hierzu
die Kodierung in Kapitel 5.2. Events tragen einen Zeitstempel,
der in Element wcnt übergeben wird. Bei einigen
Nachrichtentypen,
bei denen der Zeitpunkt üblicherweise keine Rolle spielt,
kann
der korrekte Zeitstempel auch fehlen.
Siehe Kapitel 5.1 zur Kodierung der Zeitstempel.
5. Kodierung und Konstanten
===========================
5.1 Zeitwerte
=============
Zeitwerte werden in RaceControl immer als Abstand zweier
Zeitpunkte berechnet. Ein Zeitpunkt wird dabei durch einen
sogenannten Zeitstempel (Time Stamp) festgelegt. Diese
Zeitstempel in RaceControl sind stets 32 Bit Ganzzahlen
mit der Einheit 1/4800 Sekunden (long bzw. dword).
Ein Zeitstempel markiert einen relativen Zeitpunkt.
Dabei ist völlig undefiniert, auf was dieser Zeitpunkt bezogen
ist.
Ein Rennen startet nicht notwendigerweise zum Zeitpunkt 0 sondern
zu irgend einem x-beliebigen Zeitpunkt. Zeitwerte sind daher immer
als Differenz zu einem Bezugszeitpunkt zu ermitteln!!!
Beispiel: Zeitdauer = wcnt[2] - wcnt[1]; Es ist zu beachten, dass
diese Subtraktion Modulo 32 Bit erfolgt, d.h. es kann dabei ein
arithmetischer Überlauf eintreten (Achtung in Visual BASIC
!!!).
Die Einheit dieser Zeitwerte ist 1/4800 Sekunden.
Zur Umwandlung dieser Zeitwerte in Stunden, Minuten, Sekunden
bzw. Tausendstel Sekunden werden Hilfsfunktionen in den
nächsten DLL Versionen verfügbar sein.
5.2 EVENT.comm
==============
Die Kodierung des Elements comm der Struktur
EVENT ist wie
folgt:
Die höchstwertigen 2 Bytes des Wertes comm sind zur Zeit
ohne Funktion. Bei den folgenden Festlegungen ist nur das
niederwertige Wort des Wertes betrachtet.
Im niederwertigen Byte dieses Wortes sind folgende Informationen
zu finden, wenn Einzelsensor-Nachrichten (EVENT_SENSON,
EVENT_SENSOFF) vorliegen:
Im Bit 0 wird Links/Rechts dargestellt. 0 = Links, 1 = Rechts.
Im Bit 1 wird der Zwischenzeit- oder Start-/Ziel-Sensor
unterschieden, wobei 0 für Zwischenzeit steht.
Im Bit 2 und darüber wird die Boxnummer angezeigt.
Im höherwertigen Byte (also ab Bit 8) wird der EVENT-Typ
kodiert. Folgende Kodierungen sind bisher definiert:
EVENT_NOP
0x00XX // no event
EVENT_SENSON
0x02XX
// sensor activates
EVENT_SENSOFF 0x03XX
// sensor deactivates
EVENT_BOXfound 0x04XX //
Box activates
EVENT_BOXlost 0x05XX
// Box error, connection lost
EVENT_TX
0x06XX // tx request
Beispiele:
Fährt also ein Auto über den rechten Start-/Ziel-Sensor
von Sensorbox 0, so werden die EVENTS 0x0203 und 0x0303
ausgegeben. Fährt ein Auto über den linken Zwischenzeit-
Sensor von Sensorbox 2, so erfolgen die Events 0x0208 und
0x0308
Wird die Sensorbox 3 als gültig erkannt, so wird der
Event 0x040C erzeugt. Das Anwenderprogramm kann mit diesem
Event also z.B. die rote POWER LED des entsprechenden
Sensorbox Symbols auf dem Bildschirm einschalten.
5.3 Kodierung Fehlermeldungen
=============================
Folgende Fehlerkodierungen sind definiert:
RC_NOERROR
0x0000 // kein Fehler
GENERAL_ERROR
0x8000 // allgemeiner Fehler
UNDEFINED_BOXNUM
0x8001 // falsche Boxnummer
USED_BOXNUM
0x8002 // Box bereits geöffnet
UNUSED_BOXNUM
0x8003 // Box noch nicht geöffnet
NO_EVENT
0x8004 // Kein Event verfügbar
5.4 sonstige Kodierungen
========================
EVENT_AVAILABLE
0x0002 // Nachricht verfügbar (_RX_data@8)
Homepage
Ingenieurbüro
Josef Neulinger