topdata-sdk 0.1.0__tar.gz

topdata_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: topdata-sdk
+Version: 0.1.0
+Summary: A production-ready asynchronous Python SDK for Topdata facial reader devices (AiFace, Catraca Fit, Revolution, Box, Inner Ponto 4, Inner Acesso 2). WebSocket server model — the device connects to you.
+Author-email: Tulio Amancio <root@tsuriu.com.br>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/libandpackages/topdata-sdk
+Project-URL: Source, https://gitlab.com/libandpackages/topdata-sdk
+Project-URL: Bug Tracker, https://gitlab.com/libandpackages/topdata-sdk/-/issues
+Keywords: topdata,facial-reader,access-control,biometrics,iot,async,sdk,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: Pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+
+# Topdata Python SDK
+
+A production-ready asynchronous Python SDK for **Topdata facial reader devices** (AiFace, Catraca Fit, Revolution, Box, Inner Ponto 4, Inner Acesso 2).
+
+> ⚠️ **Inverted connection model**: Unlike traditional device SDKs where your software connects _to_ the device, Topdata devices connect _to_ your server. This SDK runs a WebSocket server that accepts incoming connections from the readers.
+
+## Installation
+
+```bash
+pip install topdata-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from topdata import TopdataServer, TopdataDeviceSession, LogEvent
+
+async def main():
+    server = TopdataServer(host="0.0.0.0", port=7792)
+
+    async def on_connected(session: TopdataDeviceSession):
+        print(f"✅ Device connected: {session.serial_number}")
+        print(f"   Model: {session.device_info.modelname}")
+        print(f"   Firmware: {session.device_info.firmware}")
+        print(f"   Users: {session.device_info.useduser}/{session.device_info.usersize}")
+
+    async def on_disconnected(sn: str):
+        print(f"❌ Device disconnected: {sn}")
+
+    async def on_event(session: TopdataDeviceSession, event: LogEvent):
+        for record in event.record:
+            print(f"🔔 Access event from {session.serial_number}:")
+            print(f"   User: {record.enrollid} ({record.name})")
+            print(f"   Time: {record.time}")
+            print(f"   Mode: {record.mode} (8=face, 3=card, 2=password)")
+            print(f"   Event: {record.event}")
+
+        # For online mode, return access decision:
+        # return {"access": True, "message": "Welcome!"}
+        return None  # Offline mode — no access decision needed
+
+    server.on_device_connected = on_connected
+    server.on_device_disconnected = on_disconnected
+    server.on_event = on_event
+
+    await server.start()
+    print("🚀 Topdata server listening on ws://0.0.0.0:7792/pub/chat")
+    print("   Configure your device: MENU → REDE → SERVIDOR → IP/Porta")
+
+    # Keep running
+    try:
+        await asyncio.Future()  # Run forever
+    except KeyboardInterrupt:
+        await server.stop()
+
+asyncio.run(main())
+```
+
+## User Management
+
+Once a device is connected, you can manage users through the session object:
+
+```python
+async def on_connected(session: TopdataDeviceSession):
+    # Create a user (without photo)
+    await session.set_user(
+        enrollid=1001,
+        name="João Silva",
+        admin=0,       # 0=user, 1=admin, 2=super
+        card=25565535,  # Wiegand 10 format
+        password=1234,
+    )
+
+    # Add a facial photo
+    with open("joao.jpg", "rb") as f:
+        photo_data = f.read()
+    await session.set_user_photo(enrollid=1001, image_data=photo_data, name="João Silva")
+
+    # List all users
+    users = await session.get_user_list()
+    print(f"Device has {len(users)} user records")
+
+    # Get user details
+    info = await session.get_user_info(enrollid=1001)
+    print(f"User: {info.name}, has face: {info.faceflag}")
+
+    # Delete a user
+    await session.delete_user(enrollid=1001)
+```
+
+## Image Requirements
+
+Photos sent to the device must meet these requirements:
+- **Format**: JPEG only
+- **File size**: < 150 KB
+- **Resolution**: 240×320 to 800×1280 px (recommended: 480×640)
+- **Content**: Single person, vertical face, no mask/hat/sunglasses
+
+The SDK **automatically validates and normalizes** images: oversized files are downscaled to 480×640 and re-compressed.
+
+## Wiegand Utilities
+
+```python
+from topdata import wiegand10_to_wiegand26, wiegand26_to_wiegand10
+
+# Wiegand 10 (facility=255, card=65535) → Wiegand 26 integer
+w26 = wiegand10_to_wiegand26(255, 65535)  # → 16776959
+
+# Reverse
+facility, card = wiegand26_to_wiegand10(16776959)  # → (255, 65535)
+```
+
+## Device Configuration
+
+```python
+async def configure_device(session: TopdataDeviceSession):
+    # Set online mode (server decides access)
+    await session.set_device_info(server_verify=1)
+
+    # Set volume and door open time
+    await session.set_device_info(volume=8, door_opentime=5)
+
+    # Disable device during bulk operations
+    await session.disable()
+    # ... do bulk operations ...
+    await session.enable()
+```
+
+## Protocol Reference
+
+| Command | Direction | Description |
+|---|---|---|
+| `reg` | device → server | Handshake (serial, capabilities) |
+| `sendlog` | device → server | Access event (face/card/password recognition) |
+| `senduser` | device → server | User registered at device |
+| `enabledevice` | server → device | Re-enable recognition |
+| `disabledevice` | server → device | Suspend recognition |
+| `getuserlist` | server → device | List users (paginated) |
+| `getuserinfo` | server → device | Get user details |
+| `setuserinfo` | server → device | Create/update user |
+| `deleteuser` | server → device | Delete user data |
+| `cleanuser` | server → device | Delete ALL users |
+| `setdevinfo` | server → device | Configure device parameters |
+| `setdevlock` | server → device | Configure card format & time zones |
+| `setuserlock` | server → device | Per-user time restrictions |
+| `getalllog` | server → device | Fetch access logs (paginated) |
+| `cleanlog` | server → device | Delete all logs |
+
+## Architecture
+
+```
+┌──────────────────┐     WebSocket      ┌──────────────────┐
+│  Topdata Device  │ ──── connects to ──→│  TopdataServer   │
+│  (Facial Reader) │                     │  (Your App)      │
+│                  │ ← reg ──────────── │                  │
+│                  │ ── ret:reg ───────→ │                  │
+│                  │                     │                  │
+│                  │ ← sendlog ──────── │ on_event()       │
+│                  │ ── ret:sendlog ───→ │                  │
+│                  │                     │                  │
+│                  │ ── cmd:setuserinfo →│                  │
+│                  │ ← ret:setuserinfo ─ │                  │
+└──────────────────┘                     └──────────────────┘
+```
+
+## License
+
+MIT

topdata_sdk-0.1.0/README.md

@@ -0,0 +1,169 @@
+# Topdata Python SDK
+
+A production-ready asynchronous Python SDK for **Topdata facial reader devices** (AiFace, Catraca Fit, Revolution, Box, Inner Ponto 4, Inner Acesso 2).
+
+> ⚠️ **Inverted connection model**: Unlike traditional device SDKs where your software connects _to_ the device, Topdata devices connect _to_ your server. This SDK runs a WebSocket server that accepts incoming connections from the readers.
+
+## Installation
+
+```bash
+pip install topdata-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from topdata import TopdataServer, TopdataDeviceSession, LogEvent
+
+async def main():
+    server = TopdataServer(host="0.0.0.0", port=7792)
+
+    async def on_connected(session: TopdataDeviceSession):
+        print(f"✅ Device connected: {session.serial_number}")
+        print(f"   Model: {session.device_info.modelname}")
+        print(f"   Firmware: {session.device_info.firmware}")
+        print(f"   Users: {session.device_info.useduser}/{session.device_info.usersize}")
+
+    async def on_disconnected(sn: str):
+        print(f"❌ Device disconnected: {sn}")
+
+    async def on_event(session: TopdataDeviceSession, event: LogEvent):
+        for record in event.record:
+            print(f"🔔 Access event from {session.serial_number}:")
+            print(f"   User: {record.enrollid} ({record.name})")
+            print(f"   Time: {record.time}")
+            print(f"   Mode: {record.mode} (8=face, 3=card, 2=password)")
+            print(f"   Event: {record.event}")
+
+        # For online mode, return access decision:
+        # return {"access": True, "message": "Welcome!"}
+        return None  # Offline mode — no access decision needed
+
+    server.on_device_connected = on_connected
+    server.on_device_disconnected = on_disconnected
+    server.on_event = on_event
+
+    await server.start()
+    print("🚀 Topdata server listening on ws://0.0.0.0:7792/pub/chat")
+    print("   Configure your device: MENU → REDE → SERVIDOR → IP/Porta")
+
+    # Keep running
+    try:
+        await asyncio.Future()  # Run forever
+    except KeyboardInterrupt:
+        await server.stop()
+
+asyncio.run(main())
+```
+
+## User Management
+
+Once a device is connected, you can manage users through the session object:
+
+```python
+async def on_connected(session: TopdataDeviceSession):
+    # Create a user (without photo)
+    await session.set_user(
+        enrollid=1001,
+        name="João Silva",
+        admin=0,       # 0=user, 1=admin, 2=super
+        card=25565535,  # Wiegand 10 format
+        password=1234,
+    )
+
+    # Add a facial photo
+    with open("joao.jpg", "rb") as f:
+        photo_data = f.read()
+    await session.set_user_photo(enrollid=1001, image_data=photo_data, name="João Silva")
+
+    # List all users
+    users = await session.get_user_list()
+    print(f"Device has {len(users)} user records")
+
+    # Get user details
+    info = await session.get_user_info(enrollid=1001)
+    print(f"User: {info.name}, has face: {info.faceflag}")
+
+    # Delete a user
+    await session.delete_user(enrollid=1001)
+```
+
+## Image Requirements
+
+Photos sent to the device must meet these requirements:
+- **Format**: JPEG only
+- **File size**: < 150 KB
+- **Resolution**: 240×320 to 800×1280 px (recommended: 480×640)
+- **Content**: Single person, vertical face, no mask/hat/sunglasses
+
+The SDK **automatically validates and normalizes** images: oversized files are downscaled to 480×640 and re-compressed.
+
+## Wiegand Utilities
+
+```python
+from topdata import wiegand10_to_wiegand26, wiegand26_to_wiegand10
+
+# Wiegand 10 (facility=255, card=65535) → Wiegand 26 integer
+w26 = wiegand10_to_wiegand26(255, 65535)  # → 16776959
+
+# Reverse
+facility, card = wiegand26_to_wiegand10(16776959)  # → (255, 65535)
+```
+
+## Device Configuration
+
+```python
+async def configure_device(session: TopdataDeviceSession):
+    # Set online mode (server decides access)
+    await session.set_device_info(server_verify=1)
+
+    # Set volume and door open time
+    await session.set_device_info(volume=8, door_opentime=5)
+
+    # Disable device during bulk operations
+    await session.disable()
+    # ... do bulk operations ...
+    await session.enable()
+```
+
+## Protocol Reference
+
+| Command | Direction | Description |
+|---|---|---|
+| `reg` | device → server | Handshake (serial, capabilities) |
+| `sendlog` | device → server | Access event (face/card/password recognition) |
+| `senduser` | device → server | User registered at device |
+| `enabledevice` | server → device | Re-enable recognition |
+| `disabledevice` | server → device | Suspend recognition |
+| `getuserlist` | server → device | List users (paginated) |
+| `getuserinfo` | server → device | Get user details |
+| `setuserinfo` | server → device | Create/update user |
+| `deleteuser` | server → device | Delete user data |
+| `cleanuser` | server → device | Delete ALL users |
+| `setdevinfo` | server → device | Configure device parameters |
+| `setdevlock` | server → device | Configure card format & time zones |
+| `setuserlock` | server → device | Per-user time restrictions |
+| `getalllog` | server → device | Fetch access logs (paginated) |
+| `cleanlog` | server → device | Delete all logs |
+
+## Architecture
+
+```
+┌──────────────────┐     WebSocket      ┌──────────────────┐
+│  Topdata Device  │ ──── connects to ──→│  TopdataServer   │
+│  (Facial Reader) │                     │  (Your App)      │
+│                  │ ← reg ──────────── │                  │
+│                  │ ── ret:reg ───────→ │                  │
+│                  │                     │                  │
+│                  │ ← sendlog ──────── │ on_event()       │
+│                  │ ── ret:sendlog ───→ │                  │
+│                  │                     │                  │
+│                  │ ── cmd:setuserinfo →│                  │
+│                  │ ← ret:setuserinfo ─ │                  │
+└──────────────────┘                     └──────────────────┘
+```
+
+## License
+
+MIT

topdata_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "topdata-sdk"
+version = "0.1.0"
+authors = [
+  { name="Tulio Amancio", email="root@tsuriu.com.br" },
+]
+description = "A production-ready asynchronous Python SDK for Topdata facial reader devices (AiFace, Catraca Fit, Revolution, Box, Inner Ponto 4, Inner Acesso 2). WebSocket server model — the device connects to you."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["topdata", "facial-reader", "access-control", "biometrics", "iot", "async", "sdk", "websocket"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "websockets>=12.0",
+    "pydantic>=2.0.0",
+    "Pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+"Homepage" = "https://gitlab.com/libandpackages/topdata-sdk"
+"Source" = "https://gitlab.com/libandpackages/topdata-sdk"
+"Bug Tracker" = "https://gitlab.com/libandpackages/topdata-sdk/-/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

topdata_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

topdata_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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))