smartx-rfid 1.1.6__py3-none-any.whl → 1.8.0__py3-none-any.whl

smartx_rfid/schemas/tag.py

@@ -1,6 +1,6 @@
-import re
 from typing import Optional
 from pydantic import BaseModel, Field, field_validator
+from smartx_rfid.utils import regex_hex
 
 
 class TagSchema(BaseModel):
@@ -15,7 +15,7 @@ class TagSchema(BaseModel):
             return v
         if len(v) != 24:
             raise ValueError(f"{field} must have exactly 24 characters")
-        if not re.fullmatch(r"[0-9a-fA-F]{24}", v):
+        if not regex_hex(v, 24):
             raise ValueError(f"{field} must contain only hexadecimal characters (0-9, a-f)")
         return v.lower()
 
@@ -42,7 +42,7 @@ class WriteTagValidator(BaseModel):
 
         if len(v) != 24:
             raise ValueError(f"{field} must have exactly 24 characters")
-        if not re.fullmatch(r"[0-9a-fA-F]{24}", v):
+        if not regex_hex(v, 24):
             raise ValueError(f"{field} must contain only hexadecimal characters (0-9, a-f)")
         return v.lower()
 
@@ -50,6 +50,6 @@ class WriteTagValidator(BaseModel):
     def validate_password_length_and_hex(cls, v, field):
         if len(v) != 8:
             raise ValueError(f"{field} must have exactly 8 characters")
-        if not re.fullmatch(r"[0-9a-fA-F]{8}", v):
+        if not regex_hex(v, 8):
             raise ValueError(f"{field} must contain only hexadecimal characters (0-9, a-f)")
         return v.lower()

smartx_rfid/utils/__init__.py

@@ -1,2 +1,3 @@
+from .regex import regex_hex
 from .tag_list import TagList
 from .logger_manager import LoggerManager

smartx_rfid/utils/path.py

@@ -84,10 +84,10 @@ def include_all_routers(current_path: str, app) -> None:
                     logging.info(f"✅ Route loaded: {relative_path}")
 
                 else:
-                    logging.warning(f"⚠️  File {current_path} does not define a 'router'")
+                    logging.warning(f"⚠️  File {current_path}/{file_path.name} does not define a 'router'")
 
             except Exception as e:
-                logging.error(f"❌ Error loading {current_path}: {e}", exc_info=True)
+                logging.error(f"❌ Error loading {current_path}/{file_path.name}: {e}", exc_info=True)
 
 
 def load_file(file_path: str | Path) -> str:

smartx_rfid/utils/regex.py

@@ -0,0 +1,9 @@
+import re
+
+
+def regex_hex(value: str, length: int = 24) -> bool:
+    """
+    Validate if the given value is a valid EPC (24 hexadecimal characters).
+    """
+    pattern = rf"^[0-9A-Fa-f]{{{length}}}$"
+    return bool(re.match(pattern, value))

smartx_rfid/utils/tag_list.py

@@ -3,6 +3,7 @@ from datetime import datetime
 from threading import Lock
 import logging
 from pyepc import SGTIN
+from smartx_rfid.schemas.tag import TagSchema
 
 
 class TagList:
@@ -13,7 +14,7 @@ class TagList:
     Each tag is uniquely identified by either EPC or TID.
     """
 
-    def __init__(self, unique_identifier: Literal["epc", "tid"] = "epc"):
+    def __init__(self, unique_identifier: Literal["epc", "tid"] = "epc", prefix: str | list | None = None):
         """
         Initialize the tag list.
 
@@ -27,6 +28,10 @@ class TagList:
         self._tags: Dict[str, Dict[str, Any]] = {}
         self._lock = Lock()
 
+        if isinstance(prefix, str):
+            prefix = [prefix]
+        self.prefix: list | None = prefix
+
     def __len__(self) -> int:
         """
         Return the number of stored tags.
@@ -55,20 +60,30 @@ class TagList:
             (False, None)      if an error occurs;
         """
         try:
+            # Validate Tag
+            TagSchema.model_validate(tag)
+
             identifier_value = tag.get(self.unique_identifier)
             if not identifier_value:
                 raise ValueError(f"Tag missing '{self.unique_identifier}'")
 
+            # Check Prefix
+            if self.prefix is not None:
+                epc = tag.get("epc")
+                if epc is None or not any(epc.startswith(p) for p in self.prefix):
+                    return False, None
+
+            # handle tag
             with self._lock:
                 if identifier_value not in self._tags:
                     stored = self._new_tag(tag, device)
                     return True, stored
                 else:
-                    stored = self._existing_tag(tag)
+                    stored = self._existing_tag(tag, device)
                     return False, stored
 
         except Exception as e:
-            logging.warning(f"[ TAG ERROR ] {e}")
+            logging.error(f"[ TAG ERROR ] {e}")
             return False, None
 
     def _new_tag(self, tag: Dict[str, Any], device: str) -> Dict[str, Any]:
@@ -90,18 +105,18 @@ class TagList:
             gtin = None
 
         stored_tag = {
-            **tag,
-            "device": device,
             "timestamp": now,
-            "count": 1,
+            "device": device,
+            **tag,
             "gtin": gtin,
+            "count": 1,
         }
 
         self._tags[tag[self.unique_identifier]] = stored_tag
 
         return stored_tag
 
-    def _existing_tag(self, tag: Dict[str, Any]) -> Dict[str, Any]:
+    def _existing_tag(self, tag: Dict[str, Any], device: str) -> Dict[str, Any]:
         """
         Update an existing tag.
 
@@ -122,6 +137,7 @@ class TagList:
             if old_rssi is None or abs(new_rssi) < abs(old_rssi):
                 current["rssi"] = new_rssi
                 current["ant"] = tag.get("ant")
+                current["device"] = device
 
         return current
 
@@ -149,11 +165,11 @@ class TagList:
 
         if self.unique_identifier == identifier_type:
             return self._tags.get(identifier_value)
-        
+
         for tag in self._tags.values():
             if tag.get(identifier_type) == identifier_value:
                 return tag
-            
+
         return None
 
     def clear(self) -> None:

smartx_rfid/webhook/__init__.py

@@ -0,0 +1,2 @@
+from ._main import WebhookManager
+from .xtrack import WebhookXtrack

smartx_rfid/webhook/_main.py

@@ -0,0 +1,153 @@
+import asyncio
+import logging
+from typing import Optional, Dict, Any
+from datetime import datetime, date
+from decimal import Decimal
+
+import httpx
+
+
+class WebhookManager:
+    def __init__(
+        self,
+        url: str,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+    ):
+        self.url = url
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self.default_headers = {"Content-Type": "application/json", "User-Agent": "SmartX-Connector/1.0"}
+
+    def _make_serializable(self, obj: Any) -> Any:
+        """
+        Converts objects to JSON-serializable format.
+
+        Handles:
+        - datetime/date objects -> ISO format strings
+        - Decimal -> float
+        - Classes with __dict__ -> dict
+        - Sets -> lists
+        - Bytes -> string (decoded)
+        - Iterables -> lists
+
+        Args:
+            obj: Object to convert
+
+        Returns:
+            JSON-serializable version of the object
+        """
+        # Handle None
+        if obj is None:
+            return None
+
+        # Handle datetime and date
+        if isinstance(obj, (datetime, date)):
+            return obj.isoformat()
+
+        # Handle Decimal
+        if isinstance(obj, Decimal):
+            return float(obj)
+
+        # Handle bytes
+        if isinstance(obj, bytes):
+            try:
+                return obj.decode("utf-8")
+            except Exception:
+                return str(obj)
+
+        # Handle sets
+        if isinstance(obj, set):
+            return list(obj)
+
+        # Handle dictionaries (recursively)
+        if isinstance(obj, dict):
+            return {key: self._make_serializable(value) for key, value in obj.items()}
+
+        # Handle lists and tuples (recursively)
+        if isinstance(obj, (list, tuple)):
+            return [self._make_serializable(item) for item in obj]
+
+        # Handle objects with __dict__ (custom classes)
+        if hasattr(obj, "__dict__"):
+            return self._make_serializable(obj.__dict__)
+
+        # Handle primitive types (str, int, float, bool)
+        if isinstance(obj, (str, int, float, bool)):
+            return obj
+
+        # Last resort: convert to string
+        return str(obj)
+
+    async def post(
+        self, device: str, event_type: str, event_data: Any = None, headers: Optional[Dict[str, str]] = None
+    ) -> bool:
+        """
+        Sends data via POST to the configured webhook URL.
+
+        Args:
+            device: Name of the device sending the webhook
+            event_type: Type of event being sent
+            event_data: Data to be sent (will be converted to JSON)
+            headers: Optional headers for the request
+
+        Returns:
+            bool: True if sent successfully, False otherwise
+        """
+
+        if not self.url:
+            logging.warning("⚠️ WEBHOOK_URL not configured in settings")
+            return False
+
+        # Convert event_data to JSON-serializable format
+        serializable_event_data = self._make_serializable(event_data)
+
+        payload = {"device": device, "event_type": event_type, "event_data": serializable_event_data}
+
+        # Merge with custom headers if provided
+        if headers:
+            self.default_headers.update(headers)
+
+        retries = 0
+        last_error = None
+
+        while retries < self.max_retries:
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    response = await client.post(self.url, json=payload, headers=self.default_headers)
+
+                    # Consider success if status 2xx
+                    if response.status_code < 300:
+                        logging.info(f"✅ Webhook sent successfully to {self.url} - Status: {response.status_code}")
+                        return True
+                    else:
+                        logging.warning(
+                            f"⚠️ Webhook failed - Status: {response.status_code} - Response: {response.text[:200]}"
+                        )
+                        return False
+
+            except httpx.TimeoutException:
+                last_error = f"Timeout after {self.timeout}s"
+                retries += 1
+                logging.warning(f"⏰ Webhook timeout (attempt {retries}/{self.max_retries})")
+
+            except httpx.ConnectError:
+                last_error = "Connection error"
+                retries += 1
+                logging.warning(f"🔌 Webhook connection error (attempt {retries}/{self.max_retries})")
+
+            except Exception as e:
+                last_error = str(e)
+                retries += 1
+                logging.error(f"❌ Webhook error (attempt {retries}/{self.max_retries}): {e}")
+
+            # Wait before retrying (exponential backoff)
+            if retries < self.max_retries:
+                wait_time = 2**retries  # 2s, 4s, 8s...
+                logging.info(f"🔁 Retrying webhook in {wait_time}s...")
+                await asyncio.sleep(wait_time)
+
+        # If we reached here, all attempts failed
+        logging.error(f"❌ Webhook failed after {self.max_retries} attempts. Last error: {last_error}")
+        return False

smartx_rfid/webhook/xtrack.py

@@ -0,0 +1,30 @@
+import logging
+import httpx
+
+
+class WebhookXtrack:
+    def __init__(self, url: str, timeout: int = 5):
+        self.url = url
+        self.timeout = timeout
+
+    async def post(self, tag: dict):
+        try:
+            device = tag.get("device", "unknown")
+            ant = tag.get("ant", "1")
+            epc = tag.get("epc", None)
+            if epc is None:
+                raise Exception("EPC is required")
+            payload = f"""<msg>
+                        <command>ReportRead</command>
+                        <data>EVENT=|DEVICENAME={device}|ANTENNANAME={ant}|TAGID={epc}|</data>
+                        <cmpl>STATE=|DATA1=|DATA2=|DATA3=|DATA4=|DATA5=|</cmpl>
+                        </msg>"""
+            async with httpx.AsyncClient() as client:
+                await client.post(
+                    self.url,
+                    content=payload,
+                    headers={"Content-Type": "application/xml"},
+                    timeout=self.timeout,
+                )
+        except Exception as e:
+            logging.info(f"Error Xtrack: {e}")

smartx_rfid-1.8.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: smartx-rfid
+Version: 1.8.0
+Summary: SmartX RFID library
+License: MIT
+License-File: LICENSE
+Keywords: python,library,RFID,smartx,packaging
+Author: Gabriel Henrique Pascon
+Author-email: gh.pascon@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: bleak (>=1.1.1,<2.0.0)
+Requires-Dist: httpx (==0.28.1)
+Requires-Dist: psycopg2 (>=2.9.11,<3.0.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pyepc (==0.5.0)
+Requires-Dist: pymysql (==1.1.1)
+Requires-Dist: pyserial (==3.5)
+Requires-Dist: pyserial-asyncio (==0.6)
+Requires-Dist: sqlalchemy (==2.0.29)
+Project-URL: Documentation, https://github.com/ghpascon/smartx_rfid#readme
+Project-URL: Homepage, https://github.com/ghpascon/smartx_rfid
+Project-URL: Repository, https://github.com/ghpascon/smartx_rfid
+Description-Content-Type: text/markdown
+
+# SmartX RFID
+
+![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)
+![Version](https://img.shields.io/badge/version-1.5.0-green.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+Python library for RFID device integration and data management.
+
+## Installation
+
+```bash
+pip install smartx-rfid
+```
+
+## Quick Start
+
+```python
+from smartx_rfid.devices import X714
+import asyncio
+
+async def on_tag_read(name: str, tag_data: dict):
+    print(f"Tag: {tag_data['epc']} | RSSI: {tag_data['rssi']}dBm")
+
+async def main():
+    reader = X714(name="RFID Reader", start_reading=True)
+    reader.on_event = lambda name, event_type, data: (
+        asyncio.create_task(on_tag_read(name, data)) 
+        if event_type == "tag" else None
+    )
+    
+    await reader.connect()
+    
+    while True:
+        await asyncio.sleep(1)
+
+asyncio.run(main())
+```
+
+## Features
+
+### Supported Devices
+- **X714 RFID Reader** - Serial, TCP, Bluetooth LE connections
+- **R700 IOT** - HTTP REST API integration
+- **Generic Serial/TCP** - Custom protocol support
+
+### Core Components
+- **Device Management** - Async communication with auto-reconnection
+- **Database Integration** - SQLAlchemy with multiple database support
+- **Webhook System** - HTTP notifications with retry logic
+- **Tag Management** - Thread-safe tag list with deduplication
+
+## Device Examples
+
+### X714 RFID Reader
+
+```python
+from smartx_rfid.devices import X714
+
+# Serial connection (auto-detect)
+reader = X714(name="X714-Serial")
+
+# TCP connection
+reader = X714(
+    name="X714-TCP", 
+    connection_type="TCP", 
+    ip="192.168.1.100"
+)
+
+# Bluetooth LE
+reader = X714(
+    name="X714-BLE", 
+    connection_type="BLE"
+)
+
+def on_event(name: str, event_type: str, data: dict):
+    if event_type == "tag":
+        print(f"EPC: {data['epc']}, Antenna: {data['ant']}")
+
+reader.on_event = on_event
+await reader.connect()
+```
+
+### R700 IOT Reader
+
+```python
+from smartx_rfid.devices import R700_IOT, R700_IOT_config_example
+
+reader = R700_IOT(
+    name="R700-Reader",
+    ip="192.168.1.200",
+    config=R700_IOT_config_example
+)
+
+reader.on_event = on_event
+await reader.connect()
+```
+
+## Database Integration
+
+```python
+from smartx_rfid.db import DatabaseManager
+from sqlalchemy import Column, String, Float, Integer, DateTime
+from sqlalchemy.orm import DeclarativeBase
+from datetime import datetime
+
+class Base(DeclarativeBase):
+    pass
+
+class TagModel(Base):
+    __tablename__ = 'rfid_tags'
+    
+    id = Column(Integer, primary_key=True)
+    epc = Column(String(50), unique=True, nullable=False)
+    tid = Column(String(50))
+    ant = Column(Integer)
+    rssi = Column(Float)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+# Initialize database
+db = DatabaseManager("sqlite:///rfid_tags.db")
+db.register_models(TagModel)
+db.create_tables()
+
+# Use with sessions
+with db.get_session() as session:
+    tag = TagModel(epc="E200001175000001", ant=1, rssi=-45.2)
+    session.add(tag)
+
+# Raw SQL queries
+results = db.execute_query_fetchall(
+    "SELECT * FROM rfid_tags WHERE rssi > :threshold",
+    params={"threshold": -50}
+)
+```
+
+### Supported Databases
+- PostgreSQL: `postgresql://user:pass@localhost/db`
+- MySQL: `mysql+pymysql://user:pass@localhost/db`
+- SQLite: `sqlite:///path/to/database.db`
+
+## Webhook Integration
+
+```python
+from smartx_rfid.webhook import WebhookManager
+
+webhook = WebhookManager("https://api.example.com/rfid-events")
+
+# Send tag data
+success = await webhook.post("device_01", "tag_read", {
+    "epc": "E200001175000001",
+    "rssi": -45.2,
+    "antenna": 1,
+    "timestamp": "2026-01-15T10:30:00Z"
+})
+
+if success:
+    print("Webhook sent successfully")
+```
+
+## Tag Management
+
+```python
+from smartx_rfid.utils import TagList
+
+# Create thread-safe tag list
+tags = TagList(unique_identifier="epc")
+
+def on_tag(device: str, tag_data: dict):
+    new_tag, tag = tags.add(tag_data, device=device)
+    
+    if new_tag:
+        print(f"New tag: {tag['epc']}")
+        # Add custom data
+        tag['product_name'] = "Widget ABC"
+    else:
+        print(f"Existing tag: {tag['epc']}")
+
+# Use with device events
+reader.on_event = lambda name, event_type, data: (
+    on_tag(name, data) if event_type == "tag" else None
+)
+```
+
+## Complete Integration Example
+
+```python
+import asyncio
+from smartx_rfid.devices import X714
+from smartx_rfid.db import DatabaseManager
+from smartx_rfid.webhook import WebhookManager
+from smartx_rfid.utils import TagList
+
+async def rfid_system():
+    # Initialize components
+    reader = X714(name="Production-Scanner", start_reading=True)
+    db = DatabaseManager("postgresql://localhost/rfid_production")
+    webhook = WebhookManager("https://api.internal.com/rfid")
+    tags = TagList()
+    
+    async def process_tag(name: str, tag_data: dict):
+        # Check if new tag
+        new_tag, tag = tags.add(tag_data, device=name)
+        
+        if new_tag:
+            # Save to database
+            with db.get_session() as session:
+                session.add(TagModel(**tag_data))
+            
+            # Send notification
+            await webhook.post(name, "new_tag", tag_data)
+            print(f"New tag processed: {tag_data['epc']}")
+    
+    reader.on_event = lambda n, t, d: (
+        asyncio.create_task(process_tag(n, d)) if t == "tag" else None
+    )
+    
+    await reader.connect()
+
+asyncio.run(rfid_system())
+```
+
+## Configuration
+
+### Device Configuration
+```python
+# High-performance settings
+reader = X714(
+    name="FastScanner",
+    read_power=30,      # Max power
+    session=2,          # Session config
+    read_interval=100   # Fast scanning
+)
+
+# Database with connection pooling
+db = DatabaseManager(
+    database_url="postgresql://user:pass@localhost/db",
+    pool_size=10,
+    max_overflow=20,
+    echo=True  # Enable SQL logging
+)
+```
+
+### Logging Setup
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+```
+
+## API Reference
+
+### Core Modules
+- `smartx_rfid.devices` - Device communication classes
+- `smartx_rfid.db` - Database management
+- `smartx_rfid.webhook` - HTTP notification system
+- `smartx_rfid.utils` - Utility classes and helpers
+
+### Event System
+All devices use a consistent event callback system:
+
+```python
+def on_event(device_name: str, event_type: str, event_data: dict):
+    """
+    Event types:
+    - "connected": Device connected successfully
+    - "disconnected": Device disconnected
+    - "tag": RFID tag detected
+    - "error": Error occurred
+    """
+    pass
+
+device.on_event = on_event
+```
+
+## Examples
+
+The `examples/` directory contains working examples for all supported devices and features:
+
+```
+examples/
+├── devices/
+│   ├── RFID/           # X714, R700_IOT examples
+│   └── generic/        # Serial, TCP examples
+├── db/                 # Database integration examples
+└── utils/              # Tag management examples
+```
+
+Run examples:
+```bash
+python examples/devices/RFID/X714_SERIAL.py
+python examples/db/showcase.py
+```
+
+## Requirements
+
+- Python 3.11+
+- Dependencies automatically installed with pip
+
+## License
+
+MIT License
+
+## Support
+
+- **Repository**: [https://github.com/ghpascon/smartx_rfid](https://github.com/ghpascon/smartx_rfid)
+- **Issues**: [GitHub Issues](https://github.com/ghpascon/smartx_rfid/issues)
+- **Email**: [gh.pascon@gmail.com](mailto:gh.pascon@gmail.com)
+