vincibot 0.2.0__py3-none-any.whl

vincibot/__init__.py

@@ -0,0 +1,10 @@
+"""vincibot – den VinciBot (MatataStudio) per Bluetooth mit Python steuern."""
+from .roboter import VinciBot
+from .asynchron import VinciBotAsync
+from ._protokoll import Sensorwerte
+from ._typen import Farbe
+from ._woerter import RoboterFehler, FARBEN
+from ._verbindung import VerbindungsFehler
+
+__all__ = ["VinciBot", "VinciBotAsync", "RoboterFehler", "VerbindungsFehler", "Sensorwerte", "Farbe", "FARBEN"]
+__version__ = "0.2.0"

vincibot/_protokoll.py

@@ -0,0 +1,109 @@
+"""Internes: Aufbau der Bluetooth-Pakete (für Anfänger nicht nötig)."""
+from collections.abc import Iterable
+from typing import TypedDict
+
+class Sensorwerte(TypedDict):
+    """Die aktuellen Messwerte des Roboters."""
+    hell_links: int
+    hell_rechts: int
+    linie: list[int]
+    geraeusch: int
+    farbe: tuple[int, int, int]
+    abstand_cm: float
+    lautstaerke: int
+    tempo: int
+
+
+# Sequenznummern: Der Bot nummeriert Befehlsarten durch und antwortet mit derselben Nummer.
+SEQUENZ: dict[str, int] = {
+    "strecke": 0, "winkel": 1, "fahrt_start": 2, "fahrt_stopp": 3,
+    "strecke_tempo": 4, "winkel_tempo": 5, "motor_lauf": 6, "motor_tempo": 8, "motor_stopp": 9,
+    "tanz": 10, "emotion": 11, "verhalten": 12, "bild": 16, "text": 17, "anzeige_aus": 18,
+    "helligkeit": 19, "pixel": 20, "ausrichtung": 21, "led_feld": 22, "anzeige_drehen": 23,
+    "led_alle": 26, "led_einzeln": 27, "led_aus": 28,
+    "effekt": 31, "lied": 33, "sprich": 35, "datei": 37, "ton_stopp": 38,
+    "lautstaerke": 39, "trommel": 43, "pause": 44, "note": 45, "instrument": 46, "tempo": 47,
+    "ir_senden": 52, "abfrage": 0,
+}
+
+# Begrüßung nach dem Verbinden (wie in der offiziellen Web-Oberfläche)
+BEGRUESSUNG: list[list[int]] = [[126, 2, 2, 0, 0], [1, 1]]
+
+
+def pruefsumme(daten: Iterable[int], startwert: int = 0xFFFF) -> int:
+    ergebnis = startwert
+    for byte in daten:
+        ergebnis = ((ergebnis >> 8) | (ergebnis << 8)) & 0xFFFF
+        ergebnis ^= byte
+        ergebnis ^= (ergebnis & 0xFF) >> 4
+        ergebnis ^= (ergebnis << 12) & 0xFFFF
+        ergebnis ^= ((ergebnis & 0xFF) << 5) & 0xFFFF
+    return ergebnis
+
+
+def _maskiere(byte: int) -> list[int]:
+    if byte == 0xFE:
+        return [0xFD, 0xDE]
+    if byte == 0xFD:
+        return [0xFD, 0xDD]
+    return [byte]
+
+
+def baue_paket(nutzdaten: list[int]) -> bytes:
+    """Startbyte 0xFE, Länge, Nutzdaten, Prüfsumme (Sonderbytes werden maskiert)."""
+    laenge = len(nutzdaten) + 2
+    summe = pruefsumme(nutzdaten, pruefsumme([laenge]))
+    paket: list[int] = [0xFE] + _maskiere(laenge)
+    for byte in nutzdaten:
+        paket += _maskiere(byte)
+    paket += _maskiere(summe >> 8) + _maskiere(summe & 0xFF)
+    return bytes(paket)
+
+
+def baue_befehlspaket(code: str, sequenz: int) -> bytes:
+    """Paket für einen Python-Befehl, den der Bot ausführt."""
+    return baue_paket([0x70, 0x00, sequenz] + list(code.encode("ascii", "replace")))
+
+
+def text_literal(text: object) -> str:
+    """Macht aus beliebigem Text ein Python-Textstück für den Bot (Umlaute als \\uXXXX)."""
+    teile: list[str] = []
+    for zeichen in str(text):
+        if zeichen in "\\'\"":
+            teile.append("\\" + zeichen)
+        elif ord(zeichen) > 127:
+            teile.append("\\u%04x" % ord(zeichen))
+        else:
+            teile.append(zeichen)
+    return "'" + "".join(teile) + "'"
+
+
+def entpacke(puffer: list[int]) -> list[list[int]]:
+    """Holt vollständige Pakete aus einem Byte-Puffer. Gibt (liste_von_nutzdaten) zurück
+    und entfernt Verarbeitetes aus dem Puffer."""
+    pakete: list[list[int]] = []
+    while True:
+        if 0xFE not in puffer:
+            puffer.clear()
+            return pakete
+        del puffer[:puffer.index(0xFE)]
+        roh: list[int] = []
+        i = 1
+        ende = None
+        while i < len(puffer):
+            b = puffer[i]
+            if b == 0xFD and i + 1 < len(puffer):
+                roh.append(0xFE if puffer[i + 1] == 0xDE else 0xFD)
+                i += 2
+            elif b == 0xFD:
+                break
+            else:
+                roh.append(b)
+                i += 1
+            if roh and len(roh) >= roh[0] + 1:
+                ende = i
+                break
+        if ende is None:
+            return pakete          # Paket noch unvollständig
+        del puffer[:ende]
+        pakete.append(roh[1:roh[0] - 1])

vincibot/_typen.py

@@ -0,0 +1,45 @@
+"""Erlaubte Texte für die Befehle, als `Literal`-Typen.
+
+Dadurch erkennt der Editor (Linter) Tippfehler sofort, zum Beispiel `roboter.gefuehl("froelich")`.
+Ein Test (`tests/test_typen.py`) prüft, dass diese Listen zu den Wörterbüchern passen.
+"""
+from typing import Literal
+
+Farbname = Literal["rot", "gruen", "grün", "blau", "gelb", "orange", "lila", "tuerkis", "türkis",
+                   "rosa", "weiss", "weiß", "schwarz", "aus"]
+Farbe = Farbname | tuple[int, int, int]
+
+Position = Literal["links oben", "links mitte", "links unten",
+                   "rechts oben", "rechts mitte", "rechts unten"]
+
+Gefuehl = Literal["froehlich", "fröhlich", "wuetend", "wütend", "traurig", "ueberrascht",
+                  "überrascht", "aengstlich", "ängstlich", "angeekelt", "begeistert", "schwindelig",
+                  "muede", "müde", "schlaefrig", "schläfrig", "wach", "stolz"]
+Tanz = Literal["tango", "walzer", "steppen", "samba", "polonaise", "jazz", "rock", "polka",
+               "rumba", "disco", "mazurka"]
+Bewegung = Literal["umschauen", "verletzt", "sprinten", "kreisen", "schuetteln", "schütteln",
+                   "frech", "stolz"]
+Geraeusch = Literal["krankenwagen", "polizei", "feuerwehr", "zug", "zugpfeife", "schiffshorn",
+                    "flugzeug", "auto", "automotor", "magnetbahn"]
+Lied = Literal["funkel", "jingle bells", "geburtstag", "freude", "holzsoldaten", "jagdpolka",
+               "elise", "forelle", "peter und der wolf"]
+Instrument = Literal["klavier", "e-klavier", "orgel", "gitarre", "e-gitarre", "bass", "zupfbass",
+                     "cello", "posaune", "klarinette", "saxophon", "floete", "holzfloete", "fagott",
+                     "chor", "vibraphon", "spieluhr", "steeldrum", "marimba", "synthesizer",
+                     "weicher synthesizer"]
+Note = Literal["c", "d", "e", "f", "g", "a", "h"]
+
+FahrRichtung = Literal["vorwaerts", "vorwärts", "rueckwaerts", "rückwärts", "links", "rechts"]
+Rad = Literal["links", "rechts", "beide"]
+Einheit = Literal["grad", "umdrehungen", "sekunden"]
+Drehrichtung = Literal["uhrzeigersinn", "gegen"]
+DisplayRichtung = Literal["hoch", "runter", "links", "rechts"]
+
+Seite = Literal["links", "rechts"]
+SensorFarbe = Literal["weiss", "weiß", "rot", "gelb", "gruen", "grün", "blau", "lila", "schwarz"]
+Linienfarbe = Literal["schwarz", "weiss", "weiß"]
+Farbkanal = Literal["rot", "gruen", "grün", "blau"]
+Bodensensor = Literal[1, 2, 3, 4, 5]
+Taste = Literal["dreieck", "quadrat", "kreis"]
+Fernbedienungstaste = Literal["volume", "mode", "speed", "forward", "backward", "left", "right",
+                              "play", "dance", "led", "music", "1", "2", "3"]

vincibot/_verbindung.py

@@ -0,0 +1,160 @@
+"""Internes: Bluetooth-Verbindung (asynchron). Anfänger nutzen stattdessen `VinciBot`."""
+import asyncio
+import shutil
+import sys
+import time
+from dataclasses import dataclass
+
+from bleak import BleakClient, BleakScanner
+from bleak.backends.device import BLEDevice
+from bleak.backends.characteristic import BleakGATTCharacteristic
+
+from ._protokoll import BEGRUESSUNG, Sensorwerte, baue_befehlspaket, baue_paket, entpacke
+
+SCHREIB_UUID = "6e400002-b5a3-f393-e0a9-e50e24dcca9e"
+MELDUNG_UUID = "6e400003-b5a3-f393-e0a9-e50e24dcca9e"
+PAKETGROESSE = 20
+
+
+class VerbindungsFehler(Exception):
+    """Der Roboter konnte nicht gefunden oder verbunden werden."""
+
+
+@dataclass(frozen=True)
+class Antwort:
+    """Die Antwort des Roboters auf einen Befehl."""
+    sequenz: int
+    status: int
+    text: str
+
+    @property
+    def fehler(self) -> bool:
+        return self.status != 0
+
+class Verbindung:
+    def __init__(self, adresse: str | None = None, namensanfang: str = "VinciBot",
+                 suchdauer: float = 15) -> None:
+        self.adresse: str | None = adresse
+        self.namensanfang: str = namensanfang
+        self.suchdauer: float = suchdauer
+        self.sensoren: Sensorwerte | None = None
+        self._client: BleakClient | None = None
+        self._puffer: list[int] = []
+        self._erwartet: dict[int, asyncio.Future[Antwort]] = {}
+        self._begruessung: asyncio.Future[list[int]] | None = None
+        self._letzte_meldung: tuple[bytes, float] = (b"", 0.0)
+        self.firmware: str | None = None
+
+    async def _suche(self) -> BLEDevice | None:
+        if self.adresse:
+            return await BleakScanner.find_device_by_address(self.adresse, timeout=self.suchdauer)
+        return await BleakScanner.find_device_by_filter(
+            lambda g, _: bool(g.name) and g.name.startswith(self.namensanfang),
+            timeout=self.suchdauer)
+
+    async def _haengende_verbindung_loesen(self) -> bool:
+        """Linux: Ein Roboter, der im System noch als 'verbunden' gilt (z. B. nach einem
+        abgebrochenen Programm), wird nicht mehr gefunden. Dann trennen wir ihn hier."""
+        if not sys.platform.startswith("linux") or shutil.which("bluetoothctl") is None:
+            return False
+        prozess = await asyncio.create_subprocess_exec(
+            "bluetoothctl", "devices", "Connected",
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL)
+        ausgabe, _ = await prozess.communicate()
+        gefunden = False
+        for zeile in ausgabe.decode("utf-8", "replace").splitlines():
+            teile = zeile.split(maxsplit=2)
+            if len(teile) == 3 and teile[0] == "Device" and (
+                    teile[1].upper() == (self.adresse or "").upper()
+                    or (not self.adresse and teile[2].startswith(self.namensanfang))):
+                trennen = await asyncio.create_subprocess_exec(
+                    "bluetoothctl", "disconnect", teile[1],
+                    stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL)
+                _ = await trennen.wait()
+                gefunden = True
+        if gefunden:
+            await asyncio.sleep(3)
+        return gefunden
+
+    async def verbinden(self) -> None:
+        # Erst prüfen, ob der Roboter im System noch als "verbunden" hängt (spart die Wartezeit der Suche).
+        _ = await self._haengende_verbindung_loesen()
+        geraet = await self._suche()
+        if geraet is None:
+            raise VerbindungsFehler(
+                "Kein VinciBot gefunden. Ist er eingeschaltet und nicht schon mit einem anderen"
+                + " Programm oder Browser verbunden?")
+        self._client = BleakClient(geraet)
+        await self._client.connect()
+        await self._client.start_notify(MELDUNG_UUID, self._bei_meldung)
+        for nutzdaten in BEGRUESSUNG:
+            self._begruessung = asyncio.get_running_loop().create_future()
+            await self._sende(baue_paket(nutzdaten))
+            try:
+                _ = await asyncio.wait_for(self._begruessung, 3)
+            except asyncio.TimeoutError:
+                pass
+
+    async def trennen(self) -> None:
+        if self._client is not None:
+            try:
+                await self._client.disconnect()
+            finally:
+                self._client = None
+
+    async def _sende(self, paket: bytes) -> None:
+        assert self._client is not None, "Nicht verbunden"
+        for anfang in range(0, len(paket), PAKETGROESSE):
+            await self._client.write_gatt_char(
+                SCHREIB_UUID, paket[anfang:anfang + PAKETGROESSE], response=True)
+
+    def _bei_meldung(self, _: BleakGATTCharacteristic, daten: bytearray) -> None:
+        # Der Roboter schickt jede Meldung doppelt; die zweite Kopie wird ignoriert.
+        jetzt = time.monotonic()
+        if bytes(daten) == self._letzte_meldung[0] and jetzt - self._letzte_meldung[1] < 0.2:
+            return
+        self._letzte_meldung = (bytes(daten), jetzt)
+        self._puffer.extend(daten)
+        for nutzdaten in entpacke(self._puffer):
+            self._verarbeite(nutzdaten)
+
+    def _verarbeite(self, n: list[int]) -> None:
+        if not n:
+            return
+        if n[0] == 0x74 and len(n) >= 16:
+            self.sensoren = Sensorwerte(
+                hell_links=n[1], hell_rechts=n[2], linie=[n[3], n[4], n[5], n[6], n[7]],
+                geraeusch=n[8], farbe=(n[9], n[10], n[11]),
+                abstand_cm=((n[12] << 8) | n[13]) / 10, lautstaerke=n[14], tempo=n[15])
+        elif n[0] == 0x70 and len(n) >= 4:
+            antwort = Antwort(n[2], n[3], bytes(n[4:]).decode("utf-8", "replace"))
+            erwartet = self._erwartet.pop(antwort.sequenz, None)
+            if erwartet and not erwartet.done():
+                erwartet.set_result(antwort)
+        elif n[0] == 1 and len(n) >= 5:
+            self.firmware = f"{n[2]}.{n[3]}.{n[4]}"
+            if self._begruessung and not self._begruessung.done():
+                self._begruessung.set_result(n)
+        elif self._begruessung and not self._begruessung.done():
+            self._begruessung.set_result(n)
+
+    async def firmware_abfragen(self) -> str | None:
+        """Fragt die Firmware-Version des Roboters ab, z. B. "1.2.0"."""
+        self._begruessung = asyncio.get_running_loop().create_future()
+        await self._sende(baue_paket([1, 1]))
+        try:
+            _ = await asyncio.wait_for(self._begruessung, 3)
+        except asyncio.TimeoutError:
+            pass
+        return self.firmware
+
+    async def befehl(self, code: str, sequenz: int = 0, zeitlimit: float = 15) -> Antwort | None:
+        """Führt einen Python-Befehl auf dem Bot aus und wartet auf seine Antwort."""
+        zukunft: asyncio.Future[Antwort] = asyncio.get_running_loop().create_future()
+        self._erwartet[sequenz] = zukunft
+        await self._sende(baue_befehlspaket(code, sequenz))
+        try:
+            return await asyncio.wait_for(zukunft, zeitlimit)
+        except asyncio.TimeoutError:
+            _ = self._erwartet.pop(sequenz, None)
+            return None

vincibot/_woerter.py

@@ -0,0 +1,87 @@
+"""Internes: Wörterbücher (Deutsch -> Befehle des Roboters) und Hilfsfunktionen."""
+from collections.abc import Mapping
+from typing import TypeVar
+
+from ._typen import Farbe
+
+_T = TypeVar("_T")
+
+# ---------------------------------------------------------------- Wörterbücher (Deutsch -> Roboter)
+FARBEN: dict[str, tuple[int, int, int]] = {
+    "rot": (255, 0, 0), "gruen": (0, 255, 0), "grün": (0, 255, 0), "blau": (0, 0, 255),
+    "gelb": (255, 200, 0), "orange": (255, 100, 0), "lila": (160, 0, 255),
+    "tuerkis": (0, 220, 220), "türkis": (0, 220, 220), "rosa": (255, 80, 160),
+    "weiss": (255, 255, 255), "weiß": (255, 255, 255), "schwarz": (0, 0, 0), "aus": (0, 0, 0),
+}
+FARBEN_SENSOR: dict[str, str] = {"weiss": "white", "weiß": "white", "rot": "red", "gelb": "yellow",
+                 "gruen": "green", "grün": "green", "blau": "blue", "lila": "purple",
+                 "schwarz": "black"}
+GEFUEHLE: dict[str, str] = {
+    "froehlich": "happy", "fröhlich": "happy", "wuetend": "angry", "wütend": "angry",
+    "traurig": "sad", "ueberrascht": "surprised", "überrascht": "surprised",
+    "aengstlich": "feared", "ängstlich": "feared", "angeekelt": "disgusted",
+    "begeistert": "joyful", "schwindelig": "dizzy", "muede": "fatigued", "müde": "fatigued",
+    "schlaefrig": "sleepy", "schläfrig": "sleepy", "wach": "awake", "stolz": "proud",
+}
+TAENZE: dict[str, str] = {"tango": "tango", "walzer": "waltz", "steppen": "tap", "samba": "samba",
+          "polonaise": "polonaise", "jazz": "jazz", "rock": "rock", "polka": "polka",
+          "rumba": "rumba", "disco": "disco", "mazurka": "mazurka"}
+BEWEGUNGEN: dict[str, str] = {"umschauen": "look around", "verletzt": "hurt", "sprinten": "sprint",
+              "kreisen": "circling", "schuetteln": "shake", "schütteln": "shake",
+              "frech": "naughty", "stolz": "proud"}
+GERAEUSCHE: dict[str, str] = {
+    "krankenwagen": "ambulance", "polizei": "police car", "feuerwehr": "fire engine",
+    "zug": "train", "zugpfeife": "train whistle", "schiffshorn": "boat whistle",
+    "flugzeug": "aircraft", "auto": "automobile", "automotor": "automobile engine",
+    "magnetbahn": "magnetically levitated train",
+}
+LIEDER: dict[str, str] = {
+    "funkel": "twinkle", "jingle bells": "jingle bells", "geburtstag": "happy birthday to you",
+    "freude": "ode to joy", "holzsoldaten": "parade of the wooden soldiers",
+    "jagdpolka": "hunting polka", "elise": "to alice", "forelle": "die forelle",
+    "peter und der wolf": "peter and the wolf",
+}
+INSTRUMENTE: list[str] = ["klavier", "e-klavier", "orgel", "gitarre", "e-gitarre", "bass", "zupfbass",
+               "cello", "posaune", "klarinette", "saxophon", "floete", "holzfloete", "fagott",
+               "chor", "vibraphon", "spieluhr", "steeldrum", "marimba", "synthesizer",
+               "weicher synthesizer"]
+# Tonhöhen in Hertz für die vierte Oktave (deutsche Notennamen: h statt b/si)
+NOTEN: dict[str, int] = {"c": 262, "d": 294, "e": 330, "f": 349, "g": 392, "a": 440, "h": 494}
+
+
+# Die sechs Lichter von vorne gesehen:   1 6 / 2 5 / 3 4  (Nummer = Platz in der Befehlsliste des Roboters)
+POSITIONEN: dict[str, int] = {
+    "links oben": 1, "links mitte": 2, "links unten": 3,
+    "rechts unten": 4, "rechts mitte": 5, "rechts oben": 6,
+}
+POSITIONEN.update({name.replace(" ", "_"): nr for name, nr in list(POSITIONEN.items())})
+POSITION_NAMEN: dict[int, str] = {nr: name for name, nr in POSITIONEN.items() if " " in name}
+
+
+class RoboterFehler(Exception):
+    """Etwas ist beim Steuern des Roboters schiefgegangen."""
+
+
+def farbe_umrechnen(farbe: Farbe) -> tuple[int, int, int]:
+    """Nimmt einen Farbnamen ('rot') oder drei Zahlen (255, 0, 0) und gibt (r, g, b) zurück."""
+    if isinstance(farbe, str):
+        name = farbe.lower().strip()
+        if name not in FARBEN:
+            raise RoboterFehler(f"Die Farbe '{farbe}' kenne ich nicht. Mögliche Farben: "
+                                + ", ".join(sorted({k for k in FARBEN if k.isascii()})))
+        return FARBEN[name]
+    r, g, b = farbe
+    for wert in (r, g, b):
+        if not 0 <= wert <= 255:
+            raise RoboterFehler("Farbwerte müssen zwischen 0 und 255 liegen.")
+    return (int(r), int(g), int(b))
+
+
+def waehle(name: object, tabelle: Mapping[str, _T], art: str) -> _T:
+    schluessel = str(name).lower().strip()
+    if schluessel not in tabelle:
+        raise RoboterFehler(f"Ich kenne {art} '{name}' nicht. Mögliche Werte: "
+                            + ", ".join(sorted({k for k in tabelle if k.isascii()})))
+    return tabelle[schluessel]
+
+