SmartX RFID

Python Version Version License

Python library for SmartX RFID integrations: device communication, webhook delivery, database utilities, parsing, and support modules for production flows.

Installation

pip install smartx-rfid

For development:

poetry install

Main Modules

smartx_rfid.devices
- RFID: X714, R700_IOT, ACUPAD
- Generic: SERIAL, TCP
- Printers: SatoPrinter, SatoWs4Printer
- DeviceManager
smartx_rfid.webhook
- WebhookManager
- WebhookXtrack
smartx_rfid.db
- DatabaseManager
smartx_rfid.auth
- token and password helpers
smartx_rfid.api
- Omie and Xtrack API clients
smartx_rfid.utils
- TagList, AlertsManager, delayed_function, hash, regex helpers

Quick Start (Device Events)

import asyncio
from smartx_rfid.devices import X714


async def handle_tag(device_name: str, event_data: dict):
    print(f"[{device_name}] EPC={event_data.get('epc')} RSSI={event_data.get('rssi')}")


async def main():
    reader = X714(name="X714-Reader", start_reading=True)

    def on_event(device_name: str, event_type: str, event_data: dict):
        if event_type == "tag":
            asyncio.create_task(handle_tag(device_name, event_data))

    reader.on_event = on_event
    await reader.connect()

    while True:
        await asyncio.sleep(1)


asyncio.run(main())

Webhook Manager

The webhook API now has two explicit sending methods:

post_event: standardized event envelope
post: custom payload POST

It is designed for burst traffic and includes:

async client reuse (keep-alive)
request concurrency limiter
retry with exponential backoff for network errors, HTTP 429, and HTTP 5xx
safe payload serialization for datetime/date, Decimal, bytes, custom objects, dict/list/tuple/set

Constructor

from smartx_rfid.webhook import WebhookManager

webhook = WebhookManager(
    url="https://api.example.com/webhook",  # base URL
    timeout=5.0,
    max_retries=2,
    max_concurrent_requests=50,
)

post_event (standard payload)

success = await webhook.post_event(
    device="reader-01",
    event_type="tag_read",
    event_data={"epc": "E200001175000001", "rssi": -45.2},
)

Payload format sent by post_event:

{
  "device": "reader-01",
  "event_type": "tag_read",
  "event_data": {
    "epc": "E200001175000001",
    "rssi": -45.2
  }
}

post (custom payload + optional URL override)

from datetime import datetime
from decimal import Decimal

payload = {
    "type": "heartbeat",
    "status": "ok",
    "timestamp": datetime.utcnow(),
    "load": Decimal("0.73"),
}

success = await webhook.post(
    payload=payload,
    headers={"X-Source": "rfid-core"},
    url="https://api.example.com/custom-endpoint",  # optional
)

If url is not provided, WebhookManager uses the base URL configured in the constructor.

High-Throughput Example

import asyncio

webhook = WebhookManager(
    url="https://api.example.com/events",
    max_concurrent_requests=20,
    max_retries=2,
)

events = [{"index": i, "ok": True} for i in range(200)]
results = await asyncio.gather(*(webhook.post(payload=e) for e in events))

print(f"sent={sum(results)} failed={len(results) - sum(results)}")
await webhook.aclose()

Recommended pattern:

async with WebhookManager(url="https://api.example.com/events") as webhook:
    await webhook.post_event("reader-01", "connected", {"status": "ok"})

Migration Note

Previous usage:

await webhook.post("device", "event_type", {"data": 1})

Current usage:

await webhook.post_event("device", "event_type", {"data": 1})

For arbitrary payloads, use:

await webhook.post(payload={"anything": "you need"})

Database Example

from datetime import datetime
from sqlalchemy import Column, DateTime, Float, Integer, String
from sqlalchemy.orm import DeclarativeBase
from smartx_rfid.db import DatabaseManager


class Base(DeclarativeBase):
    pass


class TagModel(Base):
    __tablename__ = "rfid_tags"

    id = Column(Integer, primary_key=True)
    epc = Column(String(64), unique=True, nullable=False)
    rssi = Column(Float)
    created_at = Column(DateTime, default=datetime.utcnow)


db = DatabaseManager("sqlite:///rfid_tags.db")
db.register_models(TagModel)
db.create_tables()

with db.get_session() as session:
    session.add(TagModel(epc="E200001175000001", rssi=-45.2))

Event Callback Contract

All devices share a consistent callback contract:

def on_event(device_name: str, event_type: str, event_data: dict):
    # Common event_type values:
    # connected, disconnected, tag, error
    ...

Examples Directory

The examples folder includes:

examples/devices/RFID
examples/devices/generic
examples/devices/printer
examples/db
examples/api
examples/email
examples/license
examples/smtx_db
examples/utils

Run examples with:

python examples/devices/RFID/X714_SERIAL.py
python examples/db/showcase.py

Running Tests

pytest

To run only webhook-related tests:

pytest tests/utils/test_serialization.py -k webhook

Requirements

Python 3.11+
Works on Linux, macOS, and Windows (depending on device transport and drivers)

License

MIT

Support

Repository: https://github.com/ghpascon/smartx_rfid
Issues: https://github.com/ghpascon/smartx_rfid/issues

Release files for smartx-rfid 12.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smartx-rfid 12.5.0
File	Size	Uploaded
smartx_rfid-12.5.0.tar.gz	109.6 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for smartx-rfid 12.5.0
File	Interpreter	ABI	Platform	Reset
smartx_rfid-12.5.0-py3-none-any.whl 141.0 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 250.6 kB

Release files / smartx_rfid-12.5.0.tar.gz

Download URL	smartx_rfid-12.5.0.tar.gz
Size	109.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`1eb54b0b939221e866d8046e99f5e6017e66ca6712c065dacb27b50b2693bf52`
BLAKE2b-256 checksum How to use checksums	`815c4beefecddb19f051de4b3a2fa62b5f8c32f25a0f6495c30774f42de7d381`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / smartx_rfid-12.5.0-py3-none-any.whl

Download URL	smartx_rfid-12.5.0-py3-none-any.whl
Size	141.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f13e469c1c20e6dea5abde9f1c2d612cfee9c6fcbf1842a9cce32cd750dd0dc9`
BLAKE2b-256 checksum How to use checksums	`fe906c55944058be1a4cef3b6caa2f40bd3ab786fb9f832113ab99a45cbcc72e`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`