Developer Docs

Quick Start — ESP32 Arduino

The sketch below connects to a SensorCast stream as a subscriber. It uses the Links2004/arduinoWebSockets library. Install it from the Arduino Library Manager before uploading.

#include <Arduino.h>
#include <WiFi.h>
#include <SocketIOclient.h>   // Links2004/arduinoWebSockets

const char* SSID       = "your-wifi";
const char* PASS       = "your-password";
const char* SC_HOST    = "api.sensorcast.app";
const uint16_t SC_PORT = 443;
const char* USERNAME   = "alice";   // SensorCast username of the publisher

SocketIOclient socketIO;

unsigned long lastHeartbeat = 0;

void onEvent(socketIOmessageType_t type, uint8_t* payload, size_t length) {
  if (type == sIOtype_EVENT) {
    String msg = String((char*)payload, length);

    // Parse event name from Socket.IO payload ["name","data"]
    if (msg.startsWith("["connected"")) {
      Serial.println("[SC] Connected as subscriber");

    } else if (msg.startsWith("["frame"")) {
      // Extract the frame string between the outer quotes
      int start = msg.indexOf(","") + 2;
      int end   = msg.lastIndexOf(""]");
      if (start > 1 && end > start) {
        String frame = msg.substring(start, end);
        Serial.print("[FRAME] ");
        Serial.println(frame);
      }

    } else if (msg.startsWith("["publisher_disconnected"")) {
      Serial.println("[SC] Publisher left — waiting for reconnect");
    }
  }
}

void setup() {
  Serial.begin(115200);
  WiFi.begin(SSID, PASS);
  while (WiFi.status() != WL_CONNECTED) delay(500);
  Serial.println("WiFi connected");

  // Connect to namespace /stream/<username>
  String ns = "/stream/";
  ns += USERNAME;
  socketIO.beginSSL(SC_HOST, SC_PORT, "/socket.io/?EIO=4", ns.c_str());
  socketIO.onEvent(onEvent);

  // Announce subscriber role immediately after connection
  socketIO.sendEVENT("["role","subscriber"]");
}

void loop() {
  socketIO.loop();

  // Send heartbeat every 20 seconds to stay alive
  if (millis() - lastHeartbeat > 20000) {
    socketIO.sendEVENT("["heartbeat",{}]");
    lastHeartbeat = millis();
  }
}

Python / Raspberry Pi

Install the async-free client: pip install "python-socketio[client]"

"""
SensorCast subscriber — Python / Raspberry Pi
pip install "python-socketio[client]" requests
"""
import time
import socketio

SENSORCAST_HOST = "https://api.sensorcast.app"
USERNAME        = "alice"      # SensorCast username of the publisher

sio = socketio.Client()

@sio.event
def connect():
    print("[SC] Socket connected, announcing subscriber role…")
    sio.emit("role", "subscriber")

@sio.on("connected")
def on_connected(data):
    print(f"[SC] Server accepted role: {data}")

@sio.on("frame")
def on_frame(data):
    print(f"[FRAME] {data}")

@sio.on("publisher_disconnected")
def on_pub_gone():
    print("[SC] Publisher disconnected — waiting…")

@sio.event
def disconnect():
    print("[SC] Disconnected from server")

def heartbeat_loop():
    """Keep-alive: send heartbeat every 20 s or get kicked after 30 s."""
    while True:
        time.sleep(20)
        if sio.connected:
            sio.emit("heartbeat")

import threading
threading.Thread(target=heartbeat_loop, daemon=True).start()

namespace = f"/stream/{USERNAME}"
sio.connect(SENSORCAST_HOST, namespaces=[namespace], socketio_path="/socket.io/")
sio.wait()

Private Streams

When a publisher marks their stream as private, subscribers must pass the stream key in the Socket.IO auth object at connection time. You can find the stream key in the SensorCast dashboard under Stream Settings.

# For private streams, pass streamKey in the auth dict:
sio.connect(
    SENSORCAST_HOST,
    namespaces=[namespace],
    socketio_path="/socket.io/",
    auth={"streamKey": "YOUR_STREAM_KEY"},
)

Frame Formats

The Android app lets the publisher choose one of four formats. Your subscriber code should handle whichever format the publisher selects — or agree on one in advance.

Accelerometer;x,y,z:0.1230,-0.4560,9.8100

1707494400123;Accelerometer;x,y,z:0.1230,-0.4560,9.8100

1707494400123,Accelerometer,x,y,z,0.1230,-0.4560,9.8100

{"sensor":"Accelerometer","type":1,"timestamp":1707494400123,"accuracy":3,"values":{"x":0.12,"y":-0.45,"z":9.81}}

Available Sensors

These sensors are available on most Android devices. Exact field names depend on the mapping configured in the Android app; defaults are shown below.

Orientation Angles

# Python — convert quaternion [x, y, z, w] to Euler angles
import math

def quat_to_euler(x, y, z, w):
    pitch = math.atan2(2*(w*x + y*z), 1 - 2*(x*x + y*y))
    roll  = math.asin(2*(w*y - z*x))
    yaw   = math.atan2(2*(w*z + x*y), 1 - 2*(y*y + z*z))
    return math.degrees(pitch), math.degrees(roll), math.degrees(yaw)

Connection Troubleshooting