RobotLib

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

Wat is RobotLib?

Robotlib is een set van C en C++ routines voor de besturing van een robot. RobotLib draait op een aantal STM32 processoren en is vrij eenvoudig te porten naar andere 32-bit processoren. RobotLib positioneert zich tussen systemen als ROS en Carmen enerzijds en de robot- of leveranciers-specifieke libraries als de 3Pi libraries anderzijds.

ROS en Carmen draaien op multi-tasking operating systemen als Linux, terwijl RobotLib direct op de hardware draait (alhoewel dat niet noodzakelijk is...).

Leveranciers-specifieke libraries richten zich vooral op het ontsluiten van de hardware van de robot, zoals motorsturing, sensoren en bediening (knopjes, display). RobotLib ondersteunt dit ook, maar biedt nog veel meer. Het is eigenlijk een soort Robot Operating Systeem.

Features

• Een 'Hardware Abstraction Layer' maakt het mogelijk om RobotLib eenvoudig te porten naar een nieuwe robot of andere processor.
• Een uitgebreid 'bedieningssysteem' maakt het mogelijk om de robot commando's te geven, parameters aan te passen en status op te vragen. Dit systeem werkt via een seriële verbinding, infrarood afstandbediening en display op de robot. Het bedieningssysteem is eenvoudig uit te breiden om bijvoorbeeld functies toe te kennen aan knopjes van de robot of door eigen menu's en commando's toe te voegen.
• Een taak-systeem om eigen modules en modules van RobotLib te activeren.
• Ondersteuning van diverse sensoren en (andere) I2C devices.
• Navigatie voor differential-drive robots: positie bijhouden, rijden met bepaald snelheidsprofiel, naar bepaald punt, via een bepaalde curve. Zelf eenvoudig complexere bewegingen maken door reeksen van deze 'bewegingen'.
• Functies die een snelle start mogelijk maken: hulpmiddelen bij calibratie, kant-en-klare routine om een lijn te volgen.
• Diverse bouwstenen als queue's, PID controller met autotuner, debug-opties.

Is het de moeite waard?

RobotLib is weer een 'eigen' systeem en het vraagt - zoals ieder nieuw systeem - een investering om mee te beginnen. Is dat wel de moeite of kan ik beter met bijvoorbeeld Arduino gaan werken? Het antwoord op deze vraag moet je zelf bepalen en zal afhangen van het doel wat je nastreeft. Het is sneller om een eenvoudige lijnvolger te maken met een Arduino. Nog veel sneller is om een robot als de 3Pi te nemen, zodat je gebruik kunt maken van de meegeleverde library van de fabrikant (en wellicht zelfs het demo programma).

Maar... als RobotLib eenmaal werkt op je robot, heb je direct een berg functies beschikbaar. De robot houdt zijn positie bij en kan patronen rijden. Je kunt je eigen code toevoegen, parameters gebruiken die je bij het testen eenvoudig aan kunt passen (ook met je afstandsbediening) en zien wat er onder de motorkap in in jouw code gebeurt.

Het allerbelangrijkste van RobotLib is waarschijnlijk de herbruikbaarheid. Na 5 jaar robotjes bouwen was er allerlei code ontwikkeld, maar bij iedere robot wat het toch bijna weer opnieuw beginnen met kopieën van stukken broncode van eerdere projecten. RobotLib is gestart als project om al die eerdere code samen te brengen op een manier die wel herbruikbaar is. Het resultaat na 4 jaar is dat er een kleine 10 robots rijden met dezelfde code als basis. En als er nieuwe features aan RobotLib wordt toegevoegd, kunnen al die robots deze gebruiken.

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

RobotLib status

Robotlib wordt actief ontwikkeld. De bestanden staan op een git repository en er zijn geen releases. Een aantal belangrijk mijlpalen:

• juni 2013: Start van RobotLib met 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.

• september 2013: Eerste (alpha) fase van het project afgerond. Met de deelname aan de TeamBuildersDay in september 2013 is aangetoond dat RobotLib een behoorlijke basis is voor een robot.

• januari 2015: De basisbewegingen, zoals rijden naar een punt en rijden van een cirkel, zijn geoptimaliseerd en werken op iedere gekalibreerde robot. Het taaksysteem is uitgebreid, missies kunnen andere missies laten uitvoeren, objecten (zoals servo's en sensoren) worden flexibeler gekoppeld aan de hardware *en* zijn automatisch toegankelijk vanaf de command line.

• September 2015: Op de Team Building Day 2015 haalt hij met PlankTrick de derde plaats. Meerdere mensen gebruiken robotlib en Patrick heeft zijn ervaringen met PlankTrick gedocumenteerd.

• November 2015: Grote revisie onder de motorkap afgerond. Robotlib is nauwkeuriger, de interface consistenter en zijn veel schaalfactoren vervallen.

• Januari 2016: Vernieuwde opzet van Commando-verwerking (met integer en float parameters, dialogen). Een centrale Registry voor variabelen en een Command Repository voor commando strings.

• Augustus 2016: Revisie onder de motorkap om soepeler te starten en stoppen (geen sprongen in versnelling). Interne regelingen vervangen door echte PID controllers en PID autotuner toegevoegd. VL53L0x sensor en oled display ondersteuning.

• November 2016: Een lijnvolger met RobotLib behaalt de eerste plaats op de lijnvolg wedstrijd van HCC Robotica in Nederland.

• Januari 2017: SourceConnector maakt het mogelijk om op een universele manier sensoren te koppelen.

• April 2017: Nieuwe opzet 'console' (PC software) op basis van MQTT maakt het mogelijk om robot beter te bedienen en volgen. Optimalisatie van PID controllers en autotuner.

• September 2017: Mini filesysteem en routines om configuratie- en calibratie gegevens op te slaan en (automatisch) in te lezen.

• December 2017: Betere CPU belasting meting van taken.

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. Voor ontwikkeling wordt nu gewerkt met GCC versie 4.8 2014q3, maar ook andere versies zijn waarschijnlijk bruikbaar. Installeer de compiler in een directory zonder spaties in het pad, bijvoorbeeld C:\gnuarm_4.8_2014q3.

• 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.

• Clone de Git repository van ssh://git_robotmc@robotmc.git.cloudforge.com/robotlib.git naar C:\RobotLib. Deze link werkt niet in een browser, gebruik hiervoor een Git client. Toegang tot de Git server vereist een account. Stuur een mailtje naar gmail account van jsuijs als je toegang wilt hebben. Zie Bestand:RobotLib Git.pdf voor meer details.

• Je kunt de files eventueel ook zelf downloaden vanaf de Git 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 Git repository 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.

• Open een command prompt in de project directory (zorg dat je geen file hebt geselecteerd in explorer, shift indrukken, rechtse muisklik->'open command window here').

• 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 'make 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 bevat met name configuratie. Een basis configuratie is meegeleverd in 'StubsGlobals.cpp' en wordt aangeroepen met SG_Setup() en SG_TasksTakt(). Allemaal vrij technisch en niet zo interessant, want we willen dat de robot iets gaat doen. In robotlib is 'iets doen' een missie en de missie beschrijven we 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:

Onderaan staat "Mover", een module die periodiek wordt aangeroepen (via SG_TasksTakt) en die zorgt voor de uitvoering van de UniversalMover opdrachten. Deze worden aangevraagd via Um*() (zoals UmXy()) 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 jouw Mission class. met de ParamGet() functie.

Dit brengt ons bij het volgende punt: het starten van een missie. 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 Mission class module gezet worden en daarna wordt aan de Mission module gevraagd om onze eigen MissionStateMachine functie uit te gaan voeren.

Tot slot: In het plaatje staan meerdere Mission classes getekend. Dit geeft de mogelijkheid om vanuit je missie een andere missie uit te voeren. Voordat je een lijn gaat volgen kun je bijvoorbeeld missie MSM_LineSensorCalibrate() uitvoeren, die je lijnsensor kalibreert.

(todo: demo maken)

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.

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)