python-esp-bridge 0.0.2__tar.gz

python_esp_bridge-0.0.2/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

python_esp_bridge-0.0.2/.python-version

@@ -0,0 +1 @@
+3.13

python_esp_bridge-0.0.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: python-esp-bridge
+Version: 0.0.2
+Summary: Control every ESP32 peripheral from Python over USB serial — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE
+Project-URL: Homepage, https://github.com/HamzaYslmn/python-esp-bridge
+Author: HamzaYslmn
+Keywords: ble,bridge,esp32,firmata,gpio,i2c,raspberry-pi,serial,spi
+Requires-Python: >=3.10
+Requires-Dist: pyserial>=3.5
+Provides-Extra: oled
+Requires-Dist: pillow>=10; extra == 'oled'
+Description-Content-Type: text/markdown
+
+# python-esp-bridge
+
+Control every ESP32 peripheral from Python over USB serial — GPIO, PWM, ADC,
+DAC, touch, I2C, SPI, UART, Wi-Fi (with TCP/UDP sockets through the ESP32
+radio) and BLE. Flash the bridge firmware once, then it's all Python.
+
+```python
+from espbridge import Bridge
+
+with Bridge() as esp:                      # auto-detects the USB port
+    esp.gpio.mode(2, "output")
+    esp.gpio.write(2, 1)
+    print(esp.adc.read_mv(34), "mV")
+    esp.i2c.init(sda=21, scl=22)
+    print(esp.i2c.scan())
+    esp.wifi.connect("ssid", "password")
+    status, body = esp.net.http_get("http://example.com/")
+```
+
+- Firmware (flash once with Arduino IDE) and full docs:
+  **<https://github.com/HamzaYslmn/python-esp-bridge>**
+- Works on Raspberry Pi OS, Linux, Windows, macOS (Python ≥ 3.10, pyserial).
+- `espbridge` CLI: connection info; `espbridge ports`: list candidate ports.

python_esp_bridge-0.0.2/README.md

@@ -0,0 +1,23 @@
+# python-esp-bridge
+
+Control every ESP32 peripheral from Python over USB serial — GPIO, PWM, ADC,
+DAC, touch, I2C, SPI, UART, Wi-Fi (with TCP/UDP sockets through the ESP32
+radio) and BLE. Flash the bridge firmware once, then it's all Python.
+
+```python
+from espbridge import Bridge
+
+with Bridge() as esp:                      # auto-detects the USB port
+    esp.gpio.mode(2, "output")
+    esp.gpio.write(2, 1)
+    print(esp.adc.read_mv(34), "mV")
+    esp.i2c.init(sda=21, scl=22)
+    print(esp.i2c.scan())
+    esp.wifi.connect("ssid", "password")
+    status, body = esp.net.http_get("http://example.com/")
+```
+
+- Firmware (flash once with Arduino IDE) and full docs:
+  **<https://github.com/HamzaYslmn/python-esp-bridge>**
+- Works on Raspberry Pi OS, Linux, Windows, macOS (Python ≥ 3.10, pyserial).
+- `espbridge` CLI: connection info; `espbridge ports`: list candidate ports.

python_esp_bridge-0.0.2/espbridge/__init__.py

@@ -0,0 +1,45 @@
+"""espbridge — control every ESP32 peripheral from Python over USB serial.
+
+Flash esp/esp.ino once, then:
+
+    from espbridge import Bridge
+
+    with Bridge() as esp:                # auto-detects the serial port
+        esp.gpio.mode(2, "output")
+        esp.gpio.write(2, 1)
+        print(esp.adc.read(34))
+        print(esp.i2c.scan())
+        esp.wifi.connect("ssid", "password")
+        sock = esp.net.tcp_connect("example.com", 80)  # TCP through the ESP32 radio
+"""
+from .bridge import Bridge, BridgeSet, Info, connect_all
+from .constants import Cap, ChipModel, Status
+from .errors import (
+    BridgeError,
+    BridgeTimeoutError,
+    NoDeviceError,
+    ProtocolError,
+    RemoteError,
+    UnsupportedError,
+)
+from .transport import find_ports
+
+__version__ = "0.0.2"
+
+__all__ = [
+    "Bridge",
+    "BridgeSet",
+    "connect_all",
+    "Info",
+    "Cap",
+    "ChipModel",
+    "Status",
+    "BridgeError",
+    "BridgeTimeoutError",
+    "NoDeviceError",
+    "ProtocolError",
+    "RemoteError",
+    "UnsupportedError",
+    "find_ports",
+    "__version__",
+]

python_esp_bridge-0.0.2/espbridge/analog.py

@@ -0,0 +1,64 @@
+"""ADC (oneshot reads), DAC (write + cosine generator), capacitive touch."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+# Attenuation -> roughly full-scale input voltage on classic ESP32:
+#   0 dB ≈ 1.1 V, 2.5 dB ≈ 1.5 V, 6 dB ≈ 2.2 V, 11 dB ≈ 3.3 V (default)
+ATTEN = {0: 0, 2.5: 1, 6: 2, 11: 3, "0db": 0, "2.5db": 1, "6db": 2, "11db": 3}
+
+
+class Adc:
+    def __init__(self, bridge):
+        self._b = bridge
+
+    def config(self, pin: int, atten=11) -> None:
+        self._b.request(C.ADC_CONFIG, bytes([pin, ATTEN.get(atten, int(atten))]))
+
+    def read(self, pin: int) -> int:
+        """Raw 12-bit reading (0..4095)."""
+        return struct.unpack(">H", self._b.request(C.ADC_READ, bytes([pin])))[0]
+
+    def read_mv(self, pin: int) -> int:
+        """Calibrated millivolts."""
+        return struct.unpack(">H", self._b.request(C.ADC_READ_MV, bytes([pin])))[0]
+
+
+class Dac:
+    """True 8-bit DAC — classic ESP32 (GPIO 25/26) and S2 (GPIO 17/18) only."""
+
+    def __init__(self, bridge):
+        bridge.require(C.Cap.DAC, "DAC")
+        self._b = bridge
+
+    def write(self, pin: int, value: int) -> None:
+        """Output value 0..255 (0..3.3 V)."""
+        self._b.request(C.DAC_WRITE, bytes([pin, value & 0xFF]))
+
+    def cosine(self, pin: int, freq_hz: int, *, scale: int = 0, offset: int = 0,
+               phase_180: bool = False) -> None:
+        """Start the hardware cosine-wave generator (~130 Hz .. ~100 kHz).
+
+        scale: 0..3 = full/half/quarter/eighth amplitude.
+        """
+        self._b.request(C.DAC_COSINE, struct.pack(">BIBbB", pin, freq_hz, scale & 3,
+                                                  offset, 1 if phase_180 else 0))
+
+    def cosine_stop(self, pin: int) -> None:
+        self._b.request(C.DAC_COS_STOP, bytes([pin]))
+
+    def disable(self, pin: int) -> None:
+        self._b.request(C.DAC_DISABLE, bytes([pin]))
+
+
+class Touch:
+    """Capacitive touch pads (classic ESP32: lower = touched; S2/S3: higher = touched)."""
+
+    def __init__(self, bridge):
+        bridge.require(C.Cap.TOUCH, "touch sensing")
+        self._b = bridge
+
+    def read(self, pin: int) -> int:
+        return struct.unpack(">I", self._b.request(C.TOUCH_READ, bytes([pin])))[0]

python_esp_bridge-0.0.2/espbridge/ble.py

@@ -0,0 +1,223 @@
+"""BLE: scanning, advertising, GATT server and basic GATT client."""
+from __future__ import annotations
+
+import queue
+import struct
+import threading
+import time
+import uuid as _uuid
+from dataclasses import dataclass
+
+from . import constants as C
+from .errors import BridgeTimeoutError
+from .protocol import lp
+
+
+def to_uuid128(value: int | str | _uuid.UUID) -> bytes:
+    """16/32-bit ints expand into the Bluetooth base UUID; strs/UUIDs pass through."""
+    if isinstance(value, int):
+        return _uuid.UUID(f"{value:08x}-0000-1000-8000-00805f9b34fb").bytes
+    if isinstance(value, str):
+        return _uuid.UUID(value).bytes
+    return value.bytes
+
+
+@dataclass(frozen=True)
+class Advertisement:
+    addr: str
+    addr_type: int
+    rssi: int
+    data: bytes  # raw advertisement payload (AD structures)
+
+    @property
+    def name(self) -> str | None:
+        """Local name parsed from the AD structures, if present."""
+        i, d = 0, self.data
+        while i + 1 < len(d):
+            length = d[i]
+            if length == 0 or i + 1 + length > len(d) + 1:
+                break
+            ad_type = d[i + 1]
+            if ad_type in (0x08, 0x09):  # shortened / complete local name
+                return d[i + 2 : i + 1 + length].decode("utf-8", "replace")
+            i += 1 + length
+        return None
+
+
+class Characteristic:
+    """A characteristic of the local GATT server."""
+
+    def __init__(self, ble: "Ble", char_id: int, uuid_: bytes):
+        self._ble = ble
+        self.char_id = char_id
+        self.uuid = uuid_
+        self.on_write = None  # callback(bytes)
+
+    def set(self, data: bytes) -> None:
+        self._ble._b.request(C.BLE_GATTS_SET, bytes([self.char_id]) + bytes(data))
+
+    def notify(self, data: bytes) -> None:
+        self._ble._b.request(C.BLE_GATTS_NTFY, bytes([self.char_id]) + bytes(data))
+
+
+class GattClient:
+    """Connection to a remote BLE peripheral (one at a time)."""
+
+    def __init__(self, ble: "Ble"):
+        self._ble = ble
+        self.connected = True
+
+    def read(self, service, char) -> bytes:
+        return self._ble._b.request(
+            C.BLE_GATTC_READ, to_uuid128(service) + to_uuid128(char), timeout=10.0)
+
+    def write(self, service, char, data: bytes) -> None:
+        self._ble._b.request(
+            C.BLE_GATTC_WRITE, to_uuid128(service) + to_uuid128(char) + bytes(data),
+            timeout=10.0)
+
+    def subscribe(self, service, char, callback) -> None:
+        """callback(bytes) for notifications from this characteristic."""
+        self._ble._notify_callbacks[to_uuid128(char)] = callback
+        self._ble._b.request(
+            C.BLE_GATTC_SUB, to_uuid128(service) + to_uuid128(char) + b"\x01",
+            timeout=10.0)
+
+    def unsubscribe(self, service, char) -> None:
+        self._ble._notify_callbacks.pop(to_uuid128(char), None)
+        self._ble._b.request(
+            C.BLE_GATTC_SUB, to_uuid128(service) + to_uuid128(char) + b"\x00",
+            timeout=10.0)
+
+    def disconnect(self) -> None:
+        self.connected = False
+        self._ble._b.request(C.BLE_GATTC_DISC, timeout=10.0)
+
+
+class Ble:
+    # characteristic property flags
+    READ = C.GATT_PROP_READ
+    WRITE = C.GATT_PROP_WRITE
+    NOTIFY = C.GATT_PROP_NOTIFY
+    WRITE_NR = C.GATT_PROP_WRITE_NR
+
+    def __init__(self, bridge):
+        self._b = bridge
+        bridge.require(C.Cap.BLE_FW, "BLE (firmware built without it?)")
+        self._adv_queue: queue.Queue[Advertisement] = queue.Queue(maxsize=512)
+        self._adv_callbacks: list = []
+        self._chars: dict[int, Characteristic] = {}
+        self._notify_callbacks: dict[bytes, object] = {}
+        self._server_connected = threading.Event()
+        bridge.on_event(C.BLE_ADV_EVT, self._on_adv)
+        bridge.on_event(C.BLE_GATTS_WR_EVT, self._on_gatts_write)
+        bridge.on_event(C.BLE_GATTS_CONN_EVT, self._on_gatts_conn)
+        bridge.on_event(C.BLE_GATTC_NTFY_EVT, self._on_notify)
+
+    # ---- events (reader thread) ---------------------------------------------------
+
+    def _on_adv(self, p: bytes) -> None:
+        if len(p) < 8:
+            return
+        adv = Advertisement(
+            addr=":".join(f"{x:02x}" for x in p[0:6]),
+            addr_type=p[6],
+            rssi=int.from_bytes(p[7:8], "big", signed=True),
+            data=p[8:],
+        )
+        for cb in list(self._adv_callbacks):
+            cb(adv)
+        try:
+            self._adv_queue.put_nowait(adv)
+        except queue.Full:
+            pass
+
+    def _on_gatts_write(self, p: bytes) -> None:
+        if not p:
+            return
+        ch = self._chars.get(p[0])
+        if ch is not None and ch.on_write is not None:
+            ch.on_write(p[1:])
+
+    def _on_gatts_conn(self, p: bytes) -> None:
+        if p and p[0]:
+            self._server_connected.set()
+        else:
+            self._server_connected.clear()
+
+    def _on_notify(self, p: bytes) -> None:
+        if len(p) < 16:
+            return
+        cb = self._notify_callbacks.get(bytes(p[:16]))
+        if cb is not None:
+            cb(p[16:])
+
+    # ---- scanning --------------------------------------------------------------------
+
+    def scan(self, duration: float = 5.0, *, active: bool = True,
+             callback=None) -> list[Advertisement]:
+        """Collect advertisements for `duration` seconds.
+
+        With `callback`, advertisements also stream to it live. Returns devices
+        deduplicated by address (strongest RSSI kept).
+        """
+        if callback is not None:
+            self._adv_callbacks.append(callback)
+        while not self._adv_queue.empty():  # drop stale results
+            self._adv_queue.get_nowait()
+        self._b.request(C.BLE_SCAN_START, bytes([min(255, int(duration) + 1), 1 if active else 0]),
+                        timeout=10.0)
+        seen: dict[str, Advertisement] = {}
+        deadline = time.monotonic() + duration
+        while time.monotonic() < deadline:
+            try:
+                adv = self._adv_queue.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            cur = seen.get(adv.addr)
+            if cur is None or adv.rssi > cur.rssi or (adv.name and not cur.name):
+                seen[adv.addr] = adv
+        self._b.request(C.BLE_SCAN_STOP, timeout=10.0)
+        if callback is not None:
+            self._adv_callbacks.remove(callback)
+        return sorted(seen.values(), key=lambda a: -a.rssi)
+
+    # ---- advertising ----------------------------------------------------------------
+
+    def advertise(self, name: str = "", *, manufacturer_data: bytes = b"",
+                  service_uuid16: int = 0) -> None:
+        payload = lp(name) + lp(manufacturer_data) + struct.pack(">H", service_uuid16)
+        self._b.request(C.BLE_ADV_START, payload, timeout=10.0)
+
+    def advertise_stop(self) -> None:
+        self._b.request(C.BLE_ADV_STOP, timeout=10.0)
+
+    # ---- GATT server -----------------------------------------------------------------
+
+    def serve(self, service, chars: list[tuple[object, int]]) -> list[Characteristic]:
+        """Define a GATT service. `chars` is [(uuid, props), ...] with props a
+        bitmask of Ble.READ / Ble.WRITE / Ble.NOTIFY / Ble.WRITE_NR.
+        Call advertise() afterwards to become discoverable."""
+        payload = to_uuid128(service) + bytes([len(chars)])
+        for u, props in chars:
+            payload += to_uuid128(u) + bytes([props])
+        ids = self._b.request(C.BLE_GATTS_DEF, payload, timeout=10.0)
+        out = []
+        for (u, _), cid in zip(chars, ids):
+            ch = Characteristic(self, cid, to_uuid128(u))
+            self._chars[cid] = ch
+            out.append(ch)
+        return out
+
+    def wait_connect(self, timeout: float | None = None) -> bool:
+        return self._server_connected.wait(timeout)
+
+    # ---- GATT client ------------------------------------------------------------------
+
+    def connect(self, addr: str, addr_type: int = 0, timeout: float = 15.0) -> GattClient:
+        """Connect to a peripheral by address ("aa:bb:cc:dd:ee:ff")."""
+        mac = bytes(int(x, 16) for x in addr.split(":"))
+        if len(mac) != 6:
+            raise ValueError("address must be 6 bytes, e.g. 'aa:bb:cc:dd:ee:ff'")
+        self._b.request(C.BLE_GATTC_CONN, mac + bytes([addr_type]), timeout=timeout)
+        return GattClient(self)