Sandstar Web Socket

Real-Time Browser-to-Device Communication

v1.0.0 Published View Source Documentation

Connect your browser directly to building controllers -- no plugins, no Java applets, no middleware headaches.

Sandstar Web Socket brings real-time, bidirectional communication between web applications and Sedona-based building automation controllers. Open a browser tab, connect to a device, and start reading sensor values, writing setpoints, and monitoring changes -- all in real time.

Built as a native SkySpark extension, it drops right into your existing infrastructure. No extra servers to maintain, no separate processes to babysit. Just install the pod and your web apps can talk to Sedona devices instantly.

Why It Exists

Traditionally, connecting a web browser to a Sedona controller required a separate Kotlin/Java microservice acting as a translator. That meant managing another process, dealing with Java FFI quirks, and debugging across two runtime environments. Sandstar Web Socket eliminates all of that with a single, native Fantom implementation that runs inside SkySpark itself.

Who It's For

  • Building automation integrators who need web-based tools for Sedona devices
  • SkySpark developers building custom web interfaces for device interaction
  • System administrators who want fewer moving parts in their automation stack

Connection Dashboard

Every device, one glance

See every connected controller, active browser session, and message flowing through the system -- live. The status endpoint gives you instant diagnostics without touching a log file.

Connection counts, per-device session states, DASP socket health, and watch manager statistics are all available at /live/soxstatus. Integrate it into your monitoring stack or check it from a browser.

SOX WebSocket Server
ws://localhost:7070
3
Active Devices
5
Browser Clients
142
Msgs / sec
192.168.1.100:1876
ok 1 session
192.168.1.101:1876
ok 1 session
10.0.0.50:1876
down reconnecting
DASP Socket: active Uptime: 4d 12h 37m
Browser Tab 1
Vue Editor
Browser Tab 2
Dashboard
WebSocket :7070
SoxWebSocketMod
Router
JSON msgs
Pool
1 per device
Watches
30s timeout
DASP / UDP
Sedona Controller
.100:1876
Sedona Controller
.101:1876
TCP/WebSocket
UDP/DASP

Real-Time Data Flow

Browser to device in one hop

Your browser opens a WebSocket to port 7070. The server translates JSON messages into SOX protocol commands and sends them over DASP/UDP to the Sedona controller. Responses flow back the same path -- no polling, no delays.

Multiple browser tabs share the same device session automatically. The message router handles 17 SOX command types -- reads, writes, subscriptions, file transfers, component management, and more -- all through a single WebSocket connection.

r: read w: write sub: subscribe v: version a: add d: delete fileGet filePut

Session Management

Smart pooling, zero connection errors

Sedona controllers support a maximum of 2 concurrent connections. Instead of fighting that limit, the session pool shares a single connection per device across all browser clients. Open five tabs to the same controller -- they all share one session.

If a connection drops, auto-recovery kicks in with exponential backoff. Idle sessions are cleaned up after 5 minutes, and a 30-second linger timeout prevents connection thrashing from rapid connect/disconnect cycles. Your users never see connection errors.

1
Session per device
5m
Idle timeout
30s
Linger window
Session Pool SoxSessionPool
192.168.1.100:1876
connected
State ok
Shared by
Tab A Tab B Tab C
Last activity 2s ago
DASP window receiveMax: 8
192.168.1.101:1876
connected
State ok
Shared by
Tab D
Last activity 14s ago
10.0.0.50:1876
reconnecting
State down
Retry attempt 3, backoff 10s
Last seen 47s ago
Live Subscriptions 192.168.1.100
streaming
Watch tab-8f3a TTL: 28s / 30s
ZoneTemp
comp #12 · slot 3 · runtime
72.4°F
+0.2 from last
ZoneSetpoint
comp #12 · slot 5 · config
72.0°F
unchanged
DamperPos
comp #18 · slot 2 · runtime
67%
-3 from last
FanEnable
comp #20 · slot 0 · runtime
true
bool
OccSchedule
comp #25 · slot 1 · runtime
1occupied
int
5 components subscribed Batched events · 10s cleanup

Live Value Monitoring

Watch values change in real time

Subscribe to any component on a Sedona controller and see its values update live. The watch system groups subscriptions by browser tab, so each page gets exactly the data it needs -- and cleans up automatically when you close the tab.

Events are batched for efficiency and delivered through the same WebSocket connection. Background cleanup runs every 10 seconds to catch stale watches from disconnected clients. If a tab stops pinging for 30 seconds, its subscriptions are automatically unsubscribed from the device.

Multiple watches can overlap on the same component -- the system tracks reference counts and only unsubscribes from the device when the last watcher leaves. No duplicate subscriptions, no orphaned watches.

File Transfer

Upload firmware, download configs

Transfer application files (SAX, SAB) to and from Sedona controllers with chunked, resumable transfers. The three-phase protocol -- open, chunk, close -- gives you progress tracking and error recovery built in.

Per-device file locks prevent concurrent transfers from corrupting data. Each transfer gets a unique ID, and abandoned transfers are automatically cleaned up after 5 minutes of inactivity. Upload a new application, download a backup, or rename files on the device -- all through the same API.

512-byte chunks
Per-device locking
5m auto-cleanup
Upload + download
File Transfers 192.168.1.100
app.sab
completed
24,576 bytes · 48 chunks × 512B upload · 100%
kits.scode
transferring
131,072 bytes · chunk 164 / 256 download · 64%
manifest.xml
open
waiting for first chunk... upload · 0%
Device file lock: active
3 transfers · ID: #7

Interested in this project?

Explore the source code, contribute, or get in touch.

View on GitHub Get in Touch