Robotling API (MMBasic)

• Die Roboter-API
• Hinweise zur Servo-Pin-Belegung

Die Roboter-API (nun in rbl_lib.bas)

Pinbelegung

Die Robotling2-Funktionsbibliothek (library) erwartet die folgende Pin-Belegung:

'   M1  = Pin 14 (GP10) -> Servo motor 1 (PWM5A)
'   M2  = Pin 27 (GP21) -> Servo motor 2 (PWM2B)
'   M3  = Pin 4  (GP2)  -> Servo motor 3 (PWM1A)
'   LED = Pin 15 (GP11) -> Onboard LED

Falls ein Time-Of_Flight Distanzsensor von Pololu angeschlossen ist:

'   A0  = Pin 32 (GP26) -> left distance sensor out
'   A1  = Pin 32 (GP27) -> centre distance sensor out
'   D0  = Pin 5  (GP3)  -> right distance sensor out

Wichtige Konstanten

Die Belegung der Erweiterungsleiste (servo port):

Const R.TX  = 6   ' GP4  / COM2
Const R.RX  = 7   ' GP5
Const R.SDA = 1   ' GP0  / I2C
Const R.SCL = 2   ' GP1
Const R.A0  = 31  ' GP26 / ADC0
Const R.A1  = 32  ' GP27 / ADC1
Const R.A2  = 34  ' GP28 / ADC2
Const R.D0  = 5   ' GP3
Const R.D1  = 29  ' GP22

• R.DISPLAY Gibt die Art des erkannten Displays an (siehe R.GetDisplayType())

Globale Variablen

• R.LibVersion
  liefert die Version der Bibliothek als Gleitkommazahl

• R.Name$
  liefert derzeit Robotling2

• R.Servos_On
  1=Default, Servos sind an; 0=Servos bleiben aus

• R.Verbose
  1=Default, es werden Zustandsnachrichten ausgegeben; 0=Keine Nachrichten

• R.Debug
  0=Default, 1=Detailierte Fehlermeldung werden ausgegeben

• R.D_Cliff in cm
  20=Default, alles jenseits dieses Abstands ist eine Klippe

• R.D_Object in cm
  5=Default, alles näher als dieser Abstand ist ein Hindernis

Subroutinen und Funktionen

Bewegung

• R.Move mode, vel
  Lässt den Roboter abhängig von modezu loslaufen. mode kann die Werte STOP, FORWARD, TURN_LEFT, TURN_RIGHT oder BACKWARD annehmen. vel gibt die Geschwindigkeit in Prozent an.

• R.Stop
  Hält den Roboter an.

• R.isMoving() As integer
  Liefert 1 zurück, wenn eine Bewegung im Gange ist, ansonsten 0.

• R.MoveServos dt_ms, a1_deg, a2_deg, a3_deg
  Bewegt die Servomotoren innerhalb von dt_ms Millisekunden zu den Winkeln a1_deg, a2_deg und a3_deg. Der Befehl stößt die Bewegung an und kehrt sofort zurück; die Bewegung selbst wird von einer Interrupt-Routine am laufen gehalten.

• _Angle2Duty(i, a_deg) As float
  Berechnet für Servomotor i anhand eines Winkels (in °) den "duty cycle" (in %).

Power

• R.Shutdown
  Fährt den Roboter herunter

• R.Power state
  Schaltet die Servos und ggf. ein Display an (1) oder aus (0)

LEDs

• R.SetLED state
  Schaltet die LED auf dem Robotling2-Board an (1) oder aus (0).

• R.SetRGBLED rgb, mode
  Setzt die RGB-LED auf dem Breakout des PicoDisplays auf die Farbe rgb. mode kann weggelassen werden (=nur Farbe setzen), START_BEAT (Pulsieren starten) oder STOP_BEAT (Pulsieren anhalten) sein.

Sensoren

• R.CreateSensor i, pin, type, nAv, mode
  Initialisiert den Sensor i des Typs type am Pin pin. type kann SHARP_IR_15 oder POLOLU_TOF_50 sein nAv ist die Anzahl der Messungen, die gemittelt werden ("sliding average") mode kann beim Typ POLOLU_TOF_50 den Wert USE_PULSIN (=benutze Pulsin) annehmen.

• R.Dist_cm(i)
  Liefert die gemessene Distanz (in cm) für Sensor i zurück.

Display

• R.GetDisplayType() Versucht das angeschlossene Display zu erkennen:
  0= kein Display erkannt
  1= Pimoroni 240x135 pico display pack (1)
  2= Pimoroni 240x240 1.3" display

• R.Splash t_ms
  Zeigt den Splash-Screen mit Versionsinformationen für t_ms Millisekunden an.

• R.CreateGUI
  Erzeugt eine GUI auf dem Display, falls eines angeschlossen ist.

• R.UpdateGUI t_on_s
  Aktualisiert die GUI auf dem Display. Wenn t_on_s > 0 wird die GUI auch aktualisiert, wenn sich der Roboter sich im Ruhezustand befindet.

• R.OnKey key, cb$
  Hängt die Routine mit dem Namen cb$ an den Schalter key auf dem Display-Breakout. key kann R.KEY_A, R.KEY_B, R.KEY_X oder R.KEY_Y sein.
  Nur für R.DISPLAY = 1

Status und Kontrolle

• R.Spin tout_ms, untilMoveDone
  Wartet für tout_ms Millisekunden; wenn untilMoveDone = END_OF_MOVE kehrt die Funktion bereits zurück, wenn die laufende Bewegung abgeschlossen ist.
  Diese Routine muss statt Pause aufgerufen werden, da R.Spin verschiedene Prozesse am Laufen hält, wie z.B. das Auslesen der Sensoren, das Pulsieren der RGB-LED und das Updaten der GUI auf dem Display.

• R.Log type, msg$
  Gibt die Nachricht msg$ vom Typ type (NONE, INFO oder ERR) im Terminal aus.

• R.Mode()
  Liefert den aktuellen Status (mode) des Roboters zurück.
  R.State$(R.Mode()) liefert den Status als String.

Hinweise zu Servo-Pin-Belegung

Die Pins der Servomotoren werden entsprechend der Belegung auf der Platine im Programm über Konstanten festgelegt:

  Const R.M1  = 14 ' Servo motor 1 (PWM5A)
  Const R.M2  = 27 ' Servo motor 2 (PWM2B)
  Const R.M3  = 4  ' Servo motor 3 (PWM1A)

Man sollte daher meinen, dass man einfach die Pins ändern, um die Servos über andere Pins zu betreiben. Leider macht dies MMBasic nicht einfach, denn obwohl die Zuordnung von Pin und PWM-Kanal (z.B. Pin 14 -> PWM5A) eigentlich beim Pico festgelegt ist - jeder Pin kann nur einen bestimmten Kanal steuern - verlangt SetPin explizit die Kanalnummer (z.B. SetPin 14, PWM5A). Als Kanalnummer wird hier keine Variable akzeptiert. Bei der Ansteuerung des PWM-Kanals durch PWM (z.B. PWM 5, SERV_FREQ_HZ, p0) kann der Kanal zwar eine Variable sein, aber der Befehl steuert ein PWM-Kanalpaar, d.h. die Angabe PWM5A landet als Kanalpaarnummer (5) und Argumentposition (=Kanal A oder B) in der Parameterliste. D.h. man kann aus der Pin-Nummer zwar auf den Kanal schließen, aber der Code, der ein flexibles Wechseln der Pins ermöglicht, ist umständlich.

Der Einfachheit halber stehen daher am Ende des Programms (bzw. in der library-Version am Ende von rbl_lib.bas) zwei Subroutinen, die immer benutzt werden, wenn die Servos bewegt werden sollen. Möchte man also die Servo-Pins anpassen, muss man nur hier den Code ändern, damit die richtigen PWM-Kanäle angesteuert werden:

Sub _SetPin_M123
  SetPin R.M1, PWM5A
  SetPin R.M2, PWM2B
  SetPin R.M3, PWM1A
End Sub

Sub _PWM_M123 p0, p1, p2, off
  ' Set PWM for all walk servos or switch off (`off` == 1)
  If off Then
    PWM 5, OFF
    PWM 2, OFF
    PWM 1, OFF
  Else
    PWM 5, SERV_FREQ_HZ, p0
    PWM 2, SERV_FREQ_HZ,,p1
    PWM 1, SERV_FREQ_HZ, p2
  EndIf
End Sub