C++ client

rosie::rt_control::RtControlClient is a header-only C++17 client for rt-control. The Cartesian motion server and the dense trajectory daemon are built on it. It uses the generated contract types from rt_control_api_generated.hpp, keeps separate persistent connections for lifecycle, urgent, bulk and renewal traffic, and reports refusals as a Rejected exception carrying the reason code.

The headers are in rt-core/clients/cpp/include/rosie/:

Example: run one program#

clients/cpp/examples/rt_execute.cpp acquires, renews every 50 ms, enables and arms every axis, waits for readiness, uploads an .rdt program, starts it, waits for completion and releases. This is its core, shortened:

#include "rosie/rt_control_client.hpp"
using namespace rosie::rt_control;

int main(int argc, char** argv) {
    // argv: CONTROL_SOCKET PAIR_ID PAIR_REVISION CONFIGURATION_SHA256 PROGRAM.rdt
    RtControlClient client(argv[1]);
    try {
        Binding binding;
        binding.PairID = argv[2];
        binding.Revision = std::stoull(argv[3]);
        binding.ConfigurationSHA256 = argv[4];
        client.acquire("motion-server", binding);
        client.start_renewal(std::chrono::milliseconds(50));

        const auto count = client.describe().Description.Axes.size();
        const std::uint32_t mask = (1U << count) - 1;
        client.enable(mask);
        client.arm();
        // ... poll client.status() until Core.Armed == 1, every axis is Operation Enabled
        //     and Core.SafetyFaultMask == 0 ...

        std::string bytes = read_file(argv[5]);             // the immutable .rdt blob
        Program program = client.prepare_program(bytes);
        auto before = client.status();
        client.start_program(program.Identity);
        // ... poll client.status() until Execution.State == "completed" for
        //     Execution.Generation == before.Execution.Generation + 1 ...

        client.release();
        return 0;
    } catch (const Rejected& e) {
        std::cerr << e.reason << '\n';   // a reason code, e.g. not_ready
        client.stop_renewal();
        try { client.stop(); client.release(); } catch (...) {}
        return 2;
    } catch (const std::exception& e) {  // TransportError and friends: outcome unknown
        std::cerr << e.what() << '\n';
        client.stop_renewal();
        try { client.stop(); client.release(); } catch (...) {}
        return 3;
    }
}

Build and run the full example against a running rt-control:

make -C rt-core clients
rt-core/build/rt-execute /run/rosie-rt-core/control.sock cell-a 1 "$CONFIGURATION_SHA256" program.rdt

It prints the final status JSON. The exit code is 0 on completion, 2 for a rejection (it prints the reason) and 3 for a transport or observation failure. On failure it attempts Stop and Release. Two more examples sit beside it: motion_server_sequence.cpp (Home, program upload and completion) and remote_jog_sequence.cpp (remote jog).

Build#

Compile with C++17, -Irt-core/clients/cpp/include and -pthread. The jog producers and the telemetry decoders also need the generated frame codec, so add -Irt-core/include. The client includes protocol_generated.hpp by a relative path, so if you copy the client headers elsewhere, copy rt-core/include/protocol_generated.hpp with them.

Connect#

The client is not copyable. Join your other calls before destroying it; the destructor stops renewal but does not release authority.

Every call takes an optional absolute Deadline (a std::chrono::steady_clock::time_point). The default is 5 s from the call, and it bounds the call including its retry.

Methods#

There are no named methods for halt, mark_telemetry or resource; send halt and mark_telemetry with command().

Retries and request IDs#

Every mutation carries a random request_id. To retry a lost reply, keep the Request object and pass it to command() again without changing its ID, fence or body: the adapter replays the original outcome. The client itself retries once with the same request. release() and .rdt uploads are never replayed automatically. An uncertain upload must not lead to a Start: inspect state or Stop first.

Renewal#

start_renewal(interval) starts a background thread that renews at interval (0 means a third of the lease; anything larger is refused). It throws Rejected with control_session_stale when the lease cannot cover three round trips plus the interval. Poll take_renewal(), which returns the latest Renewal{grant, error} if there is one. A grant with Stopping set is a successful renewal during a Stop. Any error ends renewal, and the thread never reacquires authority. stop_renewal() joins the thread.

start_connection_keepalive() keeps idle connections open at a third of the Describe control_idle_timeout_ns.

Exceptions#

Catch Rejected first for refusals, then TransportError for everything whose outcome is uncertain. After an uncertain outcome, stop producing motion, attempt stop(), and reconcile status() before acquiring again.

Jog#

RtJogProducer jogs over the local jog.sock:

#include "rosie/rt_jog_producer.hpp"

// After acquire(), start_renewal(), enable(), arm() and observed readiness:
auto deadline = host_monotonic_ns() + 100000000;                 // 100 ms input lifetime
RtJogProducer jog(client, "/run/rosie-rt-core/jog.sock", /*mask*/ 1, deadline);
std::vector<double> v(axis_count, 0.0);
v[0] = 0.05;                                                      // rad/s on axis 0
if (!jog.update(v, host_monotonic_ns() + 100000000)) {
    // Congested: this sample was not sent. Drop it and send a fresh one.
}
jog.end();                                                        // ends the jog generation

The constructor reads /v1/jog/clock and calls begin_jog. update() returns false when the datagram could not be sent; discard that input and sample again. Stop cancels the producer, so never reuse it after a Stop. For remote jog, use RtJogRemoteProducer on a client built with a mutual-TLS factory; see remote jog.

Remote transport#

The header-only client does no TLS itself. To reach the remote listener, construct the client with a StreamFactory: a function that takes a Deadline and returns a new std::unique_ptr<HttpStream> connected over mutual TLS. HttpStream has two methods, read(data, size, deadline) and write(data, size, deadline).

Your factory must return an independent stream for every call, verify the server certificate and host name, and present the client certificate and key of the paired principal. Every read and write must honour the absolute deadline and never replay bytes. A read that times out throws DeadlineExceeded without consuming data. Keep the lifecycle, renewal and jog connections under the same authenticated identity. The client's own tests exercise the WebSocket jog path through a bridge that performs TLS on the Go side, so the C++ TLS path itself is not covered by CI.

Related pages#

• rt-control HTTP API
• Go SDK
• Control authority