Go SDK

Package rosieos/rt-core/sdk/control is the Go client for rt-control. It is what the offline programming server and the v4 pendant tooling use. It keeps separate connections for lifecycle, urgent (Stop, Release), bulk upload and renewal traffic, so a large upload can never delay a Stop or a renewal. It fills in the fence and a request_id on every command, and it returns refusals as a typed *control.Rejected.

The package builds on Linux only (//go:build linux).

Example: acquire, jog, stop, release#

This program is the simulation example from the rt-core README. It acquires, renews in the background, enables and arms all axes, waits for every drive to reach Operation Enabled, jogs axis 0 at 0.01 rad/s for one second, and then stops and releases. Start the simulated core and rt-control first (see Run everything in simulation), then set TMPDIR to the directory holding control.sock and SHA to the compiled configuration digest.

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	"rosieos/rt-core/ipcclient"
	"rosieos/rt-core/sdk/control"
)

func must[T any](v T, err error) T { if err != nil { panic(err) }; return v }
func check(err error) { if err != nil { panic(err) } }

func main() {
	// Simulation inputs: nine axes, 0.01 rad/s, 1 s of input at a 10 ms cadence,
	// 100 ms input lifetime, 10 s overall budget.
	const mask, velocity, duration, cadence, age, budget = 511, 0.01, time.Second, 10 * time.Millisecond, 100 * time.Millisecond, 10 * time.Second
	ctx, cancel := context.WithTimeout(context.Background(), budget)
	defer cancel()

	c := must(control.Dial(control.UnixPath(os.Getenv("TMPDIR") + "/control.sock")))
	defer c.Close()
	d := must(c.Describe(ctx))
	if d.Backend != "simulation" || d.ConfigurationSHA256 != os.Getenv("SHA") {
		panic("simulation identity mismatch")
	}
	g := must(c.Acquire(ctx, "readme", control.Binding{PairID: "readme", Revision: 1, ConfigurationSHA256: d.ConfigurationSHA256}))
	released := false
	defer func() {
		if !released {
			c.Stop(context.Background())
			c.Release(context.Background())
		}
	}()
	fmt.Printf("acquire generation=%d\n", g.Generation)
	renewals := must(c.StartRenewal(ctx, 0))

	fmt.Printf("enable sequence=%d\n", must(c.Enable(ctx, mask)).Sequence)
	fmt.Printf("arm sequence=%d\n", must(c.Arm(ctx)).Sequence)
	tick := time.NewTicker(cadence)
	defer tick.Stop()
	for !ipcclient.AllOperationEnabled(must(c.Status(ctx)).Core) {
		select {
		case <-tick.C:
		case <-ctx.Done():
			panic(ctx.Err())
		}
	}

	before := must(c.Status(ctx)).Core.Axes[0].PositionCounts
	jog := must(c.PrepareJogSession(ctx, mask))
	velocities := make([]float64, len(d.Axes))
	velocities[0] = velocity
	for end := time.Now().Add(duration); time.Now().Before(end); {
		origin := ipcclient.HostMonotonicNS()
		check(jog.UpdateAt(velocities, origin, origin+uint64(age)))
		select {
		case r, ok := <-renewals:
			if !ok {
				panic("renewal ended")
			}
			check(r.Err)
		case <-tick.C:
		case <-ctx.Done():
			panic(ctx.Err())
		}
	}
	check(jog.End(ctx))

	delta := must(c.Status(ctx)).Core.Axes[0].PositionCounts - before
	fmt.Printf("jog requested_ns=%d delta_counts=%d\n", duration, delta)
	fmt.Printf("stop generation=%d\n", must(c.Stop(ctx)).Generation)
	fmt.Printf("release session_empty=%t\n", must(c.Release(ctx)).Session == "")
	released = true
}

acquire generation=1
enable sequence=1
arm sequence=2
jog requested_ns=1000000000 delta_counts=207
stop generation=2
release session_empty=true

sdk/control/example_motion_server_test.go is a longer runnable example: it Homes, uploads an .rdt program, starts it and observes completion against the simulator. make test-go runs it.

Add the module#

The module path is rosieos/rt-core, which is not a fetchable URL. Point a replace directive at your checkout of the repository, as the offline programming server does:

require rosieos/rt-core v0.0.0

replace rosieos/rt-core => ../RosieOS/rt-core

The module declares go 1.24 with toolchain go1.26.2.

Connect#

Neither constructor connects: the first call does, bounded by its context.

Authority#

TimingForLease(lease, roundTrip) and RequestedLease(roundTrip, ceiling) are the helpers behind the lease sizing. See Control authority.

Commands#

Each method sends one rt-control operation with the current fence and a fresh request_id.

There are no convenience methods for halt, recovery_status or mark_telemetry. Send them with Command:

resp, err := c.Command(ctx, &control.Request{Operation: "halt"})

Command(ctx, *Request) fills in schema, the fence and a random request_id the first time, and writes them back into the request. To retry a lost reply, call Command again with the same *Request and a fresh context; the adapter then replays the first outcome instead of running the command twice. Never share one request between goroutines or change it between attempts. NewRequestID() returns a random 32-character hex ID if you want to set your own.

PrepareProgram sends the .rdt bytes with the session and generation headers. Uploads are not deduplicated and never retried: if one fails uncertainly, inspect Describe and Status, or Stop, before uploading again.

Jog#

Times are host CLOCK_MONOTONIC nanoseconds; ipcclient.HostMonotonicNS() reads that clock. A deadline may be at most the cell's max_jog_input_age_ns after its origin. Update never blocks: when the socket is congested it returns ErrJogWouldBlock, and you should drop that sample and send a fresh one. Local datagrams get no reply, so read refusals from JogIngress.

Observe#

See Events and telemetry for cursor handling.

Errors#

g, err := c.Acquire(ctx, "my-app", binding)
var rejected *control.Rejected
switch {
case errors.As(err, &rejected):
	// A 409 refusal. rejected.Reason is the reason code; NativeResult,
	// NativeJogResult and ResponseData carry any structured evidence.
	log.Printf("refused: %s", rejected.Reason)
case errors.Is(err, control.ErrConnectionUnsent):
	// The request never left this process. Safe to retry.
case errors.Is(err, control.ErrTransport):
	// The outcome is unknown. Stop, then reconcile Status before acquiring again.
case err != nil:
	log.Fatal(err)
}
_ = g

The client retries a request at most once, after a closed or stale connection, reusing the same request_id. It never retries a release or an .rdt upload whose outcome is uncertain.

Types#

The package re-exports the contract types, so you rarely need the adapter package directly: Request, Fence, Binding, Grant, Identity, Program, Execution, HandleRecord, ProcessMarker, Description, RecoveryStatus, CapabilityInfo, Point, JogClock, JogObservation, JogIngressObservation, JogIngressRefusal, Response (the raw envelope, with Data as json.RawMessage), Status, Event, EventBatch, EventsDropped, TelemetryBatch, ResourceInfo, RobotDescription, DriveDescription and DriveIdentity. Their fields are in the types reference. The capability states are exported as CapabilityStateImplemented, CapabilityStateInterim, CapabilityStateTestOnly and CapabilityStateUnimplemented. The reason codes are constants in the generated adapter package rosieos/rt-core/adapters/rosie/control, for example ReasonControlSessionStale.

Related pages#

• rt-control HTTP API
• Control authority
• C++ client