topdata-sdk 0.1.0__py3-none-any.whl

topdata/__init__.py

@@ -0,0 +1,60 @@
+from . import constants
+from .server import TopdataServer
+from .session import TopdataDeviceSession
+from .exceptions import (
+    CommandTimeoutError,
+    DeviceDisconnectedError,
+    InvalidImageError,
+    ProtocolError,
+    TopdataError,
+)
+from .models import (
+    DeviceInfo,
+    LogEvent,
+    LogRecord,
+    RegMessage,
+    RegResponse,
+    SendlogResponse,
+    UserInfo,
+    UserListItem,
+)
+from .image import prepare_image_record, validate_and_normalize
+from .wiegand import (
+    format_wiegand10,
+    parse_wiegand10,
+    wiegand10_to_wiegand26,
+    wiegand26_to_wiegand10,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core classes
+    "TopdataServer",
+    "TopdataDeviceSession",
+    # Constants module
+    "constants",
+    # Exceptions
+    "TopdataError",
+    "CommandTimeoutError",
+    "DeviceDisconnectedError",
+    "InvalidImageError",
+    "ProtocolError",
+    # Models
+    "DeviceInfo",
+    "LogEvent",
+    "LogRecord",
+    "RegMessage",
+    "RegResponse",
+    "SendlogResponse",
+    "UserInfo",
+    "UserListItem",
+    # Image utilities
+    "prepare_image_record",
+    "validate_and_normalize",
+    # Wiegand utilities
+    "format_wiegand10",
+    "parse_wiegand10",
+    "wiegand10_to_wiegand26",
+    "wiegand26_to_wiegand10",
+]

topdata/constants.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+"""
+Constants for the Topdata Facial Reader SDK.
+"""
+from enum import IntEnum
+
+
+# ─── Backup Number (data type selector for setuserinfo/getuserinfo/deleteuser) ─
+class BackupNum(IntEnum):
+    """Backup number values used in setuserinfo, getuserinfo, and deleteuser commands."""
+    ALL = 0                 # All data (no photo in setuserinfo; all data in getuserinfo/deleteuser)
+    PASSWORD = 10           # Password only
+    CARD = 11               # Card only
+    ALL_EXCEPT_BIOMETRY = 13  # All data except biometry (photo)
+    FACE = 50               # Face photo only
+
+
+# ─── Admin Level ───────────────────────────────────────────────────────────────
+class AdminLevel(IntEnum):
+    """User privilege levels on the device."""
+    USER = 0                # Standard user (facial recognition only)
+    ADMIN = 1               # Administrator (device menu access)
+    SUPER_USER = 2          # Super user (not recommended by manufacturer)
+
+
+# ─── Authentication Mode (mode field in sendlog) ──────────────────────────────
+class AuthMode(IntEnum):
+    """Authentication method used in access events (sendlog.record.mode)."""
+    PASSWORD = 2
+    CARD = 3
+    FACE = 8
+
+
+# ─── Verify Mode (verifymode in setdevinfo / setuserlock) ─────────────────────
+class VerifyMode(IntEnum):
+    """Verification mode for device/user access configuration."""
+    FACE_CARD_OR_PWD = 0    # Face, Card, or Password
+    PWD_ONLY = 2            # Password only
+    CARD_ONLY = 3           # Card only
+    FACE_ONLY = 8           # Face only
+    FACE_AND_PWD = 9        # Face and Password
+    CARD_AND_FACE = 10      # Card and Face
+    CARD_AND_PWD = 11       # Card and Password
+    FACE_AND_CARD_OR_PWD = 14  # Face and (Card or Password)
+
+
+# ─── Server Verify Mode (server_verify in setdevinfo) ─────────────────────────
+class ServerVerify(IntEnum):
+    """Server verification mode for online/offline operation."""
+    OFFLINE = 0             # Offline only (device decides access)
+    ONLINE = 1              # Online only (server decides access)
+    AUTO = 2                # Auto switch between online and offline
+
+
+# ─── Image Validation Limits ──────────────────────────────────────────────────
+MAX_IMAGE_BYTES = 150 * 1024           # 150 KB
+MIN_RESOLUTION = (240, 320)            # width, height
+MAX_RESOLUTION = (800, 1280)           # width, height
+RECOMMENDED_RESOLUTION = (480, 640)    # width, height
+
+# ─── Protocol Defaults ────────────────────────────────────────────────────────
+DEFAULT_WS_PORT = 7792
+DEFAULT_WS_PATH = "/pub/chat"
+DEFAULT_COMMAND_TIMEOUT = 10.0         # seconds
+
+# ─── Special Values ───────────────────────────────────────────────────────────
+UNKNOWN_ENROLLID = 99999999            # enrollid used by firmware for unrecognized faces
+MAX_ENROLLID = 999_999_999_999         # 12-digit maximum enrollid
+
+# ─── Card Format (setdevlock.cardformat) ──────────────────────────────────────
+class CardFormat(IntEnum):
+    """Card number display format on the device."""
+    DECIMAL = 0
+    WIEGAND = 1
+    HEXADECIMAL = 2

topdata/exceptions.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+
+class TopdataError(Exception):
+    """Base exception for the Topdata SDK."""
+    pass
+
+
+class CommandTimeoutError(TopdataError):
+    """Raised when a command sent to the device does not receive a response within the timeout."""
+    def __init__(self, command: str, timeout: float):
+        self.command = command
+        self.timeout = timeout
+        super().__init__(f"Command '{command}' timed out after {timeout}s")
+
+
+class DeviceDisconnectedError(TopdataError):
+    """Raised when the WebSocket connection to the device is lost during an operation."""
+    def __init__(self, sn: str | None = None, message: str | None = None):
+        self.sn = sn
+        msg = message or f"Device '{sn}' disconnected"
+        super().__init__(msg)
+
+
+class InvalidImageError(TopdataError):
+    """Raised when an image fails validation before being sent to the device.
+
+    Possible reasons: not JPEG, file too large (>150KB after processing),
+    resolution outside 240x320 – 800x1280, or other quality issues.
+    """
+    pass
+
+
+class ProtocolError(TopdataError):
+    """Raised when the device returns result:false in a command response.
+
+    Attributes:
+        command: The command name (ret field value).
+        reason: The numeric reason code, if present.
+        msg: The human-readable error message from the device, if present.
+    """
+    def __init__(self, command: str, reason: int | None = None, msg: str | None = None):
+        self.command = command
+        self.reason = reason
+        self.msg = msg
+        parts = [f"Command '{command}' failed"]
+        if reason is not None:
+            parts.append(f"reason={reason}")
+        if msg:
+            parts.append(f"msg='{msg}'")
+        super().__init__(", ".join(parts))

topdata/image.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+"""
+Image validation and normalization for Topdata facial readers.
+
+Requirements per the Topdata manual:
+  - Format: JPEG only
+  - File size: < 150 KB
+  - Resolution: between 240x320 and 800x1280 px
+  - Recommended: 480x640 px
+  - Single person, vertical face, no mask/hat/sunglasses, good lighting
+"""
+
+import base64
+import io
+
+from PIL import Image
+
+from .constants import MAX_IMAGE_BYTES, MAX_RESOLUTION, MIN_RESOLUTION, RECOMMENDED_RESOLUTION
+from .exceptions import InvalidImageError
+
+
+def validate_and_normalize(image_data: bytes) -> bytes:
+    """Validate and normalize an image for the Topdata facial reader.
+
+    Checks:
+      1. Must be JPEG format.
+      2. Resolution must be within MIN_RESOLUTION..MAX_RESOLUTION.
+      3. File size must be < MAX_IMAGE_BYTES (150KB).
+
+    If the image is too large (file size) or resolution exceeds MAX_RESOLUTION,
+    it will be downscaled to RECOMMENDED_RESOLUTION and re-compressed.
+
+    Args:
+        image_data: Raw image bytes.
+
+    Returns:
+        Validated (and possibly normalized) JPEG bytes.
+
+    Raises:
+        InvalidImageError: If the image cannot be processed or doesn't meet requirements.
+    """
+    if not image_data:
+        raise InvalidImageError("Image data is empty")
+
+    try:
+        img = Image.open(io.BytesIO(image_data))
+    except Exception as e:
+        raise InvalidImageError(f"Cannot open image: {e}")
+
+    # Check JPEG format
+    if img.format and img.format.upper() not in ("JPEG", "JPG"):
+        raise InvalidImageError(
+            f"Image must be JPEG format, got '{img.format}'"
+        )
+
+    # Even if format is None (raw bytes), check if it's a valid JPEG by magic bytes
+    if not image_data[:2] == b'\xff\xd8':
+        raise InvalidImageError("Image data does not start with JPEG magic bytes (FFD8)")
+
+    width, height = img.size
+
+    # Check minimum resolution
+    if width < MIN_RESOLUTION[0] or height < MIN_RESOLUTION[1]:
+        raise InvalidImageError(
+            f"Image resolution {width}x{height} is below minimum "
+            f"{MIN_RESOLUTION[0]}x{MIN_RESOLUTION[1]}"
+        )
+
+    needs_resize = False
+
+    # Check if resolution exceeds maximum
+    if width > MAX_RESOLUTION[0] or height > MAX_RESOLUTION[1]:
+        needs_resize = True
+
+    # Check file size
+    if len(image_data) > MAX_IMAGE_BYTES:
+        needs_resize = True
+
+    if needs_resize:
+        # Downscale to recommended resolution, maintaining aspect ratio
+        target_w, target_h = RECOMMENDED_RESOLUTION
+        img.thumbnail((target_w, target_h), Image.LANCZOS)
+
+        # Re-encode as JPEG with quality tuning to fit under size limit
+        for quality in (85, 75, 65, 55, 45):
+            buffer = io.BytesIO()
+            # Convert to RGB if necessary (e.g., RGBA, P mode)
+            if img.mode not in ("RGB", "L"):
+                img = img.convert("RGB")
+            img.save(buffer, format="JPEG", quality=quality, optimize=True)
+            result = buffer.getvalue()
+            if len(result) <= MAX_IMAGE_BYTES:
+                return result
+
+        raise InvalidImageError(
+            f"Cannot compress image below {MAX_IMAGE_BYTES} bytes "
+            f"even at minimum quality"
+        )
+
+    return image_data
+
+
+def prepare_image_record(image_data: bytes) -> str:
+    """Validate image and return the base64 string for the setuserinfo 'record' field.
+
+    The Topdata protocol expects the record field to contain a data URI:
+    ``data:image/jpeg;base64,<base64_data>``
+
+    Args:
+        image_data: Raw image bytes.
+
+    Returns:
+        Data URI string ready for the protocol's record field.
+
+    Raises:
+        InvalidImageError: If the image fails validation.
+    """
+    validated = validate_and_normalize(image_data)
+    b64 = base64.b64encode(validated).decode("ascii")
+    return f"data:image/jpeg;base64,{b64}"

topdata/models.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class DeviceInfo(BaseModel):
+    """Device information from the 'reg' handshake (devinfo object).
+
+    All capacity/usage fields reflect the device's current state.
+    Fields not applicable to facial readers (fpsize, usedfp, fpalgo,
+    intercom, floors, useosdp) are kept for protocol completeness.
+    """
+    modelname: str
+    usersize: int = 0
+    facesize: int = 0
+    fpsize: int = 0
+    cardsize: int = 0
+    pwdsize: int = 0
+    logsize: int = 0
+    useduser: int = 0
+    usedface: int = 0
+    usedfp: int = 0
+    usedcard: int = 0
+    usedpwd: int = 0
+    usedlog: int = 0
+    usednewlog: int = 0
+    usedrtlog: int = 0
+    netinuse: int = 0
+    usb4g: int = 0
+    fpalgo: Optional[str] = None
+    firmware: str = ""
+    time: Optional[str] = None
+    intercom: int = 0
+    floors: int = 0
+    charid: int = 0
+    useosdp: int = 0
+    dislanguage: int = 0
+    mac: Optional[str] = None
+
+
+class UserListItem(BaseModel):
+    """A single record from the getuserlist response.
+
+    Each item represents one data type for a user (e.g., enrollid with
+    backupnum=10 means that user has a password, backupnum=50 means face, etc.).
+    """
+    enrollid: int
+    admin: str | int = "0"
+    backupnum: int = 0
+
+
+class UserInfo(BaseModel):
+    """Detailed user information from getuserinfo response."""
+    enrollid: int
+    name: Optional[str] = None
+    admin: int = 0
+    card: Optional[int] = None
+    pwd: Optional[int] = None
+    faceflag: Optional[int] = None         # 1 = has face data, 0 = no
+    enable: Optional[int] = None           # 1 = enabled, 0 = disabled
+    backupnum: Optional[int] = None
+    record: Optional[str] = None           # Raw record value (photo base64 or other data)
+    # Error fields (present when result=false)
+    result: bool = True
+    reason: Optional[int] = None
+    msg: Optional[str] = None
+
+
+class LogRecord(BaseModel):
+    """A single access log record from sendlog or getalllog responses."""
+    enrollid: int
+    name: Optional[str] = None
+    time: str                              # "yyyy-MM-dd HH:mm:ss"
+    mode: int = 0                          # 2=password, 3=card, 8=face
+    inout: Optional[int] = None            # 0=entry, 1=exit (may vary)
+    event: int = 0                         # Event type code
+    image: Optional[str] = None            # Base64 photo (if use_logphoto=1)
+
+
+class LogEvent(BaseModel):
+    """Full sendlog message from the device."""
+    sn: str
+    count: int = 1
+    logindex: int = 0
+    record: list[LogRecord] = Field(default_factory=list)
+
+
+class RegMessage(BaseModel):
+    """Parsed 'reg' command from the device."""
+    cmd: str = "reg"
+    sn: str
+    devinfo: DeviceInfo
+
+
+class RegResponse(BaseModel):
+    """Response to the 'reg' command."""
+    ret: str = "reg"
+    result: bool = True
+    cloudtime: str                         # "yyyy-MM-dd HH:mm:ss"
+
+
+class SendlogResponse(BaseModel):
+    """Response to the 'sendlog' event (for online mode)."""
+    ret: str = "sendlog"
+    result: bool = True
+    cloudtime: str                         # "yyyy-MM-dd HH:mm:ss"
+    message: Optional[str] = None          # Custom message for device display
+    access: Optional[bool] = None          # True=grant, False=deny (online mode)
+
+
+class DaySection(BaseModel):
+    """A time section within a dayzone."""
+    section: str                           # "HH:MM~HH:MM"
+
+
+class DayZone(BaseModel):
+    """A day zone containing time sections."""
+    day: list[DaySection] = Field(default_factory=list)
+
+
+class WeekDay(BaseModel):
+    """A day reference within a weekzone."""
+    day: int                               # dayzone index (1-based)
+
+
+class WeekZone(BaseModel):
+    """A week zone containing 7 day references (Sun-Sat)."""
+    week: list[WeekDay] = Field(default_factory=list)
+
+
+class UserLockRecord(BaseModel):
+    """A user access lock record for setuserlock."""
+    enrollid: int
+    weekzone: int                          # weekzone ID
+    starttime: str                         # "yyyy-MM-dd HH:mm:ss"
+    endtime: str                           # "yyyy-MM-dd HH:mm:ss"