traphIQ Help Center

Overview

This guide explains how to configure and integrate RFID readers with the traphIQ Employee Tracking System. The system supports multiple RFID reader types and communication protocols through a comprehensive REST API.

System Architecture

The traphIQ system uses a centralized server architecture where RFID readers communicate with the main application server via HTTP/HTTPS REST API calls.

API Endpoints

Base URLs

• Development: http://localhost:8080
• Production: https://your-domain.com

Core RFID Endpoints

{
    "rfid_tag": "TAG001",
    "area_id": 1,
    "reader_id": "READER_ENTRANCE_A1",
    "metadata": {
        "reader_location": "Main Entrance",
        "signal_strength": 85
    }
}

{
    "rfid_tag": "TAG001", 
    "area_id": 1,
    "reader_id": "READER_EXIT_A1",
    "metadata": {
        "reader_location": "Main Exit",
        "signal_strength": 90
    }
}

{
    "rfid_tag": "TAG001",
    "area_id": 1, 
    "reader_id": "READER_TUNNEL_1",
    "metadata": {
        "detection_type": "proximity",
        "signal_strength": 78
    }
}

Alternative API Versions

Authentication Methods

1. Bearer Token Authentication (Recommended)

Generate an API token through the admin interface and include it in the Authorization header:

curl -X POST "http://your-server:8080/api/v1/rfid/entry" \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "rfid_tag": "TAG001",
    "area_id": 1,
    "reader_id": "READER_01"
  }'

2. Simple API (Testing Only)

For testing and development, use the Simple API endpoints with no authentication required:

curl -X POST "http://your-server:8080/api/simple/rfid/entry" \
  -H "Content-Type: application/json" \
  -d '{
    "rfid_tag": "TAG001",
    "area_id": 1,
    "reader_id": "TEST_READER"
  }'

RFID Reader Configuration

Required Data Fields

Event Types

Entry Events

• Use when reader detects tag entering an area
• Explicit entry detection (e.g., entrance turnstile)
• Endpoint: /api/rfid/entry

Exit Events

• Use when reader detects tag exiting an area
• Explicit exit detection (e.g., exit turnstile)
• Endpoint: /api/rfid/exit

Toggle Events (Recommended)

• Use for general proximity detection
• System automatically determines entry/exit based on current employee location
• Endpoint: /api/rfid/toggle

Hardware Compatibility

Supported Reader Types

Minimum Requirements

• Network Connectivity: Ethernet or WiFi
• HTTP Client: Ability to make HTTP POST requests
• JSON Support: Parse and generate JSON data
• Authentication: Support for Bearer token headers

Recommended Features

• HTTPS Support: Secure communication for production
• Error Handling: Retry logic for failed API calls
• Local Buffering: Store events during network outages
• Configurable Endpoints: Easy server URL updates

Network Configuration

Network Topology

Firewall Configuration

• Inbound: Allow port 8080 (or configured port) on server
• Outbound: Allow HTTP/HTTPS from readers to server
• DNS: Ensure readers can resolve server hostname (if used)

Example Reader Configuration

{
  "network": {
    "ip": "192.168.1.10",
    "netmask": "255.255.255.0", 
    "gateway": "192.168.1.1",
    "dns": "192.168.1.1"
  },
  "api": {
    "server_url": "http://192.168.1.5:8080",
    "endpoint": "/api/v1/rfid/toggle",
    "token": "your-api-token-here",
    "timeout": 5000,
    "retry_count": 3
  },
  "reader": {
    "id": "READER_ENTRANCE_01",
    "area_id": 1,
    "location": "Main Entrance"
  }
}

Testing & Validation

Quick API Tests

Test server connectivity and authentication:

# Test server connectivity
curl -I http://your-server:8080/api/status

# Test authentication
curl -X GET "http://your-server:8080/api/v1/employees" \
  -H "Authorization: Bearer your-token"

# Test RFID event submission
curl -X POST "http://your-server:8080/api/v1/rfid/entry" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "rfid_tag": "TEST001",
    "area_id": 1,
    "reader_id": "TEST_READER"
  }'

Using the Demo Interface

1. Navigate to /demo on your server
2. Select employee with valid RFID tag
3. Simulate events for different areas
4. Verify results on dashboard for real-time updates

Python Test Script

#!/usr/bin/env python3
import requests
import json
import time

# Configuration
SERVER_URL = "http://192.168.1.5:8080"
API_TOKEN = "your-api-token-here"
READER_ID = "TEST_READER_01"

def test_rfid_event(rfid_tag, area_id, event_type="toggle"):
    """Send test RFID event to server"""
    
    url = f"{SERVER_URL}/api/v1/rfid/{event_type}"
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }
    data = {
        "rfid_tag": rfid_tag,
        "area_id": area_id,
        "reader_id": READER_ID,
        "metadata": {
            "test": True,
            "timestamp": time.time()
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=data, timeout=5)
        
        if response.status_code == 201:
            print(f"✅ Event sent successfully: {rfid_tag}")
            return True
        else:
            print(f"❌ Error {response.status_code}: {response.text}")
            return False
            
    except requests.exceptions.RequestException as e:
        print(f"❌ Network error: {e}")
        return False

# Test sequence
if __name__ == "__main__":
    test_rfid_event("TAG001", 1, "entry")
    time.sleep(2)
    test_rfid_event("TAG001", 1, "exit")

Troubleshooting

Common Issues

Debug Tools

# Monitor server logs
tail -f /path/to/traphiq/logs/api.log
tail -f /path/to/traphiq/logs/app.log

# Capture network traffic
sudo tcpdump -i eth0 port 8080 -A
sudo tcpdump -i eth0 host 192.168.1.10 -A

Best Practices

Security

Reliability

Performance

Health Monitoring Script

#!/bin/bash
# Reader health check script
READER_IP="192.168.1.10"
SERVER_URL="http://192.168.1.5:8080"

# Check reader connectivity
ping -c 1 $READER_IP > /dev/null
if [ $? -eq 0 ]; then
    echo "✅ Reader $READER_IP is reachable"
else
    echo "❌ Reader $READER_IP is unreachable"
fi

# Check server API
curl -s -I $SERVER_URL/api/status > /dev/null
if [ $? -eq 0 ]; then
    echo "✅ Server API is responsive"
else
    echo "❌ Server API is not responding"
fi

Support Resources

This guide provides comprehensive instructions for integrating RFID readers with the traphIQ system. The modular API design supports various reader types and deployment scenarios while maintaining security and reliability.