micro:Maqueen Plus

Maqueen Plus, met voorop het slot voor de BBC micro:bit

De Maqueen Plus (of eigenlijk micro:Maqueen Plus) is een compacte robot en de opvolger van de Maqueen (die nu verder door het leven gaat als Maqueen Lite). Beide zijn bedoeld als aanvulling op de BBC micro:bit, een compact ARM bordje voor STEM onderwijs.

De Maqueen Plus is op een aantal punten verbeterd, waarvan de wiel-encoders voor mij het belangrijkst zijn. Daarnaast heeft de Maqueen Plus 6 lijnsensoren, die het mogelijk maken om het labyrinth op te lossen. Positief is ook dat de batterijen vervangen door een accu, die in de robot opgeladen kan worden via de USB-poort.

Kortom, een compacte robot met potentie!

Opties, opties, opties

De MaqueenPlus is bedoeld als 'add on' voor de BBC micro:bit. Dus over het algemeen zal deze robot gebruikt worden MET de micro:bit. De officieel ondersteunde talen voor de micro:bit zijn MakeCode and Python. Daarnaast beschrijft Adafruit hoe de de micro:bit met de Arduino omgeving kunt programmeren.

Het grootste deel van de functies van de Maqueen worden bestuurd door de eigen processor, die als i2c slave benaderbaar is door de micro:bit. De interface is niet expliciet gedocumenteerd, maar wordt door DFRobot toegelicht aan de hand van voorbeelden voor Python en de Arduino library.

Het grootste deel van de documentatie van de fabrikant is gericht op de grafische omgeving MindPlus, als alternatief (?) voor MakeCode, de standaard grafische omgeving van de micro:bit.

Dit artikel gaat verder niet in op de grafische omgeving, maar richt zich op 2 opties:

Aansturen van de MaqueenPlus via i2c.
Direct programmeren van de controller van de MaqueenPlus.

Aansturing via i2c (stock firmware)

De MaqueenPlus is een robot met een slot voor de BBC micro:bit. De micro:bit kan via i2c:

De beide motoren aansturen
De twee RGB leds aansturen
De beide motor-encoders uitlezen
De analoge waarden van de 6 lijnsensoren uitlezen
Een byte met een bit per lijnsensor uitlezen

Hoe dit precies werkt is niet door de fabrikant DFRobot gedocumenteerd. Wel heeft DFRobot een specifieke branche van de Python editor mu, waarin een aantal voorbeelden en functies zijn opgenomen. Daarnaast is een library voor de Arduino beschikbaar (voor zover bekend zonder verdere documentatie).

Analyse van de voorbeelden en code geeft, samen met testen, inzicht in de interface (API) van de MaqueenPlus.

API

De MaqueenPlus heeft intern minimaal 60 register van 8 bits. Deze registers vormen de API en zijn via i2c te lezen en te schrijven, op vergelijkbaar manier als de 24c02 i2c eeprom:

Bij het schrijven is het eerste byte het register-nummer. Het tweede byte wordt in dit register geplaatst. Eventuele volgende bytes worden in de opvolgende registers geplaatst.
Om een register te lezen, wordt eerst het register-adres naar de slave gestuurd. Vervolgens kunnen 1 of meer registers worden uitgelezen.

Het i2c adres van de MaqueenPlus is 0x10. Voor i2c adressering en read/write wordt verwezen naar de datasheet van de 24c02.

Register overzicht

MaqueenPlus API registers (stock firmware)
Register #	Name	Read	Write
0x00	Motor L mode	Set value	1 = drive forward, 2 = drive reverse
0x01	Motor L speed	Actual value	Speed or Pwm
0x02	Motor R mode	Set value	1 = drive forward, 2 = drive reverse
0x03	Motor R speed	Actual value	Speed or Pwm
0x04	Encoder L high byte	Actual value	0 resets counter
0x05	Encoder L low byte	Actual value	0 resets counter
0x06	Encoder R high byte	Actual value	0 resets counter
0x07	Encoder R low byte	Actual value	0 resets counter
0x08	Motor L compensation	Set value	?
0x09	Motor R compensation	Set value	?
0x0A	PID enable	Set value	1 enables PID (MotorSpeed is speed), 0 disables PID (MotorSpeed is pwm)
0x0B	RGB L	Set value	3 lower bits control RGB led (bit0 = Red, bit1 = green, bit2 = blue)

0x14	Servo0
0x15	Servo1
0x16	Servo2

0x1D	LineBits	one bit of each line sensor ('Patrol' in DF-robot speak)
0x1E	L3 High byte	Analog value of floor sensor L3
0x1F	L3 Low byte	Analog value of floor sensor L3
0x20	L2 High byte	Analog value of floor sensor L2
0x21	L2 Low byte	Analog value of floor sensor L2
0x22	L1 High byte	Analog value of floor sensor L1
0x23	L1 Low byte	Analog value of floor sensor L1
0x24	R1 High byte	Analog value of floor sensor R1
0x25	R1 Low byte	Analog value of floor sensor R1
0x26	R2 High byte	Analog value of floor sensor R2
0x27	R2 Low byte	Analog value of floor sensor R2
0x28	R3 High byte	Analog value of floor sensor R3
0x29	R3 Low byte	Analog value of floor sensor R3

0x32	VersionLen	Lenght of version string
0x33	VersionString	First byte of version string

Toelichting op de registers

Als PID mode is ingeschakeld, worden de waarden van register 1 en 3 geinterpreteerd als snelheid. De robot zal zelf de PWM waarde hierop aanpassen. De robot zal hierdoor (beter) rechtuit rijden maar langzamer reageren op wijzigingen.
Als PID mode is uitgeschakeld, worden de waarden van register 1 en 3 geinterpreteerd als PWM waarde.
Het uitlezen van registers 1 en 3 geeft een actuele waarde. Nog uit te zoeken wat hiervan de eenheid is in zowel PID als non-PID mode.
De enocoders geven 90 ticks per omwenteling en lopen altijd op, ongeacht de draairichting van de wielen.
Registers 8 en 9 lijken bedoeld om de robot (ook zonder PID) zo goed mogelijk rechtuit te laten rijden. Nog uitzoeken.
De calibratie-waarden van de robot (zie gebruik calc-key in handleiding) bepalen de schakelpunten voor de linebits (register 0x1D). De blauwe leds boven de line-sensoren volgen de linebits.

Overig

Naast bovengenoemde registers bevat register 0x64-0x69 (100-105) een copy van de analoge waarden van de vloersensor, maar dan in LLHH formaat. De overige registers lijken geen functie te hebben. Er is geen register gevonden voor de PID instellingen (naast aan/uit), de calibratie-waarden van de linesensoren of encoder-data met teken of met hogere resolutie.

Het heeft er alle schijn van dat DFRobot een mooi, elegant robotje heeft gemaakt, maar verzuimd heeft dit te documenteren voor gebruikers buiten de STEM doelgroep. Daarnaast worden de mogelijkheden van de hardware beperkt de stock firmware.

De I2C master

micro:bit & MicroPython

Bovenstaande beschrijving geeft - meer dan de Python voorbeelden - inzicht in de mogelijkheden van de MaqueenPlus en kunnen toegepast worden met de micro:bit en MicroPython.

Er is een eigen pagina op deze Wiki met uitleg hoe de MaqueenPlus in MicroPython kan worden geprogrammeerd, klik op de link om naar deze pagina te gaan:

MaqueenPlus programmeren in Micropython

micro:bit & Arduino

Naast MicroPython kun je de microbit ook programmeren met de Arduino IDE. Adafruit beschrijft hoe je dit doet. De highlights om te starten:

Download Softdevice microbit-adv.hex en copieer dit naar microbit usb-drive.
Voeg de Board Manager URL 'https://sandeepmistry.github.io/arduino-nRF5/package_nRF5_boards_index.json' toe in de Arduino IDE.
Installeer 'Nordic Semiconductor nRF5 Boards' bij de Boards manager.

En dan:

select board: 'BBC microbit'
select Softdevice 'S110'
select port (aangenomen dat mbed serial driver al is geïnstalleerd)

Met onderstaand blink-voorbeeld van Adafruit kun je controleren of het helemaal werkt.

const int COL1 = 3;     // Column #1 control
const int LED = 26;     // 'row 1' led
 
void setup() {  
  Serial.begin(9600);
  
  Serial.println("microbit is ready!");
 
  // because the LEDs are multiplexed, we must ground the opposite side of the LED
  pinMode(COL1, OUTPUT);
  digitalWrite(COL1, LOW); 
   
  pinMode(LED, OUTPUT);   
}
 
void loop(){
  Serial.println("blink!");
  
  digitalWrite(LED, HIGH);
  delay(500);
  digitalWrite(LED, LOW);
  delay(500);
}

Voeg de volgende code toe aan je sketch op printf werkend te maken.

extern "C" int _write(int file, char *buffer, int size)
   {
      Serial.write(buffer, size);
       return 0;
   }

DFRobot heeft op github een library voor de de MaqueenPlus op github geplaatst, inclusief voorbeelden. Deze, samen met de API beschrijving hierboven, moet voldoende zijn om dit werken te krijgen.

andere processoren

I2c is standaard en de MaqueenPlus kan daardoor aangestuurd worden met iedere microcontroller die i2c ondersteunt (en dat is defacto iedere microcontroller met 2 vrije IO pinnen). Zoals bijvoorbeeld de Arduino Nano, de STM32F103 Blue Pill, de STM32F411 Black Pill of... welke andere processor dan ook.

Met deze aanpak zijn de volgende functies van de MaqueenPlus niet toegankelijk, omdat ze direct op de edge connector zijn aangesloten:

IR detector (voor afstandsbedienging)
Buzzer
De io-8 pinnen aan de achterzijde.

Deze robot is ontworpen voor de micro:bit en het is daarom niet logisch om deze te vervangen door een andere processor. Tenzij je een systeem met specifieke mogelijkheden, zoals wifi, beeldverwerking, of AI op dit robot-platform wilt plaatsen. Of als je je favoriete taal / IDE / debugger wilt gebruiken en deze niet beschikbaar is voor de micro:bit. Twee draadjes + massa en je bent klaar. En als het energieverbruik niet te groot is, kun je je systeem zelfs voeden vanuit de MaqueenPlus!

Direct programmeren van de MaqueenPlus

De robot is voorzien van een STM32F103C8T6, de 32-bit ARM processor van de bekende 'blue pill'. Naast het linker wiel kan een header worden gesoldeerd en de contacten zijn gelabeld G-R-C-V-D. Dit blijkt een SWD programmeer-aansluiting te zijn met de volgende aansluitingen:

D - SW_Data
V - 3.3V
C - SW_CLock
R - Reset
G - Ground

DFRobot doet weinig moeite om zaken ontoegankelijk te maken! En in de hoop dat de firmware uit te lezen is, wordt een ST-Link aangesloten. Helaas... blijkt dat niet het geval te zijn en door een foutje wis ik de firmware en heb ik een onbruikbare robot...

Maar... ieder nadeel heeft z'n voordeel. Ik heb een leuk, klein robotje met potentie. De robot is voorzien van een bekende processor en de opzet lijkt recht-toe recht-aan. Hoe moeilijk kan het zijn om uit te zoeken hoe de robot is opgebouwd en zelf een programmatje te schrijven om de hardware aan te sturen?

Niet zo moeilijk, blijkt...

Hardware - de inventarisatie

Lijnsensoren

De Maqueen Plus heeft 6 lijnsensoren en dat is een goed startpunt. Ieder van deze sensoren heeft 4 aansluitingen (LED en foto-transistor) en daarvan hangen er 2 aan de voeding. De andere twee zijn met weerstanden van resp. 220 Ohm en 4.7 kOhm verbonden naar massa. Typische waarden voor resp. de led en de foto-transistor. En dat wordt bevestigd doordat de van de pin, die via 4k7 met massa is verbonden, ook een printspoor wegloopt. Met een multimeter wordt vastgesteld dat ieder van lijnsensoren is verbonden met een pin van de processor, allemaal analoge ingangen.

Leds

Ieder van de lijnsensoren is voorzien van een blauwe leddie oplicht als de sensor een reflectie (wit) ziet. Er blijkt geen connectie tussen deze leds en de lijnsensoren. En dat stemt overeen met het gedrag: sinds de firmware is gewist, lichten de LEDs niet meer op.

Bestudering van de print leert dat iedere led is verbonden met de voeding. De andere aansluiting is verbonden met een weerstand van 2 kOhm en van die weerstand loopt een baantje weg. Met de multimeter wordt vastgesteld dat ieder van die leds is verbonden met een pin van de processor.

De Maqueen heeft ook twee grote, 8mm RGB leds. Deze blijken op dezelfde manier aangesloten: een gemeenschappelijke pin aan de voeding en de overige pinnen via een weerstand (330 Ohm in dit geval) verbonden met de processor.

Op vergelijkbare manier worden de pinnen bepaald van de calc-switch en de drie servo-pinnen.

De Maqueen Plus heeft ook 3 I2C connectoren. Het blijkt dat de SCL en SDA pinnen hiervan parallel staan en verbonden zijn met de processor. Waarschijnlijk zijn deze pinnen ook verbonden met de BBC micro:bit connector, maar dat is nu niet relevant...

Motors en encoders

Vlak naast de motoren zitten 2 8-pin chipjes met de markering 75V18. Dit lijkt de motor-controller en enig zoekwerk levert de datasheet op van de XY-75V18, een h-brug die maximaal 1.5A kan leveren. De datasheet is grotendeels in het Chinees, maar de pin-out en waarheidstabel geven voldoende informatie. De twee input-pinnen van de chips zijn verbonden met de processor, op 4 pinnen die PWM ondersteunen. De motoren kunnen dus hard gestuurd worden! Onder de magneten op de motor-as zitten - per motor - 2 chips met 3 pinnen en de markering 6102. Dit blijkt de Cross chip CC6102TO, een hall effect switch volgens de Chinese datasheet (met dank aan Google Translate). Deze vier sensoren zijn aangesloten op de processor, op pinnen van timer 2 en 3. De encoders kunnen dus door de timers worden uitgelezen.

Hardware - de aansturing

Voorgaande zoektocht heeft de gebruikte pinnen opgeleverd. Alle pinnen van de processor blijken in gebruik te zijn, op 3 na. En de pinnen voor de motoren (aansturing en encoders) zijn zo gekozen dat optimaal gebruikt gemaakt kan worden van de 3 timers.

Het enige wat 'ontbreekt' is een seriële poort. Niet nodig als je de oorspronkelijke firmware gebruikt, maar wel erg handig als je zelf aan de slag gaat. Gelukkig zijn er twee opties om een serial port te activeren: op de pinnen van i2c of op pinnen S0 en S1, bedoeld voor de servo. Beide zijn getest en blijken te werken.

Met deze informatie kunnen alle features van de Maqueen Plus worden gebruikt. Een voorbeeld hiervan is te vinden op: https://github.com/jsuijs/ArduinoProjects/tree/master/MaqueenPlusDemo

Features:

Naar keuze kan USART1 (S0/S1) of USART3 (I2C connector) worden gebruikt.
Een functie om de motoren aan te sturen (pwm door timer 1).
Een functie om de encoders uit te lezen (die door de timers 2 en 3 worden gevolgd).
Een functie om de beide RGB leds aan te sturen.
Een functie om de individuele lijnsensoren analoog uit te lezen.

De code is (nog) niet compatible met de originele firmware. Zo is de Maqueen geen I2C slave, worden de 5 leds bij de lijnsensoren niet aangestuurd en werkt kalibratie van de lijnsensoren niet. Maar de basis is gelegd en er lijken geen opstakels om dit toe te voegen...