supercamera 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+supercamera/__init__.py,sha256=L6mHirGmONzMDZ2tQriqmYCCcteuBIeqY61ckwxbnu4,261
+supercamera/camera.py,sha256=M2KEv5mIBAZEtA4rDOXfO9S8EqSFF45sNt6JHoABSvE,9389
+supercamera/cli.py,sha256=JAAEsjFCYofhgVu2lYLTHXEd0rwv9HPvDjGJO7khE1M,3395
+supercamera/validate.py,sha256=aGKlnKKUP7_GOjYufLs54c6kXcakv2ZL1xvn_oKfgqs,823
+supercamera-0.1.0.dist-info/METADATA,sha256=KDbZlnTWbPdlGzphN_9Jbp8a2JZw1926i3WetVx80Ko,4810
+supercamera-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+supercamera-0.1.0.dist-info/entry_points.txt,sha256=sQR_ix78oyldDgDVR1rXfcrAotyvAkZNja7j9mhd8Mk,53
+supercamera-0.1.0.dist-info/RECORD,,

supercamera-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

supercamera-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+supercamera = supercamera.cli:main