SkySpark 3-Phase Smart Controller - API Reference & Simulator

System Architecture & Topology

The SkySpark Smart Controller operates using a secure hybrid architecture developed by SkySpark Technologies Private Limited. Configuration changes, credentials routing, and device catalogs are handled over standard HTTPS REST API endpoints using user-specific JWT. Real-time command propagation, persistent device monitoring, safety status feedback, and protection event triggers leverage a dedicated Secure WebSocket (WSS) JSON Protocol.

User-to-Cloud

RESTful HTTPS & TLS

Provides robust credential handling using Email ID authentication, user organization role authorization, audit logs, and status readouts.

Cloud-to-Controller

Secure WebSocket (WSS)

Ultra-low latency, persistent connection from ESP32 with fallback telemetry triggers to assure instant protection updates and controls.

Edge-to-Actuator

GPIO / Relay & Core Safety

Hard-wired dry-run limits, sequence checking, and overload relays that override any remote server control logic instantly.

Interactive Topology Diagram

Click modules to inspect system integrations

Scroll horizontally to view complete path

Topology Explorer

Click on any module above to inspect protocol bindings, security architecture layers, and physical IO links.

Critical Safety Rule & Command Flow

Absolute Protection Mandate for SkySpark Industrial Control Controllers

The SkySpark centralized servers and mobile applications **must never directly force** the high-voltage motor contactor to energize. All external triggers received via WebSocket or REST interfaces are strictly treated as requests. The ESP32 controller acts as the absolute local safety authority. On receiving a command request, the edge node executes these physical checks prior to initiating startup sequences:

1. All 3 phases present (R, Y, B line sensors check)

2. Phase sequence accurate (Must be RYB, not reverse RBY)

3. Supply voltage stays within designated safe thresholds

4. Overload sensors report stable operating currents

5. Dry Run check passes (Sensors confirm water flow present)

6. Float controls / storage tank sensor inputs are permissive

7. Manual hardware emergency stop switches are disengaged

Result: Only if all physical checks clear, contactor energizes. Else: command rejected.

1. User HTTPS REST API Reference

Authenticate organizational accounts, pull register listings, and post request actions.

POST /api/v1/auth/login

Generate Session Token

Endpoint Details

Authenticate secure sessions using enterprise **Email ID** credentials. Returns JSON Web Tokens (JWT) necessary to query resource clusters and authorize commands.

Headers

Content-Type: application/json

{
  "email": "engineer@skyspark.tech",
  "password": "strong_password"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "JWT_REFRESH_TOKEN_VALUE",
  "expires_in": 3600
}

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid Email ID or password credentials"
}

GET /api/v1/devices

List Registered Devices

Endpoint Details

Pulls the dynamic list of physical controller nodes allocated under the verified user organization account.

Required Headers

Authorization: Bearer <JWT_ACCESS_TOKEN>

[
  {
    "device_id": "DEVID-MTR-000001",
    "firmware_version": "1.0.0",
    "hardware_version": "REV-A",
    "imei": "867142055620134",
    "sim_iccid": "8991440302118492042",
    "status": "ONLINE"
  }
]

{
  "status": "error",
  "code": "EXPIRED_SESSION_TOKEN",
  "message": "Authorization token is missing or expired"
}

POST /api/v1/devices/{id}/command

Dispatch Request Instruction

Endpoint Details

Pushes a temporary activation instruction to the targeted SkySpark edge controller. Supported instructions: "MOTOR_ON" or "MOTOR_OFF".

Required Headers

Authorization: Bearer <JWT_ACCESS_TOKEN>

Content-Type: application/json

{
  "cmd": "MOTOR_ON"
}

{
  "command_id": "CMD-10001",
  "status": "QUEUED_FOR_DEVICE",
  "timestamp": 1714890100
}

{
  "status": "error",
  "code": "INVALID_CMD_VALUE",
  "message": "Supplied instruction must equal MOTOR_ON or MOTOR_OFF"
}

2. Device-Side WebSocket Protocol Reference

Details on active persistent frames between SIMCOM A7670C / ESP32 and SkySpark Cloud Routers.

WSS wss://api.skyspark.tech/ws/device

Auth Handshake Connection

Handshake Specification

As soon as cellular data connects, the controller opens a secure websocket connection and sends an `auth` message. If verification fails, the connection closes with WSS error code 4003.

Edge Rule: Device tokens are written directly to encrypted non-volatile partition (NVS) blocks inside SkySpark's production labs.

{
  "type": "auth",
  "device_id": "DEVID-MTR-000001",
  "token": "unique_device_secret_token",
  "fw": "1.0.0",
  "imei": "867xxxxxxxxxxxx"
}

{
  "type": "auth_ack",
  "status": "success",
  "server_time": "2026-07-05T12:53:00+05:30"
}

WSS PULSE heartbeat

Uplink Vital Diagnostics

Heartbeat Policy

The edge node sends telemetry status parameters every **20-30 seconds**. If the SkySpark router detects no updates for **60-90 seconds**, the controller falls to **OFFLINE** state inside the active database pool and locks any app inputs immediately.

Uplink Structure Variables:

network: Tracks signal strength, operator, and 4G connection.
power: Tracks individual phases, voltage, and phase sequence orientation.
protection: Local registers for dry run, overload, phase, and stop conditions.

{
  "type": "heartbeat",
  "device_id": "DEVID-MTR-000001",
  "timestamp": 1714890000,
  "motor_state": "OFF",
  "network": {
    "rssi": -72,
    "operator": "Airtel",
    "connection": "4G"
  },
  "power": {
    "r_phase": true,
    "y_phase": true,
    "b_phase": true,
    "phase_sequence": "RYB",
    "voltage_status": "NORMAL"
  },
  "protection": {
    "dry_run": false,
    "overload": false,
    "phase_failure": false,
    "phase_reverse": false,
    "emergency_stop": false
  }
}

{
  "type": "heartbeat_ack",
  "server_time": 1714890002
}

WSS COMMANDS command / command_ack

Relay Execution Frames

Command Handling Log

When a down-link command from the SkySpark Cloud arrives at the edge node, local evaluation runs. If the environment is completely safe, the starter coil engages and responds with an ACCEPTED status ACK. Otherwise, the state transition is blocked, returning a REJECTED code highlighting safety issues.

Replay Safety: Unique command IDs must be verified against local histories to prevent frame hijacking.

{
  "type": "command",
  "command_id": "CMD-10001",
  "device_id": "DEVID-MTR-000001",
  "cmd": "MOTOR_ON",
  "source": "APP",
  "user_id": "USER-001",
  "timestamp": 1714890100
}

{
  "type": "command_ack",
  "command_id": "CMD-10001",
  "device_id": "DEVID-MTR-000001",
  "cmd": "MOTOR_ON",
  "status": "ACCEPTED",
  "message": "Motor started successfully",
  "motor_state": "ON"
}

{
  "type": "command_ack",
  "command_id": "CMD-10001",
  "cmd": "MOTOR_ON",
  "status": "REJECTED",
  "reason": "PHASE_FAILURE",
  "message": "Motor cannot start because one phase is missing"
}

WSS EVENT event

Instant Threat Push

Asynchronous Protection Events

If safety circuits detect physical risks while running, the ESP32 instantly disengages the control relay and broadcasts an prioritized alert frame over the WSS channel.

Active Fault Triggers:

DRY_RUN_DETECTED: Undercurrent water depletion hazard.
PHASE_FAILURE: Instant alert when a line connection drops.
PHASE_REVERSE: Protection block for counter-rotation damage.
OVERLOAD: Thermal warning trip on excessive motor current draw.

{
  "type": "event",
  "event_id": "EVT-50001",
  "device_id": "DEVID-MTR-000001",
  "event": "DRY_RUN_DETECTED",
  "severity": "CRITICAL",
  "motor_state": "OFF",
  "action_taken": "MOTOR_STOPPED",
  "current": { "r": 1.2, "y": 1.1, "b": 1.3 },
  "message": "Dry run detected. Motor stopped automatically."
}

{
  "type": "event",
  "event_id": "EVT-50002",
  "device_id": "DEVID-MTR-000001",
  "event": "PHASE_FAILURE",
  "severity": "CRITICAL",
  "phase": "Y",
  "action_taken": "MOTOR_STOPPED",
  "message": "Line phase 'Y' disconnected. Motor stopped to prevent burn."
}

{
  "type": "event",
  "event_id": "EVT-50003",
  "device_id": "DEVID-MTR-000001",
  "event": "PHASE_REVERSE",
  "severity": "CRITICAL",
  "detected_sequence": "RBY",
  "required_sequence": "RYB",
  "action_taken": "START_BLOCKED",
  "message": "Reversed sequence RBY detected. Contactor lock engaged."
}

{
  "type": "event",
  "event_id": "EVT-50004",
  "device_id": "DEVID-MTR-000001",
  "event": "OVERLOAD",
  "severity": "CRITICAL",
  "current": { "r": 18.5, "y": 19.1, "b": 18.9 },
  "action_taken": "MOTOR_STOPPED",
  "message": "Motor current exceeded safety threshold. Stopped."
}

WSS TELEMETRY status

Dynamic Running Telemetry

Dispatched systematically every 60 seconds while running to capture runtime parameters, aggregate organizational power draw logs, and record active line currents.

Uplink interval defaults to 60s while running, falling back to heartbeats on standby.

{
  "type": "status",
  "device_id": "DEVID-MTR-000001",
  "motor": {
    "state": "ON",
    "runtime_minutes": 45,
    "last_start_time": "2026-07-05T12:00:00+05:30"
  },
  "phase": {
    "r": true,
    "y": true,
    "b": true,
    "sequence": "RYB"
  },
  "current": {
    "r": 8.2,
    "y": 8.4,
    "b": 8.1
  },
  "protection": {
    "dry_run": false,
    "overload": false,
    "phase_failure": false,
    "phase_reverse": false
  }
}

3. Local Safety State Machine

Autonomous edge logic processing loops inside SkySpark controllers.

The edge system strictly runs local state check logic to avoid critical issues on cellular network loss. Click on states below to view safe transitions:

State 01 STABLE

IDLE

Standby state. Relays fully open. Safe electrical conditions present.

State 02 TRANSIENT

PRE_CHECK

Pre-flight checks. Verifies safety constraints before activating mechanical contactors.

State 03 TRANSIENT

STARTING

Coil energized. Evaluating line inrush load spikes.

State 04 STABLE

RUNNING

Normal running. Relays closed. Telemetry dispatching.

State 05 TRANSIENT

STOPPING

Opening contactors. Bleeding high inductive line loads.

State 06 LOCKED

FAULT_LOCKOUT

Motor fully locked out. Controls rejected until reset.

Selected Machine State:

Click a State Card to Inspect

Select any of the operating states above to view detail parameters, transition rules, and safety gatekeepers.

4. Industrial Production Checklist

Mandatory precautions compiled by SkySpark Technologies Private Limited.

Edge Controller Hardening (ESP32)

Unique Keys: Program unique cryptographic authentication keys into hardware NVS partitions. Do not reuse credentials.
Watchdog Timers (WDT): Enable hardware watchdogs to automatically trip relay safety outputs if the core firmware stalls.
Secure Boot & Signed OTA: Enforce cryptographically signed updates to prevent sim/cell modules from loading non-corporate code.
Zero State Reboot: Design drive relays to strictly initialize to isolated, safe **OFF** configurations during reboots.

Cloud Gateway & Transport Hardening

Secure Handshakes Only: Disallow unencrypted standard HTTP/WS connections. Enforce TLS 1.3/WSS as a hard gate.
Immutable Commands Log: Document every remote control request containing User ID, Device ID, Timestamp, and Command Type.
Replay Defense: Enforce sequential command timestamps combined with dynamic nonces to prevent payload hijacking.
Role-Based Access (RBAC): Gate commands based on verified roles (Operator, Engineer, Administrator).

5. Live Protocol & Safety Simulator

Authenticate users using Email IDs, toggle safety scenarios, and observe local control decisions live.

Step 1: REST Session Authentication

Step 2: Local Sensor Controls

Phase Sequence

Phase Failure

Dry Run Activated

Thermal Overload

Hardware Emergency Stop

Step 3: App Control Triggers

EDGE LOGICAL TELEMETRY

State: IDLE

Contactor: OFF

Uplink/Downlink Log Channel

// System initialized. Generate a token to authenticate connection sequences...

Active Payload Inspector

{}