Die Asuro Library

2.71

asuro1.gif

Der Asuro

Einführung

Die Asuro Library ist eine Sammlung von C-Funktionen für den Roboter Asuro. Der Asuro wurde vom DLR (Deutschen Zentrum für Luft und Raumfahrt) http://www.dlr.de in Oberpfaffenhofen entwickelt.

Die Ur-Version der Bibliothek wurde von Jan Grewe vom DLR geschrieben. Einige User vom Roboternetz Forum http://www.roboternetz.de/phpBB2 haben die Lib erweitert.

Die Asuro Lib ist ab Version 2.70 nicht mehr nur eine Quellcode Bibliothek sondern eine Objectcode Bibliothek. D.h. die Bibliothek besteht aus einem Archiv von Objekt Files, die normalerweise nicht mehr für jedes Projekt neu übersetzt (compiliert) werden muß, sondern nur noch gelinkt wird. Die Bibliothek selbst muß nur neu übersetzt werden, wenn an den Bibliotheks Funktionen Änderungen oder Definitionen in den Header Files vorgenommen wurden.

Der Vorteil der Objekt Bibliothek gegenüber der Quellode Bibliothek ist die drastisch reduzierte Größe der Hex-Files. Im Gegensatz zur Quellcode Bibliothek werden nur die Objekt Files gelinkt, die vom Benutzer Programm aufgerufen werden. Bei der Quellcode Bibliothek werden immer alle Files gelinkt, unabhängig davon ob sie überhaupt benötigt werden.

Wichtige Links

Der Programm Code der Asuro Bibliothek steht unter der General Public License (GPL)

Voraussetzungen

Um die Asuro Lib zu verwenden wird neben dem Asuro eine Entwicklungsumgebung für die Atmel AVR Prozessoren benötigt. Der Quelllcode der Bibliothek wurde für die AVR-GCC Cross-Compiler Suite geschrieben. Den AVR-GCC ist kostenlos für diverse Plattformen (Windows, Linux, Mac) verfügbar. Es wird die Verwendung der jeweils neuesten Version empfohlen. Die Bibliothek kommt aber auch mit alten Versionen klar. Auf der Asuro CD befindet sich z.B. eine sehr alte WinAVR Version (20030913) aus dem Jahre 2003. Die aktuelle WinAVR Version (20070525) ist hier auf jeden Fall vorzuziehen.

Download Links

Installation

Es gibt 3 Möglichkeiten die Asuro Lib zu downzuloaden und zu installieren.
   SVN Einstellungen:
   Hostname: asuro.svn.sourceforge.net
   Port: 443
   Protocol: HTTPS
   Repository Path: /svnroot/asuro
   Username: SourceForge.net username für SVN Schreibrechte, keiner für Leserechte
   Password: SourceForge.net user password für SVN Schreibrechte, keines für Leserechte
   

Verzeichnis Struktur

Nach der Installation befindet sich folgende Verzeichnis Struktur auf der Festplatte. Das Installationsverzeichnis im folgenden <INST_DIR> genannt, könnte z.B. C:/ASURO_SRC/AsuroLib lauten.

   C:\ASURO_SRC\AsuroLib                     Das Installations Verzeichnis
                        \doc                 Dokumentations Verzeichnis. HTML und HTML Help Dateien
                        \lib                 Bibliotheks Quell Dateien und Objekt Bibiothek
                        \lib\inc             Bibliotheks Header Dateien
                        \examples            Beispiel Projekte
                        \examples\FirstTry   Beispiel Projekt FirstTry
                        \examples\SelfTest   Beispiel Projekt SelfTest
   

Wichtig! Anpassen der Makefiles

Die wichtigste Änderung der AsuroLib spielt sich im Hintergrund ab in den Makefiles. Hier wurde aufgeräumt um die Verwendung der Bibliothek für eigene Projekte zu erleichtern. Es gibt nur noch eine einzige Stelle, die man ändern muß um alle Pfadangaben, die mit der Lib zu tun haben, zu ändern. Das ganze kann natürlich nur funktionieren wenn nur noch diese neuen Makefiles verwendet werden.

Aufgrund der zahlreichen Probleme, die manche Nutzer beimn Installieren der Bibliothek hatten, wurde der Installationsprozess vereinfacht. Die compilierte Asuro Bibliothek 'libasuro.a' muß nun nicht mehr in das Lib-Verzeichnis des AVR-GCC bzw. WinAVR Compilers kopiert werden, sondern verbleibt im Verzeichnis <INST_DIR>/lib. Statt dessen wird im Makefile der Pfad zur Bibliothek eingetragen. Der Verzeichnisname sollte mit normalem Slash (/) angegeben sein nicht mit Backslash (\). In den aktuellen Makefiles geschieht dies (siehe Examples Ordner) durch folgende Zeilen: Hinweis: ein # am Anfang in einer Zeile eines Makefiles bedeutet. Dies ist ein Kommentar, kein Kommando zum Ausführen

   # additional Include path for libraries
   LIBPATH = ../../lib
   
In vorigen Beipiel wurden relative Pfade verwendet. Das geht solange gut, solange alle Projekte wie die Beispiel Projekte aus der Asuro Lib in der gleichen Verzeichnisebene (2 Verzeichnisebenen tiefer als die lib) liegen. Ist dies nicht der Fall, sollte man statt dessen absolute Pfade verwenden, wie z.B.:
   # additional Include path for libraries
   LIBPATH = C:/ASURO_SRC/AsuroLib/lib
   
Falls man die Bibliothek in ein Verzeichnis mit Leerzeichen installiert hat, muß man die Pfadangaben in Hochkommas einfügen
   # additional Include path for libraries
   LIBPATH = "C:/Eigene Dateien/ASURO_SRC/AsuroLib/lib"
   

Neue Projekte

Will man ein eigenes Programm für den Asuro erstellen, welches die Asuro Bibliothek verwendet kopiert man besten den kompletten Ordner <INST_DIR>/examples/FirstTry in einen neuen Ordner. Dann muß man nur noch das Makefile wie oben beschrieben anpassen, seine Programm schreiben und sollte es dann übersetzen können. In dem Projekt Ordner dürfen sich aber keine Überbleibsel von vorherigen Asuro Libs (asuro.c, asuro.h) befnden. Der Compiler und Linker übersetzt/bindet sonst nämlich diese alten Dateien ein. Auch sollte die asuro.h immer in Hochkommans eigebunden werden, nicht in spitzen Klammern. Header Dateien in spitzen Klammern werden als System Include Dateien im AVR Include Verzeichnis gesucht.

Enthält das eigene Projekt zusätzliche Quelldateien (außer test.c) müssen diese ebenfalls im Makefile eingetragen werden. Als Beispiel Projekt bietet sich hier das Makefile aus dem Selbsttest an <INST_DIR>/examples/SelfTest. Hier werden noch mehrere Quelldateien dazugefügt.

  # If there is more than one source file, append them above, or adjust and
  # uncomment the following:
  SRC += asuro.c \
  Test.c main.c \
  Demo.c LineDemo.c IRDemo.c PCDemo.c RechteckDemo.c 
   
Auch der Name der Zieldatei (sonst immer test.hex) wurde hier angepaßt. Es muß natürlich eine Quelldatei geleichen Namens existieren.
   # Target file name (without extension).
   TARGET = SelfTest
   
Ebenfalls eine Besonderheit stellt die folgende Zeile dar. Dadurch wird der Empfang von RC5 Infrarot Signalen aktiviert.:
   # Optional Definitions for conditional compiling 
   DEF = RC5_AVAILABLE
   
Zudem muß noch die folgende Zeile geändert werden, damit das Defien auch wirksam wird.
   #CFLAGS = -g -O$(OPT) -I$(INCPATH) 
   CFLAGS = -g -O$(OPT) -I$(INCPATH) -D$(DEF) \
   
Dieses Define findet man in der asuro.c wieder. Dadurch werden im Timer2 Overflow Interrupt zusätzlich die beiden Zeilen nach ifdef und vor dem endif mit übersetzt und zur Laufzeit des Programmes natürlich auch ausgeführt.
   #ifdef RC5_AVAILABLE
     if (enableRC5 && !(count36kHz % 8)) 
       IsrRC5(); // wird alle 222.2us aufgerufen
   #endif  
   

Beispiel Projekte

Im Ordner <INST_DIR>/examples befiden sich einige Beispiel Projekte, die sich für eigene Projekte anpassen oder erweitern lassen bzw. als Vorlage füre eigene Projekte dienen sollen.

Compilieren der Asuro Library

Nimmt man Änderungen an der Bibliotheks Funktionen oder den Header Files vor, muß die Bibliothek logischerweise neu übersetzt werden, damit sich die Änderungen in den Programmen auch auswirken.

Um die Lib neu zu übersetzen startet man den Make Prozess im Verzeichnis <INST_DIR>/lib mit:

   make clean
   make all
   
oder man startet die Batch-Datei lib/make-lib.bat. Das kopieren der erzeugten Asuro Objekt Library (wie bei der AsuroLib 2.7.0) in den ACR-GCC Lib Ordner ist nicht mehr notwendig.

Erstellen der ASURO Library Dokumentation

Zur Erstellung der Asuro Library Dokumentation wird das Tool Doxygen verwendet. Um die Dokumentation selbst zu aktualisieren: Die erzeugte HTML Dokumentation befindet sich im Ordner /doc/html. Dort kann die Datei index.html in einen Browser geladen werden.

Die Datei make_doc.log und make_doc.err werden erzeugt um den doxygen-Lauf zu überprüfen.

Erstellen einer HTML Help Datei

Doxygen erzeugt neben der HTML Doku zusätzlich ein HTML Help Projekt File /doc/html/index.hhp. Daraus kann mit Hilfe des HTML Help Workshop von Microsoft eine HTML Help Datei erstellt werden. Das erzeugte HTML Help File befindet sich dann unter /doc/html/index.chm

Troubleshooting

Falls es doch noch zu Fehlern oder Warnungen beim Übersetzen gibt, hier noch einige Hinweise:

  warning: pointer targets in passing argument 1 of 'SerWrite' differ in signedness
  
Diese Warnung gibt es bei Verwendung des neuesten AVR Compilers. Das bedeutet nur, dass man der Funktion SerWrite einen String als Parameter übergeben hat. SerWrite erwartet aber unsigned char * als Parameter. Für die Ausgabe von Strings ist die Funktion SerPrint besser geeignet. Man spart sich zudem das Zählen der auszugebenden Zeichen.
  make: *** No rule to make target `test.hex', needed by `all'.  Stop. 
  
Dieser Fehler kann viele Ursachen haben. Meistens fehlt eine Header-Datei o.ä. Evtl. steht vor dieser Fehlermeldung noch ein Hinweis warum das Übersetzen nicht funktioniert. Kann der Compiler z.B. die asuro.h nicht finden, stimmt wahrscheinlich der LIBPATH im Makefile nicht. Näheres siehe unter Anpassen der Makefiles Oft hilft auch ein Make Clean (durch Aufruf von Test-Clean.bat) und plötzlich geht das Übersetzen wieder ohne Fehler.

Versions History

ASURO Library Versions History 
==============================
16.11.2007 Version 2.7.1
* Installationsprogramm vereinfacht (ohne Abfrage ob WinAVR installiert ist)  (Autor: m.a.r.v.i.n)
* Pfadangaben in Makefiles geändert (Autor: m.a.r.v.i.n)
* Projekt Files für AVR Studio und Programmers Notepad (Autor: m.a.r.v.i.n)
* PrintFloat Funktion (Autor: M1.R)
* Unterstützung der Ultraschallerweiterung (Autor: dopez)
* kleinere Bugfixes (Variablen volatile gemacht, falls diese in
Interruptfunktionen verändert werden) (Autoren: Sternthaler, m.a.r.v.i.n)
09.04.2007 Version 2.7.0rc3
* I2C Funktionen. I2C Master Emulation (Autor raid_ox)
* LCD Funktionen. LCD Modul Anschluss ueber I2C Port Erweiterungs Chip PCF8574 (Autor raid_ox) 
* RC5 Funktionen. Fernbedienung ueber RC5 kompatibel Fernbedienungen (Autor m.ar.v.i.n)
* SelfTest Demomode wieder mit IRDemo und RechteckDemo. Demomode startet, wenn
  nach dem Einschalten eine Taste gedrückt wurde.
* teilweise englische Dokumentation (Autoren: MadMan2k, m.ar.v.i.n, raid_ox)

25.01.2007 Version 2.7.0rc2
* intro.c fuer Doxygen HTML Doku mainpage (Autor m.a.r.v.i.n)
* Kommentare zur Doku ueber Doxygen in adc.c (Autor Sternthaler)

19.01.2007 Version 2.7.0rc1
* Umstellung der Asuro Lib auf eine Objekt Library (Autor m.a.r.v.i.n)

07.01.2007 Version 2.7.0beta
* void Go(int distance, int power) mm Einheit als Wegstreckenangabe (Autor stochri)
* void SetMotorPower(int8_t leftpwm, int8_t rightpwm )  (Autor stochri)
  Funktion zum setzen der PWM Werte, negative Zahlen für Rückwärtsgang. 
  Vorteil MotorDir muss nicht getrennt aufgerufen werden, der Entwurf von Reglern vereinfacht sich.
* void SerPrint(unsigned char *data) 0-terminierte Strings ausgeben
  man muss nicht mehr die Buchstaben von Hand zählen
* void Sound(uint16_t freq, uint16_t duration_msec, uint8_t amplitude) Einführung einer Sound Funktion (Autor stochri)

20.11.2006 Version 2.6.1
* Bugfixes: (Autor: m.a.r.v.i.n)
** PrinInt Funktion: evtl. Fehler beim Flashen mit RS232/IR Transceiver, 
   wg. Folge von 0-Bytes im erzeugten Hex-File. 
   Bug Report von francesco 
** SIGNAL (SIG_ADC): static Variable toggle initialisiert
   Bug Report von Rolf_Ebert 
* Warnings entfernt wg. obsolete Header File bei neueren WinAVR Versionen. 

28.09.2005 Version 2.6
* Doxygen Kommentare. (Autor: m.a.r.v.i.n)

31.07.2005 Version 2.5
* Turn() Funktion mit speed Parameter. (Autor: Andun)
 
30.07.2005 Version 2.4
* Erweiterungen, Go() und Turn() Funktionen. (Autoren: stochri, Andun)

10.06.2005 Version 2.3
* Anpassungen wg. Umbau der Infrarot Schnittstelle als Kollisionsdetektor (Autor: waste)
	count36kHz ersetzt count72kHz. Timer2 geändert.  

31.03.2005 Version 2.2
* Erweiterte Funktionen (Autor: weja - Robotrixer Buxtehude)
	Kurzbeschreibung der Funktionen in der neuen asuro.h, asuro.c vom 31.03.05

  Leider konnten die neuen Funktionen nicht mehr in einer Extradatei untergebracht
	werden, weil mehrere "alte" Funktionen verändert wurden, damit z.B. die Systemzeit
	integriert werden konnte. Auch wurde die PollSwitch Funktion vom Ballast der Fließkomma-
	berechnung befreit. Nun ist wieder mehr Platz für eigenen Code vorhanden.
** EncoderInit()
   Dieser Befehl installiert die Interrupt Funktion für den automatischen Wegzähler.
** EncoderStart()
   Startet die automatische Zählung nach
** EncoderStop()
   neu. Diese Stopp Funktion hält den Zähler an
** EncoderSet(int,int)
   Setzt die Variablen encoder[0] und encoder[1]. Z.B.: EncoderSet(0,0) setzt beide
	 Variablen auf Null.
** switches
   ist eine Variable, die, wenn Startswitch() gestartet wurde, auf wahr gesetzt wird, 
   sobald eine Taste gedrückt wurde. gleichzeitig wird die Tastenüberwachung wieder 
   abgeschaltet. Beispiel:
   Start_Switch();
   while (!switches){;} //wartet auf Tastendruck
   // an dieser Stelle kann mit Pollswitch geprüft werden
   // welche Taste gedrückt wurde, wenn nötig.
   switches=FALSE;  // für eine neuen Aufruf von Startswitch()
** Msleep(int)
   wartet die angegebene Zeit in ms. Z.B warte 10 Sekunden: Msleep(10000);
** Gettime()
   Gibt die Zeit, die seit dem letzten Start des Asuro vergangen ist als unsigned long zurück.
   Die Angabe erfolgt auch hier in Millisekunden.
** PrintInt(int)
   Eine kleine Ausgabehilfe für Integerwerte.
   Beispiel Zeilenweise Ausgabe der encoder Werte:
   PrintInt(encoder[0]);SerWrite("   ",3);PrintInt(encoder[1]);SerWrite("\n\r",2);

10.11.2003 Version 2.1
* Original Version von der ASURO CD (Autor: Jan Grewe - DLR)

Autoren der Bibliothek

contributors, in alphabetical order:

Andun
Jan Grewe
MadMan2k
m.a.r.v.i.n
raid_ox 
Robotrixer
Sternthaler
Stochri
Waste 

Autoren dieser Doku:

m.a.r.v.i.n
Sternthaler
Erzeugt am Sun Nov 18 18:24:52 2007 für ASURO Library von  doxygen 1.5.1-p1