RobotLib

Zie deze pagina 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 valt 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.

Library of Framework?

Op het eerste gezicht lijkt RobotLib het meest op een framework. Het is een compleet robot besturingssysteem met bijvoorbeeld 3 takenlijsten, een engine om missies uit te voeren en de mogelijkheid om de robot met afstandbediening of seriële verbinding te bedienen en te monitoren. 'Uit de doos' kan de robot patronen rijden. Sensoren toevoegen en missies beschrijven en je kunt aan de slag.

Deze standaard 'implementatie' wordt bepaald door een enkele sourcefile (Framework.cpp), die alle bouwstenen samenvoegt. Wil je een andere configuratie, maak dan je eigen framework.cpp. RobotLib is dan ineens een verzameling van bouwstenen die je kunt combineren. Deze bouwstenen zijn zoveel mogelijk onafhankelijk, maar maken soms ook gebruik van andere bouwstenen. Vaak zijn die koppelingen compile-time uit te schakelen.

Een eigen configuratie is zinvol als je een subset van RobotLib wilt gebruiken. Een voorbeeld hiervan is PrintBot III. Deze robot heeft geen uitgebreide ondersteuning nodig voor missies en patronen rijden, maar heeft wel meerdere taken, sensoren, bediening en diagnose-opties. Een 'uitgekleed' framework past in de STM32F1 van deze robot.

In veel gevallen is het handig om het framework te gebruiken. Dingen die je niet gebruikt zitten (meestal) niet in de weg en uitbreiden (met RobotLib of eigen code) kan altijd.

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 deze pagina 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:

• Oktober 2019: De ontwikkelingen hebben niet stilgestaan dit jaar. Veel kleine verbeteringen en wat bugfixes. Filesysteem backup/restore en uitwisseling van data naar het console is consistenter gemaakt, verbeteringen en uitbreidingen van de basic toolchain. En eerder werk van de obstacle avoider is toegevoegd en doorontwikkeld.

• Oktober 2018: De ontwikkeling gaat door. De Team Building Day 2017 was de beta test van een basic virtual machine, als alternatief voor MissionStateMachines. Door de kortere ontwikkel/test cyclus handig op bijvoorbeeld de Team Building Day. En dit jaar voor opnieuw gebruikt en daarmee is de beta test wel afgerond.

• Januari 2018: Real time grafieken op het console (de pc). Tientallen (vaak kleine) wijzigingen om de robot soepeler en nauwkeuriger te laten rijden, en om calibratie en het gebruik van Robotlib in het algemeen te vereenvoudigen.

• December 2017: Betere CPU belasting meting van taken.

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

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

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

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

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

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

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

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

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

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

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 (oled 128/64 of tekst van minimaal 16x2)

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 was 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 in C worden geprogrammeerd zoals je dat bijvoorbeeld ook met Arduino kunt doen.

Nog geen controller op het oog? Kijk dan eens naar een STM32F407 'core development board' i.c.m. een ST-Link V2 clone. Dit board heeft dezelfde processor als een STM32F4 discovery board, is kleiner, goedkoper en heeft meer IO pinnen vrij.

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

De minimale configuratie om de RobotLib software te testen is een ondersteund processorbord (met programmer) met een seriële verbinding met je pc.

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 seriële poort aansluiten op de PC (bij voorkeur draadloos).
• RC5 ontvanger aansluiten.
• LCD display aansluiten.

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.

Uiteraard heb je ook een editor nodig. Ik kan Ultraedit van harte aanbevelen. Een goed freeware alternatief is Notepad++. Programmers Notepad was (of is) ook een goede optie, maar lijkt niet meer actief te worden ontwikkeld.

Voor interactie met en debugging van je robot wordt de seriele poort gebruikt. Hiervoor heb je een terminal programma nodig zoals putty. Robotlib heeft een verzameling Python console scripts voor interactie met je robot, waaronder een terminal programma. Een debugger wordt (nog) niet ondersteund.

Installatie & configuratie

• Download de ARM cross compiler (AArch32 bare-metal target / arm-none-eabi)voor Windows vanaf arm.com. Voor ontwikkeling wordt nu gewerkt met GCC release 2020q2], maar ook andere versies zijn waarschijnlijk bruikbaar (1). Installeer de compiler in een directory zonder spaties in het pad, bijvoorbeeld C:\gnuarm_2020q2.

(1) Het streven is dat compileren met maximale controle (-Wall) geen warnings geeft. Voor nieuwere compilers, die steeds meer controleren, vraagt dit aanpassingen die op oudere compilers weer warnings geven. Dit ook nog onderdrukken gaat mij te ver, dus in dit geval accepeteren of upgraden ;)

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

• Voor het bouwen van robotlib wordt gebruikt gemaakt van Python 3.

• 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 onder 'boards' zijn de basis voor een nieuwe toepassing. Kopieer 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).

• (todo: beschrijven configuratie via json, paden, deploy).

• Open een command prompt in de project directory (zorg dat je geen file hebt geselecteerd in explorer, shift indrukken, rechtse muisklik->'open PowerShell 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 correct ingesteld zijn, zal 'make.bat' het project compileren.

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 RobotProject.json.

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 gelijk van opzet, en bevat met name configuratie. Een basis configuratie is meegeleverd in 'Frameworks.cpp' en wordt aangeroepen met FrameworkSetup() en FrameworkTasksTakt(). 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 FrameworkTasksTakt) 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 is de super include. Include deze in iedere file van je project, gevolgd door project.h.
• HAL source files kunnen C en CPP zijn.
• RobotLib en Project source files alleen CPP. (Het gebruik van files met .C extensie wordt afgeraden!)
• geen IDE
• eigen build tool (DO)