RobotLib

Uit RoboWiki
Ga naar: navigatie, zoeken

Zie RobotLib Index voor een overzicht van alle RobotLib documentatie op deze wiki.

RobotLib

Robotlib is een set van C en C++ source files voor de besturing van een robot. Deze library maakt de overstap van een 8-bit platform (Arduino, PIC16/18, AtMega) naar een 32-bit embedded platform eenvoudiger. Daarnaast geeft het universele basisfuncties waardoor een robot toepassing eenvoudig is over te zetten naar een ander platform dat RobotLib ondersteunt.

Zie RobotLib Index voor een overzicht van alle RobotLib documentatie op deze wiki.

RobotLib status & ToDo

In juni 2013 is dit project gestart met het verzamelen en structureren van beschikbare code. Vervolgens is de code uitgebreid om voldoende functionaliteit te bieden om een praktische robot te besturen. Daarnaast is de code geport naar 3 verschillende processoren en werkend gemaakt op 3 verschillende robots. Met de deelname aan de TeamBuildersDay in september 2013 is aangetoond dat RobotLib een behoorlijke basis is voor een robot. Hiermee is de eerste (alpha) fase van het project afgesloten en zijn we in de beta fase beland. In deze fase is het volgende van belang:

  • implementatie op meer robots door meer mensen en meer testen
  • oplossen van fouten, doorvoeren verbeteringen en uitbreiden van de functionaliteit.

De volgende zaken staan op de ToDo list:

Code / testen:

  • Toevoegen van optionele enable/disable aan hal_motors voor de STM32F4
  • Testen kortere main_takt tijd, invloed op regelingen en op odometrie
  • Optimalisatie UmXYPhi, inclusief demo
  • ADC routines voor LPC2148

Tools / documentatie:

  • Meer documentatie tags aan sources toevoegen.

RobotLib Functionaliteit

  • Universele onderlaag (HAL), gemaakt of aangepast voor de robot.
  • Timing controle en meting
  • Seriele poort als STDIN en STDOUT
  • Calibratie van wielen en encoders
  • Robotpositie bijhouden
  • Bewegingen (vectoren, way point etc).
  • Commando's via seriele poort
  • Bediening met RC5 afstandsbediening
  • Parameter menu op LCD scherm, bediend met afstandbediening.
  • State Machines starten en volgen tijdens uitvoering

zie RobotLib_Modules voor details over de functionaliteit.

De robot

RobotLib is bedoeld voor een robot met:

  • Differential drive.
  • Wiel encoders.
  • Een seriele poort voor debugging en analyse.

Daarnaast zijn de volgende functies handig:

  • Ontvanger voor RC5 afstandsbediening.
  • LCD scherm (16x2 of groter)

De controller

RobotLib is gesplitst in een microcontroller-specifiek deel - de Hardware Abstraction Layer (HAL) - en een generiek deel. Het generieke deel is geschikt voor 32 bits platformen (sizeof(int) == 4). Op dit moment is een HAL beschikbaar voor een drietal ARM STM32 processoren. De HAL implementatie voor een ARM LPC processor is voorzien. Uitgangspunt is dat RobtLib zonder operating systeem op de hardware kan draaien (bare metal). Overigens is een poort naar een operating system met een 32-bit C-compiler - bijvoorbeeld de Raspberry Pi - eenvoudig. De HAL kan bestaan uit C en C++ files. De overige RobotLib files zijn C++ en ook gebruikersfiles zijn C++. RobotLib gebruikt 'classes' voor bepaalde functionaliteit, bijvoorbeeld voor de aansturing van sharp sensoren. In RobotLib_Modules wordt beschreven hoe zo'n class wordt gebruikt. Dit betekent overigens niet dat je als gebruiker in C++ moet te programmeren: de robot kan verder gewoon in C worden geprogrammeerd.

Nog geen controller op het oog? Kijk dan eens naar een STM32F4 discovery board.

Toepassingen

Toepassingen (Missions) voor de robot worden geschreven in C in de vorm van 'Finite State Machines', zodat alle huishuidelijke taken 'tegelijk' met de Mission uitgevoerd worden (cooperative multi tasking). RobotLib heeft diverse functies om het gebruik van State Machines te ondersteunen en het aantal states te beperken. En door gebruik te maken van de HAL functies, kan een Mission eenvoudig worden overgezet naar een andere robot die op RobotLib is gebaseerd.

Aan de slag

De hardware

RobotLib is ontworpen voor een differential drive robot met wiel-encoders. Als voorbereiding kun je deze hardwarematig (mechanisch en elektrisch) helemaal gereed maken:

  • de motoren aansluiten via een motor controller (bij voorkeur push-pull).
  • de encoders aansluiten op de processor.
  • de serieele poort aansluiten op de PC (bij voorkeur draadloos).

en optioneel:

  • RC5 ontvanger aansluiten.
  • LCD display aansluiten.

Maar... je kunt een deel van RobotLib al testen met de volgende, minimale configuratie:

  • een ondersteund processorbord
  • een seriele verbinding tussen dit bord en je PC.

Je eerste project

Hieronder wordt beschreven hoe je RobotLib en de benodigde tools download, installeert en configureert. Dit betreft allemaal tools die vanaf de commandline gebruikt kunnen worden. Het is daarom handig om te weten dat je de explorer in Windows Vista & 7 de optie 'Open command window here' heeft in het rechter-muis-klik-menu als je shift ingedrukt hebt. Voor windows XP gebruiker is deze optie te activeren met doshere.inf (bestand opslaan, rechter muisklik, install). Uiteraard heb je ook een editor nodig. Ik kan Ultraedit van harte aanbevelen. Een goed freeware alternatief is Programmers Notepad. Op de pagina Programmers_Notepad wordt beschreven hoe je Programmers Notepad configureert en gebruikt met RobotLib. Een debugger wordt (nog) niet ondersteund. (welk terminal programma?)

Installatie & configuratie

  • Download de ARM cross compiler voor Windows vanaf Launchpad.net. De STM32 toepassingen zijn getest met GCC versie 4.6 2012q4. Installeer deze in een directory zonder spaties in het pad, bijvoorbeeld C:\gnuarm_4.6_2012q4.
  • Voor het programmeren van STM32 wordt gebruik gemaakt van de STM32 ST-Link utility direct. Dit tool heeft een GUI, maar kan ook vanaf de command line worden aangeroepen. Installeer dit op de default locatie.
  • Doe een SVN checkout van https://robotmc.svn.cloudforge.com/robotlib/trunk naar C:\RobotLib. Deze link werkt niet in een browser, gebruik hiervoor een SVN client zoals TortoiseSVN. (JS: toegang tot SVN server is waarschijnlijk beperkt; stuur een mailtje naar gmail account van jsuijs als je de bestanden wilt hebben en geen toegang via SVN krijgt).
  • Je kunt de files eventueel ook zelf downloaden vanaf de SVN webinterface. Let op dat je de naamgeving van bestanden en directories niet wijzigt en geen spaties krijgt in de padnaam.
  • De sample_project directories zijn de basis voor een nieuwe toepassing. Copieer een sample_project directory naar een andere plaats (want het is waarschijnlijk niet de bedoeling dat je nieuwe project het sample project in de SVN gaat overschrijven).
  • Bovenaan in de file 'configure.bat' staat een aantal paden. Pas deze aan voor jouw situatie. Waarschijnlijk moeten de regel 'set PRJ_path=' en mogelijk ook 'set gcc_path=' worden gewijzigd.
  • Klik dan op 'cmdprompt.bat' om Command Prompt met je project directory te laten verschijnen.
  • Voer de 'make.bat' uit. Make.bat gebruikt te instellingen in 'configure.bat' om de paden voor het compileren in te stellen. Als de paden correcty ingesteld zijn, zal 'make.bat' het project compileren.
  • In de file 'makefile.do' staat onderaan de sectie 'command(deploy)'. Dit wordt gebruikt bij 'make.bat deploy'. Indien dit niet werkt, moet waarschijnlijk in de sectie command(deploy) het pad naar ST-LINK_CLI.exe worden aangepast.

That's all.

Compileren

Als alles goed is gegaan, kun je nu het sample project compileren en toepassen (deploy-en). Drie belangrijke commando's zijn:

  • 'make all' - compileer de laatste wijzigingen en link de applicatie.
  • 'make deploy' - programmeer de target met behulp van de command line utility.
  • 'make clean' - verwijder alle tijdelijke files (waaronder objecten). Een volgend 'm all' commando is daarmee 'rebuild all'.

Je kunt meerdere command's tegelijk aan 'make' meegeven. Het commando wat ik het meest gebruik is 'make all deploy', af en toe vooraf gegaan door 'make clean'.

Met 'deploy' wordt de programmeer-tool voor de gekozen microcontroller aangeroepen. Deze tool, de parameters en de plaats waar de tool staat kan worden gewijzigd in makefile.do, in de sectie 'command(deploy)'.

Test

Start een terminal programma en als alles juist is geconfigureerd, wordt systeeminformatie geprint:

 RCC_Clocks 168 MHz
 Pclock1 : 42 MHz
 Pclock2 : 84 MHz
 CoreInit complete!
 FLASH: 35264 van 1048576 bytes (3 %) gebruikt)
 stack start: 0x20001510 (0x1000 words)
 RAM: 21776 van 131072 bytes (16 %) gebruikt)
 Global constructor ok (123)
 Auto constructor ok (123)
 init_array: 80089b8 80089c0
 loop kost 611 microseconden (performance indicator).
 controleer of UsClock loopt... okay.
 wait_ms(3) gemeten, duur: 3000 microseconden.
 controleer of UsClock loopt... Serial send test - 50 tekens @ 115k2 = 4340 us..
 Gemeten, duur: 36 microseconden, dus queued console comms.
 MsCounter increment gemiddeld in 998 microseconden
 Seconde test...
 1000 float berekening in 129 microseconden, 10 / 3 = 3.333333
 sin(2) = 0.909297 (must be 0.909297)
 Try malloc()... Succes!
 PFKeyHandler function set to 'Motor calibrate'
   OdoT_mm           : 0
   Testvar           : 77
   Testvar2          : 4711
 CliAddCommands: 'Default commands' added
 CliAddCommands: 'User commands' added


Ook kunnen via de terminal commando's worden gegeven. '?' geeft een overzicht van de beschikbare commando's.

  • controleer werking HAL (timers, constructors)
  • controleer werking LCD, RC5

Vervolgstappen

  • hal configuratie aanpassen
  • lcd, rc5
  • motors_conf (motorsturing, encoders) werkend maken - RobotLib commando's om dit te ondersteunen x y z
  • RobotLib_MotorCalibratie Calibreer motoren en encoders - RobotLib commando's om dit te ondersteunen x y z

Nu kun je aan de slag om Missions te maken.

Een nieuwe missie

De functie main() van robotlib is voor de meeste robots nagenoeg gelijk, en bepaalt met name welke modules geinitialiseerd worden en actief zijn. Allemaal vrij technisch en niet zo interessant, want we willen dat de robot iets gaat doen. In robotlib is 'iets doen' een missie en we moeten de missie beschrijven in de vorm van een Mission State Machine. Hierin wordt stap voor stap bepaald wat de robot gaat doen en wanneer de robot naar een volgende stap (state) gaat.

Bij de uitvoering van de missie kan gebruik gemaakt worden van Universal Movements, voorgeprogrammeerde bewegingen. "Missions" en "Universal Movements" hangen als volgt samen:

RL Mission Mover.jpg

Onderaan staat "Mover", een module die periodiek door vanuit de hoofdlus wordt aangeroepen (via Takt) en die zorgt voor de uitvoering van de UniversalMover opdrachten. Deze worden aangevraagd via Um*Set() aanroepen en via Mover.IsDone() kan worden bepaald of de beweging is afgelopen. De verzoeken tot beweging worden gedaan vanuit de module "Mission", die ook een takt() heeft.

"Mission" zorgt voor de uitvoering van jouw eigen MissionStateMachine functie. Eventuele parameters voor jouw MissionStateMachine kun je ophalen uit de MhParam module.

Dit brengt ons bij het laatste punt van deze paragraaf: het starten van een mission. Dit gebeurt normaal vanuit de actieve Programmable Function Key handler, die op haar beurt weer geactiveerd kan worden met de afstandbediening (RC5) of vanaf de command line interface (CLI). De PfKey handler wordt aangeroepen met het nummer van de functie-toets als parameter. In een case statement kunnen vervolgens de gewenste parameters in de MhParam module gezet worden en daarna wordt aan de Mission modulge gevraag om onze eigen MissionStateMachine functie uit te gaan voeren.

De file prj_umbmark.cpp bevat een voorbeeld van een mission state machine (Msm) en een PfKey handler.

structuur en conventies

RobotLib kent 4 belangrijke directories:

  • PRJ_path - de directory met de user files.
  • Hal_path - de directory (met evt. subdirectories) van de HAL
  • RL_path - de RoboLib directory
  • gcc_path - de bin directory van de compiler

Deze directories worden ingesteld in de batchfile 'configure.bat'. Vervolgens deze file uitvoeren, zodat deze instellingen worden gebruikt bij het compileren en includen.

Robotlib overzicht.jpg

Een RobotLib project is opgebouwd uit 3 type files:

  • Rode files zijn voor alle projecten gelijk. Bij een nieuwe versie van RobotLib worden deze files overschreven.
  • Paarse files zijn de HAL files die processor afhankelijk zijn. Bij een nieuwe versie van de RobotLib HAL worden deze files overschreven.
  • Groene files zijn projectfiles die door de gebruiker gemaakt of uitgebreid worden.

Met zowel de rode als de paarse files worden templates meegeleverd. Dit zijn groene files waarvan de filename eindigt op _conf. Met deze files worden RobotLib en de HAL geconfigureerd.

  • robotlib.h in de project-directory is (gegenereerde) super include en wordt *via de command line van de compiler* ge-include bij iedere C en CPP file.
  • HAL source files kunnen C en CPP zijn.
  • RobotLib en Project source files alleen CPP.

(Bij het mixen van CPP en C moet rekening gehouden worden met 'c++ name mangling'. Dit is wel mogelijk, maar kan worden voorkomen door de C sources de CPP extensie te geven).

  • geen IDE
  • eigen build tool (DO)