DERAS Protocol — API Documentation

Introduction

🔗

Protocol

WebSocket (JSON)

🔒

Default Port

3030 – 3033

📦

Storage

SQLite (optional)

DERAS Protocol solves the fragmentation problem in RFID deployments. Instead of writing custom code for each hardware vendor, DERAS provides a single, normalized WebSocket interface that works across Zebra, Chainway, and TUDI readers. Your application sends JSON events and receives JSON responses — regardless of the underlying hardware.

Architecture

🖥️

Application Layer

POS / WMS / WebApp — Business logic, visualization, ERP integration

WebSocket JSON (ws://<IP>:3030)

📦

DERAS Protocol Layer — on DERAS Box

WebSocket JSON streaming · Tag decoding (EPC, TID, RSSI) · Local SQLite · Multi-reader (up to 4)

TCP/IP · USB · Bluetooth

📡

Hardware Layer — RFID Readers / Antennas

Raw data capture: EPC, TID, RSSI · Device control: GPIO, antenna power · Brands: Zebra, Chainway, TUDI

ℹ️ DERAS Box supports up to 4 readers per box, each accessible on its own port (3030, 3031, 3032, 3033).

Quick Start

1

Deploy DERAS Box / Install DERAS APK

Connect your RFID reader to the DERAS Box via TCP/IP, Bluetooth, or USB. All devices must be on the same LAN.

2

Connect via WebSocket

Open a WebSocket connection to ws://<DERAS_IP>:3030. The DERAS Box typically runs on 192.168.2.100.

3

Send your first event

Send {"event": "scan-rfid-on"} and listen for streamed tag results. That's it — no SDK required.

4

Map EPC/TID to your business data

Use the Database Operations API to link scanned tags to your SKU, inventory, or asset records.

5

Access the WebApp monitor

Visit http://<DERAS_IP>:80 in your browser for the built-in monitoring interface.

WebSocket Connection

All communication with DERAS Protocol happens over a persistent WebSocket connection. Establish the connection once; all commands and streaming results flow through the same channel.

Connection URL

ws://<DERAS_IP>:3030   // Reader Instance 1
ws://<DERAS_IP>:3031   // Reader Instance 2
ws://<DERAS_IP>:3032   // Reader Instance 3
ws://<DERAS_IP>:3033   // Reader Instance 4

JavaScript Example

const ws = new WebSocket('ws://192.168.2.100:3030');

ws.onopen = () => {
  console.log('Connected to DERAS Protocol');
  ws.send(JSON.stringify({ "event": "scan-rfid-on" }));
};

ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  console.log('DERAS event:', data.event, data);
};

ws.onclose = () => console.log('Disconnected');
ws.onerror = (err) => console.error('WS Error', err);

💡 All DERAS devices should be on the same LAN (e.g., 192.168.2.x) provided by a local gateway. IP addresses shown throughout this guide are examples.

RFID Scanning Operations

EVENT scan-rfid-on Start continuous RFID scanning (EPC + TID) ▼

Instructs the reader to begin continuously scanning for UHF RFID tags. DERAS will stream tag events as they are detected.

Request Payload

{ "event": "scan-rfid-on" }

Success Response

{
  "event":      "response-scan-rfid-on",
  "statusCode": 1,
  "message":    "success"
}

Streaming Result (per tag detected)

{
  "event":      "scan-rfid-result",
  "type":       1,
  "data":       "64D99DF0FECABE275F89B617A7D44606",  // EPC
  "data_tid":   "E28011702000005672D20B5B",         // TID
  "pc":         null,
  "user":       "",
  "ant":        "1",                               // Antenna number
  "rssi":       "-50,7.0",                        // Signal strength
  "sensor":     null,
  "rfid_valid": "1"
}

Response Fields

Field	Type	Description
data	string	EPC (Electronic Product Code) of the tag
data_tid	string	TID (Tag Identifier) — unique factory-written ID
ant	string	Antenna port number that detected the tag
rssi	string	Received signal strength indicator
rfid_valid	string	"1" = valid read, "0" = invalid

EVENT scan-rfid-off Stop RFID scanning ▼

Stops the active RFID scan session. No more tag events will be streamed until scanning is re-enabled.

Request Payload

{ "event": "scan-rfid-off" }

Success Response

{
  "event":      "response-scan-rfid-off",
  "statusCode": 1,
  "message":    "success"
}

EVENT scan-rfid-light-on Light scan — returns TID only (faster) ▼

Performs a lightweight scan that reads TID only, without full EPC decoding. Useful for quick tag presence detection.

Request Payload

{ "event": "scan-rfid-light-on" }

ℹ️ Light scan is faster and consumes less resources. Use when you only need TID for tag identification.

Reader & Antenna Control

SET set-rfid-power Set reader transmission power (dBm) ▼

Adjusts the antenna transmission power of the reader. Higher values increase read range but may cause interference.

Request Payload

{
  "event": "set-rfid-power",
  "value": 28
}

Parameters

Field	Type	Required	Description
value	number	required	Power level in dBm. Typical range: 5–30 dBm

Success Response

{
  "event":      "response-set-rfid-power",
  "statusCode": 1,
  "message":    "success"
}

GET get-rfid-power Get current reader power level ▼

Request Payload

{ "event": "get-rfid-power" }

Response

{
  "event":      "response-get-rfid-power",
  "statusCode": 1,
  "value":      28
}

SET set-antenna Enable/disable specific antenna ports ▼

Request Payload

{
  "event":   "set-antenna",
  "antenna": [1, 2]   // Array of antenna port numbers to enable
}

GET get-antenna-status Get current antenna configuration ▼

Request Payload

{ "event": "get-antenna-status" }

GPIO & Peripheral Control

Control external devices such as buzzers, indicator lights, or alarm systems connected to the reader's GPIO pins.

SET set-gpio-on Activate a GPIO pin (turn device ON) ▼

Request Payload

{
  "event": "set-gpio-on",
  "pin":   1   // GPIO pin number
}

Use Cases

🔔 Alarm buzzer 💡 Indicator light 🚨 Gate trigger 📟 Notification relay

SET set-gpio-off Deactivate a GPIO pin (turn device OFF) ▼

Request Payload

{
  "event": "set-gpio-off",
  "pin":   1
}

Database Operations

CRUD-style events for managing tag data in DERAS' local SQLite database. No custom SQL or external SDK required — everything goes through the same WebSocket channel.

GET db-storage-get-rfid-list Retrieve stored RFID tag records ▼

Request Payload

{ "event": "db-storage-get-rfid-list" }

Response

{
  "event":      "response-db-storage-get-rfid-list",
  "statusCode": 1,
  "data": [
    {
      "tid":         "E28011702000014B772D70B5B",
      "status":      1,
      "category":    0,
      "description": "BOX A",
      "flag_alarm":  0
    }
  ]
}

POST db-storage-insert-rfid-list Insert RFID tag records (single or bulk) ▼

Inserts one or multiple RFID tag records into local storage. Use the bulk variant for batch operations.

Request Payload (bulk)

{
  "event": "db-storage-insert-rfid-list-bulk",
  "value": [
    {
      "tid":         "E28011702000014B772D70B5B",
      "status":      1,
      "category":    0,
      "description": "BOX A",
      "flag_alarm":  0
    },
    {
      "tid":         "E28011702000012EEE06C0B4BFD9001220D0A",
      "status":      1,
      "category":    0,
      "description": "BOX B",
      "flag_alarm":  1
    }
  ]
}

Record Fields

Field	Type	Description
tid	string	Tag TID — unique hardware identifier
status	number	1 = active, 0 = inactive
category	number	Custom category code for your business logic
description	string	Human-readable label (e.g., SKU, item name)
flag_alarm	number	1 = triggers alarm on detection, 0 = normal

Success Response

{
  "event":      "response-db-storage-insert-rfid-list-bulk",
  "statusCode": 1,
  "message":    "success"
}

POST db-storage-update-rfid-list Update existing RFID tag record ▼

Request Payload

{
  "event": "db-storage-update-rfid-list",
  "value": {
    "tid":         "E28011702000014B772D70B5B",
    "description": "BOX A - Updated",
    "flag_alarm":  0
  }
}

DEL db-storage-remove-rfid-list Remove an RFID tag record ▼

Request Payload

{
  "event": "db-storage-remove-rfid-list",
  "tid":   "E28011702000014B772D70B5B"
}

Services & Reporting

Built-in operational services that activate pre-built DERAS modules — no additional middleware required.

EVENT service-api-start-track Start LACAK tracking service ▼

Activates the LACAK track-and-trace module. DERAS begins recording tag movement history and zone transitions.

Request Payload

{ "event": "service-api-start-track" }

💡 Combine with the LACAK optional module for full track-and-trace functionality across multiple zones.

EVENT service-api-start-loss-prevention Activate AMAN anti-theft / loss prevention ▼

Enables the AMAN loss prevention service. DERAS will monitor scanned tags against the database and trigger GPIO alarms for items marked with flag_alarm: 1.

Request Payload

{ "event": "service-api-start-loss-prevention" }

⚠️ Ensure items with flag_alarm: 1 are registered in the database before activating this service.

GET report-logs Retrieve stored scan logs from DERAS Box ▼

Fetches historical scan and event logs stored locally on the DERAS Box's SQLite database.

Request Payload

{ "event": "report-logs" }

Response

{
  "event":      "response-report-logs",
  "statusCode": 1,
  "data": [ /* array of log entries */ ]
}

Common Network Topology

📦 DERAS Box A — 192.168.2.100

Runs DERAS Protocol (port 3030)
Hosts Master Database & WebApp
Connects reader via TCP/IP or USB
WebApp: http://192.168.2.100:80

📦 DERAS Box B — 192.168.2.102

Runs DERAS Protocol (port 3030)
Connects to Master DB via WebSocket
Accesses WebApp at 192.168.2.100

📱 Android Handheld — 192.168.2.101

Runs DERAS APK (localhost:3030)
Connects to reader via Bluetooth
Syncs to Master DB via WebSocket

📡 RFID Readers — 192.168.99.x

Fixed UHF readers with 2–4 antennas
Connect via TCP/IP to DERAS Box
Brands: Zebra, Chainway, TUDI

ℹ️ One-to-Many setup: a single DERAS Box can connect up to 4 readers simultaneously on ports 3030–3033.

Optional Ready Modules

🛡️

AMAN

Anti-theft & loss prevention logic. Triggers GPIO alarms for flagged items.

📍

LACAK

Track & trace module. Records movement history and zone transitions.

📋

INVENTARIS

Inventory management logic. Stock counting, receiving, and auditing workflows.

DERAS Protocol API

Introduction

Architecture

Quick Start

WebSocket Connection

RFID Scanning Operations

Reader & Antenna Control

GPIO & Peripheral Control

Database Operations

Services & Reporting

Common Network Topology

Optional Ready Modules