Installationsanleitung für den c't-Bot und den c't-Sim

Tipps und Fehlersuche

Falsche Pfade (unter Windows)

Meckert der C-Compiler beim Übersetzen des Codes, so liegt das meist an fehlenden oder falschen PATH-Einträgen. Öffnen Sie unter Eclipse:

Window->Preferences->C/C++->Build->Environment

und bearbeiten Sie dort den Eintrag für PATH. Am besten enthält er nur Einträge für folgende Verzeichnisse (absolute Pfade (vor dem ersten Backslash) bitte selbst ergänzen):

\MinGW\bin
\MinGW\msys\1.0\bin
\Winavr\bin

Vorgefertigte Entwicklungsumgebung (für Windows)

Windows-Anwender finden auf der Heft-DVD des c't Sonderhefts c't Hardware Hacks eine bereits komplett eingerichtete Entwicklungsumgebung, die nur noch in ein beliebiges Verzeichnis der Festplatte kopiert werden muss und anschließend durch Aufrufen der Datei eclipse.bat gestartet wird.
Eine manuelle Installation von Eclipse, MinGW, WinAVR usw. ist in diesem Fall nicht mehr erforderlich.

Tipp: Über den Menüpunkt Help->Check for Updates lässt sich die Eclipse-Installation inkl. aller Plugins aktuell halten.

Ergänzende Hinweise: USB-Adapter

Treiber

Steckt man den USB-2-Bot-Adapter zum ersten Mal an einen Windows-PC, so fragt Windows nach einem Treiber. Hier gibt man den VCP-Treiber an, der einen virtuellen COM-Port einrichtet.

Fehlerbehebung

Wer mit der Entwicklungsumgebung von der Sonderheft-DVD den USB-2-Bot-Adapter oder einen anderen seriellen Anschluss nutzen will, um c't-Bot und c't-Sim zu verbinden sollte folgendes beachten:

Leider liegt eine Datei nicht im richtigen Ordnern, sodass der Sim beim Start immer meldet: "serielle Schnittstelle konnte nicht geladen werden". Das lässt sich leicht korrigieren. Dazu kopiert man die Datei

rxtxSerial.dll

aus dem Ordner

ct-Bot\workspace\ct-Sim\contrib\rxtx\Windows\i368-mingw32

in den Ordner

ct-Bot\JavaSDK\jdk1.6.0_26\jre\bin

Konfiguration

Dann sollte der Sim automatisch eine Verbindung zu Bots aufbauen, die sich an COM3 anmelden und auf 115200 Baud eingestellt sind.

Wer seinen Bot an einem anderen Port oder mit einer anderen Geschwindigkeit betreibt, muss das in der Konfigurationsdatei ct-Sim.xml ändern.

Achtung:

Die Batch-Datei "startSim.bat" verwendet ein komprimiertes Archiv namens D:\ct-Bot\Precompiled\ct-sim.jar. In diesem Archiv steckt auch die Konfigurationsdatei. Diese kann man anpassen, indem man das Archiv von ct-sim.jar in ct-sim.zip umbenennt, dann mit dem Windows-Explorer öffnet und darin die Datei config\ct-sim.xml bearbeitet. Danach gibt man dem Archiv wieder die Endung .jar

Startet man den c't-Sim aus Eclipse heraus, dann kommt indes ct-Bot\workspace\ct-Sim\config\ct-sim.xml zum Zuge.

Manuelle Installation der Toolchain (für Linux, Mac OS X und Windows)

Überblick/Architektur

Auf Software-Seite besteht der c't-Bot in erster Linie aus Steuercode, der von c't-Bot-Bastlern in C geschrieben wird. Dieser bekommt mittels des c't-Bot-Frameworks Daten von den Licht-, Abstands- und sonstigen Sensoren des Bot, und kann Befehle an die Motoren (oder andere Aktuatoren) geben. Der Steuercode repräsentiert also das gesamte Verhalten eines Bots. Er lässt sich auf zwei Arten kompilieren:

• zur Ausführung auf der realen c't-Bot-Hardware
• oder zur Ausführung auf einem PC (Linux oder Windows) als virtuellem c't-Bot.

Das letztere ist deshalb interessant, weil man den Steuercode dann an den c't-Sim anbinden kann. Dabei handelt es sich um ein in Java geschriebenes Open-Source-Programm, das unter Federführung der c't-Redaktion entwickelt wird. Es simuliert verschiedene Parcours und die Bots in ihnen, d.h. der c't-Sim berechnet, wie weit die Abstandssensoren des virtuellen Bots von den Parcourswänden entfernt sind, wieviel Licht auf seine Lichtsensoren fällt usw. Der an den c't-Sim angebundene virtuelle Bot bekommt diese Daten ständig per TCP/IP übermittelt und reagiert auf sie, als ob er auf realer Bot-Hardware liefe und Werte von tatsächlichen Sensoren erhielte. Wenn der virtuelle Bot z.B. Befehle an seine Motoren gibt, werden diese an den c't-Sim übermittelt und der virtuelle Bot im Parcours um die entsprechende Strecke weiterbewegt.

Außerdem besteht die Möglichkeit, mehrere virtuelle Bots gleichzeitig mit dem c't-Sim zu verbinden und im Parcours umherziehen zu lassen.

1. In jedem Fall umfasst die vorgeschlagene Entwicklungsumgebung für das Projekt:
   • JRE 5 (oder neuer) '''Achtung:''' Wer den c't-Sim selbst als .jar-Datei exportieren will, installiert besser gleich das JDK und nicht das JRE
   • Eclipse (detaillierte Anleitung zur Installation von Eclipse inkl. aller Plugins)


2. Je nach dem, was man tun möchte, ist zusätzliche Software nötig – siehe die folgende Tabelle.


3. Schließlich wird der Quelltext benötigt, der in dem in der Tabelle angegebenen SVN-Modul bereitsteht. (Wie bekommt man Quelltext aus dem SVN?)

Erzeugen der Dokumentation mit Javadoc

Aufgabe	Werkzeuge unter Linux / Mac	Werkzeuge unter Windows	SVN-Modul	Eventuell relevant
Bot-Steuercode entwickeln und auf realer Bot-Hardware ausführen	siehe Anleitung Installation der AVR-Toolchain		ct-Bot	Einrichten des USB-2-Bot-Adapters
Bot-Steuercode entwickeln und als virtueller Bot im c't-Sim ausführen (Wie startet man c't-Sim?)	Java 3D gcc (Linux) gcc (Mac)	Java 3D gcc (MinGW)	ct-Bot, ct-Sim
c't-Sim weiterentwickeln	JDK 5 oder neuer Die 64-Bit-Version von Eclipse kommt Standardmäßig ohne ANT-Support (hilft beim erstellen von ct-Sim.jar). Dieser versteckt sich im Paket “Eclipse Plug-in Development Environment”		ct-Sim
c't-Sim-HTML-Dokumentation generieren (Näheres dazu)	javadoc aus dem JDK		ct-Sim
c't-Bot-HTML-Dokumentation generieren	Doxygen		ct-Bot
AVR-spezifischen C-Code debuggen (Was heißt das?)	AVR-gdb Simulavr	(nicht von uns getestet, Hinweise willkommen)	ct-Bot

Dem Programmiertool Ponyprog zum Übertragen der .hex-Dateien in den Roboter haben wir hier keine eigene Sektion gewidmet, da die Installation keine Probleme bereiten sollte. Weitere Informationen finden sich auf der zugehörigen Wikiseite.

Manche Linux-Distributionen bringen von Haus aus bereits das eine oder andere Werkzeug mit; Windows-Nutzer müssen mit Downloads im Gesamtumfang von rund 200 MB rechnen.

Installation des JRE/JDK

Zur Ausführung der fürs c't-Bot-Projekt empfohlenen Entwicklungsumgebung Eclipse und des c't-Sim ist eine Java-Laufzeitumgebung (Java Runtime Environment, JRE) in der Version 5.0 oder höher erforderlich. Falls der Sim darüber hinaus auch weiterentwickelt werden soll, ist das Java Development Kit (JDK) 5.0 oder höher nötig. Das JDK enthält das JRE, sodass in jedem Fall nur eine Installation zu erledigen ist. '''Achtung:''' Befinden sich mehrere Java-Umgebungen auf dem System (etwa weil man JDK und JRE installiert hat oder dem JDK erlaubt hat auch noch das "Public JRE" zu installieren) so kann es sein, dass Eclipse das "falsche" erwischt. Welches JRE zum Zuge kommt verrät Eclipse unter Windows/Preferences/Java/Installed JRE.

Bei Sun sind sowohl JRE als auch JDK erhältlich. Einige Linux-Distributionen zählen aus lizenzrechtlichen Gründen andere Java-Implementierungen zu ihrem Standard-Repertoire. Diese erfüllen allerdings teilweise nicht den kompletten Java-Standard 1.5 – funktioniert c't-Sim in einer solchen alternativen Java-Umgebung nicht richtig, wird empfohlen, auf das JDK von Sun auszuweichen.

Installation von Java3D

Für die Anzeige der virtuellen Welt benötigt der c't-Sim das Paket Java3D ab Version 1.5.2.

Java3D steht als Installer oder als Archiv verpackt im Netz. Im letzteren Fall extrahiert man den Inhalt in das Unterverzeichnis „jre“ des Java-JDK-Verzeichnisses. Eventuell warnt hierbei der Rechner, im Zielverzeichnis seien die Verzeichnisse „bin“ und „lib“ bereits vorhanden – es besteht hierbei allerdings keine Gefahr, dass wichtige Dateien überschrieben werden.

Damit Elemente aus Java3D richtig angezeigt werden können, muss der Treiber der Grafikkarte den Standard OpenGL 1.3 oder höher unterstützen.

Evtl. erwischt der Installer die falsche JRE-Version oder findet deren Unterverzeichnisse nicht. Dann muss man das Verzeichnis Java3D suchen und dessen Unterverzeichnisse "bin" und "lib" in das Verzeichnis der verwendeten JRE schieben.

Java3D unter Windows

Wer Probleme mit OpenGL hat (z.B. unter Windows Vista), kann unter Windows alternativ auch DirectX benutzen. Dazu stellt man in Eclipse folgendes ein:

1. Im Menü Window/Preferences den Eintrag Java/Installed JREs wählen.
2. Den angehakten Eintrag auswählen und mit Edit bearbeiten.
3. In die Zeile hinter Default VM Arguments den Parameter -Dj3d.rend=d3d eintragen.

Java3D unter Linux

Eine Anleitung zur Installation von Java3D unter Linux gibt es hier.

Java3D unter Mac OS X

1. Java3D für Mac herunterladen (Link s.o.).
2. Die Zip-Datei entpacken und die enthaltene "j3d-jre.zip" ebenfalls entpacken.
3. Die drei Dateien, die dann in lib/ext/ liegen nach /System/Library/Java/Extensions/ kopieren. Je nach OS X Version gibt es dort schon eine ältere Version von Java3D, die Dateien einfach überschreiben.
4. jogl herunterladen (getestete Version ist JSR-231 1.1.1a universal).
5. jogl entpacken und den Inhalt von lib ebenfalls nach /System/Library/Java/Extensions/ kopieren.
6. ct-Sim als 32 Bit Applikation ausführen: Run Configurations... -> Arguments -> VM Arguments: -d32

Hinweise:

• Nach einem Java-Update von Mac OS X muss man Schritt 3 in der Regel erneut ausführen, weil dabei wieder die ältere Version installiert wurde.
• Falls der Sim nach dem Start anstatt der Welt nur einen schwarzen Bereich anzeigt, hilft ein wenig Ein- oder Auszoomen (--> Mausrad).

Erzeugen der Dokumentation mit Javadoc

Der Quelltext des c't-Sim ist ausführlich dokumentiert. Aus den Kommentaren im Source kann man bequem durchsuchbare HTML-Seiten generieren. Für den Java-Code benutzt man dazu das Tool Javadoc, das zum Lieferumfang des JDK gehört. Unter dem Eclipse-Menüpunkt „Project/Generate Javadoc“ trägt man bei „Javadoc command“ den Pfad zum Programm javadoc(.exe) ein, das sich im Unterverzeichnis bin des JDK befindet. Die fertigen HTML-Seiten können in einen beliebigen Ordner geschrieben werden, voreingestellt ist das Unterverzeichnis „doc“ des Java-Projekts ct-Sim.

Zurück zum Überblick

c't-Sim inkl. virtueller Bots starten

1. Gemäß Überblick die nötige Software installieren und den betreffenden Quelltext auschecken
2. c't-Sim starten. Hierzu gibt es drei gleichwertige Möglichkeiten:
   • In Eclipse klickt man die Datei ctSim/controller/Main.java rechts an und wählt „Run As/Application“. (Tipp: Nach dem ersten „Run“ startet Strg-F11 die zuletzt ausgeführte Datei.)
   • Von der Kommandozeile aus wechselt man in das Verzeichnis, in dem Eclipse das ctSim-Projekt aufhebt (ein Unterverzeichnis des Eclipse-Workspace, den man bei der Eclipse-Installation angegeben hat). Dort: java ctSim.controller.Main
   • Zum möglichst bequemen Start in Zukunft kann man ein Jar-Archiv erzeugen (Details siehe FAQ).
3. Falls nicht schon geschehen, c't-Bot kompilieren (ct-Bot-Projekt markieren und „Project/Clean“ wählen)
4. c't-Bot starten:
   • In Eclipse im ctBot-Projekt die Datei Debug-Linux/ctBot.elf (Linux) bzw. Debug-W32\ctBot.exe doppelt anklicken
   • Auf der Kommandozeile Wechsel in das Verzeichnis, in dem Eclipse das ctBot-Projekt aufhebt, und die eben genannte Datei ausführen

Hinweis: Die Datei ct-Bot.exe bzw. ct-Bot.elf beendet sich zügig wieder, wenn sie keinen Simulator findet, der auf ihren Versuch einer TCP/IP-Verbindung antwortet. Daher ist die Reihenfolge „zuerst Sim, dann Bot“ wichtig.

Zurück zum Überblick

Installation des gcc (Linux)

Der gcc gehört zur Grundausstattung jeder Linux-Distribution, wird aber nicht unbedingt bei jeder Installation auf dem System eingerichtet – gegebenenfalls muss er über den Paketmanager der jeweiligen Distribution nachinstalliert werden. Außerdem müssen die glibc-Header installiert sein (Paket libc-dev).

Zurück zum Überblick

Installation des gcc (Mac)

Der gcc ist in den Developer Tools (XCode) enthalten, die man von der OS X-Installations-DVD installieren oder bei Apple herunterladen und dann installieren kann.

Zurück zum Überblick

Installation des gcc inkl. Unix-Umgebung (Windows)

Wer eine ältere Version des Codes (vor Release 20) benutzt, verwendet bitte die alte Anleitung.

Einführung: Eine Windows-Version des C-Compilers gcc wird von dem kostenlosen Paket MinGW zur Verfügung gestellt. Erforderliche Zusatzwerkzeuge kommen im MinGW-Zusatzpaket MSYS. Unix-kompatibles Threading nach dem Posix-Standard wird von der Bibliothek Pthreads zur Verfügung gestellt. In der Summe kann mit dieser Umgebung derselbe in C geschriebene Bot-Steuercode, der unter Linux funktioniert, auch unter Windows kompiliert und ausgefürt werden.

Installation:

1. MinGW Installer (mingw-get-inst-[Version].exe) herunterladen (getestete Version mingw-get-inst-20110530) und als Administrator ausführen. Bei der Paketauswahl einen Haken bei MSYS Basic System ergänzen:

2. Das „bin“-Verzeichnis von MinGW und MSYS zur Path-Variablen des Systems hinzuzufügen: Im Dialog „Systemsteuerung/System“ (erreichbar über Windowstaste+Pause) unter „Erweitert“ den Knopf „Umgebungsvariablen“ drücken. Zur Variablen „Path“ ist der Pfad zu MinGWs und MSYSs „bin“-Verzeichnis hinzufügen – standardmäßig also ;C:\MinGW\bin;C:\MinGW\msys\1.0\bin (; wird als Trennzeichen benutzt).
3. Weitere Informationen zur MinGW-Installation findet man bei Bedarf hier.

Zurück zum Überblick

Installation von Doxygen

Ähnlich wie es Javadoc für Java-Code tut, extrahiert das Programm Doxygen Kommentare aus C-Quelltext. Unter Linux gehört dieses Tool zur Standardinstallation oder ist per Paketmanager installierbar; Windows-Nutzer können es per Installationsprogramm nachrüsten.
Ein ebenfalls nettes und nützliches Tool ist Graphviz (bei Linux ebenfalls meist installiert). Doxygen beutzt es, um Zusammenhänge im Code grafisch darzustellen. Unter Windows muss man es selbst installieren.

Zurück zum Überblick

usb-adapter

Treiber

Wer noch alte D2XX-Treiber installiert hat, sollte diese zuallererst entfernen. Die ursprünglich von uns vorgeschlagene Kommunikation über die JD2XX-Bibliothek und den D2XX-Treiber für Windows erforderte Klimmzüge unter Linux und harmonierte nicht mit anderen Adaptern zum c't-Bot. Daher haben wir nun die Kommunikation mit tatkräftiger Unterstützung einiger Leser auf die RXTX-Bibliothek umgestellt.

Steckt man den USB-2-Bot-Adapter zum ersten Mal an einen Windows-PC, so fragt Windows nach einem Treiber. Hier gibt man den VCP-Treiber an, der einen virtuellen COM-Port einrichtet. Aktuelle Linux-Kernel erkennen den FTDI-Chip bereits von Haus aus und machen ihn über /dev/ttyUSB0 zugänglich.

USB und Java

Damit Java auf den Port zugreifen kann, haben wir die <a href="http://www.rxtx.org">RXTX-Bibliothek</a> in den c't-Sim-Quelltext aufgenommen:

Die Binaries für Windows, Linux und Mac OS X und Solaris stehen im Code-Archiv im Verzeichnis contrib/rxtx bereit. Sie müssen nur noch an den richtigen Ort:

Windows

Die Datei contrib\rxtx\Windows\i386-mingw32\rxtxSerial.dll kommt in das Verzeichnis JAVA_HOME\jre\bin.

Linux

Die Datei contrib\rxtx\Linux\i686-unknown-linux-gnu\librxtxSerial.so kommt in das Verzeichnis JAVA_HOME/jre/lib/i386. Des Weiteren muss der Benutzer, der später den Sim startet Mitglied in einer Gruppe sein (einstellbar über /etc/group), die Lockfiles schreiben darf (z.B. lock oder uucp).

Sonstige

Anleitungen für weitere Betriebssysteme finden sich in der Datei contrib/rxtx/INSTALL.

Konfiguration

über welchen COM-Port und mit welcher Geschwindigkeit der Bot erreichbar ist, teilt man dem c't-Sim in der Datei config/ct-sim.xml mit. Für Windows (Welchen Port man eintragen muss, verrät der Gerätemanager) sieht das wie folgt aus:

   parameter name="serialport" value="COM1"
   parameter name="serialportBaudrate" value="57600"

F&uuml;r Linux sieht die Config-Datei ungefähr so aus:

   parameter name="serialport" value="/dev/ttyUSB0"
   parameter name="serialportBaudrate" value="57600"

Download des Codes aus dem SVN

Diese Sektion der Installationsumleitung ist bereits in das SVN-Howto umgezogen.

Zurück zum Überblick

Alternative: Import des Codes aus Zip-Archiven

Wir empfehlen, den Code für c't-Bot und c't-Sim aus dem SVN zu benutzen -- dieser befindet sich stets auf dem neuesten Stand. Falls Sie nicht auf das SVN zugreifen können (etwa weil Ihr Rechner durch eine Firewall vom Internet abgeschottet ist, welche die notwendigen Ports geschlossen hält), können Sie auf den Code aus Zip-Archiven auf unserem Server zurückgreifen. Solche Archive bringen wir allerdings nur bei umfangreicheren Änderungen auf den neuesten Stand, nicht für jedes kleine Bugfix, deshalb ist der Code im Zip-Archiv eventuell älter als jener im SVN.

Wenn Sie trotzdem auf das Zip-Archiv zugreifen wollen oder müssen, laden Sie es sich auf den eigenen Rechner und packen es aus. Nach dem Start von Eclipse kann unter dem Menüpunkt File / Import die Option Existing Project into Workspace ausgewählt werden. Als root directory muss dann der Ordner ct-Sim oder ct-Bot angeben werden.

Zurück zum Überblick