supercamera 0.1.0__tar.gz

supercamera-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

supercamera-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# macOS
+.DS_Store
+*.jpg

supercamera-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: supercamera
+Version: 0.1.0
+Summary: Python driver for USB endoscopes using the supercamera/useeplus protocol (Oasis, Depstech, etc.)
+Project-URL: Homepage, https://github.com/Revise-Robotics/supercamera-endoscope
+Project-URL: Issues, https://github.com/Revise-Robotics/supercamera-endoscope/issues
+Author: g
+License-Expression: MIT
+Keywords: borescope,camera,endoscope,oasis,opencv,supercamera,usb,useeplus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Requires-Dist: pyusb>=1.2.0
+Provides-Extra: all
+Requires-Dist: numpy; extra == 'all'
+Requires-Dist: opencv-python; extra == 'all'
+Requires-Dist: pillow; extra == 'all'
+Provides-Extra: opencv
+Requires-Dist: numpy; extra == 'opencv'
+Requires-Dist: opencv-python; extra == 'opencv'
+Provides-Extra: validate
+Requires-Dist: pillow; extra == 'validate'
+Description-Content-Type: text/markdown
+
+# supercamera
+
+Python driver for USB endoscopes that use the **supercamera / useeplus protocol** — the cheap endoscopes sold under brands like Oasis, Depstech, and others that only work with the "UseeePlus" mobile app.
+
+These devices don't implement standard UVC, so they won't show up as webcams. This package talks to them directly over USB and gives you JPEG frames or numpy arrays.
+
+## Supported devices
+
+| USB ID | Device name | Chip |
+|--------|-------------|------|
+| `2ce3:3828` | supercamera (Geek szitman) | Common |
+| `0329:2022` | supercamera (variant) | Common |
+
+Check yours with `lsusb` (Linux) or `system_profiler SPUSBDataType` (macOS).
+
+## Install
+
+```bash
+pip install supercamera
+```
+
+For OpenCV/numpy support (`.read()` returns numpy arrays):
+
+```bash
+pip install supercamera[opencv]
+```
+
+## Usage
+
+### Python API
+
+```python
+from supercamera import Camera
+
+# Like cv2.VideoCapture
+with Camera() as cam:
+    ret, frame = cam.read()  # numpy array (BGR), requires opencv
+    # or
+    jpeg_bytes = cam.read_jpeg()  # raw JPEG, no extra deps
+```
+
+### Multiple cameras
+
+```python
+from supercamera import Camera, list_devices
+
+list_devices()       # returns list of CameraInfo with bus/address
+Camera(index=0)      # first camera
+Camera(index=1)      # second camera
+```
+
+Note: these devices often share the same serial number, so use `index` or `bus`/`address` to distinguish them.
+
+### CLI
+
+```bash
+supercamera --list       # list connected cameras
+supercamera              # capture one frame
+supercamera -n 10        # capture 10 frames
+supercamera -i 1         # use second camera
+supercamera --show       # live view (requires opencv-python)
+```
+
+### Frame validation
+
+```python
+from supercamera import is_valid_jpeg
+is_valid_jpeg(jpeg_bytes)  # True/False (uses Pillow full decode if available)
+```
+
+### OpenCV pipeline example
+
+```python
+import cv2
+from supercamera import Camera
+
+cam = Camera()
+while True:
+    ret, frame = cam.read()
+    if not ret:
+        continue
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    cv2.imshow("endoscope", gray)
+    if cv2.waitKey(1) & 0xFF == ord("q"):
+        break
+cam.release()
+```
+
+## How it works
+
+These endoscopes use a proprietary USB protocol (`com.useeplus.protocol`) instead of UVC. The driver:
+
+1. Claims USB interfaces, sends magic init (`ff 55 ff 55 ee 10`) and connect command (`bb aa 05 00 00`)
+2. Reads bulk USB packets containing JPEG-encoded 640x480 frames
+3. Properly resets the device on disconnect so it's ready for the next session
+
+Resolution is **640x480** regardless of what the product listing claims.
+
+## Testing
+
+Plug in one or both cameras, then:
+
+```bash
+python test_camera.py
+```
+
+Runs: device listing, single capture, 3x reconnect (no replug), OpenCV read, and two-camera simultaneous capture (if two connected).
+
+## Platform notes
+
+- **macOS**: Works out of the box. No kernel extensions needed.
+- **Linux**: Works. You may need a udev rule for non-root access:
+  ```bash
+  echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2ce3", ATTR{idProduct}=="3828", MODE="0666"' | \
+    sudo tee /etc/udev/rules.d/99-supercamera.rules
+  sudo udevadm control --reload-rules
+  ```
+- **Windows**: Should work with [libusb](https://libusb.info/) + [Zadig](https://zadig.akeo.ie/) driver. Untested.
+
+## Credits
+
+Protocol reverse-engineered by:
+- [hbens/geek-szitman-supercamera](https://github.com/hbens/geek-szitman-supercamera) (C++ PoC, CC0)
+- [MAkcanca/useeplus-linux-driver](https://github.com/MAkcanca/useeplus-linux-driver) (Linux kernel driver)
+
+## License
+
+MIT

supercamera-0.1.0/README.md

@@ -0,0 +1,128 @@
+# supercamera
+
+Python driver for USB endoscopes that use the **supercamera / useeplus protocol** — the cheap endoscopes sold under brands like Oasis, Depstech, and others that only work with the "UseeePlus" mobile app.
+
+These devices don't implement standard UVC, so they won't show up as webcams. This package talks to them directly over USB and gives you JPEG frames or numpy arrays.
+
+## Supported devices
+
+| USB ID | Device name | Chip |
+|--------|-------------|------|
+| `2ce3:3828` | supercamera (Geek szitman) | Common |
+| `0329:2022` | supercamera (variant) | Common |
+
+Check yours with `lsusb` (Linux) or `system_profiler SPUSBDataType` (macOS).
+
+## Install
+
+```bash
+pip install supercamera
+```
+
+For OpenCV/numpy support (`.read()` returns numpy arrays):
+
+```bash
+pip install supercamera[opencv]
+```
+
+## Usage
+
+### Python API
+
+```python
+from supercamera import Camera
+
+# Like cv2.VideoCapture
+with Camera() as cam:
+    ret, frame = cam.read()  # numpy array (BGR), requires opencv
+    # or
+    jpeg_bytes = cam.read_jpeg()  # raw JPEG, no extra deps
+```
+
+### Multiple cameras
+
+```python
+from supercamera import Camera, list_devices
+
+list_devices()       # returns list of CameraInfo with bus/address
+Camera(index=0)      # first camera
+Camera(index=1)      # second camera
+```
+
+Note: these devices often share the same serial number, so use `index` or `bus`/`address` to distinguish them.
+
+### CLI
+
+```bash
+supercamera --list       # list connected cameras
+supercamera              # capture one frame
+supercamera -n 10        # capture 10 frames
+supercamera -i 1         # use second camera
+supercamera --show       # live view (requires opencv-python)
+```
+
+### Frame validation
+
+```python
+from supercamera import is_valid_jpeg
+is_valid_jpeg(jpeg_bytes)  # True/False (uses Pillow full decode if available)
+```
+
+### OpenCV pipeline example
+
+```python
+import cv2
+from supercamera import Camera
+
+cam = Camera()
+while True:
+    ret, frame = cam.read()
+    if not ret:
+        continue
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    cv2.imshow("endoscope", gray)
+    if cv2.waitKey(1) & 0xFF == ord("q"):
+        break
+cam.release()
+```
+
+## How it works
+
+These endoscopes use a proprietary USB protocol (`com.useeplus.protocol`) instead of UVC. The driver:
+
+1. Claims USB interfaces, sends magic init (`ff 55 ff 55 ee 10`) and connect command (`bb aa 05 00 00`)
+2. Reads bulk USB packets containing JPEG-encoded 640x480 frames
+3. Properly resets the device on disconnect so it's ready for the next session
+
+Resolution is **640x480** regardless of what the product listing claims.
+
+## Testing
+
+Plug in one or both cameras, then:
+
+```bash
+python test_camera.py
+```
+
+Runs: device listing, single capture, 3x reconnect (no replug), OpenCV read, and two-camera simultaneous capture (if two connected).
+
+## Platform notes
+
+- **macOS**: Works out of the box. No kernel extensions needed.
+- **Linux**: Works. You may need a udev rule for non-root access:
+  ```bash
+  echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2ce3", ATTR{idProduct}=="3828", MODE="0666"' | \
+    sudo tee /etc/udev/rules.d/99-supercamera.rules
+  sudo udevadm control --reload-rules
+  ```
+- **Windows**: Should work with [libusb](https://libusb.info/) + [Zadig](https://zadig.akeo.ie/) driver. Untested.
+
+## Credits
+
+Protocol reverse-engineered by:
+- [hbens/geek-szitman-supercamera](https://github.com/hbens/geek-szitman-supercamera) (C++ PoC, CC0)
+- [MAkcanca/useeplus-linux-driver](https://github.com/MAkcanca/useeplus-linux-driver) (Linux kernel driver)
+
+## License
+
+MIT

supercamera-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "supercamera"
+version = "0.1.0"
+description = "Python driver for USB endoscopes using the supercamera/useeplus protocol (Oasis, Depstech, etc.)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "g" },
+]
+keywords = ["usb", "endoscope", "camera", "supercamera", "useeplus", "oasis", "borescope", "opencv"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Capture",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pyusb>=1.2.0",
+]
+
+[project.optional-dependencies]
+opencv = ["opencv-python", "numpy"]
+validate = ["pillow"]
+all = ["opencv-python", "numpy", "pillow"]
+
+[project.scripts]
+supercamera = "supercamera.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Revise-Robotics/supercamera-endoscope"
+Issues = "https://github.com/Revise-Robotics/supercamera-endoscope/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

supercamera-0.1.0/supercamera/__init__.py

@@ -0,0 +1,6 @@
+"""Python driver for USB endoscopes using the supercamera/useeplus protocol."""
+
+from supercamera.camera import Camera, CameraInfo, list_devices
+from supercamera.validate import is_valid_jpeg
+
+__all__ = ["Camera", "CameraInfo", "list_devices", "is_valid_jpeg"]

supercamera-0.1.0/supercamera/camera.py

@@ -0,0 +1,344 @@
+"""USB communication with supercamera devices (Oasis, Depstech, etc.)."""
+
+import usb.core
+import usb.util
+import time
+
+# Known vendor/product ID pairs for supercamera devices
+KNOWN_DEVICES = [
+    (0x2CE3, 0x3828),
+    (0x0329, 0x2022),
+]
+
+# Interface 1 (com.useeplus.protocol) endpoints
+EP_OUT = 0x01
+EP_IN = 0x81
+
+# Interface 0 (iAP) endpoints
+EP_IAP_OUT = 0x02
+EP_IAP_IN = 0x82
+
+# Protocol commands (reverse-engineered from C++ PoC and Linux driver)
+MAGIC_INIT = bytes([0xFF, 0x55, 0xFF, 0x55, 0xEE, 0x10])
+CONNECT_CMD = bytes([0xBB, 0xAA, 0x05, 0x00, 0x00])
+
+HEADER_SIZE = 12
+JPEG_SOI = bytes([0xFF, 0xD8])
+JPEG_EOI = bytes([0xFF, 0xD9])
+
+
+class CameraInfo:
+    """Info about a detected supercamera device."""
+
+    def __init__(self, usb_dev):
+        self._dev = usb_dev
+
+    @property
+    def vendor_id(self):
+        return self._dev.idVendor
+
+    @property
+    def product_id(self):
+        return self._dev.idProduct
+
+    @property
+    def serial_number(self):
+        try:
+            return self._dev.serial_number
+        except Exception:
+            return None
+
+    @property
+    def manufacturer(self):
+        try:
+            return self._dev.manufacturer
+        except Exception:
+            return None
+
+    @property
+    def product(self):
+        try:
+            return self._dev.product
+        except Exception:
+            return None
+
+    @property
+    def bus(self):
+        return self._dev.bus
+
+    @property
+    def address(self):
+        return self._dev.address
+
+    def __repr__(self):
+        return (
+            f"CameraInfo({self.vendor_id:04x}:{self.product_id:04x} "
+            f"serial={self.serial_number!r} bus={self.bus} addr={self.address})"
+        )
+
+
+def list_devices():
+    """Find all connected supercamera devices.
+
+    Returns:
+        list[CameraInfo]: Info about each detected device.
+    """
+    found = []
+    for vid, pid in KNOWN_DEVICES:
+        devs = usb.core.find(find_all=True, idVendor=vid, idProduct=pid)
+        for d in devs:
+            found.append(CameraInfo(d))
+    return found
+
+
+class Camera:
+    """USB endoscope camera using the useeplus/supercamera protocol.
+
+    Works as a drop-in for cv2.VideoCapture:
+
+        from supercamera import Camera
+        cam = Camera()
+        ret, frame = cam.read()  # returns numpy array (requires opencv-python)
+        cam.release()
+
+    Or use as a context manager:
+
+        with Camera() as cam:
+            ret, frame = cam.read()
+
+    For raw JPEG bytes without OpenCV dependency:
+
+        cam = Camera()
+        jpeg_bytes = cam.read_jpeg()
+        cam.release()
+
+    With multiple cameras, select by serial number or index:
+
+        cameras = supercamera.list_devices()
+        cam = Camera(serial="022018050100030")
+        cam = Camera(index=1)  # second camera
+    """
+
+    def __init__(self, serial=None, index=0, timeout=5.0):
+        """Open a supercamera device.
+
+        Args:
+            serial: Serial number string to match a specific camera.
+            index: Which camera to open if multiple are found (0-based).
+                   Ignored if serial is provided.
+            timeout: Seconds to wait for a frame before giving up.
+        """
+        self._dev = None
+        self._streaming = False
+        self._frames_read = 0
+        self._serial = serial
+        self._index = index
+        self._timeout = timeout
+        self._open()
+
+    def _find_device(self):
+        all_devs = []
+        for vid, pid in KNOWN_DEVICES:
+            devs = list(usb.core.find(find_all=True, idVendor=vid, idProduct=pid))
+            all_devs.extend(devs)
+
+        if not all_devs:
+            raise RuntimeError(
+                "No supercamera devices found. Is it plugged in?\n"
+                "Known USB IDs: " + ", ".join(f"{v:04x}:{p:04x}" for v, p in KNOWN_DEVICES)
+            )
+
+        if self._serial is not None:
+            for dev in all_devs:
+                try:
+                    if dev.serial_number == self._serial:
+                        return dev
+                except Exception:
+                    continue
+            serials = []
+            for dev in all_devs:
+                try:
+                    serials.append(dev.serial_number)
+                except Exception:
+                    serials.append("???")
+            raise RuntimeError(
+                f"No camera with serial {self._serial!r} found. "
+                f"Available: {serials}"
+            )
+
+        if self._index >= len(all_devs):
+            raise RuntimeError(
+                f"Camera index {self._index} out of range. "
+                f"Found {len(all_devs)} device(s)."
+            )
+
+        return all_devs[self._index]
+
+    def _open(self):
+        dev = self._find_device()
+        self._dev = dev
+
+        # Detach kernel drivers
+        for intf in [0, 1]:
+            try:
+                if dev.is_kernel_driver_active(intf):
+                    dev.detach_kernel_driver(intf)
+            except Exception:
+                pass
+
+        dev.set_configuration()
+        usb.util.claim_interface(dev, 0)
+        usb.util.claim_interface(dev, 1)
+
+        # Drain pending heartbeat data from iAP interface
+        for _ in range(30):
+            try:
+                dev.read(EP_IAP_IN, 512, timeout=100)
+            except usb.core.USBError:
+                break
+
+        # Activate bulk endpoints on interface 1
+        dev.set_interface_altsetting(interface=1, alternate_setting=1)
+        dev.clear_halt(EP_OUT)
+
+        # Send init sequence
+        dev.write(EP_IAP_OUT, MAGIC_INIT, timeout=1000)
+        dev.write(EP_OUT, CONNECT_CMD, timeout=1000)
+        time.sleep(0.3)
+
+        self._streaming = True
+        self._frames_read = 0
+
+        # Skip first frame (always partial/corrupt after connect)
+        self._read_jpeg_internal()
+
+    def _read_jpeg_internal(self):
+        """Read one complete JPEG frame from USB. Returns bytes or None."""
+        buf = bytearray()
+        in_frame = False
+        deadline = time.monotonic() + self._timeout
+
+        while time.monotonic() < deadline:
+            try:
+                data = bytes(self._dev.read(EP_IN, 65536, timeout=1000))
+            except usb.core.USBError:
+                continue
+
+            # Strip 12-byte protocol header
+            payload = data
+            if len(data) >= HEADER_SIZE and data[0] == 0xAA and data[1] == 0xBB:
+                payload = data[HEADER_SIZE:]
+
+            soi_pos = payload.find(JPEG_SOI)
+            if soi_pos >= 0 and not in_frame:
+                in_frame = True
+                buf = bytearray(payload[soi_pos:])
+            elif in_frame:
+                buf.extend(payload)
+
+            if in_frame:
+                eoi_pos = buf.find(JPEG_EOI)
+                if eoi_pos >= 0:
+                    self._frames_read += 1
+                    return bytes(buf[:eoi_pos + 2])
+
+        return None
+
+    def read_jpeg(self):
+        """Read one JPEG frame as raw bytes.
+
+        Returns:
+            bytes or None: JPEG data, or None if read failed.
+        """
+        if not self._streaming:
+            raise RuntimeError("Camera is not streaming. Call open() or use Camera().")
+        return self._read_jpeg_internal()
+
+    def read(self):
+        """Read one frame as a numpy array (BGR, like OpenCV).
+
+        Returns:
+            tuple: (success: bool, frame: numpy.ndarray or None)
+        """
+        try:
+            import cv2
+            import numpy as np
+        except ImportError:
+            raise ImportError(
+                "opencv-python and numpy are required for read(). "
+                "Install them with: pip install opencv-python numpy\n"
+                "Or use read_jpeg() for raw JPEG bytes without extra dependencies."
+            )
+
+        jpeg = self.read_jpeg()
+        if jpeg is None:
+            return False, None
+
+        arr = np.frombuffer(jpeg, dtype=np.uint8)
+        frame = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+        if frame is None:
+            return False, None
+        return True, frame
+
+    def release(self):
+        """Stop streaming and release the USB device."""
+        if self._dev is None:
+            return
+
+        if self._streaming:
+            try:
+                self._dev.set_interface_altsetting(interface=1, alternate_setting=0)
+            except Exception:
+                pass
+            self._streaming = False
+
+        for intf in [1, 0]:
+            try:
+                usb.util.release_interface(self._dev, intf)
+            except Exception:
+                pass
+
+        try:
+            self._dev.reset()
+        except Exception:
+            pass
+
+        self._dev = None
+
+    @property
+    def serial_number(self):
+        if self._dev is None:
+            return None
+        try:
+            return self._dev.serial_number
+        except Exception:
+            return None
+
+    @property
+    def bus(self):
+        return self._dev.bus if self._dev else None
+
+    @property
+    def address(self):
+        return self._dev.address if self._dev else None
+
+    @property
+    def is_opened(self):
+        return self._streaming and self._dev is not None
+
+    @property
+    def resolution(self):
+        return (640, 480)
+
+    @property
+    def frames_read(self):
+        return self._frames_read
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.release()
+
+    def __del__(self):
+        self.release()

supercamera-0.1.0/supercamera/cli.py

@@ -0,0 +1,120 @@
+"""CLI tool to capture frames from a supercamera USB endoscope."""
+
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Capture JPEG frames from a USB endoscope (supercamera/useeplus protocol)"
+    )
+    parser.add_argument(
+        "-n", "--num-frames", type=int, default=1,
+        help="Number of frames to capture (default: 1)"
+    )
+    parser.add_argument(
+        "-o", "--output", default="frame",
+        help="Output filename prefix (default: 'frame')"
+    )
+    parser.add_argument(
+        "-s", "--serial", default=None,
+        help="Serial number of the camera to use"
+    )
+    parser.add_argument(
+        "-i", "--index", type=int, default=0,
+        help="Camera index if multiple are connected (default: 0)"
+    )
+    parser.add_argument(
+        "-l", "--list", action="store_true",
+        help="List connected cameras and exit"
+    )
+    parser.add_argument(
+        "--show", action="store_true",
+        help="Display frames using OpenCV (requires opencv-python)"
+    )
+    args = parser.parse_args()
+
+    if args.list:
+        _list_cameras()
+        return
+
+    from supercamera import Camera
+
+    try:
+        cam = Camera(serial=args.serial, index=args.index)
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Connected: {cam.resolution[0]}x{cam.resolution[1]} (serial: {cam.serial_number})")
+
+    if args.show:
+        _live_view(cam)
+    else:
+        _capture(cam, args.num_frames, args.output)
+
+
+def _list_cameras():
+    from supercamera import list_devices
+
+    cameras = list_devices()
+    if not cameras:
+        print("No supercamera devices found.")
+        sys.exit(1)
+
+    print(f"Found {len(cameras)} device(s):\n")
+    for i, cam in enumerate(cameras):
+        print(f"  [{i}] {cam.vendor_id:04x}:{cam.product_id:04x}"
+              f"  serial={cam.serial_number}"
+              f"  ({cam.manufacturer} {cam.product})"
+              f"  bus={cam.bus} addr={cam.address}")
+
+
+def _capture(cam, num_frames, prefix):
+    try:
+        for i in range(1, num_frames + 1):
+            jpeg = cam.read_jpeg()
+            if jpeg is None:
+                print(f"Failed to read frame {i}", file=sys.stderr)
+                continue
+            if num_frames == 1:
+                fname = f"{prefix}.jpg"
+            else:
+                fname = f"{prefix}_{i:03d}.jpg"
+            with open(fname, "wb") as f:
+                f.write(jpeg)
+            print(f"Saved {fname} ({len(jpeg)} bytes)")
+    finally:
+        cam.release()
+
+
+def _live_view(cam):
+    try:
+        import cv2
+    except ImportError:
+        print("Live view requires opencv-python: pip install opencv-python", file=sys.stderr)
+        sys.exit(1)
+
+    print("Live view — press 'q' to quit, 's' to save a frame")
+    saved = 0
+    try:
+        while True:
+            ret, frame = cam.read()
+            if not ret:
+                continue
+            cv2.imshow("supercamera", frame)
+            key = cv2.waitKey(1) & 0xFF
+            if key == ord("q"):
+                break
+            elif key == ord("s"):
+                saved += 1
+                fname = f"capture_{saved:03d}.jpg"
+                cv2.imwrite(fname, frame)
+                print(f"Saved {fname}")
+    finally:
+        cam.release()
+        cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    main()

supercamera-0.1.0/supercamera/validate.py

@@ -0,0 +1,32 @@
+"""JPEG frame validation."""
+
+
+def is_valid_jpeg(data):
+    """Check if JPEG data is structurally valid.
+
+    Checks SOI/EOI markers and attempts a full decode if Pillow is available.
+
+    Returns:
+        bool: True if the JPEG is valid.
+    """
+    if not data or len(data) < 4:
+        return False
+
+    # Must start with SOI and end with EOI
+    if data[0] != 0xFF or data[1] != 0xD8:
+        return False
+    if data[-2] != 0xFF or data[-1] != 0xD9:
+        return False
+
+    # Try full decode (catches truncation, corrupted huffman tables, etc.)
+    try:
+        from PIL import Image
+        import io
+        img = Image.open(io.BytesIO(data))
+        img.load()
+    except ImportError:
+        pass  # No Pillow, markers-only check is the best we can do
+    except Exception:
+        return False
+
+    return True

supercamera-0.1.0/test_camera.py

@@ -0,0 +1,162 @@
+"""Interactive test script for supercamera devices."""
+
+import time
+import sys
+
+
+def test_list():
+    """Test device listing."""
+    from supercamera import list_devices
+
+    print("=" * 60)
+    print("TEST: list_devices()")
+    print("=" * 60)
+
+    cameras = list_devices()
+    print(f"Found {len(cameras)} device(s)")
+    for i, info in enumerate(cameras):
+        print(f"  [{i}] {info}")
+
+    if not cameras:
+        print("\n  No cameras found! Plug one in and try again.")
+        return 0
+
+    print("  PASS")
+    return len(cameras)
+
+
+def test_single_capture(serial=None, index=0, label=""):
+    """Test opening, capturing, and releasing one camera."""
+    from supercamera import Camera
+    from supercamera.validate import is_valid_jpeg
+
+    tag = f" ({label})" if label else ""
+    print(f"\nTEST: single capture{tag}")
+    print("-" * 40)
+
+    cam = Camera(serial=serial, index=index)
+    print(f"  Opened: serial={cam.serial_number}")
+
+    jpeg = cam.read_jpeg()
+    assert jpeg is not None, "read_jpeg() returned None"
+    print(f"  read_jpeg(): {len(jpeg)} bytes")
+
+    valid = is_valid_jpeg(jpeg)
+    print(f"  Valid JPEG: {valid}")
+    assert valid, "Frame failed validation"
+
+    cam.release()
+    print(f"  Released")
+    print("  PASS")
+    return jpeg
+
+
+def test_repeated_connect(serial=None, index=0, rounds=3):
+    """Test connecting and disconnecting multiple times without replug."""
+    from supercamera import Camera
+    from supercamera.validate import is_valid_jpeg
+
+    print(f"\nTEST: {rounds}x connect/capture/release (no replug)")
+    print("-" * 40)
+
+    for i in range(1, rounds + 1):
+        cam = Camera(serial=serial, index=index)
+        jpeg = cam.read_jpeg()
+        valid = jpeg is not None and is_valid_jpeg(jpeg)
+        print(f"  Round {i}: {len(jpeg) if jpeg else 0} bytes, valid={valid}, serial={cam.serial_number}")
+        cam.release()
+        assert valid, f"Round {i} failed"
+        if i < rounds:
+            time.sleep(1)
+
+    print("  PASS")
+
+
+def test_opencv_read(serial=None, index=0):
+    """Test the OpenCV .read() path."""
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        print("\nTEST: opencv read — SKIPPED (opencv not installed)")
+        return
+
+    from supercamera import Camera
+
+    print(f"\nTEST: opencv .read()")
+    print("-" * 40)
+
+    with Camera(serial=serial, index=index) as cam:
+        ret, frame = cam.read()
+        print(f"  ret={ret}, shape={frame.shape if ret else None}, dtype={frame.dtype if ret else None}")
+        assert ret, "read() returned False"
+        assert frame.shape == (480, 640, 3), f"Unexpected shape: {frame.shape}"
+        assert frame.dtype == np.uint8
+        cv2.imwrite("test_opencv.jpg", frame)
+        print("  Saved test_opencv.jpg")
+
+    print("  PASS")
+
+
+def test_two_cameras():
+    """Test opening two cameras simultaneously."""
+    from supercamera import Camera, list_devices
+    from supercamera.validate import is_valid_jpeg
+
+    cameras = list_devices()
+    if len(cameras) < 2:
+        print(f"\nTEST: two cameras — SKIPPED (only {len(cameras)} device(s) found)")
+        return
+
+    print(f"\nTEST: two cameras simultaneously")
+    print("-" * 40)
+
+    cam0 = Camera(index=0)
+    print(f"  Camera 0 opened: serial={cam0.serial_number}")
+
+    cam1 = Camera(index=1)
+    print(f"  Camera 1 opened: serial={cam1.serial_number}")
+
+    jpeg0 = cam0.read_jpeg()
+    jpeg1 = cam1.read_jpeg()
+
+    valid0 = jpeg0 is not None and is_valid_jpeg(jpeg0)
+    valid1 = jpeg1 is not None and is_valid_jpeg(jpeg1)
+
+    print(f"  Camera 0: {len(jpeg0) if jpeg0 else 0} bytes, valid={valid0}")
+    print(f"  Camera 1: {len(jpeg1) if jpeg1 else 0} bytes, valid={valid1}")
+
+    cam0.release()
+    cam1.release()
+
+    assert valid0, "Camera 0 frame invalid"
+    assert valid1, "Camera 1 frame invalid"
+    print("  PASS")
+
+
+def main():
+    print("supercamera test suite")
+    print("Plug in your camera(s) before running.\n")
+
+    num_cams = test_list()
+    if num_cams == 0:
+        sys.exit(1)
+
+    test_single_capture()
+    time.sleep(1)
+
+    test_repeated_connect(rounds=3)
+    time.sleep(1)
+
+    test_opencv_read()
+    time.sleep(1)
+
+    test_two_cameras()
+
+    print("\n" + "=" * 60)
+    print("ALL TESTS PASSED")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()