BoardControl Schnittstellen-Referenz

Die JavaScript-Bibliothek aus dem BoardControl-Paket zur Fernsteuerung eines BBC micro:bit enthält einen Namespace namens MicroBit mit folgendem Inhalt:

• WebBTisSupported
  ist true falls der benutzte Browser Web Bluetooth unterstützt und false falls nicht
• WebBTisAvailable
  ist true falls Web Bluetooth eingeschaltet ist und false falls nicht. Falls Bluetooth im laufenden Betrieb ein- und ausgeschaltet wird, reflektiert WebBTisAvailable den jeweils aktuellen Zustand
• Board
  ist eine Klasse, deren Instanzen eine Bluetooth-Verbindung zu einem BBC micro:bit repräsentieren

Die Schnittstelle der Klasse MicroBit.Board enthält u.a. eine Reihe von Akzessor-Methoden ähnlich wie sie jQuery definiert:

• ohne Argumente aufgerufen, liefern die Akzessor-Methoden den aktuellen Wert einer Eigenschaft zurück,
• mit Argumenten aufgerufen, ändern die Akzessor-Methoden den Wert der zugehörigen Eigenschaft.

Der Grund für diese Art der Modellierung ist die asynchrone Natur aller Zugriffe auf WebBT-Geräte, die von JavaScript-Gettern und -Settern nicht abgebildet werden kann, von Methoden aber sehr wohl.

Aufrufe mit Seiteneffekten liefern die Zielinstanz der Methode zurück - auf diese Weise können mehrere Methodenaufrufe hintereinander geschaltet werden.

Instanzen der Klasse MicroBit.Board bieten folgende Methoden an:

• isConnected ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht oder false sonst
• async connect ():Promise<Board>
  beginnt einen Vorgang zur Verbindung mit einem BCC micro:bit
• async disconnect ():Promise<Board>
  trennt eine ggfs. bestehende Verbindung zu einem BCC micro:bit

Device Information Service

• DeviceInfoServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "Device Information Service" anbietet oder false sonst
• async ModelNumber ():Promise<string>
  liefert den "Model Number String" aus dem "Device Information Service" eines verbundenen BCC micro:bit
• async SerialNumber ():Promise<string>
  sollte eigentlich den "Serial Number String" aus dem "Device Information Service" eines verbundenen BCC micro:bit liefern, allerdings scheint diese Characteristic auf dem Board derzeit nicht implementiert zu sein
• async FirmwareRevision ():Promise<string>
  liefert den "Firmware Revision String" aus dem "Device Information Service" eines verbundenen BCC micro:bit
• async HardwareRevision ():Promise<string>
  sollte eigentlich den "Hardware Revision String" aus dem "Device Information Service" eines verbundenen BCC micro:bit liefern, allerdings scheint diese Characteristic auf dem Board derzeit nicht implementiert zu sein
• async ManufacturerName ():Promise<string>
  sollte eigentlich den "Manufacturer Name String" aus dem "Device Information Service" eines verbundenen BCC micro:bit liefern, allerdings scheint diese Characteristic auf dem Board derzeit nicht implementiert zu sein

Accelerometer Service

• AccelerometerServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "Accelerometer Service" anbietet oder false sonst
• async AccelerometerData ():Promise<{x:number,y:number,z:number}>
  liefert die aktuellen Messwerte des Accelerometers in den drei Raumachsen x,y und z in Vielfachen der Erdbeschleunigung g
• on('AccelerometerData', Handler:Function):Board
  sobald Sie einen Event Handler für das Event AccelerometerData registrieren, wird das angeschlossene Board veranlasst, im Abstand von jeweils AccelerometerInterval Millisekunden laufend neue Accelerometer-Messwerte zu verschicken
• async AccelerometerInterval ():Promise<number>
  liefert das aktuell eingestellte Intervall (gemessen in Millisekunden) für das laufende Senden von Accelerometer-Messwerten
• async AccelerometerInterval (Interval:number):Promise<Board>
  stellt das Intervall für das laufende Senden von Accelerometer-Messwerten auf den angegebenen Wert (gemessen in Millisekunden). Zulässig sind lediglich die Werte 1, 2, 5, 10, 20, 80, 160 und 640.

Magnetometer Service

• MagnetometerServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "Magnetometer Service" anbietet oder false sonst
• async MagnetometerData ():Promise<{x:number,y:number,z:number}>
  liefert die aktuellen Messwerte des Magnetometers in den drei Raumachsen x,y und z in Mikro-Tesla
• on('MagnetometerData', Handler:Function):Board
  sobald Sie einen Event Handler für das Event MagnetometerData registrieren, wird das angeschlossene Board veranlasst, im Abstand von jeweils MagnetometerInterval Millisekunden laufend neue Magnetometer-Messwerte zu verschicken
• async MagnetometerInterval ():Promise<number>
  liefert das aktuell eingestellte Intervall (gemessen in Millisekunden) für das laufende Senden von Magnetometer-Messwerten. Eigentlich sind nur die Werte 1, 2, 5, 10, 20, 80, 160 und 640 zulässig, beim Autor meldet das Board aber auch schon einmal einen Wert von 100ms.
• async MagnetometerInterval (Interval:number):Promise<Board>
  stellt das Intervall für das laufende Senden von Magnetometer-Messwerten auf den angegebenen Wert (gemessen in Millisekunden). Zulässig sind lediglich die Werte 1, 2, 5, 10, 20, 80, 160 und 640.
• async MagnetometerBearing ():Promise<number>
  liefert den Winkel zwischen der y-Achse des BBC micro:bit und der magnetischen Nordrichtung in Grad (0...359)
• on('MagnetometerBearing', Handler:Function):Board
  sobald Sie einen Event Handler für das Event MagnetometerBearing registrieren, wird das angeschlossene Board veranlasst, im Abstand von jeweils MagnetometerInterval Millisekunden laufend neue Richtungswerte zu verschicken
• async MagnetometerCalibrationState (State:1):Promise<Board>
  veranlasst das angeschlossene Board dazu, eine Kalibrierung des Magnetometers zu beginnen. Der Benutzer wird dabei eigentlich durch Hinweise auf der LED-Anzeige geführt - allerdings bricht der Vorgang (beim Autor) nach kurzer Zeit ab und das Board muss zurückgesetzt werden.
• on('MagnetometerCalibrationState', Handler:Function):Board
  sobald Sie einen Event Handler für das Event MagnetometerCalibrationState registrieren, wird das angeschlossene Board veranlasst, bei Änderungen des Kalibrierungszustandes automatisch den neuen Zustand zu verschicken

Temperature Service

• TemperatureServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "Temperature Service" anbietet oder false sonst
• async Temperature ():Promise<number>
  liefert den aktuellen Wert der Prozessor-Temperatur (in °C) zurück - und da der Chip meist kaum wärmer als die Umgebung ist, kann dieser Messwert auch zur Abschätzung der Umgebungstemperatur verwendet werden
• on('Temperature', Handler:Function):Board
  sobald Sie einen Event Handler für das Event Temperature registrieren, wird das angeschlossene Board veranlasst, im Abstand von jeweils TemperatureInterval Millisekunden laufend neue Messwerte zu verschicken
• async TemperatureInterval ():Promise<number>
  liefert das aktuell eingestellte Intervall (gemessen in Millisekunden) für das laufende Senden von Temperatur-Messwerten. Die Ergebnisse liegen im Bereich von 0 bis 65535
• async TemperatureInterval (Interval:number):Promise<Board>
  stellt das Intervall für das laufende Senden von Temperatur-Messwerten auf den angegebenen Wert (gemessen in Millisekunden). Zulässig sind Werte von 0 bis 65535

Button Service

• ButtonServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "Button Service" anbietet oder false sonst
• async ButtonA ():Promise<number>
  liefert den aktuellen Zustand des linken Tasters. Mögliche Werte sind 0 (nicht gedrückt), 1 (gedrückt) oder 2 (lange gedrückt)
• on('ButtonA', Handler:Function):Board
  sobald Sie einen Event Handler für das Event ButtonA registrieren, wird das angeschlossene Board veranlasst, Zustandsänderungen des linken Tasters automatisch zu melden
• async ButtonB ():Promise<number>
  liefert den aktuellen Zustand des rechten Tasters. Mögliche Werte sind 0 (nicht gedrückt), 1 (gedrückt) oder 2 (lange gedrückt)
• on('ButtonB', Handler:Function):Board
  sobald Sie einen Event Handler für das Event ButtonA registrieren, wird das angeschlossene Board veranlasst, Zustandsänderungen des rechten Tasters automatisch zu melden

LED Service

• LEDServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "LED Service" anbietet oder false sonst
• async LEDMatrix ():Promise<number>
  liefert den aktuellen Zustand der LED-Matrix in Form einer Ganzzahl, deren Bits einzelnen Leuchtdioden aus de Matrix zugeordnet sind: Bit 24 entspricht der linken oberen LED (Zeile 0, Spalte 0), Bit 0 der rechten unteren (Zeile 4, Spalte 4). Die anderen LEDs werden zeilenweise von links nach rechts den restlichen Bits zugeordnet
• async LEDMatrix (Bitmask:number):Promise<Board>
  ändert den Zustand der LED-Matrix. Dazu wird in Bitmask eine Ganzzahl übergeben, deren Bits einzelnen Leuchtdioden aus de Matrix zugeordnet sind: Bit 24 entspricht der linken oberen LED (Zeile 0, Spalte 0), Bit 0 der rechten unteren (Zeile 4, Spalte 4). Die anderen LEDs werden zeilenweise von links nach rechts den restlichen Bits zugeordnet
• async LEDText (Text:string):Promise<Board>
  lässt den gegebenen Text auf der LED-Matrix (einmalig) von rechts nach links durchlaufen. Text darf bis zu 20 ASCII-Zeichen enthalten, andere Zeichen als diejenigen aus dem ASCII-Zeichensatz werden nicht angezeigt
• async LEDScrollDelay ():Promise<number>
  liefert den aktuell eingestellten Wert für die Verzögerung zwischen den einzelnen Anzeigeschritten einer Laufschrift (gemessen in Millisekunden). Die Ergebnisse liegen im Bereich von 0 bis 65535
• async LEDScrollDelay (Interval:number):Promise<Board>
  stellt die Verzögerung zwischen den einzelnen Anzeigeschritten einer Laufschrift auf den angegebenen Wert (gemessen in Millisekunden). Zulässig sind Werte von 0 bis 65535, ein guter Wert ist 100

IO Pin Service

• IOPinServiceIsSupported ():boolean
  liefert true falls eine Verbindung zu einem BCC micro:bit besteht und das Gerät einen "IO Pin Service" anbietet oder false sonst
• async IOPinDirections ():Promise<number>
  liefert die aktuelle Richtungseinstellung der GPIO-Anschlüsse 0 bis 20 in Form einer Ganzzahl, deren n-tes Bit dem n-ten Pin zugeordnet ist. Ein gelöschtes Bit steht für einen Ausgabe-Pin, ein gesetztes Bit für einen Eingabe-Pin. Achtung: die Bedeutung der Pins 17...19 ist dem Autor unklar!
• async IOPinDirections (Bitmask:number):Promise<Board>
  ändert die Richtungseinstellung der GPIO-Anschlüsse 0 bis 20. Dazu wird in Bitmask eine Ganzzahl übergeben, deren n-tes Bit dem n-ten Pin zugeordnet ist. Ein gelöschtes Bit steht für einen Ausgabe-Pin, ein gesetztes Bit für einen Eingabe-Pin. Achtung: die Bedeutung der Pins 17...19 ist dem Autor unklar!
• async IOPinModes ():Promise<number>
  liefert die aktuelle Moduseinstellung der GPIO-Anschlüsse 0 bis 20 in Form einer Ganzzahl, deren n-tes Bit dem n-ten Pin zugeordnet ist. Ein gelöschtes Bit steht für einen digitalen Pin, ein gesetztes Bit für einen analogen. Achtung: die Bedeutung der Pins 17...19 ist dem Autor unklar!
• async IOPinModes (Bitmask:number):Promise<Board>
  ändert die Moduseinstellung der GPIO-Anschlüsse 0 bis 20. Dazu wird in Bitmask eine Ganzzahl übergeben, deren n-tes Bit dem n-ten Pin zugeordnet ist. Ein gelöschtes Bit steht für einen digitalen Pin, ein gesetztes Bit für einen analogen. Achtung: die Bedeutung der Pins 17...19 ist dem Autor unklar!
• async IOPinData ():Promise<{Pin:number,Value:number}[]>
  liefert die aktuellen Werte aller als Eingabe-Pin konfigurierten GPIO-Anschlüsse. Das Ergebnis ist eine Liste von Objekten mit den Feldern Pin und Value: Pin gibt die Nummer eines Pins an (im Bereich 0...20), Value dessen Wert - für digitale Pins ist Value entweder 0 oder 1, für analoge Pins liegt er im Bereich 0...255. Ausgabe-Pins tauchen in der gelieferten Liste niemals auf
• async IOPinData (DataList:{Pin:number,Value:number}[]):Promise<Board>
  ändert den Wert aller angegebenen Ausgabe-Pins. dazu wird in DataList eine Liste von Objekten mit den Feldern Pin und Value übergeben: Pin gibt die Nummer des zu ändernden Pins an (im Bereich 0...20), Value den zu setzenden Wert (im Bereich 0...255) - digitale Pins werden gelöscht, wenn der gegebene Wert 0 ist, anderenfalls werden sie gesetzt. Eingabe-Pins, die in DataList auftauchen, bleiben unbehelligt
• async IOPinPWMControl (DataList:{Pin:number,Value:number,Period:number}[]):Promise<Board>
  versetzt bis zu zwei digitale Ausgabe-Pins in einen PWM-Modus. Dazu wird in DataList eine Liste von bis zu zwei Objekten mit den Feldern Pin, Period und Value übergeben: Pin gibt die Nummer des zu ändernden Pins an (zulässige Werte sind 0...4 oder 10), Period die Periode der PWM-Ausgabe (gemessen in Mikrosekunden, im Bereich 0...4294967295) und Value bestimmt die relative Dauer eines einzelnen Pulses (im Bereich 0...1024: 0 schaltet die PWM-Ausgabe ab, 1 erzeugt den kürzestmöglichen Puls, 1024 den längstmöglichen)

Die Belegung der einzelnen Anschlüsse und deren Bedeutung finden Sie in [3]

Abb. 1: Anschlussbelegung eines BBC micro:bit

Event Support

• on (EventName:string, EventHandler:Function):Board
  trägt die Funktion EventHandler als Handler für das Event EventName ein. Ist die Funktion dort bereits eingetragen, so passiert nichts
• off ():Board
  entfernt alle registrierten Event Handler - für alle möglichen Events
• off (EventName:string):Board
  entfernt alle für das Event EventName registrierten Event Handler und lässt die Registrierungen für alle anderen Events unbehelligt
• off (EventName:string, EventHandler:Function):Board
  entfernt nur die Funktion EventHandler aus der Liste aller für das Event EventName registrierten Event Handler und lässt alle anderen unbehelligt. Ist die Funktion nicht registriert, passiert nichts.
• dispatchEvent (EventName:string, ...ArgumentList:any[]):Board
  ruft jeden für das Event EventName registrierten Event Handler mit den restlichen beim Aufruf von dispatchEvent mitgegebenen Argumenten auf

Literaturverzeichnis