----------------------------------------------------------				
| Erweiterung der de_la_exp1.dll
| um neue Interpretations-Routinen
  Stand: 19.05.2010
----------------------------------------------------------

Im folgenden wird erlutert, wie einzelne, eigene Interpretaionsroutinen 
zur de_la_exp1.dll hinzugefgt werden und somit spter in der Software 
Logi+ verwendet werden knnen.
Es empfiehlt sich, das Projekt mit Microsoft Visual-C++ zu kompilieren, 
da alle ntigen Einstellungen hier bereits im Projekt enthalten sind.


Grundstzlich mssen Sie zur Erweiterung der DLL in mehreren Funktionen 
Eintrge hinzufgen, welche in diesem Dokument erlutert werden. In einer 
eigenen Funktion knnen Sie dann die Daten vom Logik-Analysator verarbeiten 
und an die Software weiterreichen.


Die Haupt-Funktionen befinden sich in der "de_la_exp1.cpp", in welcher die 
ersten Erweiterungen hinzugefgt werden mssen.


Testen der neuen Quell-Codes:

Um das Projekt whrend der Entwicklung zu testen, mssen Sie die Quellcodes 
zunchst Compilieren (Erstellen/Alles neu erstellen). Danach wechseln Sie in 
den Unterordner "00Build_Dll" und fhren die Datei "00Build.bat" aus. Im selben 
Verzeichnis finden Sie dann die 2 neuen, von der LA-Software bentigten Dateien 
"de_la_exp1.dll" und "de_la_exp1.lib".
Kopieren Sie beide Dateien in das Verzeichnis, in welches Sie die Software Logi+
installiert haben. Es wre durchaus sinnvoll, die beiden Originaldateien, welche 
sich bereits in dem Ordner befinden, vorher zu sichern. Danach knnen Sie diese 
berschreiben und die Software testen.


1) Interpreter-Namen hinzufgen
----------------------------------------------------------

Um der Software (SW) den Namen eines neuen Interpreters zu nennen, existiert 
die Funktion

	LA_EXP_GetInterpreterNames(ULONG todo, char * text, ULONG text_length)

Wird hier der Wert todo == 0 bergeben, so muss die Funktion die Anzahl der 
einzelnen Interpreter zurck liefern. Bei 3 Interpretern z.B. muss die Funktion 
dann 3 zurck geben.

Danach wird die Funktion fr jeden Interpreter einzeln aufgerufen - in todo 
steht dann die Nummer des Interpreters (von 1 bis n). In das Zeichen-Array
*text muss dann der Name des Interpreters kopiert werden. Das Array ist schon 
alloziert und besitzt eine Gre von "text_length".

Bsp.-Code: - 4-ter, neuer Interpreter Namens "Bus-System A":

	//...
		case 4:
		{
			strncpy(text, "Bus-System A\0", text_length);
			break;
		}


2) Konfigurationsmglichkeiten angeben
-----------------------------------------------------------

Nachfolgend muss Logi+ die Einstellungsmglichkeiten des Interpreters 
wissen, welche sie mit folgender Funktion abruft:

	ULONG LA_EXP_GetConfigurationInfo(ULONG InterpreterNr, ULONG todo, char * name, 
					 ULONG name_length, char * auswahl, ULONG auswahl_length)


In einer switch-case Anweisung, welche hier erweitert werden muss, werden 
dann die einzelnen Interpreter behandelt. 

Hat todo den Wert 0, so muss die Anzahl der Parameter zurckgegeben werden, 
z.B. 3 fr 3 Parameter (Darstellung, Datenkanal, Geschwindigkeit).

Danach luft todo die einzelnen Parameter durch (im Beispiel: 1..3), um 
die Anzeigetexte zu erlangen. Zu jedem Parameter muss dann angeben werden, 
um welchen Typ es sich handelt. Folgende Typen sind definiert:

	Type			Beschreibung

	PARAM_CHANNEL		Zu diesem Parameter kann spter ein Kanal eingestellt 
				werden. Dieser Typ findet bei Einstellungen wie "Datenkanal", 
				"Clock" oder "Chip-Select" Anwendung.

	PARAM_SELECTION		Hier wird spter eine Drop-Down-Menu angezeigt, dessen Inhalt 
				selbst definiert ist. Dies kann z.B. zur Geschwindigkeitsangabe,
				verschiedenen Modis oder Darstellungsarten verwendet werden.

Grundstzlich muss zunchst der Name des Parameters festgelegt werden, was 
in dem Zeichen-Array "name" geschieht. der Parameter ist spter der Rckgabetyp 
und wird mit return angegeben (im Code mittels der Variable nRet).

Handelt es sich um eine Kanal-Auswahl, muss nichts weiter angegeben werden. 
Bei einer Text-Auswahl (PARAM_SELECTION) muss das Array "auswahl" noch gefllt 
werden. Die einzelnen Einstellungen mssen dann, getrennt durch ein Semikolon, 
hierhin kopiert werden.

Beispiel-Code:
	//...
	case 4:		//Bus-System A
	{
		switch(todo)
		{
		case 0:		//Anz. der Parameter
			return 3;
			break;
		case 1:		//Darstellung
			{
				nRet = PARAM_SELECTION;
				strncpy(name, "Darstellung\0", name_length);
				strncpy(auswahl, "Dezimal;Hexadezimal;Binr;ASCII\0", auswahl_length);
				break;
			}
		case 2:		//Datenkanal
			{
				nRet = PARAM_CHANNEL;
				strncpy(name, "Datenkanals\0", name_length);
				break;
			}
		case 3:		//Geschwindigkeit (Baudrate)
			{
				nRet = PARAM_CHANNEL;
				strncpy(name, "Baudrate\0", name_length);
				strncpy(auswahl, "128kBit;256kBit;512kBit;1Mbit;1,5MBit\0", auswahl_length);
				break;
			}


3) Interpreter bei Selektion in die "Warteschleife" setzen
-----------------------------------------------------------

Whlt der Benutzer in der SW einen Interpreter aus, so wird dies 
an die DLL weitergeleitet. Hierzu gibt es die Funktion 

	ULONG LA_EXP_setInterpreter(ULONG channelNo, ULONG nInterpreter, ULONG parCount)

Dabei wird die Interpreter-Nr., die Kanal-Nr. und die Anzahl der Parameter bergeben. 
Nun wird geprft, ob der Kanal bereits belegt ist. Ist dies nicht der Fall, so kann der 
Interpreter nun hinzugefgt werden. Folgender Quellcode soll dies verdeutlichen:

	//...
	case 4:	// Bus-System A
		{
			if (LL_ChanInfoGet(ChanList, channelNo) == NULL)
			{
				ChannelInfo ChanInfo;
				ChanInfo.bUseInterpreter = false;
				ChanInfo.nNumParamsSet	 = 0;
				ChanInfo.nChannel		 = channelNo;
				ChanInfo.nInterpreterNr  = nInterpreter;
				ChanList = LL_ChanInfoAdd(ChanList, ChanInfo);	
				
				#ifdef DebugMode
					sprintf(msg, " [DLL] SetInterpreter(): Erkannter Interpreter: Bus-System A(Kanal %d   Interpreter: %d  Anz.Param.: %d)\n",
											channelNo, nInterpreter, parCount);	
					PrintDebug(msg);
				#endif
			}
			break;
		}



4) Konfigurations-Struktur erstellen und fllen
-----------------------------------------------------------

Nun muss eine neue Struktur angelegt werden, welche die einzelnen Parameter 
speichert. Diese muss in der Datei structs.h definiert werden. Struktur 
aus dem Beispiel:

	//Konfiguration Bus-System A
	struct BSAConfig
	{
		int nChannelData;	//Datenkanal
		int nBaud;		//Baudrate

		unsigned char cType;	//Darstellung (hex/bin..?)
	};

Auch muss diese Struktur in der Kanal-Beschreibung mit aufgenommen werden. 
Diese Kanalbeschreibung befindet sich in der Datei "llist_ChanInfo.h":

struct ChannelInfo
{
	int bUseInterpreter;
	int nNumParamsSet;
		
	int nChannel;
	int nInterpreterNr;

	struct SPIConfig	SpiCfg;
	struct RS232Config	RsCfg;
	struct CANConfig	CanCfg;
	//..eigener Interpreter:
	struct BSAConfig	BsaCfg;
};


Diese Konfigurationsstruktur (BSAConfig) muss dann gefllt werden. Die Logi+ Software
ruft dazu fr jeden Parameter des Interpreters folgende Funktion auf:

	ULONG LA_EXP_setConfiguration(ULONG channelNo, ULONG parNo, ULONG nChannel, ULONG nSelection)

Dabei gibt channelNo den "Spezial-Kanal" an, in welchem ein Interpreter aktiviert 
wurde, parNo die Nummer des Parameters, beginnend bei 1. In der schon programmierten 
switch-case Anweisung knnen die einzelnen Parameter dann abgefragt werden.

Beispiel-Code:

		case 4:		//Bus-System A
		{

			switch(parNo)	// 3 Parameter (Type, Kanal, Baud
			{
			case 1:	// Type
				{
					ChanList->ChanInfo.BSACfg.cType = (unsigned char)nSelection;
					ChanList->ChanInfo.nNumParamsSet++;
					break;
				}
			case 2: // Datenkanal
				{
					ChanList->ChanInfo.BSACfg.nChannelData = (unsigned char)nChannel-1;
					ChanList->ChanInfo.nNumParamsSet++;
					break;
				}
			case 3:	//Baud
				{
					int nBaud = 0;
					switch(nSelection)
					{
						case 1: nBaud = 128000;		break;
						case 2: nBaud = 256000;		break;
						case 3: nBaud = 512000;		break;
						case 4: nBaud = 1000000;	break;
						case 5: nBaud = 1500000;	break;
						default: nBaud = 0;			break;
					}

					ChanList->ChanInfo.BSACfg.nBaud = nBaud;
					ChanList->ChanInfo.nNumParamsSet++;
					break;
				}
			}
		}

Die Ausgewhlten Parameter beginnen wieder mit dem Index 1. Kanal Null entspricht also einer 1.



5) Aufruf der Interpretations-Routine
-----------------------------------------------------------

Die letzte nderung innerhalb der Datei de_la_exp1.cpp ist dazu da, damit die 
eigene Interpretations-Routine ausgefhrt wird (Welche spter noch genauer 
erlutert und auch erstellt wird).

Diese Routine muss in folgender Funktion aufgerufen werden:


	ULONG la_exp_interprete_data(LA_HWInfo HWInfo, LA_Configuration LAConf, 
					unsigned char *la_buffer, unsigned int todo)

Hier interessieren uns die einzelnen Parameter nicht, interessant ist nur die 
Stelle, an welcher die Interpreter aufgerufen werden:

	//...
	for (i=0;i<nNumChan;i++)
	{
		if (ChanList != NULL)
		{
			if (ChanList->ChanInfo.bUseInterpreter == 1)
			{
			
				switch(ChanList->ChanInfo.nInterpreterNr)
				{
				//...

Hier muss nun unsere Interpretations Routine aufgerufen werden, falls die 
Interpreter-Nr. die unseres Interpreters ist (im Beispiel: 4).

Beispiel-Code:

			case 4:
				{
					int res;
					res = ConvertBSA(HWInfo, LAConf, ChanList->ChanInfo.nChannel, 
									ChanList->ChanInfo.BsaCfg, la_buffer, &DataList);

						#ifdef DebugMode
							sprintf(msg, "                            %d.Spezialkanal(Kanal: %d): CAN 2.0\n", 
								i+1,ChanList->ChanInfo.nChannel);	
							PrintDebug(msg);
						#endif
					break;
				}


Der Name der Funktion kann frei gewhlt werden - die Funktion erstellen 
wir im nchsten Abschnitt. Halten Sie sich bitte an die angegebenen Parameter, 
da Sie dadurch spter alle ntigen Informationen in der Funktion erhalten.


6) Erstellen der Interpretations-Routine
-----------------------------------------------------------


Fgen Sie nun 2 neue Dateien dem Projekt DLL hinzu: ConvertBSA.cpp und ConvertBSA.h.
Ebenso mssen Sie die Dateien in der Haupt-Datei de_la_exp1.cpp zu Beginn mittels 
"#include "de_la_exp1.h" hinzufgen.

Die Header-Datei sollte folgenden Aufbau erhalten:

	#pragma once

	#include <stdio.h>
	#include "structs.h"
	#include "BitOperations.h"

	extern "C"
	{
		#include "llist_data.h"
	}


	int ConvertBSA(LA_HWInfo HWInfo,LA_Configuration LAConf, int nChannel, 
				 BSAConfig BsaCfg, unsigned char *cBuffer, LL_DataNode **dList);


Falls Sie weitere Funktionen bentigen, knnen Sie diese hier natrlich auch 
deklarieren.

Weiter geht es in der entsprechenden .cpp-Datei. Hier mssen Sie nun die Interpretations-
Routine Aufbauen. 


	#include "ConvertBSA.h"

	int ConvertBSA(LA_HWInfo HWInfo,LA_Configuration LAConf, int nChannel, 
					 BSAConfig BsaCfg, unsigned char *cBuffer, LL_DataNode **dList)
	{

		//starten Sie Ihre Interpretations-Routine
	
		//Fehlerbafragen
		//..

		//Daten-Analyse
		//..

		//Datenpakete hinzufgen
		//..

		return 0;
	}

Damit Sie die Roh-Daten analysieren knnen, haben Sie Zugriff auf die Strukturen 
LA_HWInfo und LA_Configuration. Die Roh-Daten befinden sich in dem Puffer cBuffer. 
Mittels der Funktion

	int IsSet(const LA_HWInfo HWInfo,unsigned char *buf, 
				ULONG nChannel, ULONG nSample);

kann berprft werden, ob ein Bit mit angegebenem Kanal (nSample entspricht der Position) 
gesetzt ist, oder nicht. (0, oder 1; bei Fehler -1).



7) Hinzufgen analysierter Daten in die Logi+ Software
-----------------------------------------------------------

Um Datenpakete zur Logi+ Software hinzuzufgen, gibt es folgendes Datenpaket


struct sData
{
	ULONG		nValue;			//Wert des Datenpakets
	ULONG		nStart;			//Begin des Datenpakets
	ULONG		nLength;		//Lnge des Datenpakets
	unsigned char	cText;			//reserviert
	unsigned char	cType;			//reserviert
	unsigned char	cColor;			//vordefinierte Farben
	unsigned char	cChannel;		//Nummer des Kanals

	char cStr[33];				//Anzeige-Text
};

Die Wichtigsten Angaben sind hierbei der Startwert, die Lnge, die Farbe 
und der Text. Bitte vergessen Sie nicht, das Zeichenketten Array mit '\0' zu 
terminieren.
Die Variable nValue kann intern verwendet werden, wird jedoch nicht an 
die LA-Software geleitet. Fr die Logi+ Software ist vor allem der Text wichtig, 
welcher z.B. den Datenwert des Pakets oder auch eine kurze Fehler-Information 
beinhalten kann.

Haben Sie ein solches Paket nun innerhalb Ihrer Analyse heraus gefiltert, so 
mssen Sie dies noch einer Liste hinzufgen. Dies ist folgendermaen mglich:


Beispiel-Code:

	//Test-Paket
	sData Data;

	Data.cText = 0;
	Data.cType = 0;
	Data.nValue = 0;

	Data.nStart = 5;
	Data.nLength = 50;
	Data.cColor = 0;
	Data.cChannel = BsaCfg.nChannelData;
	strncpy(dIdent.cStr, "Test: 123\0",33);
	
	//Paket hinzufgen
	(*dList) = LL_DataAdd((*dList), Data);

Nun wurde das Paket der Datenliste hinzugefgt und wird an die Logi+ Software weitergeleitet.


8) Hinweise
-----------------------------------------------------------

Die Quellcodes der vordefinierten Interpreter sind offen und knnen 
von Ihnen eingesehen werden. Bei Problemen knnen Sie diese als 
Referenzen verwenden.











