CubeSTEM Digital Twin · V3.5B

Hardware-Ready Interface Specification

CubeSTEM is software-first today. This specification defines the stable command and telemetry protocol that will later connect real CubeSat kits, rover/robot kits, and local adapter bridges — without requiring any hardware right now.

Mock / browser-local onlyNo real hardware runtimeWebSocket-first future transportProtocol spec phase

Scope boundary: This page is a protocol specification and mock preview. It does not connect to real hardware, open network sockets, or control any physical device. Real hardware integration is a future supervised lab phase.

Protocol Overview

The interface protocol defines how assets communicate via telemetry and commands. Transport channels are layered — mock is available now in-browser; others require a supervised local bridge adapter.

Supported Assets

CubeSatNanosatellite kit — telemetry/command over pass window
Rover / Robot KitGround rover or tabletop robot — drive, scan, safe-stop preview
Ground StationBase station for uplink/downlink windows
Mission ControlCentral hub receiving all asset telemetry
Sensor NodeEnvironmental or payload sensor asset
ADCS Demo KitAttitude control teaching kit — angle/slew preview

Message Types

TelemetryHardware → BrowserAsset health, position, attitude, faults, subsystem status
CommandBrowser → HardwareInstruction issued to an asset (with safety classification)
AcknowledgementHardware → BrowserAccept or reject a command with reason
Fault EventHardware → BrowserAnomaly notification with severity and fault code
HeartbeatHardware → BrowserPeriodic alive signal from asset adapter
Evidence EventBrowser → RecordStudent captures a telemetry clue into evidence log
Mission StateBrowser SyncSnapshot of active mission assets, phases, and commands

Transport Channels

Available Now
Mock / Browser Preview
Fully available now — browser-local simulation, no hardware required.
Spec Only
WebSocket Bridge
Protocol defined. Requires a local Python/Node bridge server (future phase).
Spec Only
Serial / USB Bridge
Protocol defined. Requires a supervised local Python serial adapter (future phase).
Future Phase
MQTT Broker
Message schema compatible. Requires local MQTT broker + adapter (future phase).
Future Phase
ROS / ROS2 Bridge
Advanced robotics labs only. Requires ROS environment + bridge adapter (future phase).

Message Schema

Full field definitions for telemetry and command messages. These schemas are the contract between the browser UI and any future hardware bridge adapter.

Telemetry Message Fields

Field	Type	Req	Description	Unit
messageType	string	✓	Always 'inbound_telemetry'
messageId	string	✓	Unique message ID (UUID or counter)
assetId	string	✓	Unique asset identifier
assetType	AssetType	✓	Category of hardware asset
missionId	string	✓	Mission context identifier
timestamp	ISO8601 string	✓	Message creation time (UTC)
status	MessageStatus	✓	Processing state of this message
transport	TransportType	✓	Transport channel used
batteryPct	number		Battery state of charge (0–100)	%
position	{ x, y, z? }		Asset position in mission coordinate frame	grid units
headingDeg	number		Heading direction	degrees (0–360)
attitude	{ rollDeg, pitchDeg, yawDeg }		Attitude angles	degrees
temperatureC	number		Onboard temperature	°C
voltageV	number		Bus voltage	V
currentA	number		Bus current draw	A
wheelCurrentA	number		Wheel motor current (rover)	A
linkStatus	string		Communication link state
signalDelayMs	number		One-way signal propagation delay	ms
subsystemStatus	SubsystemStatus		Per-subsystem health indicators
faultMode	string		Active fault code or 'none'
evidenceTags	string[]		Tags for student evidence capture

Command Message Fields

Field	Type	Req	Description
messageType	string	✓	Always 'outbound_command'
commandId	string	✓	Unique command identifier
targetAssetId	string	✓	ID of target asset
commandType	string	✓	Command identifier string
payload	Record<string, unknown>	✓	Command parameters
issuedAt	ISO8601 string	✓	Command issue time (UTC)
safetyClass	CommandSafetyClass	✓	Safety classification for this command
requiresSupervision	boolean	✓	Whether a supervisor must approve execution
expectedEffect	string	✓	Human-readable expected outcome
timeoutMs	number	✓	Command execution timeout
transport	TransportType	✓	Transport channel to use
status	MessageStatus	✓	Current status of this command

Example Payloads

Rover Telemetry

{
  "messageType": "inbound_telemetry",
  "messageId": "tlm-ex-001",
  "assetId": "rover-01",
  "assetType": "rover",
  "missionId": "lunar_rover_rescue",
  "timestamp": "2026-05-12T00:00:00.000Z",
  "status": "received",
  "transport": "mock",
  "batteryPct": 84,
  "position": {
    "x": 4,
    "y": 3
  },
  "headingDeg": 90,
  "wheelCurrentA": 0.8,
  "temperatureC": 34,
  "voltageV": 3.85,
  "currentA": 0.45,
  "linkStatus": "relay_active",
  "signalDelayMs": 1200,
  "subsystemStatus": {
    "power": "nominal",
    "comms": "nominal",
    "thermal": "nominal",
    "adcs": "nominal",
    "payload": "nominal"
  },
  "faultMode": "none",
  "evidenceTags": []
}

CubeSat Health Telemetry

{
  "messageType": "inbound_telemetry",
  "messageId": "tlm-ex-002",
  "assetId": "cubesat-01",
  "assetType": "cubesat",
  "missionId": "cubesat_rover_relay",
  "timestamp": "2026-05-12T00:01:00.000Z",
  "status": "received",
  "transport": "mock",
  "batteryPct": 72,
  "temperatureC": 22,
  "voltageV": 8.2,
  "currentA": 0.31,
  "linkStatus": "pass_window_open",
  "signalDelayMs": 420,
  "subsystemStatus": {
    "power": "nominal",
    "comms": "nominal",
    "thermal": "nominal",
    "adcs": "nominal",
    "payload": "nominal"
  },
  "faultMode": "none",
  "evidenceTags": [
    "pass_window_active"
  ]
}

ADCS Demo Kit Telemetry

{
  "messageType": "inbound_telemetry",
  "messageId": "tlm-ex-003",
  "assetId": "adcs-kit-01",
  "assetType": "adcs_demo_kit",
  "missionId": "adcs_demo",
  "timestamp": "2026-05-12T00:02:00.000Z",
  "status": "received",
  "transport": "mock",
  "attitude": {
    "rollDeg": 0.2,
    "pitchDeg": -0.1,
    "yawDeg": 45
  },
  "temperatureC": 28,
  "batteryPct": 91,
  "subsystemStatus": {
    "power": "nominal",
    "comms": "nominal",
    "thermal": "nominal",
    "adcs": "nominal",
    "payload": "nominal"
  },
  "faultMode": "none",
  "evidenceTags": []
}

Command: rover.scan_preview

{
  "messageType": "outbound_command",
  "commandId": "cmd-ex-001",
  "targetAssetId": "rover-01",
  "commandType": "rover.scan_preview",
  "payload": {
    "direction": "north",
    "range": 2
  },
  "issuedAt": "2026-05-12T00:00:10.000Z",
  "safetyClass": "safe_demo",
  "requiresSupervision": false,
  "expectedEffect": "Rover performs 360-degree environment scan preview (mock only — no motor movement)",
  "timeoutMs": 5000,
  "transport": "mock",
  "status": "queued"
}

Command: adcs.set_demo_angle_preview

{
  "messageType": "outbound_command",
  "commandId": "cmd-ex-002",
  "targetAssetId": "adcs-kit-01",
  "commandType": "adcs.set_demo_angle_preview",
  "payload": {
    "targetYawDeg": 90,
    "rampRateDegPerSec": 5
  },
  "issuedAt": "2026-05-12T00:02:05.000Z",
  "safetyClass": "safe_demo",
  "requiresSupervision": false,
  "expectedEffect": "ADCS kit slews to 90° yaw at 5°/s (mock preview — no physical movement without supervised lab adapter)",
  "timeoutMs": 8000,
  "transport": "mock",
  "status": "queued"
}

Mock Adapter Preview

Run the in-browser mock adapter to see a simulated message exchange — rover telemetry, CubeSat health, ADCS telemetry, safe command acknowledgement, and restricted command rejection. No real hardware or network connection is used.

Browser-local only — no hardware, no network

Safety Boundary

Every command in this system carries a safety class. The browser mock adapter enforces these boundaries — restricted commands are never executed, even in preview.

Command Safety Classes

safe_demo
Available in browser mock preview. No physical movement. No supervision required.
supervised_lab
Requires a supervised local lab adapter. Not available in browser preview alone.
restricted
Rejected in all browser and preview modes. Requires hardware safety review before any lab use.
disabled_in_browser
Never available in browser. Requires certified ground station or lab environment only.

Allowed in Mock Preview

✓ rover.move_preview
✓ rover.scan_preview
✓ rover.safe_stop_preview
✓ cubesat.request_health
✓ adcs.set_demo_angle_preview

Blocked — Restricted Commands

✗ real_motor_drive
Direct motor drive control requires supervised lab hardware — not available in browser preview.
✗ real_radio_transmit
Radio transmission commands require licensed operation and local RF hardware — blocked in all preview modes.
✗ upload_flight_software
Flight software uploads are restricted to certified ground station operations — never available in browser.
✗ disable_safety_limit
Safety limit override is disabled in all preview and lab modes — requires explicit hardware safety review.

This product does not: control real robots over the internet, transmit RF signals, upload flight software, or override hardware safety limits. Any future real hardware integration will be local, supervised, and reviewed before activation.

Integration Map

How the hardware interface protocol connects to existing missions and future bridge paths.

Lunar Rover Rescue

/twin/missions/lunar-rover-rescue →

Rover telemetry and command protocol maps directly to the Lunar Rover Rescue mission. Future hardware bridge: rover kit connected via serial/USB Python bridge.

Assets: rover-01

Commands: rover.move_preview, rover.scan_preview, rover.safe_stop_preview

Telemetry: batteryPct, position, wheelCurrentA, linkStatus, faultMode

CubeSat–Rover Relay

/twin/missions/cubesat-rover-relay →

CubeSat pass-window telemetry and relay command protocol matches this mission. Future hardware bridge: CubeSat kit + ESP32 relay node via WebSocket bridge.

Assets: cubesat-01, rover-01

Commands: cubesat.request_health, rover.safe_stop_preview

Telemetry: batteryPct, linkStatus, signalDelayMs, passWindowStatus

ADCS Demo Kit

/twin/learn/tracks/attitude_control →

ADCS attitude control telemetry links to Track 5 learning activities. Future hardware bridge: ADCS demo kit via serial/Arduino bridge.

Assets: adcs-kit-01

Commands: adcs.set_demo_angle_preview

Telemetry: attitude, temperatureC, batteryPct

Future Bridge Paths

Spec Only
Python Serial Bridge
Local Python script reads sensor/rover serial output and forwards JSON to browser via WebSocket loopback.
See: docs/product/V3_5B_PYTHON_BRIDGE_INTEGRATION_PLAN.md
Spec Only
ESP32 / Arduino WebSocket Bridge
ESP32 or Arduino sketch reads sensors and posts telemetry JSON to a local WebSocket endpoint on the same network.
See: docs/product/V3_5B_ESP32_ARDUINO_INTEGRATION_PLAN.md
Spec Only
WebSocket First Transport
Browser connects to ws://localhost:8765 (or local IP). Protocol messages defined in this spec are the wire format.
See: docs/product/V3_5B_WEBSOCKET_BRIDGE_SPEC.md
Future Phase
MQTT Broker
Assets publish to local MQTT topics. A bridge script subscribes and relays to browser WebSocket.
See: docs/product/V3_5B_WEBSOCKET_BRIDGE_SPEC.md
Future Phase
ROS / ROS2 Bridge
Advanced robotics labs: ROS topics mapped to this protocol schema via rosbridge_suite or rclpy adapter.

Next Steps

This specification is the foundation. Real hardware integration follows a phased, supervised path.

Now — Software-First

✓ Protocol model defined (TypeScript)
✓ Telemetry + command schemas
✓ Mock adapter preview (browser-local)
✓ Safety class boundary enforced
✓ Mission integration map documented
✓ WebSocket bridge spec defined

Future — Supervised Lab

○ Python serial bridge (local, supervised)
○ ESP32/Arduino WebSocket adapter
○ Local WebSocket bridge server
○ Supervised rover kit lab session
○ CubeSat kit ground-pass lab session
○ MQTT / ROS2 bridge (advanced labs)

← Hardware Hub Space Mission Challenge Pack →ADCS Track (Track 5) →Demo Pack →Mission Realism Lab → packet protocol concepts →

Packet protocol link to Mission Realism Layer

The telemetry packet schema defined here (syncWord, sequenceNumber, checksum, payload fields) is the conceptual basis for the packet protocol teaching model in the Mission Realism Lab. In a future supervised hardware phase, real telemetry from a CubeSat kit would flow through this same schema — with CRC and ACK/NACK protocol matching what students learn in the Realism Lab.

V3.6B applied realism: CubeSat–Rover Relay and Lunar Rover Rescue surface teaching packet runs (checksum/CRC, retries, drops) and link-margin language that intentionally mirrors these schema fields — so future hardware telemetry can be discussed with the same vocabulary students already practiced in-browser.

Phase: V3.5B Hardware-Ready Interface Specification · Status: Spec + mock complete · Next: supervised hardware bridge (future phase); see Mission Realism Lab + mission panels for teaching alignment