Step 4 of 6

Connect via WebSocket

Program your device to open a WebSocket connection, authenticate, and start sending data. Copy-paste examples for Node.js, Python, and ESP32.

Connection Details

WebSocket URL

ws://[SERVER_IP]:3000/ws

Protocol

JSON (generic) or XML (biometric)

Replace [SERVER_IP] with your actual server address. Get your device_id and token from the Devices page after adding your device.

Connection Flow

How your device communicates with the server

Connect

Open WebSocket

Send device_id + token

Authenticated

Receive confirmation

Communicate

Send/receive messages

Example Code

Copy and adapt for your device

JavaScript (Node.js)

const WebSocket = require("ws")

const WS_URL = "ws://YOUR_SERVER_IP:3000/ws"
const DEVICE_ID = "your-device-uuid"  // From dashboard
const TOKEN = "tok_your_device_token"  // From dashboard

let ws = null
let reconnectTimer = null

function connect() {
  console.log("Connecting to", WS_URL)
  ws = new WebSocket(WS_URL)

  ws.on("open", () => {
    console.log("Connected! Registering...")
    ws.send(JSON.stringify({
      type: "register",
      device_id: DEVICE_ID,
      token: TOKEN
    }))
  })

  ws.on("message", (data) => {
    const msg = JSON.parse(data.toString())
    console.log("Received:", msg)

    if (msg.type === "command") {
      handleCommand(msg.command, msg.payload)
    }
  })

  ws.on("close", () => {
    console.log("Disconnected. Reconnecting in 5s...")
    reconnectTimer = setTimeout(connect, 5000)
  })

  ws.on("error", (err) => {
    console.error("WebSocket error:", err.message)
  })
}

function handleCommand(command, payload) {
  console.log("Executing command:", command, payload)
  // Implement your device-specific logic here
}

function sendTelemetry(data) {
  if (ws?.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({
      type: "telemetry",
      payload: data
    }))
  }
}

// Start connection
connect()

// Send telemetry every 30 seconds
setInterval(() => {
  sendTelemetry({
    temperature: 22.5 + Math.random() * 2,
    humidity: 45 + Math.random() * 10
  })
}, 30000)

Required Changes

• Replace YOUR_SERVER_IP with actual server address
• Replace DEVICE_ID with UUID from dashboard
• Replace TOKEN with your device token

Testing

• Run the code on your device
• Check the dashboard for "Online" status
• Send a test command from the dashboard

Message Types Reference

Direction	Type	Purpose
Device → Server	`register`	Authenticate with device_id + token
Device → Server	`telemetry`	Send sensor data / readings
Device → Server	`event`	Report device events
Device → Server	`ping`	Heartbeat (server replies with pong)
Server → Device	`command`	Execute action on device
Server → Device	`registered`	Confirmation of successful registration

Verify Connection

Device appears as 'Online' in the dashboard
Device name shows in the Devices list
Event stream shows 'device_connected' event
Telemetry data appears on device detail page

HTTP/HTTPS Protocol (Legacy Devices)

If your device doesn't support WebSocket or requires HTTP POST

Devices that can't establish persistent WebSocket connections can use the HTTP/HTTPS protocol instead. All communication is via POST requests with JSON payloads and JSON responses.

1. Register on Startup

json

POST /api/device-http
Content-Type: application/json

{
  "cmd": "reg",
  "sn": "YOUR_DEVICE_SN",
  "cpusn": "CPU_SERIAL",
  "devinfo": {
    "modelname": "device-model",
    "usersize": 1000,
    "firmware": "v1.0.0",
    "mac": "00:11:22:33:44:55"
  }
}

Response:
{
  "ret": "reg",
  "result": true,
  "cloudtime": "2026-06-12T10:00:00Z"
}

2. Send Attendance Logs

json

POST /api/device-http
Content-Type: application/json

{
  "cmd": "sendlog",
  "sn": "YOUR_DEVICE_SN",
  "count": 1,
  "logindex": 0,
  "record": [{
    "enrollid": 1,
    "time": "2026-06-12T09:15:30",
    "mode": 1,
    "inout": 0,
    "event": 0,
    "temp": 36.5
  }]
}

Response:
{
  "ret": "sendlog",
  "result": true,
  "cloudtime": "2026-06-12T09:16:00Z"
}

3. Heartbeat (Every 60s)

json

POST /api/device-http
Content-Type: application/json

{
  "cmd": "checklive",
  "sn": "YOUR_DEVICE_SN",
  "time": "2026-06-12T09:20:00"
}

Response:
{
  "ret": "checklive",
  "result": true,
  "cloudtime": "2026-06-12T09:20:05Z"
}

Python Example

python

import requests
import json
from datetime import datetime

URL = "https://your-host/api/device-http"
SN = "YOUR_DEVICE_SN"

# 1. Register device
def register():
    payload = {
        "cmd": "reg",
        "sn": SN,
        "cpusn": "12345",
        "devinfo": {"modelname": "device", "firmware": "v1.0"}
    }
    r = requests.post(URL, json=payload)
    print("Registered:", r.json())

# 2. Send attendance log
def send_log():
    payload = {
        "cmd": "sendlog",
        "sn": SN,
        "count": 1,
        "record": [{
            "enrollid": 123,
            "time": datetime.now().isoformat(),
            "mode": 1,
            "inout": 0
        }]
    }
    r = requests.post(URL, json=payload)
    print("Sent log:", r.json())

# 3. Send heartbeat
def heartbeat():
    payload = {
        "cmd": "checklive",
        "sn": SN,
        "time": datetime.now().isoformat()
    }
    r = requests.post(URL, json=payload)
    print("Heartbeat:", r.json()['result'])

if __name__ == "__main__":
    register()
    send_log()
    heartbeat()

Send a checklive heartbeat every 60 seconds to keep the device marked as online. Without it, the device will be marked offline after 5 minutes of inactivity.

Biometric Setup Send Commands