Skip to content
GitHub · 2.7.0

Guides

Drive a remote target

A remote target runs as a separate application, reached over gRPC and driven over LSL. For a device in the MyoGestic process, use an in-process target that ControlBus calls directly on the thread MyoGestic already owns. This simpler route needs no transport. Use the remote contract only when the device is its own program.

If you have not chosen between the two yet, Concepts › Controls explains how to choose. This page defines the contract. For a tutorial with runnable stages, see Your first remote target.

Stream direction

MyoGestic writes, you read. One stream per continuous DOF (one degree of freedom), named for the DOF’s own address and one channel wide:

MyoGestic --[ vhi.prediction.index, 1 channel ]--> your target (you read this)

Use the manifest address as the stream name. Each stream has one channel. There is no extra transport declaration, width setting or positional layout to agree on. A DOF applies each sample on arrival and holds its last command between samples. These DOFs are independently actuated, possibly driven by different processes at different rates. Two programs can each drive a different DOF.

MyoGestic drives all of it with one RemoteTarget, which publishes one outlet per continuous address the map names and sends discrete changes over gRPC.

Publishing a read-back of your own is optional; VHI does it (VHI_Predict and VHI_Control, nine positional channels each, whatever the inbound shape) so a client can verify movement and catch a sign error.

The contract

you must why
serve GetControlManifest lets a control map resolve each address against its kind, range and states
report vocabulary_version "2" or newer MyoGestic refuses an older target by name at bind. The applications are installed separately; a mismatch can leave a target waiting silently for an unpublished stream
advertise one address per control the address identifies the control and names its stream. Multiple spellings create a second vocabulary to maintain and prevent collision checks from recognizing aliases for the same control
read one stream per address, exactly one float32 channel wide refuse any other width or dtype. Do not read only element zero. Reading element zero of a nine-channel pose can silently apply another DOF’s value to the address named by the stream
you may for
serve SetControl discrete held states and gestures belong off the per-tick stream. Both maps use manifest addresses as keys. Resolve the control from the key and the state from the value; refuse unexported addresses. Two discrete controls can share a state name, so resolving by state alone cannot distinguish them
serve SweepControl letting a client sweep one DOF and read back the degrees it produced, as a direction check
serve SetPresentation for a client asking you to smooth incoming poses
serve the four recording RPCs driving a ground-truth hand through a capture session
report target_version in the manifest your build’s release version ("2.1.0"). A client can refuse a build with known behaviour faults even when vocabulary_version matches. An absent version produces a warning and is accepted because the target may omit versioning

Implement these runtime checks and policies in the target; the client cannot verify them.

every remote target why
validate sample values a correctly shaped stream can carry NaN or 12.0. Enforce the advertised range before moving the device
refuse an address published by more than one outlet resolving into {info.name: info} keeps whichever producer the sweep answered with last, so two applications driving one DOF look exactly like one, and which you obey changes between restarts
state a liveness policy choose hold-last, timed return to rest or a hardware deadman. A SIGKILLed producer sends no neutral frame; a quiet stream may be idle or dead. source_id recovery handles reconnection. Device behaviour while disconnected needs its own policy and an independent safety interlock
close inlets and join reader threads on shutdown setting an event alone leaves the reader in pull_chunk and the inlets open and reconnecting

The reference target below demonstrates transport only. It accepts any correctly shaped sample, uses {info.name: info} without duplicate detection and holds the last command. stop() sets a flag without joining the reader or closing inlets. It meets none of the four runtime requirements; hold-last is an omission rather than a chosen policy. Do not deploy this transport example as a template. For deployment, build all four runtime checks and policies using Your first remote target, which also documents the limit of its duplicate check.

Client calls

You do not need to write client code. RemoteTarget drives the wire through two clients, RemoteClient and RecordingClient. Both are built from the InterfaceSpec that says where your target listens, and both are reached as spec.control_client() and spec.recording_client(). Calls return None or False without raising while the target is unavailable, allowing the app to stay responsive during launch.

the client calls when, and what it needs back
control_client().capabilities() at bind, and on every retry until you answer. Your manifest is the whole reply. None means “not up yet” and is deferred, never failed
control_client().set_control(...) on a discrete edge from the predict thread. Queued with latest-wins delivery; it never blocks or raises, keeping a 60 fps loop responsive. rejected reasons are logged
control_client().sweep(name) on an explicit verification request from a person or test. It animates one DOF and reads back the degrees produced
control_client().set_presentation(blend=…) when a client requests display smoothing. Keep the commanded values unchanged
recording.set_recording_session(True/False) around a capture, to gate any local input of your own so the recording has one movement source
recording.start_trajectory(movement, frequency_hz=…) to sweep a ground-truth control through a range while training data is collected
recording.state() to show a client which movements you have, which one is current, and whether a trajectory is running

Calls other than set_control are synchronous because setup, teardown and verification need a reply. set_control is queued to meet the predict thread’s deadline.

The whole target

The complete reference target includes every method without elision. It implements the service in myogestic/remote/_proto/remote_control.proto. Generate stubs from that file for languages other than Python:

Python
--8 < --"examples/synthetic/reference_target.py"

The standard

Values are [-1, 1], 0 is rest, +1 is the direction the DOF’s name denotes. Across the nine addresses of a VHI-shaped hand, a fist is [1, -1, 1, 1, 1, 1, 0, 0, 0], with five flexions and an adducted thumb. These values apply to the addresses whether sent as one nine-channel sample or nine one-channel samples.

The warning

Watch the device to verify direction. Contract tests can pass despite a sign error; the one convention a device may not redefine explains why. This repository previously shipped a sign error while its contract suite passed.

Design notes

A liveness timeout is not a safety interlock. A target that has itself crashed, hung or been swapped out cannot time anything out. Anything that can injure a person needs a release the software is not in the path of.

Stream recovery and the liveness timeout are different jobs. Recovery decides whether the stream comes back; the timeout decides what the device does meanwhile. A rig can want both.

SetControl delivery timing is not guaranteed. set_control queues a frame for the client’s worker thread, which drains one blocking RPC at a time with a two-second deadline. A later state can be queued before an earlier one is delivered, and two can land inside one tick of a status poller. Verify discrete state with a handler that prints each applied state; a poller can miss changes.

See also