ASURO Library  2.80
Die Asuro Library
asuro1.gif
Der Asuro

Einfuehrung

Die Asuro Library ist eine Sammlung von C-Funktionen fuer den Roboter Asuro. Der Asuro wurde vom DLR (Deutschen Zentrum fuer 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 fuer jedes Projekt neu uebersetzt (compiliert) werden muss, sondern nur noch gelinkt wird. Die Bibliothek selbst muss nur neu uebersetzt werden, wenn an den Bibliotheks Funktionen Änderungen oder Definitionen in den Header Files vorgenommen wurden.

Der Vorteil der Objekt Bibliothek gegenueber der Quellode Bibliothek ist die drastisch reduzierte Groesse 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, unabhaengig davon ob sie ueberhaupt benoetigt 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 fuer die Atmel AVR Prozessoren benoetigt. Der Quelllcode der Bibliothek wurde fuer die AVR-GCC Cross-Compiler Suite geschrieben. Den AVR-GCC ist kostenlos fuer diverse Plattformen (Windows, Linux, Mac) verfuegbar. 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 Moeglichkeiten 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 fuer SVN Schreibrechte, keiner fuer Leserechte
  Password: SourceForge.net user password fuer SVN Schreibrechte, keines fuer Leserechte

Verzeichnis Struktur

Nach der Installation befindet sich folgende Verzeichnis Struktur auf der Festplatte. Das Installationsverzeichnis im folgenden [INST_DIR] genannt, koennte 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 aufgeraeumt um die Verwendung der Bibliothek fuer eigene Projekte zu erleichtern. Es gibt nur noch eine einzige Stelle, die man aendern muss um alle Pfadangaben, die mit der Lib zu tun haben, zu aendern. Das ganze kann natuerlich 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' muss 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 Ausfuehren

  # 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, muss man die Pfadangaben in Hochkommas einfuegen

  # additional Include path for libraries
  LIBPATH = "C:/Eigene Dateien/ASURO_SRC/AsuroLib/lib"

Neue Projekte

Will man ein eigenes Programm fuer den Asuro erstellen, welches die Asuro Bibliothek verwendet kopiert man besten den kompletten Ordner [INST_DIR]/examples/FirstTry in einen neuen Ordner. Dann muss man nur noch das Makefile wie oben beschrieben anpassen, seine Programm schreiben und sollte es dann uebersetzen koennen. In dem Projekt Ordner duerfen sich aber keine Überbleibsel von vorherigen Asuro Libs (asuro.c, asuro.h) befnden. Der Compiler und Linker uebersetzt/bindet sonst naemlich 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.

Enthaelt das eigene Projekt zusaetzliche Quelldateien (ausser test.c) muessen 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 dazugefuegt.

 # 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 angepasst. Es muss natuerlich eine Quelldatei geleichen Namens existieren.

  # Target file name (without extension).
  TARGET = SelfTest

Beispiel Projekte

Im Ordner [INST_DIR]/examples befiden sich einige Beispiel Projekte, die sich fuer eigene Projekte anpassen oder erweitern lassen bzw. als Vorlage fuere eigene Projekte dienen sollen.

Compilieren der Asuro Library

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

Um die Lib neu zu uebersetzen 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 ueberpruefen.

Erstellen einer HTML Help Datei

Doxygen erzeugt neben der HTML Doku zusaetzlich 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 uebergeben hat. SerWrite erwartet aber unsigned char * als Parameter. Fuer die Ausgabe von Strings ist die Funktion SerPrint besser geeignet. Man spart sich zudem das Zaehlen 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.ae. 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. Naeheres siehe unter Anpassen der Makefiles Oft hilft auch ein Make Clean (durch Aufruf von Make-Clean.bat) und ploetzlich geht das Übersetzen wieder ohne Fehler.

Versions History

ASURO Library Versions History 
==============================
29.03.2008 Version 2.8.0
* Anpassungen fuer ATmega168
* neue Funktion ReadADC zur A/D Wandler Abfrage
* neue Funktion PrintLCD_p zur Ausgabe von Strings aus dem Programmspeicher
* neue Funktion SetCharLCD zum Setzen von Sonderzeichen
* neue Funktion PollSwitchLCD zur Abfrage der Tasten des Arexx LCD 
* neue Funktion MyMotorSpeed die Korrekturwerte aus der myasuro.h berücksichtigt.
* neue Funktion SerPrint_p zur Ausgabe von Strings aus dem Programmspeicher
* UART Baudrate einstellbar durch Define
* Interrupt User Funktionen für Timer und A/D Wandler      
* AVR Studio Projektfiles für alle Beispielprojekte

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