Events and telemetry streams

rt-control publishes two observation streams. Neither needs a lease, so any client that can reach the socket can watch the cell while another client controls it.

• Events are a JSON log of state changes: grants, enable and arm, handle and execution transitions, jog sessions, faults, Home epochs and restarts. They are good for reacting to changes.
• Telemetry is binary: one record per control cycle with positions, targets, drive state and fault masks. It is good for plotting, logging and replay.

Both use the same cursor model: you pass after, the last sequence you handled, and the server tells you exactly what you missed.

Follow the event stream#

# Server-Sent Events from the beginning of the retained log; Ctrl-C to stop.
curl -sN --unix-socket /run/rosie-rt-core/control.sock \
  'http://localhost/v1/events/stream?after=0'

c, err := control.Dial("/run/rosie-rt-core/control.sock")
if err != nil {
	log.Fatal(err)
}
defer c.Close()
var cursor uint64
err = c.StreamEvents(ctx, cursor, func(e control.Event) error {
	if e.Type == "events_dropped" {
		// History was lost: re-read Status before trusting your local view.
		log.Printf("lost events %d..%d", e.Dropped.FirstLostSequence, e.Dropped.LastLostSequence)
	}
	log.Printf("%d %s", e.Sequence, e.Type)
	cursor = e.Sequence
	return nil
})

: rt-core events

id: 1
event: adapter_incarnation_changed
data: {"sequence":1,"time_ns":81230000000000,"type":"adapter_incarnation_changed","daemon_incarnation":"3b9d…","adapter_incarnation":"a41c…","incarnation":{"previous":"","current":"a41c…"}}

id: 2
event: grant_acquired
data: {"sequence":2,"time_ns":81234567890123,"type":"grant_acquired","daemon_incarnation":"3b9d…","adapter_incarnation":"a41c…","grant":{"generation":1,"stopping":false}}

Events#

Cursors and loss#

• after is the sequence of the last event you handled. Omit it (or send 0) to start at the oldest retained event. It must be one unsigned decimal number, otherwise you get 409 invalid_event_cursor. A cursor newer than the log gets 409 event_cursor_ahead.
• Sequences increase by one within an adapter_incarnation. A poll returns next_sequence (use it as your next after) and latest_sequence.
• The log keeps the last 256 events. If your cursor is older than that, the first record you receive is a synthetic events_dropped event whose first_lost_sequence..last_lost_sequence range (inclusive) is what you missed. Its own sequence equals last_lost_sequence, so it is also your resume cursor. The retained events that follow keep their original sequence numbers.
• The SSE handler does not read Last-Event-ID. To resume, reconnect with ?after= set to the last id you handled.
• When rt-control restarts, the sequence starts again under a new adapter_incarnation. Discard your cursor, read Status and start from 0.

Events are observations, not a lossless trace. time_ns is the core's publication time, and native snapshots can merge transitions that happen between publications. After any loss or incarnation change, reconcile from GET /v1/status rather than replaying motion.

Event types#

Every event has sequence, time_ns, type, daemon_incarnation and adapter_incarnation, plus one payload field for its type:

Events never contain the session token. The field tables for every payload type are in the types section of the HTTP reference.

Telemetry#

Telemetry is application/octet-stream, never JSON or base64. A batch is a 312-byte TelemetryBatchHeaderV1 followed by exactly record_count records of 5392 bytes (CycleCaptureRecordV2), all little-endian. A batch is at most 312 + 4096 × 5392 = 22085944 bytes.

err := c.TelemetryStream(ctx, 0, func(b control.TelemetryBatch) error {
	if b.Header.Dropped != 0 {
		log.Printf("lost %d records", b.Header.Dropped)
	}
	for _, r := range b.Records {
		j1 := r.Ax[0]
		_ = j1.Position // drive counts; convert with Describe counts_per_unit and sign
	}
	return nil
})

Cursors and loss#

• after is the last record sequence you consumed. 0 (the default) starts at sequence 1, and history that the ring has already overwritten is reported in dropped.
• A non-empty batch starts at after + dropped + 1 and its sequences are contiguous. An empty batch has first_sequence 0 and last_sequence equal to after + dropped. Always resume from last_sequence, after you have handled the batch and its loss.
• Errors come back as JSON with HTTP 409: invalid_telemetry_cursor, telemetry_cursor_ahead, telemetry_unavailable, or telemetry_busy with Retry-After: 1 (retry the same cursor). On an established stream, a busy read becomes an empty batch with the cursor unchanged.
• A stream closes when the core disconnects or a write blocks for 5 s. HTTP proxies may re-chunk the stream, so find batch boundaries from the header, not from chunks.
• If adapter_incarnation or daemon_incarnation changes, stop. Re-read Describe and Status before you reset the cursor.

Telemetry needs no session, but on the remote listener it still needs a valid client certificate.

Batch header#

TelemetryBatchHeaderV1, 312 bytes. Check magic, version, header_bytes, record_bytes, the layout digest, axis_count (1..16) and record_count (≤ 4096) before reading the body.

The current record layout digest is 1173439681672348f35f9652f2a4821d251638c70b60362ff59b37032a794b6b. A reader that sees a different digest must refuse the batch: the Go, C++ and TypeScript decoders all raise TelemetryLayoutMismatchError with both digests.

Cycle record#

CycleCaptureRecordV2, 5392 bytes: 52 group fields followed by ax, 16 per-axis entries. Positions and targets are in drive counts, not radians; convert them with the axis's counts_per_unit and sign from Describe.

Axis entry#

CycleCaptureAxisV2, 320 bytes, 16 per record. Check pdo_fresh and each field's validity flag before you use a value; invalid values are not meaningful, and di_valid = 0 means unavailable, not "inputs off".

Decoders for these layouts are generated from protocol/control.json: Go in rosieos/rt-core/ipcclient (used by Client.TelemetryBatches and TelemetryStream), C++ in protocol_generated.hpp (used by RtControlClient::telemetry), and TypeScript in rt_protocol_generated.ts.

Resources#

Describe's robot.resources lists the compiled robot description files (manifest, URDF, meshes, calibration) with their SHA-256 digests. Fetch one with GET /v1/resources/<sha256>. The bytes are immutable, and an unknown digest returns 404 resource_unknown.

Related pages#

• rt-control HTTP API: subscribe_events, telemetry, mark_telemetry and resource.
• The real-time core: where the telemetry ring comes from.
• TypeScript contracts: decoding telemetry in the browser or Node.