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

pip install topdata-sdk

Quick Start

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:

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

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

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

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