Device integrators connect cameras, trackers, controllers, or companion apps to MotionStage’s server-authoritative runtime.
| Phase | Goal | Commands | Pass Criteria |
|---|---|---|---|
| P1 | Validate runtime and protocol baseline | cargo test -p motionstage-server -p motionstage-transport-quic -p motionstage-testkit |
Handshake, signaling, ingest, and soak tests pass |
| P2 | Dry run with built-in simulated device | cargo run -p motionstage-cli -- simulate --server-bind 127.0.0.1:0 --sample-hz 120 then start, status, record start recordings/device-dryrun.cmtrk, record stop, quit |
Motion counters increase and recording is generated |
| P3 | Loopback transport dry run (real QUIC path) | cargo test -p motionstage-server quic_runtime_accepts_session_and_ingests_motion -- --nocapture and cargo test -p motionstage-server quic_control_routes_and_drains_video_signals -- --nocapture |
QUIC control + datagram path passes end-to-end |
| P4 | Bring up your real device client | Point your client at cargo run -p motionstage-cli -- serve endpoint |
Client reaches Active session state and motion updates apply |
Use the local simulator first to validate your expected cadence and mapping behavior:
cargo run -p motionstage-cli -- simulate --server-bind 127.0.0.1:0 --sample-hz 120Then switch to serve and replace the simulated client with your device-side client implementation.
Use these before real hardware bring-up.
- Runs server + simulated motion source together.
- Simulated source uses real QUIC session flow (
ServerHello/ClientHello/RegisterRequest) and motion datagrams. - No network discovery required.
- Best for quick mapping/recording pipeline checks.
Command:
cargo run -p motionstage-cli -- simulate --server-bind 127.0.0.1:0 --sample-hz 120Smoke commands:
start
status
record start recordings/device-dryrun.cmtrk
record stop
quit
- Uses real QUIC control/datagram flow on localhost.
- Validates your assumptions about handshake + ingest + signaling behavior.
Commands:
cargo test -p motionstage-server quic_runtime_accepts_session_and_ingests_motion -- --nocapture
cargo test -p motionstage-server quic_control_routes_and_drains_video_signals -- --nocapture- Runs only the simulated client against your already running server.
- Does not create scenes or mappings on the server.
- Requires server-side scene/mapping/mode to be configured before streaming.
Command:
cargo run -p motionstage-cli -- simulate --connect 127.0.0.1:7788 --output-attribute demo.position
# or discover via mDNS (single-server auto-select):
cargo run -p motionstage-cli -- simulate --connect discover --output-attribute demo.position
# or select a specific discovery service:
cargo run -p motionstage-cli -- simulate --connect discover:motionstage-blender --output-attribute demo.positionSmoke commands:
start
status
quit
- Discovery: mDNS
_motionstage._udp.local. - Transport: QUIC
- Control channel: bi-directional stream (
ControlMessage) - Motion channel: QUIC datagrams (
MotionDatagram) - Wire compatibility: major/minor protocol validation on decode
Expected control sequence:
- Receive
ServerHello - Send
ClientHelloincluding advertised output attributes forMotionSourceroles - Send
RegisterRequest - Receive
RegisterAcceptedorRegisterRejected - Session enters active loop for ping/signaling/control
A session must reach Active before it can participate in signaling and motion/video operations.
Roles:
MotionSourceCameraControllerVideoSinkOperator
Features:
MotionMappingRecordingVideoHdr10SdrFallback
Registration negotiates intersection between client-declared and server-supported features.
MotionDatagram payload:
device_idtimestamp_nsupdates[](attribute key + typed value)
Server behavior:
- Rejects updates without active mapping
- Applies component-mask transform and filter chain
- Increments ingest metrics (
motion_datagrams,motion_updates)
Control messages include:
CreateVideoOffer { stream_id, track_id }VideoOffer(SdpMessage)VideoSignal(SignalMessage)DrainSignals/SignalsBatch
Signaling can be:
- Server-owned peer flow (device signals to itself for offer/answer lifecycle)
- Device-to-device routed flow via server queue
Security modes:
trusted_lanpairing_requiredapi_keyapi_key_plus_pairing
Registration failures return explicit reject codes (auth, capacity, compatibility, role/feature mismatch).
- Implement protocol version negotiation fallback on minor versions.
- Send heartbeat-like motion traffic at stable cadence.
- Keep source output names stable and fully-qualified as
<device-id>.<attr>[.<component>]because mappings are key-based. - Handle
Errorcontrol messages as actionable protocol failures. - Reconnect by repeating full handshake and registration.
If you are integrating from an iOS client app, use the Swift binding build pipeline:
- Build Rust+iOS XCFramework:
./scripts/build-swift-ios.sh - Swift package wrapper:
swift/MotionStageClient - FFI contract header:
crates/motionstage-sdk-swift/include/motionstage_swift.h
Detailed iOS integration and validation matrix:
docs/ios-integrators.md