terra-streaming

Implement realtime wearable biometric streaming over the Terra API websocket protocol.

Updated Sep 2, 2026
One-click install
npx skills add https://github.com/tryterra/agent-skills --skill terra-streaming-tryterra
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: terra-streaming
Source: https://github.com/tryterra/agent-skills/tree/main/skills/terra-streaming
Command: npx skills add https://github.com/tryterra/agent-skills --skill terra-streaming-tryterra

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building live, per-second biometric data streams from wearables requires navigating a producer/broker/consumer architecture, an opcode-framed websocket handshake, single-use tokens, and platform-specific SDK setup, where small protocol mistakes cause silent failures or reconnect loops. ## Core Features & Use Cases - Websocket protocol guidance: Covers the wss://ws.tryterra.co/connect handshake, IDENTIFY roles, heartbeats, close codes, and REPLAY backfill with exclusive bounds. - Token architecture: Explains the three single-use token types (phone-registration, producer, consumer) and how to mint them server-side per session. - Per-platform RT SDK setup: Reference guides for iOS, Android, React Native, Flutter, and Wear OS producers, including Apple Watch workout sessions and ANT+ support. - Use Case: A backend engineer needs to consume live heart-rate data from users' BLE chest straps; the skill walks through minting a consumer token, completing the IDENTIFY handshake, handling sparse seq gaps, and backfilling missed data with REPLAY after a drop. ## Quick Start Ask the agent to help you build a backend consumer that connects to the Terra streaming websocket and receives live heart-rate data from a test user.

Frequently Asked Questions about terra-streaming

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stream live heart rate data from a wearable to my backend?

Pair the wearable to a mobile app running a TerraRT SDK (the producer), which forwards data to the Terra websocket broker. Your backend opens a consumer connection to wss://ws.tryterra.co/connect, identifies with a developer token, and receives DISPATCH payloads.

How do I reconnect to the Terra streaming websocket after a dropped connection?

Mint a fresh token before reconnecting because tokens are single-use and deleted after a successful IDENTIFY. After reconnecting, send REPLAY with after set to your last processed seq and before set to the first live seq to backfill the gap.

Why is my Terra stream empty for a data type I requested?

Requesting a data type does not guarantee receiving it; the wearable must actually broadcast that signal over BLE or ANT+. Most heart-rate straps are cardiac only and will never produce STEPS or LOCATION, so render per-signal state and degrade gracefully.

What do Terra streaming websocket close codes 4000 and 4001 mean?

Close code 4000 means IDENTIFY was not sent within 15 seconds of connecting, a client bug to fix rather than retry. Code 4001 means a bad or expired token, so mint a fresh one and reconnect.

Does Terra streaming work with Apple Watch and Wear OS?

Yes, Apple Watch streams via a native Swift watchOS companion app using the Terra class, and Wear OS uses the terra-wearos library paired to an Android phone running TerraRTAndroid. Wear OS exercise streams label payloads with concatenated types like RUNNING_HEART_RATE.

When should I use the Streaming API instead of the Terra Unified API?

Use the Streaming API only for realtime, per-second signals like heart rate, steps, and acceleration. Workouts, sleep, daily totals, body, and nutrition data belong to the Unified API, not the streaming surface.