From 08e9c4e2ea5d54e9ce04f57feb9086bf29283787 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 21 Oct 2026 10:41:50 -0700 Subject: [PATCH 01/18] feat(remote_device_bridge): add the remote plugin-session wire codec Add the Teleop::remote_plugin_session library with its only serialization point: little-endian frames of a 24-byte header plus payload, 14 frame types (HELLO/ACK, OPEN_*, CLOSE, hand/schema/wrist samples, HEARTBEAT, ERROR, PING/PONG). Schema samples carry the plugin's FlatBuffer bytes opaquely. The library links only pusherio, never the OpenXR loader, and is gated by BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE (default ON, skipped on Windows). Signed-off-by: Jonghyun Kim --- CMakeLists.txt | 1 + src/plugins/CMakeLists.txt | 3 + src/plugins/remote_device_bridge/AGENTS.md | 11 + .../remote_device_bridge/CMakeLists.txt | 11 + .../session/CMakeLists.txt | 24 + .../inc/remote_plugin_session/wire_codec.hpp | 195 +++++ .../session/wire_codec.cpp | 676 ++++++++++++++++++ tests/cpp/plugins/CMakeLists.txt | 4 + .../remote_device_bridge/CMakeLists.txt | 16 + .../remote_device_bridge/test_wire_codec.cpp | 438 ++++++++++++ 10 files changed, 1379 insertions(+) create mode 100644 src/plugins/remote_device_bridge/AGENTS.md create mode 100644 src/plugins/remote_device_bridge/CMakeLists.txt create mode 100644 src/plugins/remote_device_bridge/session/CMakeLists.txt create mode 100644 src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp create mode 100644 src/plugins/remote_device_bridge/session/wire_codec.cpp create mode 100644 tests/cpp/plugins/remote_device_bridge/CMakeLists.txt create mode 100644 tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 521ec03c30..0099554bbf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -71,6 +71,7 @@ option(BUILD_PLUGIN_NOITOM_MOCAP "Build Noitom mocap plugin (downloads MocapApi option(BUILD_PLUGIN_OGLO "Build OGLO tactile glove plugin (BLE, Linux only; fetches SimpleBLE + nlohmann/json)" OFF) option(BUILD_PLUGIN_WUJI_GLOVE "Build Wuji glove plugin (requires the wuji_sdk C SDK)" OFF) option(BUILD_PLUGIN_SHARPA_AVATAR "Build Sharpa AvatarExo Glove plugin (Linux; skips if the Avatar SDK is missing)" OFF) +option(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE "Build the remote device bridge, RemotePluginSession library and synthetic sender (POSIX sockets; skipped on Windows)" ON) option(BUILD_EXAMPLES "Build examples" ON) option(BUILD_EXAMPLE_TELEOP_ROS2 "Build only the teleop_ros2 ROS 2 reference integration (e.g. for Docker)" OFF) option(BUILD_TESTING "Build unit tests" ON) diff --git a/src/plugins/CMakeLists.txt b/src/plugins/CMakeLists.txt index c26d9384c2..3d3ae72dc5 100644 --- a/src/plugins/CMakeLists.txt +++ b/src/plugins/CMakeLists.txt @@ -23,6 +23,9 @@ add_subdirectory(gamepad) add_subdirectory(xsens_full_body) add_subdirectory(so101_leader) add_subdirectory(rebot_devarm_leader) +if(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE) + add_subdirectory(remote_device_bridge) +endif() add_subdirectory(manus) add_subdirectory(manus_calibration) add_subdirectory(haptikos) diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md new file mode 100644 index 0000000000..bab6f07eee --- /dev/null +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -0,0 +1,11 @@ + + +# Agent notes — `src/plugins/remote_device_bridge` + +**CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. + +- `session/wire_codec.{hpp,cpp}` is the single serialization point. Every frame type is encoded and decoded there and nowhere else; changing the wire format means changing that file and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. +- `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin using `--remote` must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/CMakeLists.txt b/src/plugins/remote_device_bridge/CMakeLists.txt new file mode 100644 index 0000000000..0e516622d0 --- /dev/null +++ b/src/plugins/remote_device_bridge/CMakeLists.txt @@ -0,0 +1,11 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +if(WIN32) + message(STATUS "Skipping remote_device_bridge (POSIX sockets only)") + return() +endif() + +add_subdirectory(session) diff --git a/src/plugins/remote_device_bridge/session/CMakeLists.txt b/src/plugins/remote_device_bridge/session/CMakeLists.txt new file mode 100644 index 0000000000..599bca58a4 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/CMakeLists.txt @@ -0,0 +1,24 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +# Transport-only library shared by the bridge, the synthetic sender and any +# plugin that offers --remote. It must never link the OpenXR loader or +# plugin_utils: plugin processes using it stay free of an OpenXR runtime. +add_library(remote_plugin_session STATIC + wire_codec.cpp + inc/remote_plugin_session/wire_codec.hpp +) + +target_include_directories(remote_plugin_session + INTERFACE + $ +) + +target_link_libraries(remote_plugin_session + PUBLIC + pusherio::pusherio +) + +add_library(Teleop::remote_plugin_session ALIAS remote_plugin_session) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp new file mode 100644 index 0000000000..c7697065d8 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp @@ -0,0 +1,195 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include +#include + +#include +#include +#include +#include +#include +#include + +namespace remote_plugin_session +{ +namespace wire +{ + +/*! + * Wire protocol v0: fixed little-endian frames over one TCP connection per + * plugin session. Frame = 24-byte header + payload. `str` = u32 length + bytes, + * `pose` = 7 x f32 in XrPosef order (orientation x,y,z,w then position x,y,z). + * This file is the single serialization point; swapping the hand payload for + * a FlatBuffer later only changes encode/decode of HandSample here. + */ + +constexpr uint32_t kMagic = 0x30535052u; // "RPS0" +constexpr uint8_t kProtocolVersion = 0; +//! HELLO proto_version: 1 = the client answers PING with PONG. The bridge still accepts 0 and never PINGs it +//! (a v0 client fails on unknown frame types). +constexpr uint16_t kHelloVersion = 1; +constexpr size_t kHeaderSize = 24; +constexpr uint16_t kSessionChannelId = 0; +constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded + +enum class FrameType : uint8_t +{ + Hello = 1, // c->s: proto_version, app_name, requirements + HelloAck = 2, // s->c: accepted, reason + OpenHand = 3, // c->s: hand (0 left, 1 right) + OpenSchema = 4, // c->s: SchemaPusherConfig + OpenPull = 5, // c->s: empty + OpenWrist = 6, // c->s: WristTrackingSourceConfig on the pull channel id + Close = 7, // c->s: empty + HandSample = 8, // c->s: sample_time + 26 joints + SchemaSample = 9, // c->s: two timestamps + bytes + WristSample = 10, // s->c: sample_time, is_left, valid, tracked, pose + Heartbeat = 11, // both: empty + Error = 12, // s->c: message; on channel 0 the connection closes afterwards, on a channel id only that + // channel is refused + Ping = 13, // s->c: t1 (bridge send time) + Pong = 14, // c->s: t1 echoed, t2 (client receive time), t3 (client send time) +}; + +struct FrameHeader +{ + FrameType type = FrameType::Heartbeat; + uint8_t version = kProtocolVersion; + uint16_t channel_id = kSessionChannelId; + uint32_t seq = 0; + uint32_t payload_size = 0; + int64_t t_send_monotonic_ns = 0; +}; + +struct Frame +{ + FrameHeader header; + std::vector payload; +}; + +class DecodeError : public std::runtime_error +{ +public: + using std::runtime_error::runtime_error; +}; + +struct Hello +{ + uint16_t proto_version = kHelloVersion; + std::string app_name; + core::PluginSessionRequirements requirements; +}; + +struct HelloAck +{ + bool accepted = false; + std::string reason; +}; + +struct OpenHand +{ + XrHandEXT hand = XR_HAND_LEFT_EXT; +}; + +struct HandSample +{ + int64_t sample_time_ns = 0; + std::array joints{}; +}; + +struct SchemaSample +{ + int64_t sample_time_local_common_clock_ns = 0; + int64_t sample_time_raw_device_clock_ns = 0; + std::vector bytes; +}; + +struct WristSample +{ + int64_t sample_time_ns = 0; + bool is_left = true; + core::WristTrackingSample sample; +}; + +struct Error +{ + std::string message; +}; + +//! Times are CLOCK_MONOTONIC ns of the side that took them. +struct Ping +{ + int64_t t1_ns = 0; +}; + +struct Pong +{ + int64_t t1_ns = 0; + int64_t t2_ns = 0; + int64_t t3_ns = 0; +}; + +constexpr size_t kPoseSize = 7 * sizeof(float); +constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); +constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; +constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + kPoseSize; +constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * kPoseSize; + +static_assert(kHeaderSize == 4 + 1 + 1 + 2 + 4 + 4 + 8); +static_assert(kJointSize == 40); +static_assert(kHandSamplePayloadSize == 1048); +static_assert(sizeof(XrSpaceLocationFlags) == sizeof(uint64_t)); + +const char* to_string(FrameType type); + +//! `out` must hold kHeaderSize bytes. +void encode_header(const FrameHeader& header, uint8_t* out); +//! Throws DecodeError on bad magic, unsupported version or an oversized payload. +FrameHeader decode_header(const uint8_t* in); + +std::vector encode(const Hello& value); +std::vector encode(const HelloAck& value); +std::vector encode(const OpenHand& value); +std::vector encode(const core::SchemaPusherConfig& value); +std::vector encode(const core::WristTrackingSourceConfig& value); +std::vector encode(const WristSample& value); +std::vector encode(const Error& value); +std::vector encode(const Ping& value); +std::vector encode(const Pong& value); + +// Frame builders write header + payload into one contiguous buffer. seq and t_send stay zero until +// stamp_header(). Samples are only encoded this way: the builders read the plugin's buffers directly so a +// push copies once. +std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); +std::vector encode_hand_sample_frame(uint16_t channel_id, + const XrHandJointLocationEXT* joints, + int64_t sample_time_ns); +std::vector encode_schema_sample_frame(uint16_t channel_id, + const uint8_t* bytes, + size_t size, + int64_t sample_time_local_common_clock_ns, + int64_t sample_time_raw_device_clock_ns); +//! Patches seq and t_send into an encoded frame's header in place; on a PONG also sets t3 = t_send, so t3 is +//! the time the frame actually left, not when it was queued. +void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns); +//! Splits one complete message into header and payload (payload moved, not copied). Throws DecodeError. +Frame split_frame(std::vector message); + +// Decoders throw DecodeError on truncated or over-long payloads. +Hello decode_hello(const std::vector& payload); +HelloAck decode_hello_ack(const std::vector& payload); +OpenHand decode_open_hand(const std::vector& payload); +core::SchemaPusherConfig decode_open_schema(const std::vector& payload); +core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload); +HandSample decode_hand_sample(const std::vector& payload); +SchemaSample decode_schema_sample(const std::vector& payload); +WristSample decode_wrist_sample(const std::vector& payload); +Error decode_error(const std::vector& payload); +Ping decode_ping(const std::vector& payload); +Pong decode_pong(const std::vector& payload); + +} // namespace wire +} // namespace remote_plugin_session diff --git a/src/plugins/remote_device_bridge/session/wire_codec.cpp b/src/plugins/remote_device_bridge/session/wire_codec.cpp new file mode 100644 index 0000000000..1ac2036342 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/wire_codec.cpp @@ -0,0 +1,676 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/remote_plugin_session/wire_codec.hpp" + +#include +#include + +namespace remote_plugin_session +{ +namespace wire +{ + +namespace +{ + +//! Appends little-endian fields to a caller-owned buffer. +class Writer +{ +public: + explicit Writer(std::vector& out) : m_out(out) + { + } + + void u8(uint8_t value) + { + m_out.push_back(value); + } + + void u16(uint16_t value) + { + for (int i = 0; i < 2; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void u32(uint32_t value) + { + for (int i = 0; i < 4; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void u64(uint64_t value) + { + for (int i = 0; i < 8; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void i64(int64_t value) + { + u64(static_cast(value)); + } + + void f32(float value) + { + uint32_t bits = 0; + std::memcpy(&bits, &value, sizeof(bits)); + u32(bits); + } + + void str(const std::string& value) + { + if (value.size() > std::numeric_limits::max()) + { + throw std::invalid_argument("wire: string too long"); + } + u32(static_cast(value.size())); + m_out.insert(m_out.end(), value.begin(), value.end()); + } + + void bytes(const uint8_t* data, size_t size) + { + m_out.insert(m_out.end(), data, data + size); + } + + void pose(const XrPosef& value) + { + f32(value.orientation.x); + f32(value.orientation.y); + f32(value.orientation.z); + f32(value.orientation.w); + f32(value.position.x); + f32(value.position.y); + f32(value.position.z); + } + +private: + std::vector& m_out; +}; + +class Reader +{ +public: + Reader(const uint8_t* data, size_t size) : m_data(data), m_size(size) + { + } + + explicit Reader(const std::vector& payload) : Reader(payload.data(), payload.size()) + { + } + + uint8_t u8() + { + need(1); + return m_data[m_pos++]; + } + + uint16_t u16() + { + need(2); + uint16_t value = 0; + for (int i = 0; i < 2; ++i) + { + value = static_cast(value | (static_cast(m_data[m_pos++]) << (8 * i))); + } + return value; + } + + uint32_t u32() + { + need(4); + uint32_t value = 0; + for (int i = 0; i < 4; ++i) + { + value |= static_cast(m_data[m_pos++]) << (8 * i); + } + return value; + } + + uint64_t u64() + { + need(8); + uint64_t value = 0; + for (int i = 0; i < 8; ++i) + { + value |= static_cast(m_data[m_pos++]) << (8 * i); + } + return value; + } + + int64_t i64() + { + return static_cast(u64()); + } + + float f32() + { + const uint32_t bits = u32(); + float value = 0.0f; + std::memcpy(&value, &bits, sizeof(value)); + return value; + } + + std::string str() + { + const uint32_t size = u32(); + need(size); + std::string value(reinterpret_cast(m_data + m_pos), size); + m_pos += size; + return value; + } + + std::vector bytes(size_t size) + { + need(size); + std::vector value(m_data + m_pos, m_data + m_pos + size); + m_pos += size; + return value; + } + + XrPosef pose() + { + XrPosef value; + value.orientation.x = f32(); + value.orientation.y = f32(); + value.orientation.z = f32(); + value.orientation.w = f32(); + value.position.x = f32(); + value.position.y = f32(); + value.position.z = f32(); + return value; + } + + void finish() const + { + if (m_pos != m_size) + { + throw DecodeError("wire: " + std::to_string(m_size - m_pos) + " trailing bytes"); + } + } + +private: + void need(size_t count) const + { + if (m_size - m_pos < count) + { + throw DecodeError("wire: truncated payload"); + } + } + + const uint8_t* m_data; + size_t m_size; + size_t m_pos = 0; +}; + +uint8_t to_wire_hand(XrHandEXT hand) +{ + switch (hand) + { + case XR_HAND_LEFT_EXT: + return 0; + case XR_HAND_RIGHT_EXT: + return 1; + default: + throw std::invalid_argument("wire: unsupported XrHandEXT value"); + } +} + +XrHandEXT from_wire_hand(uint8_t hand) +{ + switch (hand) + { + case 0: + return XR_HAND_LEFT_EXT; + case 1: + return XR_HAND_RIGHT_EXT; + default: + throw DecodeError("wire: invalid hand value " + std::to_string(hand)); + } +} + +uint8_t to_wire_mode(core::WristTrackingSourceMode mode) +{ + switch (mode) + { + case core::WristTrackingSourceMode::Auto: + return 0; + case core::WristTrackingSourceMode::HandTracking: + return 1; + case core::WristTrackingSourceMode::Controller: + return 2; + } + throw std::invalid_argument("wire: unsupported wrist tracking source mode"); +} + +core::WristTrackingSourceMode from_wire_mode(uint8_t mode) +{ + switch (mode) + { + case 0: + return core::WristTrackingSourceMode::Auto; + case 1: + return core::WristTrackingSourceMode::HandTracking; + case 2: + return core::WristTrackingSourceMode::Controller; + default: + throw DecodeError("wire: invalid wrist tracking source mode " + std::to_string(mode)); + } +} + +//! Reserves the header, writes the payload behind it, then fills the header in with the resulting size. +template +std::vector build_frame(FrameType type, uint16_t channel_id, size_t payload_hint, WritePayload write_payload) +{ + std::vector out; + out.reserve(kHeaderSize + payload_hint); + out.resize(kHeaderSize); + Writer writer(out); + write_payload(writer); + if (out.size() - kHeaderSize > kMaxPayloadSize) + { + throw std::invalid_argument("wire: payload too large"); + } + FrameHeader header; + header.type = type; + header.channel_id = channel_id; + header.payload_size = static_cast(out.size() - kHeaderSize); + encode_header(header, out.data()); + return out; +} + +bool to_bool(uint8_t value) +{ + if (value > 1) + { + throw DecodeError("wire: invalid boolean value " + std::to_string(value)); + } + return value == 1; +} + +} // namespace + +const char* to_string(FrameType type) +{ + switch (type) + { + case FrameType::Hello: + return "HELLO"; + case FrameType::HelloAck: + return "HELLO_ACK"; + case FrameType::OpenHand: + return "OPEN_HAND"; + case FrameType::OpenSchema: + return "OPEN_SCHEMA"; + case FrameType::OpenPull: + return "OPEN_PULL"; + case FrameType::OpenWrist: + return "OPEN_WRIST"; + case FrameType::Close: + return "CLOSE"; + case FrameType::HandSample: + return "HAND_SAMPLE"; + case FrameType::SchemaSample: + return "SCHEMA_SAMPLE"; + case FrameType::WristSample: + return "WRIST_SAMPLE"; + case FrameType::Heartbeat: + return "HEARTBEAT"; + case FrameType::Error: + return "ERROR"; + case FrameType::Ping: + return "PING"; + case FrameType::Pong: + return "PONG"; + } + return "UNKNOWN"; +} + +void encode_header(const FrameHeader& header, uint8_t* out) +{ + std::vector bytes; + Writer writer(bytes); + writer.u32(kMagic); + writer.u8(static_cast(header.type)); + writer.u8(header.version); + writer.u16(header.channel_id); + writer.u32(header.seq); + writer.u32(header.payload_size); + writer.i64(header.t_send_monotonic_ns); + std::memcpy(out, bytes.data(), kHeaderSize); +} + +void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns) +{ + // Byte offsets follow encode_header: seq at 8, t_send at 16. + for (int i = 0; i < 4; ++i) + { + frame[8 + i] = static_cast(seq >> (8 * i)); + } + const uint64_t t_send = static_cast(t_send_monotonic_ns); + for (int i = 0; i < 8; ++i) + { + frame[16 + i] = static_cast(t_send >> (8 * i)); + } + // Pong payload: t1, t2, t3 (i64 each); t3 at payload offset 16. + if (frame[4] == static_cast(FrameType::Pong) && decode_header(frame).payload_size == 3 * sizeof(int64_t)) + { + for (int i = 0; i < 8; ++i) + { + frame[kHeaderSize + 16 + i] = static_cast(t_send >> (8 * i)); + } + } +} + +Frame split_frame(std::vector message) +{ + if (message.size() < kHeaderSize) + { + throw DecodeError("wire: message shorter than a header"); + } + Frame frame; + frame.header = decode_header(message.data()); + if (message.size() != kHeaderSize + frame.header.payload_size) + { + throw DecodeError("wire: message length does not match payload_size"); + } + message.erase(message.begin(), message.begin() + static_cast(kHeaderSize)); + frame.payload = std::move(message); + return frame; +} + +std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload) +{ + return build_frame( + type, channel_id, payload.size(), [&payload](Writer& writer) { writer.bytes(payload.data(), payload.size()); }); +} + +std::vector encode_hand_sample_frame(uint16_t channel_id, + const XrHandJointLocationEXT* joints, + int64_t sample_time_ns) +{ + return build_frame(FrameType::HandSample, channel_id, kHandSamplePayloadSize, + [&](Writer& writer) + { + writer.i64(sample_time_ns); + for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + { + writer.u64(joints[i].locationFlags); + writer.pose(joints[i].pose); + writer.f32(joints[i].radius); + } + }); +} + +std::vector encode_schema_sample_frame(uint16_t channel_id, + const uint8_t* bytes, + size_t size, + int64_t sample_time_local_common_clock_ns, + int64_t sample_time_raw_device_clock_ns) +{ + if (size > kMaxPayloadSize) + { + throw std::invalid_argument("wire: schema sample too large"); + } + return build_frame(FrameType::SchemaSample, channel_id, 2 * sizeof(int64_t) + sizeof(uint32_t) + size, + [&](Writer& writer) + { + writer.i64(sample_time_local_common_clock_ns); + writer.i64(sample_time_raw_device_clock_ns); + writer.u32(static_cast(size)); + writer.bytes(bytes, size); + }); +} + +FrameHeader decode_header(const uint8_t* in) +{ + Reader reader(in, kHeaderSize); + if (reader.u32() != kMagic) + { + throw DecodeError("wire: bad frame magic"); + } + FrameHeader header; + const uint8_t type = reader.u8(); + if (type < static_cast(FrameType::Hello) || type > static_cast(FrameType::Pong)) + { + throw DecodeError("wire: unknown frame type " + std::to_string(type)); + } + header.type = static_cast(type); + header.version = reader.u8(); + if (header.version != kProtocolVersion) + { + throw DecodeError("wire: unsupported protocol version " + std::to_string(header.version)); + } + header.channel_id = reader.u16(); + header.seq = reader.u32(); + header.payload_size = reader.u32(); + if (header.payload_size > kMaxPayloadSize) + { + throw DecodeError("wire: payload size " + std::to_string(header.payload_size) + " exceeds limit"); + } + header.t_send_monotonic_ns = reader.i64(); + reader.finish(); + return header; +} + +std::vector encode(const Hello& value) +{ + std::vector out; + Writer writer(out); + writer.u16(value.proto_version); + writer.str(value.app_name); + writer.u8(value.requirements.schema_push ? 1 : 0); + writer.u8(value.requirements.hand_tracking_push ? 1 : 0); + writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); + return out; +} + +std::vector encode(const HelloAck& value) +{ + std::vector out; + Writer writer(out); + writer.u8(value.accepted ? 1 : 0); + writer.str(value.reason); + return out; +} + +std::vector encode(const OpenHand& value) +{ + std::vector out; + Writer writer(out); + writer.u8(to_wire_hand(value.hand)); + return out; +} + +std::vector encode(const core::SchemaPusherConfig& value) +{ + std::vector out; + Writer writer(out); + writer.str(value.collection_id); + writer.u64(static_cast(value.max_flatbuffer_size)); + writer.str(value.tensor_identifier); + writer.str(value.localized_name); + writer.str(value.app_name); + return out; +} + +std::vector encode(const core::WristTrackingSourceConfig& value) +{ + std::vector out; + Writer writer(out); + writer.u8(to_wire_mode(value.mode)); + writer.pose(value.left_aim_to_wrist); + writer.pose(value.right_aim_to_wrist); + return out; +} + +std::vector encode(const WristSample& value) +{ + std::vector out; + Writer writer(out); + writer.i64(value.sample_time_ns); + writer.u8(value.is_left ? 1 : 0); + writer.u8(value.sample.valid ? 1 : 0); + writer.u8(value.sample.tracked ? 1 : 0); + writer.pose(value.sample.pose); + return out; +} + +std::vector encode(const Error& value) +{ + std::vector out; + Writer writer(out); + writer.str(value.message); + return out; +} + +std::vector encode(const Ping& value) +{ + std::vector out; + Writer writer(out); + writer.i64(value.t1_ns); + return out; +} + +std::vector encode(const Pong& value) +{ + std::vector out; + Writer writer(out); + writer.i64(value.t1_ns); + writer.i64(value.t2_ns); + writer.i64(value.t3_ns); + return out; +} + +Hello decode_hello(const std::vector& payload) +{ + Reader reader(payload); + Hello value; + value.proto_version = reader.u16(); + value.app_name = reader.str(); + value.requirements.schema_push = to_bool(reader.u8()); + value.requirements.hand_tracking_push = to_bool(reader.u8()); + value.requirements.wrist_tracking_pull = to_bool(reader.u8()); + reader.finish(); + return value; +} + +HelloAck decode_hello_ack(const std::vector& payload) +{ + Reader reader(payload); + HelloAck value; + value.accepted = to_bool(reader.u8()); + value.reason = reader.str(); + reader.finish(); + return value; +} + +OpenHand decode_open_hand(const std::vector& payload) +{ + Reader reader(payload); + OpenHand value; + value.hand = from_wire_hand(reader.u8()); + reader.finish(); + return value; +} + +core::SchemaPusherConfig decode_open_schema(const std::vector& payload) +{ + Reader reader(payload); + core::SchemaPusherConfig value; + value.collection_id = reader.str(); + value.max_flatbuffer_size = static_cast(reader.u64()); + value.tensor_identifier = reader.str(); + value.localized_name = reader.str(); + value.app_name = reader.str(); + reader.finish(); + return value; +} + +core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) +{ + Reader reader(payload); + core::WristTrackingSourceConfig value; + value.mode = from_wire_mode(reader.u8()); + value.left_aim_to_wrist = reader.pose(); + value.right_aim_to_wrist = reader.pose(); + reader.finish(); + return value; +} + +HandSample decode_hand_sample(const std::vector& payload) +{ + Reader reader(payload); + HandSample value; + value.sample_time_ns = reader.i64(); + for (XrHandJointLocationEXT& joint : value.joints) + { + joint.locationFlags = reader.u64(); + joint.pose = reader.pose(); + joint.radius = reader.f32(); + } + reader.finish(); + return value; +} + +SchemaSample decode_schema_sample(const std::vector& payload) +{ + Reader reader(payload); + SchemaSample value; + value.sample_time_local_common_clock_ns = reader.i64(); + value.sample_time_raw_device_clock_ns = reader.i64(); + const uint32_t size = reader.u32(); + value.bytes = reader.bytes(size); + reader.finish(); + return value; +} + +WristSample decode_wrist_sample(const std::vector& payload) +{ + Reader reader(payload); + WristSample value; + value.sample_time_ns = reader.i64(); + value.is_left = to_bool(reader.u8()); + value.sample.valid = to_bool(reader.u8()); + value.sample.tracked = to_bool(reader.u8()); + value.sample.pose = reader.pose(); + reader.finish(); + return value; +} + +Error decode_error(const std::vector& payload) +{ + Reader reader(payload); + Error value; + value.message = reader.str(); + reader.finish(); + return value; +} + +Ping decode_ping(const std::vector& payload) +{ + Reader reader(payload); + Ping value; + value.t1_ns = reader.i64(); + reader.finish(); + return value; +} + +Pong decode_pong(const std::vector& payload) +{ + Reader reader(payload); + Pong value; + value.t1_ns = reader.i64(); + value.t2_ns = reader.i64(); + value.t3_ns = reader.i64(); + reader.finish(); + return value; +} + +} // namespace wire +} // namespace remote_plugin_session diff --git a/tests/cpp/plugins/CMakeLists.txt b/tests/cpp/plugins/CMakeLists.txt index fd7e2d2e68..51d4666a9e 100644 --- a/tests/cpp/plugins/CMakeLists.txt +++ b/tests/cpp/plugins/CMakeLists.txt @@ -21,3 +21,7 @@ endif() if(TARGET manus_calibration_core) add_subdirectory(manus_calibration) endif() + +if(TARGET Teleop::remote_plugin_session) + add_subdirectory(remote_device_bridge) +endif() diff --git a/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt new file mode 100644 index 0000000000..2d8fe4acf3 --- /dev/null +++ b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt @@ -0,0 +1,16 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +cmake_minimum_required(VERSION 3.20) + +add_executable(remote_plugin_session_tests + test_wire_codec.cpp +) + +target_link_libraries(remote_plugin_session_tests PRIVATE + Teleop::remote_plugin_session + pusherio::pusherio + Catch2::Catch2WithMain +) + +catch_discover_tests(remote_plugin_session_tests ADD_TAGS_AS_LABELS) diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp new file mode 100644 index 0000000000..e47d685549 --- /dev/null +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -0,0 +1,438 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include + +#include +#include +#include +#include +#include +#include + +using namespace remote_plugin_session; + +namespace +{ + +bool same_pose(const XrPosef& a, const XrPosef& b) +{ + return std::memcmp(&a, &b, sizeof(XrPosef)) == 0; +} + +XrPosef make_pose(float seed) +{ + return { { seed, seed + 0.25f, -seed, 0.5f }, { 10.0f * seed, -20.0f * seed, 30.0f * seed } }; +} + +void put_u32(std::vector& out, uint32_t v) +{ + for (int i = 0; i < 4; ++i) + { + out.push_back(static_cast(v >> (8 * i))); + } +} + +void put_u64(std::vector& out, uint64_t v) +{ + put_u32(out, static_cast(v)); + put_u32(out, static_cast(v >> 32)); +} + +void put_f32(std::vector& out, float v) +{ + uint32_t bits = 0; + std::memcpy(&bits, &v, sizeof(bits)); + put_u32(out, bits); +} + +//! Reference payload encoder (the pre-frame-builder layout) kept as the golden for HAND_SAMPLE. +std::vector reference_hand_payload(const wire::HandSample& sample) +{ + std::vector out; + put_u64(out, static_cast(sample.sample_time_ns)); + for (const XrHandJointLocationEXT& joint : sample.joints) + { + put_u64(out, joint.locationFlags); + for (const float f : + { joint.pose.orientation.x, joint.pose.orientation.y, joint.pose.orientation.z, joint.pose.orientation.w, + joint.pose.position.x, joint.pose.position.y, joint.pose.position.z, joint.radius }) + { + put_f32(out, f); + } + } + return out; +} + +std::vector hand_payload(const wire::HandSample& sample) +{ + return wire::split_frame(wire::encode_hand_sample_frame(1, sample.joints.data(), sample.sample_time_ns)).payload; +} + +std::vector schema_payload(const wire::SchemaSample& sample) +{ + return wire::split_frame(wire::encode_schema_sample_frame(1, sample.bytes.data(), sample.bytes.size(), + sample.sample_time_local_common_clock_ns, + sample.sample_time_raw_device_clock_ns)) + .payload; +} + +} // namespace + +TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit]") +{ + wire::FrameHeader header; + header.type = wire::FrameType::HandSample; + header.channel_id = 0xBEEF; + header.seq = 0x01020304; + header.payload_size = static_cast(wire::kHandSamplePayloadSize); + header.t_send_monotonic_ns = -1234567890123LL; + + uint8_t bytes[wire::kHeaderSize]; + wire::encode_header(header, bytes); + REQUIRE(bytes[0] == 0x52); // little-endian "RPS0" + REQUIRE(bytes[1] == 0x50); + REQUIRE(bytes[2] == 0x53); + REQUIRE(bytes[3] == 0x30); + + const wire::FrameHeader decoded = wire::decode_header(bytes); + REQUIRE(decoded.type == wire::FrameType::HandSample); + REQUIRE(decoded.version == wire::kProtocolVersion); + REQUIRE(decoded.channel_id == 0xBEEF); + REQUIRE(decoded.seq == 0x01020304); + REQUIRE(decoded.payload_size == wire::kHandSamplePayloadSize); + REQUIRE(decoded.t_send_monotonic_ns == -1234567890123LL); + + SECTION("bad magic is rejected") + { + bytes[0] ^= 0xFF; + REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + } + SECTION("unknown type is rejected") + { + bytes[4] = 200; + REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + } + SECTION("other protocol versions are rejected") + { + bytes[5] = 1; + REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + } + SECTION("oversized payloads are rejected") + { + std::memset(bytes + 12, 0xFF, 4); + REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + } +} + +TEST_CASE("Wire contract v1 is 12 message types plus PING and PONG in a 24-byte header", "[remote_device_bridge][unit]") +{ + const std::vector> contract = { + { wire::FrameType::Hello, "HELLO" }, + { wire::FrameType::HelloAck, "HELLO_ACK" }, + { wire::FrameType::OpenHand, "OPEN_HAND" }, + { wire::FrameType::OpenSchema, "OPEN_SCHEMA" }, + { wire::FrameType::OpenPull, "OPEN_PULL" }, + { wire::FrameType::OpenWrist, "OPEN_WRIST" }, + { wire::FrameType::Close, "CLOSE" }, + { wire::FrameType::HandSample, "HAND_SAMPLE" }, + { wire::FrameType::SchemaSample, "SCHEMA_SAMPLE" }, + { wire::FrameType::WristSample, "WRIST_SAMPLE" }, + { wire::FrameType::Heartbeat, "HEARTBEAT" }, + { wire::FrameType::Error, "ERROR" }, + { wire::FrameType::Ping, "PING" }, // bridge -> sender, t1 + { wire::FrameType::Pong, "PONG" }, // sender -> bridge, t1 t2 t3 + }; + for (size_t i = 0; i < contract.size(); ++i) + { + REQUIRE(static_cast(contract[i].first) == i + 1); + REQUIRE(std::string(wire::to_string(contract[i].first)) == contract[i].second); + } + REQUIRE(wire::kHeaderSize == 24); + REQUIRE(wire::kProtocolVersion == 0); + REQUIRE(wire::kHelloVersion == 1); + + // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. + wire::FrameHeader header; + header.type = wire::FrameType::Pong; + header.channel_id = 0x0A0B; + header.seq = 0x0C0D0E0F; + header.payload_size = 24; + header.t_send_monotonic_ns = 0x1112131415161718LL; + uint8_t bytes[wire::kHeaderSize]; + wire::encode_header(header, bytes); + const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, + 24, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; + REQUIRE(std::vector(bytes, bytes + wire::kHeaderSize) == expected); + + for (const uint8_t type : { 0, 15 }) + { + bytes[4] = type; + REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + } +} + +TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") +{ + wire::Hello hello; + hello.app_name = "ManusHandPlugin"; + hello.requirements = { .schema_push = true, .hand_tracking_push = false, .wrist_tracking_pull = true }; + const wire::Hello decoded = wire::decode_hello(wire::encode(hello)); + REQUIRE(decoded.proto_version == wire::kHelloVersion); + REQUIRE(decoded.app_name == "ManusHandPlugin"); + REQUIRE(decoded.requirements.schema_push); + REQUIRE_FALSE(decoded.requirements.hand_tracking_push); + REQUIRE(decoded.requirements.wrist_tracking_pull); + + const wire::HelloAck ack = wire::decode_hello_ack(wire::encode(wire::HelloAck{ false, "no runtime" })); + REQUIRE_FALSE(ack.accepted); + REQUIRE(ack.reason == "no runtime"); + + const wire::HelloAck ok = wire::decode_hello_ack(wire::encode(wire::HelloAck{ true, "" })); + REQUIRE(ok.accepted); + REQUIRE(ok.reason.empty()); +} + +TEST_CASE("OPEN_HAND encodes both hands and rejects others", "[remote_device_bridge][unit]") +{ + REQUIRE(wire::encode(wire::OpenHand{ XR_HAND_LEFT_EXT }) == std::vector{ 0 }); + REQUIRE(wire::encode(wire::OpenHand{ XR_HAND_RIGHT_EXT }) == std::vector{ 1 }); + REQUIRE(wire::decode_open_hand({ 0 }).hand == XR_HAND_LEFT_EXT); + REQUIRE(wire::decode_open_hand({ 1 }).hand == XR_HAND_RIGHT_EXT); + REQUIRE_THROWS_AS(wire::decode_open_hand({ 2 }), wire::DecodeError); + REQUIRE_THROWS_AS(wire::decode_open_hand({}), wire::DecodeError); + REQUIRE_THROWS_AS(wire::decode_open_hand({ 0, 0 }), wire::DecodeError); +} + +TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][unit]") +{ + core::SchemaPusherConfig config{ .collection_id = "manus_sensors_left", + .max_flatbuffer_size = 4096, + .tensor_identifier = "joint_state", + .localized_name = "Manus Sensors Left", + .app_name = "" }; + const core::SchemaPusherConfig decoded = wire::decode_open_schema(wire::encode(config)); + REQUIRE(decoded.collection_id == config.collection_id); + REQUIRE(decoded.max_flatbuffer_size == 4096); + REQUIRE(decoded.tensor_identifier == config.tensor_identifier); + REQUIRE(decoded.localized_name == config.localized_name); + REQUIRE(decoded.app_name.empty()); + + std::vector truncated = wire::encode(config); + truncated.pop_back(); + REQUIRE_THROWS_AS(wire::decode_open_schema(truncated), wire::DecodeError); +} + +TEST_CASE("OPEN_WRIST round-trips WristTrackingSourceConfig", "[remote_device_bridge][unit]") +{ + core::WristTrackingSourceConfig config; + config.mode = core::WristTrackingSourceMode::Controller; + config.left_aim_to_wrist = make_pose(0.1f); + config.right_aim_to_wrist = make_pose(0.7f); + + const std::vector bytes = wire::encode(config); + REQUIRE(bytes.size() == wire::kWristConfigPayloadSize); + const core::WristTrackingSourceConfig decoded = wire::decode_open_wrist(bytes); + REQUIRE(decoded.mode == core::WristTrackingSourceMode::Controller); + REQUIRE(same_pose(decoded.left_aim_to_wrist, config.left_aim_to_wrist)); + REQUIRE(same_pose(decoded.right_aim_to_wrist, config.right_aim_to_wrist)); + + REQUIRE(wire::decode_open_wrist(wire::encode(core::WristTrackingSourceConfig{})).mode == + core::WristTrackingSourceMode::Auto); + std::vector bad_mode = bytes; + bad_mode[0] = 7; + REQUIRE_THROWS_AS(wire::decode_open_wrist(bad_mode), wire::DecodeError); +} + +TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge][unit]") +{ + wire::HandSample sample; + sample.sample_time_ns = 987654321012345LL; + for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + { + sample.joints[static_cast(i)].locationFlags = 0xF000000000000000ULL | static_cast(i); + sample.joints[static_cast(i)].pose = make_pose(0.01f * static_cast(i + 1)); + sample.joints[static_cast(i)].radius = 0.001f * static_cast(i); + } + + const std::vector bytes = hand_payload(sample); + REQUIRE(bytes.size() == wire::kHandSamplePayloadSize); + + const wire::HandSample decoded = wire::decode_hand_sample(bytes); + REQUIRE(decoded.sample_time_ns == sample.sample_time_ns); + for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + { + REQUIRE(decoded.joints[i].locationFlags == sample.joints[i].locationFlags); + REQUIRE(same_pose(decoded.joints[i].pose, sample.joints[i].pose)); + REQUIRE(std::memcmp(&decoded.joints[i].radius, &sample.joints[i].radius, sizeof(float)) == 0); + } + + std::vector truncated(bytes.begin(), bytes.end() - 1); + REQUIRE_THROWS_AS(wire::decode_hand_sample(truncated), wire::DecodeError); + std::vector extended = bytes; + extended.push_back(0); + REQUIRE_THROWS_AS(wire::decode_hand_sample(extended), wire::DecodeError); +} + +TEST_CASE("SCHEMA_SAMPLE round-trips bytes and timestamps", "[remote_device_bridge][unit]") +{ + wire::SchemaSample sample; + sample.sample_time_local_common_clock_ns = 111; + sample.sample_time_raw_device_clock_ns = 222; + sample.bytes = { 0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01 }; + + const wire::SchemaSample decoded = wire::decode_schema_sample(schema_payload(sample)); + REQUIRE(decoded.sample_time_local_common_clock_ns == 111); + REQUIRE(decoded.sample_time_raw_device_clock_ns == 222); + REQUIRE(decoded.bytes == sample.bytes); + + const wire::SchemaSample empty = wire::decode_schema_sample(schema_payload(wire::SchemaSample{})); + REQUIRE(empty.bytes.empty()); + + std::vector lying = schema_payload(sample); + lying[16] = 0xFF; // declared size larger than the remaining bytes + REQUIRE_THROWS_AS(wire::decode_schema_sample(lying), wire::DecodeError); +} + +TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") +{ + wire::WristSample sample; + sample.sample_time_ns = -5; + sample.is_left = false; + sample.sample.valid = true; + sample.sample.tracked = false; + sample.sample.pose = make_pose(0.3f); + + const std::vector bytes = wire::encode(sample); + REQUIRE(bytes.size() == wire::kWristSamplePayloadSize); + const wire::WristSample decoded = wire::decode_wrist_sample(bytes); + REQUIRE(decoded.sample_time_ns == -5); + REQUIRE_FALSE(decoded.is_left); + REQUIRE(decoded.sample.valid); + REQUIRE_FALSE(decoded.sample.tracked); + REQUIRE(same_pose(decoded.sample.pose, sample.sample.pose)); + + std::vector bad_bool = bytes; + bad_bool[9] = 2; + REQUIRE_THROWS_AS(wire::decode_wrist_sample(bad_bool), wire::DecodeError); +} + +TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_bridge][unit]") +{ + REQUIRE(wire::decode_error(wire::encode(wire::Error{ "boom" })).message == "boom"); + REQUIRE(wire::decode_error(wire::encode(wire::Error{ "" })).message.empty()); + REQUIRE_THROWS_AS(wire::decode_error({ 4, 0, 0, 0, 'a' }), wire::DecodeError); + REQUIRE(std::string(wire::to_string(wire::FrameType::Heartbeat)) == "HEARTBEAT"); +} + +TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remote_device_bridge][unit]") +{ + const std::vector ping = wire::encode(wire::Ping{ -123456789012345LL }); + REQUIRE(ping.size() == 8); + REQUIRE(wire::decode_ping(ping).t1_ns == -123456789012345LL); + REQUIRE_THROWS_AS(wire::decode_ping({ 1, 2, 3 }), wire::DecodeError); + + const std::vector payload = wire::encode(wire::Pong{ 1, 2, 3 }); + REQUIRE(payload.size() == 24); + const wire::Pong pong = wire::decode_pong(payload); + REQUIRE(pong.t1_ns == 1); + REQUIRE(pong.t2_ns == 2); + REQUIRE(pong.t3_ns == 3); + REQUIRE_THROWS_AS(wire::decode_pong(std::vector(25, 0)), wire::DecodeError); + + std::vector frame = wire::encode_frame(wire::FrameType::Pong, wire::kSessionChannelId, payload); + wire::stamp_header(frame.data(), 7, 0x0102030405060708LL); + const wire::Frame split = wire::split_frame(frame); + REQUIRE(split.header.type == wire::FrameType::Pong); + REQUIRE(split.header.t_send_monotonic_ns == 0x0102030405060708LL); + const wire::Pong stamped = wire::decode_pong(split.payload); + REQUIRE(stamped.t1_ns == 1); + REQUIRE(stamped.t2_ns == 2); + REQUIRE(stamped.t3_ns == 0x0102030405060708LL); + + // stamp_header leaves the payload of every other frame type alone. + std::vector ping_frame = wire::encode_frame(wire::FrameType::Ping, wire::kSessionChannelId, ping); + wire::stamp_header(ping_frame.data(), 8, 42); + REQUIRE(wire::decode_ping(wire::split_frame(ping_frame).payload).t1_ns == -123456789012345LL); + REQUIRE(std::string(wire::to_string(wire::FrameType::Ping)) == "PING"); + REQUIRE(std::string(wire::to_string(wire::FrameType::Pong)) == "PONG"); +} + +TEST_CASE("Contiguous frame builders match header + payload encoder byte for byte", "[remote_device_bridge][unit]") +{ + SECTION("SCHEMA_SAMPLE against a hand-built golden frame") + { + const std::vector bytes = { 0xDE, 0xAD }; + std::vector frame = + wire::encode_schema_sample_frame(3, bytes.data(), bytes.size(), 0x0102030405060708LL, -1); + // clang-format off + const std::vector golden = { + 0x52, 0x50, 0x53, 0x30, // magic "RPS0" + 0x09, 0x00, // type SCHEMA_SAMPLE, version 0 + 0x03, 0x00, // channel 3 + 0x00, 0x00, 0x00, 0x00, // seq (unstamped) + 0x16, 0x00, 0x00, 0x00, // payload_size 22 + 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // t_send (unstamped) + 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01, // sample_time_local_common_clock_ns + 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, // sample_time_raw_device_clock_ns = -1 + 0x02, 0x00, 0x00, 0x00, // byte count + 0xDE, 0xAD, + }; + // clang-format on + REQUIRE(frame == golden); + + wire::stamp_header(frame.data(), 0x11223344u, 0x0807060504030201LL); + REQUIRE(std::vector(frame.begin() + 8, frame.begin() + 12) == + std::vector{ 0x44, 0x33, 0x22, 0x11 }); + REQUIRE(std::vector(frame.begin() + 16, frame.begin() + 24) == + std::vector{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 }); + REQUIRE(std::equal(frame.begin() + 24, frame.end(), golden.begin() + 24)); // payload untouched + + const wire::Frame split = wire::split_frame(frame); + REQUIRE(split.header.type == wire::FrameType::SchemaSample); + REQUIRE(split.header.channel_id == 3); + REQUIRE(split.header.seq == 0x11223344u); + REQUIRE(split.header.t_send_monotonic_ns == 0x0807060504030201LL); + REQUIRE(split.payload == std::vector(golden.begin() + 24, golden.end())); + wire::SchemaSample decoded = wire::decode_schema_sample(split.payload); + REQUIRE(decoded.bytes == bytes); + REQUIRE(decoded.sample_time_raw_device_clock_ns == -1); + } + SECTION("HAND_SAMPLE against the reference payload encoder") + { + wire::HandSample sample; + sample.sample_time_ns = -42; + for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + { + sample.joints[i].locationFlags = 0xA000000000000000ULL | i; + sample.joints[i].pose = make_pose(0.02f * static_cast(i + 1)); + sample.joints[i].radius = 0.001f * static_cast(i); + } + const std::vector payload = reference_hand_payload(sample); + REQUIRE(payload.size() == wire::kHandSamplePayloadSize); + const std::vector frame = wire::encode_hand_sample_frame(0x0102, sample.joints.data(), -42); + REQUIRE(frame.size() == wire::kHeaderSize + wire::kHandSamplePayloadSize); + const wire::FrameHeader header = wire::decode_header(frame.data()); + REQUIRE(header.type == wire::FrameType::HandSample); + REQUIRE(header.channel_id == 0x0102); + REQUIRE(header.payload_size == wire::kHandSamplePayloadSize); + REQUIRE(std::equal(frame.begin() + 24, frame.end(), payload.begin(), payload.end())); + REQUIRE(wire::encode_frame(wire::FrameType::HandSample, 0x0102, payload) == frame); + } + SECTION("split_frame rejects short or inconsistent messages") + { + REQUIRE_THROWS_AS(wire::split_frame(std::vector(10, 0)), wire::DecodeError); + std::vector frame = wire::encode_frame(wire::FrameType::Heartbeat, 0, {}); + REQUIRE(frame.size() == wire::kHeaderSize); + REQUIRE(wire::split_frame(frame).payload.empty()); + frame.push_back(0); + REQUIRE_THROWS_AS(wire::split_frame(frame), wire::DecodeError); + } + SECTION("payloads above the limit are refused at build time") + { + std::vector too_big(wire::kMaxPayloadSize + 1); + REQUIRE_THROWS_AS( + wire::encode_schema_sample_frame(1, too_big.data(), too_big.size(), 0, 0), std::invalid_argument); + } +} From b62a77f63ee0c83ca1f58715cc26dcc589aaedc3 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:11:16 -0700 Subject: [PATCH 02/18] rebase onto pr00 review PluginSessionRequirements::wrist_tracking_pull is now an optional, so HELLO carries the wrist config (mode + both aim-to-wrist poses, same layout as OPEN_WRIST) behind its presence byte instead of a bool. HELLO proto_version goes 1 -> 2 and decode_hello rejects older versions, whose payload layout differs. The 24-byte frame header and kProtocolVersion are unchanged. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../inc/remote_plugin_session/wire_codec.hpp | 6 +-- .../session/wire_codec.cpp | 39 +++++++++++++++---- .../remote_device_bridge/test_wire_codec.cpp | 18 ++++++++- 3 files changed, 50 insertions(+), 13 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp index c7697065d8..e8f4ea2c02 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp @@ -28,9 +28,9 @@ namespace wire constexpr uint32_t kMagic = 0x30535052u; // "RPS0" constexpr uint8_t kProtocolVersion = 0; -//! HELLO proto_version: 1 = the client answers PING with PONG. The bridge still accepts 0 and never PINGs it -//! (a v0 client fails on unknown frame types). -constexpr uint16_t kHelloVersion = 1; +//! HELLO proto_version: 2 = requirements carry the wrist source config (not a flag) and the client answers +//! PING with PONG. decode_hello rejects older versions, whose payload layout differs. +constexpr uint16_t kHelloVersion = 2; constexpr size_t kHeaderSize = 24; constexpr uint16_t kSessionChannelId = 0; constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded diff --git a/src/plugins/remote_device_bridge/session/wire_codec.cpp b/src/plugins/remote_device_bridge/session/wire_codec.cpp index 1ac2036342..9dc4e864a2 100644 --- a/src/plugins/remote_device_bridge/session/wire_codec.cpp +++ b/src/plugins/remote_device_bridge/session/wire_codec.cpp @@ -293,6 +293,22 @@ bool to_bool(uint8_t value) return value == 1; } +void write_wrist_config(Writer& writer, const core::WristTrackingSourceConfig& value) +{ + writer.u8(to_wire_mode(value.mode)); + writer.pose(value.left_aim_to_wrist); + writer.pose(value.right_aim_to_wrist); +} + +core::WristTrackingSourceConfig read_wrist_config(Reader& reader) +{ + core::WristTrackingSourceConfig value; + value.mode = from_wire_mode(reader.u8()); + value.left_aim_to_wrist = reader.pose(); + value.right_aim_to_wrist = reader.pose(); + return value; +} + } // namespace const char* to_string(FrameType type) @@ -467,6 +483,10 @@ std::vector encode(const Hello& value) writer.u8(value.requirements.schema_push ? 1 : 0); writer.u8(value.requirements.hand_tracking_push ? 1 : 0); writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); + if (value.requirements.wrist_tracking_pull) + { + write_wrist_config(writer, *value.requirements.wrist_tracking_pull); + } return out; } @@ -503,9 +523,7 @@ std::vector encode(const core::WristTrackingSourceConfig& value) { std::vector out; Writer writer(out); - writer.u8(to_wire_mode(value.mode)); - writer.pose(value.left_aim_to_wrist); - writer.pose(value.right_aim_to_wrist); + write_wrist_config(writer, value); return out; } @@ -552,10 +570,18 @@ Hello decode_hello(const std::vector& payload) Reader reader(payload); Hello value; value.proto_version = reader.u16(); + if (value.proto_version < kHelloVersion) + { + throw DecodeError("wire: HELLO version " + std::to_string(value.proto_version) + " is older than " + + std::to_string(kHelloVersion)); + } value.app_name = reader.str(); value.requirements.schema_push = to_bool(reader.u8()); value.requirements.hand_tracking_push = to_bool(reader.u8()); - value.requirements.wrist_tracking_pull = to_bool(reader.u8()); + if (to_bool(reader.u8())) + { + value.requirements.wrist_tracking_pull = read_wrist_config(reader); + } reader.finish(); return value; } @@ -595,10 +621,7 @@ core::SchemaPusherConfig decode_open_schema(const std::vector& payload) core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) { Reader reader(payload); - core::WristTrackingSourceConfig value; - value.mode = from_wire_mode(reader.u8()); - value.left_aim_to_wrist = reader.pose(); - value.right_aim_to_wrist = reader.pose(); + const core::WristTrackingSourceConfig value = read_wrist_config(reader); reader.finish(); return value; } diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index e47d685549..704a3254b7 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -151,7 +151,7 @@ TEST_CASE("Wire contract v1 is 12 message types plus PING and PONG in a 24-byte } REQUIRE(wire::kHeaderSize == 24); REQUIRE(wire::kProtocolVersion == 0); - REQUIRE(wire::kHelloVersion == 1); + REQUIRE(wire::kHelloVersion == 2); // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. wire::FrameHeader header; @@ -177,13 +177,27 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") { wire::Hello hello; hello.app_name = "ManusHandPlugin"; - hello.requirements = { .schema_push = true, .hand_tracking_push = false, .wrist_tracking_pull = true }; + const core::WristTrackingSourceConfig wrist{ + .mode = core::WristTrackingSourceMode::Controller, + .left_aim_to_wrist = { { 0.0f, 0.0f, 0.0f, 1.0f }, { 1.0f, 2.0f, 3.0f } }, + .right_aim_to_wrist = { { 0.0f, 1.0f, 0.0f, 0.0f }, { -1.0f, 0.5f, 0.25f } } + }; + hello.requirements = { .schema_push = true, .hand_tracking_push = false, .wrist_tracking_pull = wrist }; const wire::Hello decoded = wire::decode_hello(wire::encode(hello)); REQUIRE(decoded.proto_version == wire::kHelloVersion); REQUIRE(decoded.app_name == "ManusHandPlugin"); REQUIRE(decoded.requirements.schema_push); REQUIRE_FALSE(decoded.requirements.hand_tracking_push); REQUIRE(decoded.requirements.wrist_tracking_pull); + REQUIRE(decoded.requirements.wrist_tracking_pull->mode == core::WristTrackingSourceMode::Controller); + REQUIRE(decoded.requirements.wrist_tracking_pull->left_aim_to_wrist.position.y == 2.0f); + REQUIRE(decoded.requirements.wrist_tracking_pull->right_aim_to_wrist.orientation.y == 1.0f); + + hello.requirements.wrist_tracking_pull.reset(); + REQUIRE_FALSE(wire::decode_hello(wire::encode(hello)).requirements.wrist_tracking_pull); + + hello.proto_version = 1; + REQUIRE_THROWS_AS(wire::decode_hello(wire::encode(hello)), wire::DecodeError); const wire::HelloAck ack = wire::decode_hello_ack(wire::encode(wire::HelloAck{ false, "no runtime" })); REQUIRE_FALSE(ack.accepted); From b8acc2f49e740de21aaafd18fb0949c572941b43 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:13:37 -0700 Subject: [PATCH 03/18] wire codec: split frame layer from payload codecs Addresses the #1321 review: the codec becomes remote_plugin_protocol. - protocol_frame.{hpp,cpp}: header constants, FrameType, FrameHeader, Frame, DecodeError, encode_header/decode_header, encode_frame, stamp_header, split_frame. - protocol_payloads.{hpp,cpp}: one named builder/parser pair per frame type (encode_hello/decode_hello, ...), plus the sample frame builders. - protocol_io.hpp (private): the little-endian Writer/Reader shared by both. - Single-field payload structs are gone: OPEN_HAND, ERROR and PING build from and parse to XrHandEXT, std::string and int64_t. - to_string(FrameType) is private to protocol_payloads.cpp, where parsers use it to name the frame in DecodeError messages. - WristSample carries XrHandEXT instead of bool is_left; its wire byte keeps its meaning (1 = left). The 24-byte header and every payload layout are unchanged. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/remote_device_bridge/AGENTS.md | 2 +- .../session/CMakeLists.txt | 7 +- .../remote_plugin_session/protocol_frame.hpp | 82 ++ .../protocol_payloads.hpp | 115 +++ .../inc/remote_plugin_session/wire_codec.hpp | 195 ----- .../session/protocol_frame.cpp | 109 +++ .../session/protocol_io.hpp | 240 ++++++ .../session/protocol_payloads.cpp | 407 ++++++++++ .../session/wire_codec.cpp | 699 ------------------ .../remote_device_bridge/test_wire_codec.cpp | 248 +++---- 10 files changed, 1081 insertions(+), 1023 deletions(-) create mode 100644 src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp create mode 100644 src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp delete mode 100644 src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp create mode 100644 src/plugins/remote_device_bridge/session/protocol_frame.cpp create mode 100644 src/plugins/remote_device_bridge/session/protocol_io.hpp create mode 100644 src/plugins/remote_device_bridge/session/protocol_payloads.cpp delete mode 100644 src/plugins/remote_device_bridge/session/wire_codec.cpp diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index bab6f07eee..d9f35d471d 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -7,5 +7,5 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. -- `session/wire_codec.{hpp,cpp}` is the single serialization point. Every frame type is encoded and decoded there and nowhere else; changing the wire format means changing that file and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. +- `session/protocol_frame.*` (header and frame layer) and `session/protocol_payloads.*` (one builder/parser pair per frame type) are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. - `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin using `--remote` must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/CMakeLists.txt b/src/plugins/remote_device_bridge/session/CMakeLists.txt index 599bca58a4..b13809cd7f 100644 --- a/src/plugins/remote_device_bridge/session/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/session/CMakeLists.txt @@ -7,8 +7,11 @@ cmake_minimum_required(VERSION 3.20) # plugin that offers --remote. It must never link the OpenXR loader or # plugin_utils: plugin processes using it stay free of an OpenXR runtime. add_library(remote_plugin_session STATIC - wire_codec.cpp - inc/remote_plugin_session/wire_codec.hpp + protocol_frame.cpp + protocol_payloads.cpp + protocol_io.hpp + inc/remote_plugin_session/protocol_frame.hpp + inc/remote_plugin_session/protocol_payloads.hpp ) target_include_directories(remote_plugin_session diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp new file mode 100644 index 0000000000..64352ffc8a --- /dev/null +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -0,0 +1,82 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include +#include +#include +#include + +namespace remote_plugin_protocol +{ + +/*! + * Remote plugin protocol v0: fixed little-endian frames over one connection per + * plugin session. Frame = 24-byte header + payload. Payload layouts live in + * protocol_payloads.hpp. + */ + +constexpr uint32_t kMagic = 0x30535052u; // "RPS0" +constexpr uint8_t kProtocolVersion = 0; +constexpr size_t kHeaderSize = 24; +constexpr uint16_t kSessionChannelId = 0; +constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded + +enum class FrameType : uint8_t +{ + Hello = 1, // c->s: proto_version, app_name, requirements + HelloAck = 2, // s->c: accepted, reason + OpenHand = 3, // c->s: hand (0 left, 1 right) + OpenSchema = 4, // c->s: SchemaPusherConfig + OpenPull = 5, // c->s: empty + OpenWrist = 6, // c->s: WristTrackingSourceConfig on the pull channel id + Close = 7, // c->s: empty + HandSample = 8, // c->s: sample_time + 26 joints + SchemaSample = 9, // c->s: two timestamps + bytes + WristSample = 10, // s->c: sample_time, hand, valid, tracked, pose + Heartbeat = 11, // both: empty + Error = 12, // s->c: message; on channel 0 the connection closes afterwards, on a channel id only that + // channel is refused + Ping = 13, // s->c: t1 (bridge send time) + Pong = 14, // c->s: t1 echoed, t2 (client receive time), t3 (client send time) +}; + +struct FrameHeader +{ + FrameType type = FrameType::Heartbeat; + uint8_t version = kProtocolVersion; + uint16_t channel_id = kSessionChannelId; + uint32_t seq = 0; + uint32_t payload_size = 0; + int64_t t_send_monotonic_ns = 0; +}; + +struct Frame +{ + FrameHeader header; + std::vector payload; +}; + +class DecodeError : public std::runtime_error +{ +public: + using std::runtime_error::runtime_error; +}; + +static_assert(kHeaderSize == 4 + 1 + 1 + 2 + 4 + 4 + 8); + +//! `out` must hold kHeaderSize bytes. +void encode_header(const FrameHeader& header, uint8_t* out); +//! Throws DecodeError on bad magic, unknown type, unsupported version or an oversized payload. +FrameHeader decode_header(const uint8_t* in); + +//! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(). +std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); +//! Patches seq and t_send into an encoded frame's header in place; on a PONG also sets t3 = t_send, so t3 is +//! the time the frame actually left, not when it was queued. +void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns); +//! Splits one complete message into header and payload (payload moved, not copied). Throws DecodeError. +Frame split_frame(std::vector message); + +} // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp new file mode 100644 index 0000000000..74faa7195e --- /dev/null +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -0,0 +1,115 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include "protocol_frame.hpp" + +#include +#include + +#include +#include +#include +#include +#include + +namespace remote_plugin_protocol +{ + +/*! + * Payload builders and parsers, one pair per frame type. `str` = u32 length + + * bytes, `pose` = 7 x f32 in XrPosef order (orientation x,y,z,w then position + * x,y,z). Swapping the hand payload for a FlatBuffer later only changes the + * HAND_SAMPLE pair here. + */ + +//! HELLO proto_version: 2 = requirements carry the wrist source config (not a flag) and the client answers +//! PING with PONG. decode_hello rejects older versions, whose payload layout differs. +constexpr uint16_t kHelloVersion = 2; + +struct Hello +{ + uint16_t proto_version = kHelloVersion; + std::string app_name; + core::PluginSessionRequirements requirements; +}; + +struct HelloAck +{ + bool accepted = false; + std::string reason; +}; + +struct HandSample +{ + int64_t sample_time_ns = 0; + std::array joints{}; +}; + +struct SchemaSample +{ + int64_t sample_time_local_common_clock_ns = 0; + int64_t sample_time_raw_device_clock_ns = 0; + std::vector bytes; +}; + +struct WristSample +{ + int64_t sample_time_ns = 0; + XrHandEXT hand = XR_HAND_LEFT_EXT; + core::WristTrackingSample sample; +}; + +//! Times are CLOCK_MONOTONIC ns of the side that took them. +struct Pong +{ + int64_t t1_ns = 0; + int64_t t2_ns = 0; + int64_t t3_ns = 0; +}; + +constexpr size_t kPoseSize = 7 * sizeof(float); +constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); +constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; +constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + kPoseSize; +constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * kPoseSize; + +static_assert(kJointSize == 40); +static_assert(kHandSamplePayloadSize == 1048); +static_assert(sizeof(XrSpaceLocationFlags) == sizeof(uint64_t)); + +std::vector encode_hello(const Hello& value); +std::vector encode_hello_ack(const HelloAck& value); +std::vector encode_open_hand(XrHandEXT hand); +std::vector encode_open_schema(const core::SchemaPusherConfig& value); +std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value); +std::vector encode_wrist_sample(const WristSample& value); +std::vector encode_error(const std::string& message); +std::vector encode_ping(int64_t t1_ns); +std::vector encode_pong(const Pong& value); + +// Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. +std::vector encode_hand_sample_frame(uint16_t channel_id, + const XrHandJointLocationEXT* joints, + int64_t sample_time_ns); +std::vector encode_schema_sample_frame(uint16_t channel_id, + const uint8_t* bytes, + size_t size, + int64_t sample_time_local_common_clock_ns, + int64_t sample_time_raw_device_clock_ns); + +// Parsers throw DecodeError, naming the frame type, on truncated, over-long or out-of-range payloads. +Hello decode_hello(const std::vector& payload); +HelloAck decode_hello_ack(const std::vector& payload); +XrHandEXT decode_open_hand(const std::vector& payload); +core::SchemaPusherConfig decode_open_schema(const std::vector& payload); +core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload); +HandSample decode_hand_sample(const std::vector& payload); +SchemaSample decode_schema_sample(const std::vector& payload); +WristSample decode_wrist_sample(const std::vector& payload); +std::string decode_error(const std::vector& payload); +int64_t decode_ping(const std::vector& payload); +Pong decode_pong(const std::vector& payload); + +} // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp deleted file mode 100644 index e8f4ea2c02..0000000000 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/wire_codec.hpp +++ /dev/null @@ -1,195 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#pragma once - -#include -#include - -#include -#include -#include -#include -#include -#include - -namespace remote_plugin_session -{ -namespace wire -{ - -/*! - * Wire protocol v0: fixed little-endian frames over one TCP connection per - * plugin session. Frame = 24-byte header + payload. `str` = u32 length + bytes, - * `pose` = 7 x f32 in XrPosef order (orientation x,y,z,w then position x,y,z). - * This file is the single serialization point; swapping the hand payload for - * a FlatBuffer later only changes encode/decode of HandSample here. - */ - -constexpr uint32_t kMagic = 0x30535052u; // "RPS0" -constexpr uint8_t kProtocolVersion = 0; -//! HELLO proto_version: 2 = requirements carry the wrist source config (not a flag) and the client answers -//! PING with PONG. decode_hello rejects older versions, whose payload layout differs. -constexpr uint16_t kHelloVersion = 2; -constexpr size_t kHeaderSize = 24; -constexpr uint16_t kSessionChannelId = 0; -constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded - -enum class FrameType : uint8_t -{ - Hello = 1, // c->s: proto_version, app_name, requirements - HelloAck = 2, // s->c: accepted, reason - OpenHand = 3, // c->s: hand (0 left, 1 right) - OpenSchema = 4, // c->s: SchemaPusherConfig - OpenPull = 5, // c->s: empty - OpenWrist = 6, // c->s: WristTrackingSourceConfig on the pull channel id - Close = 7, // c->s: empty - HandSample = 8, // c->s: sample_time + 26 joints - SchemaSample = 9, // c->s: two timestamps + bytes - WristSample = 10, // s->c: sample_time, is_left, valid, tracked, pose - Heartbeat = 11, // both: empty - Error = 12, // s->c: message; on channel 0 the connection closes afterwards, on a channel id only that - // channel is refused - Ping = 13, // s->c: t1 (bridge send time) - Pong = 14, // c->s: t1 echoed, t2 (client receive time), t3 (client send time) -}; - -struct FrameHeader -{ - FrameType type = FrameType::Heartbeat; - uint8_t version = kProtocolVersion; - uint16_t channel_id = kSessionChannelId; - uint32_t seq = 0; - uint32_t payload_size = 0; - int64_t t_send_monotonic_ns = 0; -}; - -struct Frame -{ - FrameHeader header; - std::vector payload; -}; - -class DecodeError : public std::runtime_error -{ -public: - using std::runtime_error::runtime_error; -}; - -struct Hello -{ - uint16_t proto_version = kHelloVersion; - std::string app_name; - core::PluginSessionRequirements requirements; -}; - -struct HelloAck -{ - bool accepted = false; - std::string reason; -}; - -struct OpenHand -{ - XrHandEXT hand = XR_HAND_LEFT_EXT; -}; - -struct HandSample -{ - int64_t sample_time_ns = 0; - std::array joints{}; -}; - -struct SchemaSample -{ - int64_t sample_time_local_common_clock_ns = 0; - int64_t sample_time_raw_device_clock_ns = 0; - std::vector bytes; -}; - -struct WristSample -{ - int64_t sample_time_ns = 0; - bool is_left = true; - core::WristTrackingSample sample; -}; - -struct Error -{ - std::string message; -}; - -//! Times are CLOCK_MONOTONIC ns of the side that took them. -struct Ping -{ - int64_t t1_ns = 0; -}; - -struct Pong -{ - int64_t t1_ns = 0; - int64_t t2_ns = 0; - int64_t t3_ns = 0; -}; - -constexpr size_t kPoseSize = 7 * sizeof(float); -constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); -constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; -constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + kPoseSize; -constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * kPoseSize; - -static_assert(kHeaderSize == 4 + 1 + 1 + 2 + 4 + 4 + 8); -static_assert(kJointSize == 40); -static_assert(kHandSamplePayloadSize == 1048); -static_assert(sizeof(XrSpaceLocationFlags) == sizeof(uint64_t)); - -const char* to_string(FrameType type); - -//! `out` must hold kHeaderSize bytes. -void encode_header(const FrameHeader& header, uint8_t* out); -//! Throws DecodeError on bad magic, unsupported version or an oversized payload. -FrameHeader decode_header(const uint8_t* in); - -std::vector encode(const Hello& value); -std::vector encode(const HelloAck& value); -std::vector encode(const OpenHand& value); -std::vector encode(const core::SchemaPusherConfig& value); -std::vector encode(const core::WristTrackingSourceConfig& value); -std::vector encode(const WristSample& value); -std::vector encode(const Error& value); -std::vector encode(const Ping& value); -std::vector encode(const Pong& value); - -// Frame builders write header + payload into one contiguous buffer. seq and t_send stay zero until -// stamp_header(). Samples are only encoded this way: the builders read the plugin's buffers directly so a -// push copies once. -std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); -std::vector encode_hand_sample_frame(uint16_t channel_id, - const XrHandJointLocationEXT* joints, - int64_t sample_time_ns); -std::vector encode_schema_sample_frame(uint16_t channel_id, - const uint8_t* bytes, - size_t size, - int64_t sample_time_local_common_clock_ns, - int64_t sample_time_raw_device_clock_ns); -//! Patches seq and t_send into an encoded frame's header in place; on a PONG also sets t3 = t_send, so t3 is -//! the time the frame actually left, not when it was queued. -void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns); -//! Splits one complete message into header and payload (payload moved, not copied). Throws DecodeError. -Frame split_frame(std::vector message); - -// Decoders throw DecodeError on truncated or over-long payloads. -Hello decode_hello(const std::vector& payload); -HelloAck decode_hello_ack(const std::vector& payload); -OpenHand decode_open_hand(const std::vector& payload); -core::SchemaPusherConfig decode_open_schema(const std::vector& payload); -core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload); -HandSample decode_hand_sample(const std::vector& payload); -SchemaSample decode_schema_sample(const std::vector& payload); -WristSample decode_wrist_sample(const std::vector& payload); -Error decode_error(const std::vector& payload); -Ping decode_ping(const std::vector& payload); -Pong decode_pong(const std::vector& payload); - -} // namespace wire -} // namespace remote_plugin_session diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp new file mode 100644 index 0000000000..678a96fdc3 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -0,0 +1,109 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/remote_plugin_session/protocol_frame.hpp" + +#include "protocol_io.hpp" + +#include +#include +#include + +namespace remote_plugin_protocol +{ + +using detail::build_frame; +using detail::Reader; +using detail::Writer; + +void encode_header(const FrameHeader& header, uint8_t* out) +{ + std::vector bytes; + Writer writer(bytes); + writer.u32(kMagic); + writer.u8(static_cast(header.type)); + writer.u8(header.version); + writer.u16(header.channel_id); + writer.u32(header.seq); + writer.u32(header.payload_size); + writer.i64(header.t_send_monotonic_ns); + std::memcpy(out, bytes.data(), kHeaderSize); +} + +void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns) +{ + // Byte offsets follow encode_header: seq at 8, t_send at 16. + for (int i = 0; i < 4; ++i) + { + frame[8 + i] = static_cast(seq >> (8 * i)); + } + const uint64_t t_send = static_cast(t_send_monotonic_ns); + for (int i = 0; i < 8; ++i) + { + frame[16 + i] = static_cast(t_send >> (8 * i)); + } + // Pong payload: t1, t2, t3 (i64 each); t3 at payload offset 16. + if (frame[4] == static_cast(FrameType::Pong) && decode_header(frame).payload_size == 3 * sizeof(int64_t)) + { + for (int i = 0; i < 8; ++i) + { + frame[kHeaderSize + 16 + i] = static_cast(t_send >> (8 * i)); + } + } +} + +Frame split_frame(std::vector message) +{ + if (message.size() < kHeaderSize) + { + throw DecodeError("protocol: message shorter than a header"); + } + Frame frame; + frame.header = decode_header(message.data()); + if (message.size() != kHeaderSize + frame.header.payload_size) + { + throw DecodeError("protocol: message length does not match payload_size"); + } + message.erase(message.begin(), message.begin() + static_cast(kHeaderSize)); + frame.payload = std::move(message); + return frame; +} + +std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload) +{ + return build_frame( + type, channel_id, payload.size(), [&payload](Writer& writer) { writer.bytes(payload.data(), payload.size()); }); +} + +FrameHeader decode_header(const uint8_t* in) +{ + Reader reader(in, kHeaderSize, "header"); + if (reader.u32() != kMagic) + { + throw DecodeError("protocol: bad frame magic"); + } + FrameHeader header; + const uint8_t type = reader.u8(); + if (type < static_cast(FrameType::Hello) || type > static_cast(FrameType::Pong)) + { + throw DecodeError("protocol: unknown frame type " + std::to_string(type)); + } + header.type = static_cast(type); + header.version = reader.u8(); + if (header.version != kProtocolVersion) + { + throw DecodeError("protocol: unsupported protocol version " + std::to_string(header.version)); + } + header.channel_id = reader.u16(); + header.seq = reader.u32(); + header.payload_size = reader.u32(); + if (header.payload_size > kMaxPayloadSize) + { + throw DecodeError("protocol: payload size " + std::to_string(header.payload_size) + " exceeds limit"); + } + header.t_send_monotonic_ns = reader.i64(); + reader.finish(); + return header; +} + +} // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp new file mode 100644 index 0000000000..bd4e8987e1 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -0,0 +1,240 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#pragma once + +#include "inc/remote_plugin_session/protocol_frame.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace remote_plugin_protocol +{ +namespace detail +{ + +//! Appends little-endian fields to a caller-owned buffer. +class Writer +{ +public: + explicit Writer(std::vector& out) : m_out(out) + { + } + + void u8(uint8_t value) + { + m_out.push_back(value); + } + + void u16(uint16_t value) + { + for (int i = 0; i < 2; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void u32(uint32_t value) + { + for (int i = 0; i < 4; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void u64(uint64_t value) + { + for (int i = 0; i < 8; ++i) + { + m_out.push_back(static_cast(value >> (8 * i))); + } + } + + void i64(int64_t value) + { + u64(static_cast(value)); + } + + void f32(float value) + { + uint32_t bits = 0; + std::memcpy(&bits, &value, sizeof(bits)); + u32(bits); + } + + void str(const std::string& value) + { + if (value.size() > std::numeric_limits::max()) + { + throw std::invalid_argument("protocol: string too long"); + } + u32(static_cast(value.size())); + m_out.insert(m_out.end(), value.begin(), value.end()); + } + + void bytes(const uint8_t* data, size_t size) + { + m_out.insert(m_out.end(), data, data + size); + } + + void pose(const XrPosef& value) + { + f32(value.orientation.x); + f32(value.orientation.y); + f32(value.orientation.z); + f32(value.orientation.w); + f32(value.position.x); + f32(value.position.y); + f32(value.position.z); + } + +private: + std::vector& m_out; +}; + +class Reader +{ +public: + //! `what` names the frame or header being read in DecodeError messages. + Reader(const uint8_t* data, size_t size, const char* what) : m_data(data), m_size(size), m_what(what) + { + } + + Reader(const std::vector& payload, const char* what) : Reader(payload.data(), payload.size(), what) + { + } + + uint8_t u8() + { + need(1); + return m_data[m_pos++]; + } + + uint16_t u16() + { + need(2); + uint16_t value = 0; + for (int i = 0; i < 2; ++i) + { + value = static_cast(value | (static_cast(m_data[m_pos++]) << (8 * i))); + } + return value; + } + + uint32_t u32() + { + need(4); + uint32_t value = 0; + for (int i = 0; i < 4; ++i) + { + value |= static_cast(m_data[m_pos++]) << (8 * i); + } + return value; + } + + uint64_t u64() + { + need(8); + uint64_t value = 0; + for (int i = 0; i < 8; ++i) + { + value |= static_cast(m_data[m_pos++]) << (8 * i); + } + return value; + } + + int64_t i64() + { + return static_cast(u64()); + } + + float f32() + { + const uint32_t bits = u32(); + float value = 0.0f; + std::memcpy(&value, &bits, sizeof(value)); + return value; + } + + std::string str() + { + const uint32_t size = u32(); + need(size); + std::string value(reinterpret_cast(m_data + m_pos), size); + m_pos += size; + return value; + } + + std::vector bytes(size_t size) + { + need(size); + std::vector value(m_data + m_pos, m_data + m_pos + size); + m_pos += size; + return value; + } + + XrPosef pose() + { + XrPosef value; + value.orientation.x = f32(); + value.orientation.y = f32(); + value.orientation.z = f32(); + value.orientation.w = f32(); + value.position.x = f32(); + value.position.y = f32(); + value.position.z = f32(); + return value; + } + + void finish() const + { + if (m_pos != m_size) + { + throw DecodeError(std::string("protocol: ") + m_what + ": " + std::to_string(m_size - m_pos) + + " trailing bytes"); + } + } + +private: + void need(size_t count) const + { + if (m_size - m_pos < count) + { + throw DecodeError(std::string("protocol: ") + m_what + ": truncated"); + } + } + + const uint8_t* m_data; + size_t m_size; + const char* m_what; + size_t m_pos = 0; +}; + +//! Reserves the header, writes the payload behind it, then fills the header in with the resulting size. +template +inline std::vector build_frame(FrameType type, uint16_t channel_id, size_t payload_hint, WritePayload write_payload) +{ + std::vector out; + out.reserve(kHeaderSize + payload_hint); + out.resize(kHeaderSize); + Writer writer(out); + write_payload(writer); + if (out.size() - kHeaderSize > kMaxPayloadSize) + { + throw std::invalid_argument("protocol: payload too large"); + } + FrameHeader header; + header.type = type; + header.channel_id = channel_id; + header.payload_size = static_cast(out.size() - kHeaderSize); + encode_header(header, out.data()); + return out; +} + +} // namespace detail +} // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp new file mode 100644 index 0000000000..3e84b98c67 --- /dev/null +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -0,0 +1,407 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +#include "inc/remote_plugin_session/protocol_payloads.hpp" + +#include "protocol_io.hpp" + +#include + +namespace remote_plugin_protocol +{ + +using detail::build_frame; +using detail::Reader; +using detail::Writer; + +namespace +{ + +const char* to_string(FrameType type) +{ + switch (type) + { + case FrameType::Hello: + return "HELLO"; + case FrameType::HelloAck: + return "HELLO_ACK"; + case FrameType::OpenHand: + return "OPEN_HAND"; + case FrameType::OpenSchema: + return "OPEN_SCHEMA"; + case FrameType::OpenPull: + return "OPEN_PULL"; + case FrameType::OpenWrist: + return "OPEN_WRIST"; + case FrameType::Close: + return "CLOSE"; + case FrameType::HandSample: + return "HAND_SAMPLE"; + case FrameType::SchemaSample: + return "SCHEMA_SAMPLE"; + case FrameType::WristSample: + return "WRIST_SAMPLE"; + case FrameType::Heartbeat: + return "HEARTBEAT"; + case FrameType::Error: + return "ERROR"; + case FrameType::Ping: + return "PING"; + case FrameType::Pong: + return "PONG"; + } + return "UNKNOWN"; +} + +uint8_t to_wire_hand(XrHandEXT hand) +{ + switch (hand) + { + case XR_HAND_LEFT_EXT: + return 0; + case XR_HAND_RIGHT_EXT: + return 1; + default: + throw std::invalid_argument("protocol: unsupported XrHandEXT value"); + } +} + +XrHandEXT from_wire_hand(uint8_t hand) +{ + switch (hand) + { + case 0: + return XR_HAND_LEFT_EXT; + case 1: + return XR_HAND_RIGHT_EXT; + default: + throw DecodeError("protocol: invalid hand value " + std::to_string(hand)); + } +} + +// WRIST_SAMPLE keeps its original byte: 1 = left, 0 = right (OPEN_HAND uses 0 = left). +uint8_t to_wire_is_left(XrHandEXT hand) +{ + switch (hand) + { + case XR_HAND_LEFT_EXT: + return 1; + case XR_HAND_RIGHT_EXT: + return 0; + default: + throw std::invalid_argument("protocol: unsupported XrHandEXT value"); + } +} + +uint8_t to_wire_mode(core::WristTrackingSourceMode mode) +{ + switch (mode) + { + case core::WristTrackingSourceMode::Auto: + return 0; + case core::WristTrackingSourceMode::HandTracking: + return 1; + case core::WristTrackingSourceMode::Controller: + return 2; + } + throw std::invalid_argument("protocol: unsupported wrist tracking source mode"); +} + +core::WristTrackingSourceMode from_wire_mode(uint8_t mode) +{ + switch (mode) + { + case 0: + return core::WristTrackingSourceMode::Auto; + case 1: + return core::WristTrackingSourceMode::HandTracking; + case 2: + return core::WristTrackingSourceMode::Controller; + default: + throw DecodeError("protocol: invalid wrist tracking source mode " + std::to_string(mode)); + } +} + +bool to_bool(uint8_t value) +{ + if (value > 1) + { + throw DecodeError("protocol: invalid boolean value " + std::to_string(value)); + } + return value == 1; +} + +void write_wrist_config(Writer& writer, const core::WristTrackingSourceConfig& value) +{ + writer.u8(to_wire_mode(value.mode)); + writer.pose(value.left_aim_to_wrist); + writer.pose(value.right_aim_to_wrist); +} + +core::WristTrackingSourceConfig read_wrist_config(Reader& reader) +{ + core::WristTrackingSourceConfig value; + value.mode = from_wire_mode(reader.u8()); + value.left_aim_to_wrist = reader.pose(); + value.right_aim_to_wrist = reader.pose(); + return value; +} + +} // namespace + +std::vector encode_hand_sample_frame(uint16_t channel_id, + const XrHandJointLocationEXT* joints, + int64_t sample_time_ns) +{ + return build_frame(FrameType::HandSample, channel_id, kHandSamplePayloadSize, + [&](Writer& writer) + { + writer.i64(sample_time_ns); + for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + { + writer.u64(joints[i].locationFlags); + writer.pose(joints[i].pose); + writer.f32(joints[i].radius); + } + }); +} + +std::vector encode_schema_sample_frame(uint16_t channel_id, + const uint8_t* bytes, + size_t size, + int64_t sample_time_local_common_clock_ns, + int64_t sample_time_raw_device_clock_ns) +{ + if (size > kMaxPayloadSize) + { + throw std::invalid_argument("protocol: schema sample too large"); + } + return build_frame(FrameType::SchemaSample, channel_id, 2 * sizeof(int64_t) + sizeof(uint32_t) + size, + [&](Writer& writer) + { + writer.i64(sample_time_local_common_clock_ns); + writer.i64(sample_time_raw_device_clock_ns); + writer.u32(static_cast(size)); + writer.bytes(bytes, size); + }); +} + +std::vector encode_hello(const Hello& value) +{ + std::vector out; + Writer writer(out); + writer.u16(value.proto_version); + writer.str(value.app_name); + writer.u8(value.requirements.schema_push ? 1 : 0); + writer.u8(value.requirements.hand_tracking_push ? 1 : 0); + writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); + if (value.requirements.wrist_tracking_pull) + { + write_wrist_config(writer, *value.requirements.wrist_tracking_pull); + } + return out; +} + +std::vector encode_hello_ack(const HelloAck& value) +{ + std::vector out; + Writer writer(out); + writer.u8(value.accepted ? 1 : 0); + writer.str(value.reason); + return out; +} + +std::vector encode_open_hand(XrHandEXT hand) +{ + std::vector out; + Writer writer(out); + writer.u8(to_wire_hand(hand)); + return out; +} + +std::vector encode_open_schema(const core::SchemaPusherConfig& value) +{ + std::vector out; + Writer writer(out); + writer.str(value.collection_id); + writer.u64(static_cast(value.max_flatbuffer_size)); + writer.str(value.tensor_identifier); + writer.str(value.localized_name); + writer.str(value.app_name); + return out; +} + +std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value) +{ + std::vector out; + Writer writer(out); + write_wrist_config(writer, value); + return out; +} + +std::vector encode_wrist_sample(const WristSample& value) +{ + std::vector out; + Writer writer(out); + writer.i64(value.sample_time_ns); + writer.u8(to_wire_is_left(value.hand)); + writer.u8(value.sample.valid ? 1 : 0); + writer.u8(value.sample.tracked ? 1 : 0); + writer.pose(value.sample.pose); + return out; +} + +std::vector encode_error(const std::string& message) +{ + std::vector out; + Writer writer(out); + writer.str(message); + return out; +} + +std::vector encode_ping(int64_t t1_ns) +{ + std::vector out; + Writer writer(out); + writer.i64(t1_ns); + return out; +} + +std::vector encode_pong(const Pong& value) +{ + std::vector out; + Writer writer(out); + writer.i64(value.t1_ns); + writer.i64(value.t2_ns); + writer.i64(value.t3_ns); + return out; +} + +Hello decode_hello(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::Hello)); + Hello value; + value.proto_version = reader.u16(); + if (value.proto_version < kHelloVersion) + { + throw DecodeError("protocol: HELLO version " + std::to_string(value.proto_version) + " is older than " + + std::to_string(kHelloVersion)); + } + value.app_name = reader.str(); + value.requirements.schema_push = to_bool(reader.u8()); + value.requirements.hand_tracking_push = to_bool(reader.u8()); + if (to_bool(reader.u8())) + { + value.requirements.wrist_tracking_pull = read_wrist_config(reader); + } + reader.finish(); + return value; +} + +HelloAck decode_hello_ack(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::HelloAck)); + HelloAck value; + value.accepted = to_bool(reader.u8()); + value.reason = reader.str(); + reader.finish(); + return value; +} + +XrHandEXT decode_open_hand(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::OpenHand)); + const XrHandEXT hand = from_wire_hand(reader.u8()); + reader.finish(); + return hand; +} + +core::SchemaPusherConfig decode_open_schema(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::OpenSchema)); + core::SchemaPusherConfig value; + value.collection_id = reader.str(); + value.max_flatbuffer_size = static_cast(reader.u64()); + value.tensor_identifier = reader.str(); + value.localized_name = reader.str(); + value.app_name = reader.str(); + reader.finish(); + return value; +} + +core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::OpenWrist)); + const core::WristTrackingSourceConfig value = read_wrist_config(reader); + reader.finish(); + return value; +} + +HandSample decode_hand_sample(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::HandSample)); + HandSample value; + value.sample_time_ns = reader.i64(); + for (XrHandJointLocationEXT& joint : value.joints) + { + joint.locationFlags = reader.u64(); + joint.pose = reader.pose(); + joint.radius = reader.f32(); + } + reader.finish(); + return value; +} + +SchemaSample decode_schema_sample(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::SchemaSample)); + SchemaSample value; + value.sample_time_local_common_clock_ns = reader.i64(); + value.sample_time_raw_device_clock_ns = reader.i64(); + const uint32_t size = reader.u32(); + value.bytes = reader.bytes(size); + reader.finish(); + return value; +} + +WristSample decode_wrist_sample(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::WristSample)); + WristSample value; + value.sample_time_ns = reader.i64(); + value.hand = to_bool(reader.u8()) ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; + value.sample.valid = to_bool(reader.u8()); + value.sample.tracked = to_bool(reader.u8()); + value.sample.pose = reader.pose(); + reader.finish(); + return value; +} + +std::string decode_error(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::Error)); + std::string message = reader.str(); + reader.finish(); + return message; +} + +int64_t decode_ping(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::Ping)); + const int64_t t1_ns = reader.i64(); + reader.finish(); + return t1_ns; +} + +Pong decode_pong(const std::vector& payload) +{ + Reader reader(payload, to_string(FrameType::Pong)); + Pong value; + value.t1_ns = reader.i64(); + value.t2_ns = reader.i64(); + value.t3_ns = reader.i64(); + reader.finish(); + return value; +} + +} // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/wire_codec.cpp b/src/plugins/remote_device_bridge/session/wire_codec.cpp deleted file mode 100644 index 9dc4e864a2..0000000000 --- a/src/plugins/remote_device_bridge/session/wire_codec.cpp +++ /dev/null @@ -1,699 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -#include "inc/remote_plugin_session/wire_codec.hpp" - -#include -#include - -namespace remote_plugin_session -{ -namespace wire -{ - -namespace -{ - -//! Appends little-endian fields to a caller-owned buffer. -class Writer -{ -public: - explicit Writer(std::vector& out) : m_out(out) - { - } - - void u8(uint8_t value) - { - m_out.push_back(value); - } - - void u16(uint16_t value) - { - for (int i = 0; i < 2; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } - } - - void u32(uint32_t value) - { - for (int i = 0; i < 4; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } - } - - void u64(uint64_t value) - { - for (int i = 0; i < 8; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } - } - - void i64(int64_t value) - { - u64(static_cast(value)); - } - - void f32(float value) - { - uint32_t bits = 0; - std::memcpy(&bits, &value, sizeof(bits)); - u32(bits); - } - - void str(const std::string& value) - { - if (value.size() > std::numeric_limits::max()) - { - throw std::invalid_argument("wire: string too long"); - } - u32(static_cast(value.size())); - m_out.insert(m_out.end(), value.begin(), value.end()); - } - - void bytes(const uint8_t* data, size_t size) - { - m_out.insert(m_out.end(), data, data + size); - } - - void pose(const XrPosef& value) - { - f32(value.orientation.x); - f32(value.orientation.y); - f32(value.orientation.z); - f32(value.orientation.w); - f32(value.position.x); - f32(value.position.y); - f32(value.position.z); - } - -private: - std::vector& m_out; -}; - -class Reader -{ -public: - Reader(const uint8_t* data, size_t size) : m_data(data), m_size(size) - { - } - - explicit Reader(const std::vector& payload) : Reader(payload.data(), payload.size()) - { - } - - uint8_t u8() - { - need(1); - return m_data[m_pos++]; - } - - uint16_t u16() - { - need(2); - uint16_t value = 0; - for (int i = 0; i < 2; ++i) - { - value = static_cast(value | (static_cast(m_data[m_pos++]) << (8 * i))); - } - return value; - } - - uint32_t u32() - { - need(4); - uint32_t value = 0; - for (int i = 0; i < 4; ++i) - { - value |= static_cast(m_data[m_pos++]) << (8 * i); - } - return value; - } - - uint64_t u64() - { - need(8); - uint64_t value = 0; - for (int i = 0; i < 8; ++i) - { - value |= static_cast(m_data[m_pos++]) << (8 * i); - } - return value; - } - - int64_t i64() - { - return static_cast(u64()); - } - - float f32() - { - const uint32_t bits = u32(); - float value = 0.0f; - std::memcpy(&value, &bits, sizeof(value)); - return value; - } - - std::string str() - { - const uint32_t size = u32(); - need(size); - std::string value(reinterpret_cast(m_data + m_pos), size); - m_pos += size; - return value; - } - - std::vector bytes(size_t size) - { - need(size); - std::vector value(m_data + m_pos, m_data + m_pos + size); - m_pos += size; - return value; - } - - XrPosef pose() - { - XrPosef value; - value.orientation.x = f32(); - value.orientation.y = f32(); - value.orientation.z = f32(); - value.orientation.w = f32(); - value.position.x = f32(); - value.position.y = f32(); - value.position.z = f32(); - return value; - } - - void finish() const - { - if (m_pos != m_size) - { - throw DecodeError("wire: " + std::to_string(m_size - m_pos) + " trailing bytes"); - } - } - -private: - void need(size_t count) const - { - if (m_size - m_pos < count) - { - throw DecodeError("wire: truncated payload"); - } - } - - const uint8_t* m_data; - size_t m_size; - size_t m_pos = 0; -}; - -uint8_t to_wire_hand(XrHandEXT hand) -{ - switch (hand) - { - case XR_HAND_LEFT_EXT: - return 0; - case XR_HAND_RIGHT_EXT: - return 1; - default: - throw std::invalid_argument("wire: unsupported XrHandEXT value"); - } -} - -XrHandEXT from_wire_hand(uint8_t hand) -{ - switch (hand) - { - case 0: - return XR_HAND_LEFT_EXT; - case 1: - return XR_HAND_RIGHT_EXT; - default: - throw DecodeError("wire: invalid hand value " + std::to_string(hand)); - } -} - -uint8_t to_wire_mode(core::WristTrackingSourceMode mode) -{ - switch (mode) - { - case core::WristTrackingSourceMode::Auto: - return 0; - case core::WristTrackingSourceMode::HandTracking: - return 1; - case core::WristTrackingSourceMode::Controller: - return 2; - } - throw std::invalid_argument("wire: unsupported wrist tracking source mode"); -} - -core::WristTrackingSourceMode from_wire_mode(uint8_t mode) -{ - switch (mode) - { - case 0: - return core::WristTrackingSourceMode::Auto; - case 1: - return core::WristTrackingSourceMode::HandTracking; - case 2: - return core::WristTrackingSourceMode::Controller; - default: - throw DecodeError("wire: invalid wrist tracking source mode " + std::to_string(mode)); - } -} - -//! Reserves the header, writes the payload behind it, then fills the header in with the resulting size. -template -std::vector build_frame(FrameType type, uint16_t channel_id, size_t payload_hint, WritePayload write_payload) -{ - std::vector out; - out.reserve(kHeaderSize + payload_hint); - out.resize(kHeaderSize); - Writer writer(out); - write_payload(writer); - if (out.size() - kHeaderSize > kMaxPayloadSize) - { - throw std::invalid_argument("wire: payload too large"); - } - FrameHeader header; - header.type = type; - header.channel_id = channel_id; - header.payload_size = static_cast(out.size() - kHeaderSize); - encode_header(header, out.data()); - return out; -} - -bool to_bool(uint8_t value) -{ - if (value > 1) - { - throw DecodeError("wire: invalid boolean value " + std::to_string(value)); - } - return value == 1; -} - -void write_wrist_config(Writer& writer, const core::WristTrackingSourceConfig& value) -{ - writer.u8(to_wire_mode(value.mode)); - writer.pose(value.left_aim_to_wrist); - writer.pose(value.right_aim_to_wrist); -} - -core::WristTrackingSourceConfig read_wrist_config(Reader& reader) -{ - core::WristTrackingSourceConfig value; - value.mode = from_wire_mode(reader.u8()); - value.left_aim_to_wrist = reader.pose(); - value.right_aim_to_wrist = reader.pose(); - return value; -} - -} // namespace - -const char* to_string(FrameType type) -{ - switch (type) - { - case FrameType::Hello: - return "HELLO"; - case FrameType::HelloAck: - return "HELLO_ACK"; - case FrameType::OpenHand: - return "OPEN_HAND"; - case FrameType::OpenSchema: - return "OPEN_SCHEMA"; - case FrameType::OpenPull: - return "OPEN_PULL"; - case FrameType::OpenWrist: - return "OPEN_WRIST"; - case FrameType::Close: - return "CLOSE"; - case FrameType::HandSample: - return "HAND_SAMPLE"; - case FrameType::SchemaSample: - return "SCHEMA_SAMPLE"; - case FrameType::WristSample: - return "WRIST_SAMPLE"; - case FrameType::Heartbeat: - return "HEARTBEAT"; - case FrameType::Error: - return "ERROR"; - case FrameType::Ping: - return "PING"; - case FrameType::Pong: - return "PONG"; - } - return "UNKNOWN"; -} - -void encode_header(const FrameHeader& header, uint8_t* out) -{ - std::vector bytes; - Writer writer(bytes); - writer.u32(kMagic); - writer.u8(static_cast(header.type)); - writer.u8(header.version); - writer.u16(header.channel_id); - writer.u32(header.seq); - writer.u32(header.payload_size); - writer.i64(header.t_send_monotonic_ns); - std::memcpy(out, bytes.data(), kHeaderSize); -} - -void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns) -{ - // Byte offsets follow encode_header: seq at 8, t_send at 16. - for (int i = 0; i < 4; ++i) - { - frame[8 + i] = static_cast(seq >> (8 * i)); - } - const uint64_t t_send = static_cast(t_send_monotonic_ns); - for (int i = 0; i < 8; ++i) - { - frame[16 + i] = static_cast(t_send >> (8 * i)); - } - // Pong payload: t1, t2, t3 (i64 each); t3 at payload offset 16. - if (frame[4] == static_cast(FrameType::Pong) && decode_header(frame).payload_size == 3 * sizeof(int64_t)) - { - for (int i = 0; i < 8; ++i) - { - frame[kHeaderSize + 16 + i] = static_cast(t_send >> (8 * i)); - } - } -} - -Frame split_frame(std::vector message) -{ - if (message.size() < kHeaderSize) - { - throw DecodeError("wire: message shorter than a header"); - } - Frame frame; - frame.header = decode_header(message.data()); - if (message.size() != kHeaderSize + frame.header.payload_size) - { - throw DecodeError("wire: message length does not match payload_size"); - } - message.erase(message.begin(), message.begin() + static_cast(kHeaderSize)); - frame.payload = std::move(message); - return frame; -} - -std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload) -{ - return build_frame( - type, channel_id, payload.size(), [&payload](Writer& writer) { writer.bytes(payload.data(), payload.size()); }); -} - -std::vector encode_hand_sample_frame(uint16_t channel_id, - const XrHandJointLocationEXT* joints, - int64_t sample_time_ns) -{ - return build_frame(FrameType::HandSample, channel_id, kHandSamplePayloadSize, - [&](Writer& writer) - { - writer.i64(sample_time_ns); - for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) - { - writer.u64(joints[i].locationFlags); - writer.pose(joints[i].pose); - writer.f32(joints[i].radius); - } - }); -} - -std::vector encode_schema_sample_frame(uint16_t channel_id, - const uint8_t* bytes, - size_t size, - int64_t sample_time_local_common_clock_ns, - int64_t sample_time_raw_device_clock_ns) -{ - if (size > kMaxPayloadSize) - { - throw std::invalid_argument("wire: schema sample too large"); - } - return build_frame(FrameType::SchemaSample, channel_id, 2 * sizeof(int64_t) + sizeof(uint32_t) + size, - [&](Writer& writer) - { - writer.i64(sample_time_local_common_clock_ns); - writer.i64(sample_time_raw_device_clock_ns); - writer.u32(static_cast(size)); - writer.bytes(bytes, size); - }); -} - -FrameHeader decode_header(const uint8_t* in) -{ - Reader reader(in, kHeaderSize); - if (reader.u32() != kMagic) - { - throw DecodeError("wire: bad frame magic"); - } - FrameHeader header; - const uint8_t type = reader.u8(); - if (type < static_cast(FrameType::Hello) || type > static_cast(FrameType::Pong)) - { - throw DecodeError("wire: unknown frame type " + std::to_string(type)); - } - header.type = static_cast(type); - header.version = reader.u8(); - if (header.version != kProtocolVersion) - { - throw DecodeError("wire: unsupported protocol version " + std::to_string(header.version)); - } - header.channel_id = reader.u16(); - header.seq = reader.u32(); - header.payload_size = reader.u32(); - if (header.payload_size > kMaxPayloadSize) - { - throw DecodeError("wire: payload size " + std::to_string(header.payload_size) + " exceeds limit"); - } - header.t_send_monotonic_ns = reader.i64(); - reader.finish(); - return header; -} - -std::vector encode(const Hello& value) -{ - std::vector out; - Writer writer(out); - writer.u16(value.proto_version); - writer.str(value.app_name); - writer.u8(value.requirements.schema_push ? 1 : 0); - writer.u8(value.requirements.hand_tracking_push ? 1 : 0); - writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); - if (value.requirements.wrist_tracking_pull) - { - write_wrist_config(writer, *value.requirements.wrist_tracking_pull); - } - return out; -} - -std::vector encode(const HelloAck& value) -{ - std::vector out; - Writer writer(out); - writer.u8(value.accepted ? 1 : 0); - writer.str(value.reason); - return out; -} - -std::vector encode(const OpenHand& value) -{ - std::vector out; - Writer writer(out); - writer.u8(to_wire_hand(value.hand)); - return out; -} - -std::vector encode(const core::SchemaPusherConfig& value) -{ - std::vector out; - Writer writer(out); - writer.str(value.collection_id); - writer.u64(static_cast(value.max_flatbuffer_size)); - writer.str(value.tensor_identifier); - writer.str(value.localized_name); - writer.str(value.app_name); - return out; -} - -std::vector encode(const core::WristTrackingSourceConfig& value) -{ - std::vector out; - Writer writer(out); - write_wrist_config(writer, value); - return out; -} - -std::vector encode(const WristSample& value) -{ - std::vector out; - Writer writer(out); - writer.i64(value.sample_time_ns); - writer.u8(value.is_left ? 1 : 0); - writer.u8(value.sample.valid ? 1 : 0); - writer.u8(value.sample.tracked ? 1 : 0); - writer.pose(value.sample.pose); - return out; -} - -std::vector encode(const Error& value) -{ - std::vector out; - Writer writer(out); - writer.str(value.message); - return out; -} - -std::vector encode(const Ping& value) -{ - std::vector out; - Writer writer(out); - writer.i64(value.t1_ns); - return out; -} - -std::vector encode(const Pong& value) -{ - std::vector out; - Writer writer(out); - writer.i64(value.t1_ns); - writer.i64(value.t2_ns); - writer.i64(value.t3_ns); - return out; -} - -Hello decode_hello(const std::vector& payload) -{ - Reader reader(payload); - Hello value; - value.proto_version = reader.u16(); - if (value.proto_version < kHelloVersion) - { - throw DecodeError("wire: HELLO version " + std::to_string(value.proto_version) + " is older than " + - std::to_string(kHelloVersion)); - } - value.app_name = reader.str(); - value.requirements.schema_push = to_bool(reader.u8()); - value.requirements.hand_tracking_push = to_bool(reader.u8()); - if (to_bool(reader.u8())) - { - value.requirements.wrist_tracking_pull = read_wrist_config(reader); - } - reader.finish(); - return value; -} - -HelloAck decode_hello_ack(const std::vector& payload) -{ - Reader reader(payload); - HelloAck value; - value.accepted = to_bool(reader.u8()); - value.reason = reader.str(); - reader.finish(); - return value; -} - -OpenHand decode_open_hand(const std::vector& payload) -{ - Reader reader(payload); - OpenHand value; - value.hand = from_wire_hand(reader.u8()); - reader.finish(); - return value; -} - -core::SchemaPusherConfig decode_open_schema(const std::vector& payload) -{ - Reader reader(payload); - core::SchemaPusherConfig value; - value.collection_id = reader.str(); - value.max_flatbuffer_size = static_cast(reader.u64()); - value.tensor_identifier = reader.str(); - value.localized_name = reader.str(); - value.app_name = reader.str(); - reader.finish(); - return value; -} - -core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) -{ - Reader reader(payload); - const core::WristTrackingSourceConfig value = read_wrist_config(reader); - reader.finish(); - return value; -} - -HandSample decode_hand_sample(const std::vector& payload) -{ - Reader reader(payload); - HandSample value; - value.sample_time_ns = reader.i64(); - for (XrHandJointLocationEXT& joint : value.joints) - { - joint.locationFlags = reader.u64(); - joint.pose = reader.pose(); - joint.radius = reader.f32(); - } - reader.finish(); - return value; -} - -SchemaSample decode_schema_sample(const std::vector& payload) -{ - Reader reader(payload); - SchemaSample value; - value.sample_time_local_common_clock_ns = reader.i64(); - value.sample_time_raw_device_clock_ns = reader.i64(); - const uint32_t size = reader.u32(); - value.bytes = reader.bytes(size); - reader.finish(); - return value; -} - -WristSample decode_wrist_sample(const std::vector& payload) -{ - Reader reader(payload); - WristSample value; - value.sample_time_ns = reader.i64(); - value.is_left = to_bool(reader.u8()); - value.sample.valid = to_bool(reader.u8()); - value.sample.tracked = to_bool(reader.u8()); - value.sample.pose = reader.pose(); - reader.finish(); - return value; -} - -Error decode_error(const std::vector& payload) -{ - Reader reader(payload); - Error value; - value.message = reader.str(); - reader.finish(); - return value; -} - -Ping decode_ping(const std::vector& payload) -{ - Reader reader(payload); - Ping value; - value.t1_ns = reader.i64(); - reader.finish(); - return value; -} - -Pong decode_pong(const std::vector& payload) -{ - Reader reader(payload); - Pong value; - value.t1_ns = reader.i64(); - value.t2_ns = reader.i64(); - value.t3_ns = reader.i64(); - reader.finish(); - return value; -} - -} // namespace wire -} // namespace remote_plugin_session diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 704a3254b7..0534a11a14 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -2,7 +2,9 @@ // SPDX-License-Identifier: Apache-2.0 #include -#include +#include +#include +#include #include #include @@ -11,7 +13,7 @@ #include #include -using namespace remote_plugin_session; +namespace protocol = remote_plugin_protocol; namespace { @@ -48,7 +50,7 @@ void put_f32(std::vector& out, float v) } //! Reference payload encoder (the pre-frame-builder layout) kept as the golden for HAND_SAMPLE. -std::vector reference_hand_payload(const wire::HandSample& sample) +std::vector reference_hand_payload(const protocol::HandSample& sample) { std::vector out; put_u64(out, static_cast(sample.sample_time_ns)); @@ -65,16 +67,16 @@ std::vector reference_hand_payload(const wire::HandSample& sample) return out; } -std::vector hand_payload(const wire::HandSample& sample) +std::vector hand_payload(const protocol::HandSample& sample) { - return wire::split_frame(wire::encode_hand_sample_frame(1, sample.joints.data(), sample.sample_time_ns)).payload; + return protocol::split_frame(protocol::encode_hand_sample_frame(1, sample.joints.data(), sample.sample_time_ns)).payload; } -std::vector schema_payload(const wire::SchemaSample& sample) +std::vector schema_payload(const protocol::SchemaSample& sample) { - return wire::split_frame(wire::encode_schema_sample_frame(1, sample.bytes.data(), sample.bytes.size(), - sample.sample_time_local_common_clock_ns, - sample.sample_time_raw_device_clock_ns)) + return protocol::split_frame(protocol::encode_schema_sample_frame(1, sample.bytes.data(), sample.bytes.size(), + sample.sample_time_local_common_clock_ns, + sample.sample_time_raw_device_clock_ns)) .payload; } @@ -82,100 +84,92 @@ std::vector schema_payload(const wire::SchemaSample& sample) TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit]") { - wire::FrameHeader header; - header.type = wire::FrameType::HandSample; + protocol::FrameHeader header; + header.type = protocol::FrameType::HandSample; header.channel_id = 0xBEEF; header.seq = 0x01020304; - header.payload_size = static_cast(wire::kHandSamplePayloadSize); + header.payload_size = static_cast(protocol::kHandSamplePayloadSize); header.t_send_monotonic_ns = -1234567890123LL; - uint8_t bytes[wire::kHeaderSize]; - wire::encode_header(header, bytes); + uint8_t bytes[protocol::kHeaderSize]; + protocol::encode_header(header, bytes); REQUIRE(bytes[0] == 0x52); // little-endian "RPS0" REQUIRE(bytes[1] == 0x50); REQUIRE(bytes[2] == 0x53); REQUIRE(bytes[3] == 0x30); - const wire::FrameHeader decoded = wire::decode_header(bytes); - REQUIRE(decoded.type == wire::FrameType::HandSample); - REQUIRE(decoded.version == wire::kProtocolVersion); + const protocol::FrameHeader decoded = protocol::decode_header(bytes); + REQUIRE(decoded.type == protocol::FrameType::HandSample); + REQUIRE(decoded.version == protocol::kProtocolVersion); REQUIRE(decoded.channel_id == 0xBEEF); REQUIRE(decoded.seq == 0x01020304); - REQUIRE(decoded.payload_size == wire::kHandSamplePayloadSize); + REQUIRE(decoded.payload_size == protocol::kHandSamplePayloadSize); REQUIRE(decoded.t_send_monotonic_ns == -1234567890123LL); SECTION("bad magic is rejected") { bytes[0] ^= 0xFF; - REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); } SECTION("unknown type is rejected") { bytes[4] = 200; - REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); } SECTION("other protocol versions are rejected") { bytes[5] = 1; - REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); } SECTION("oversized payloads are rejected") { std::memset(bytes + 12, 0xFF, 4); - REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); } } TEST_CASE("Wire contract v1 is 12 message types plus PING and PONG in a 24-byte header", "[remote_device_bridge][unit]") { - const std::vector> contract = { - { wire::FrameType::Hello, "HELLO" }, - { wire::FrameType::HelloAck, "HELLO_ACK" }, - { wire::FrameType::OpenHand, "OPEN_HAND" }, - { wire::FrameType::OpenSchema, "OPEN_SCHEMA" }, - { wire::FrameType::OpenPull, "OPEN_PULL" }, - { wire::FrameType::OpenWrist, "OPEN_WRIST" }, - { wire::FrameType::Close, "CLOSE" }, - { wire::FrameType::HandSample, "HAND_SAMPLE" }, - { wire::FrameType::SchemaSample, "SCHEMA_SAMPLE" }, - { wire::FrameType::WristSample, "WRIST_SAMPLE" }, - { wire::FrameType::Heartbeat, "HEARTBEAT" }, - { wire::FrameType::Error, "ERROR" }, - { wire::FrameType::Ping, "PING" }, // bridge -> sender, t1 - { wire::FrameType::Pong, "PONG" }, // sender -> bridge, t1 t2 t3 + // Frame type numbers are part of the wire contract. + const std::vector contract = { + protocol::FrameType::Hello, protocol::FrameType::HelloAck, protocol::FrameType::OpenHand, + protocol::FrameType::OpenSchema, protocol::FrameType::OpenPull, protocol::FrameType::OpenWrist, + protocol::FrameType::Close, protocol::FrameType::HandSample, protocol::FrameType::SchemaSample, + protocol::FrameType::WristSample, protocol::FrameType::Heartbeat, protocol::FrameType::Error, + protocol::FrameType::Ping, // bridge -> sender, t1 + protocol::FrameType::Pong, // sender -> bridge, t1 t2 t3 }; for (size_t i = 0; i < contract.size(); ++i) { - REQUIRE(static_cast(contract[i].first) == i + 1); - REQUIRE(std::string(wire::to_string(contract[i].first)) == contract[i].second); + REQUIRE(static_cast(contract[i]) == i + 1); } - REQUIRE(wire::kHeaderSize == 24); - REQUIRE(wire::kProtocolVersion == 0); - REQUIRE(wire::kHelloVersion == 2); + REQUIRE(protocol::kHeaderSize == 24); + REQUIRE(protocol::kProtocolVersion == 0); + REQUIRE(protocol::kHelloVersion == 2); // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. - wire::FrameHeader header; - header.type = wire::FrameType::Pong; + protocol::FrameHeader header; + header.type = protocol::FrameType::Pong; header.channel_id = 0x0A0B; header.seq = 0x0C0D0E0F; header.payload_size = 24; header.t_send_monotonic_ns = 0x1112131415161718LL; - uint8_t bytes[wire::kHeaderSize]; - wire::encode_header(header, bytes); + uint8_t bytes[protocol::kHeaderSize]; + protocol::encode_header(header, bytes); const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, 24, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; - REQUIRE(std::vector(bytes, bytes + wire::kHeaderSize) == expected); + REQUIRE(std::vector(bytes, bytes + protocol::kHeaderSize) == expected); for (const uint8_t type : { 0, 15 }) { bytes[4] = type; - REQUIRE_THROWS_AS(wire::decode_header(bytes), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); } } TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") { - wire::Hello hello; + protocol::Hello hello; hello.app_name = "ManusHandPlugin"; const core::WristTrackingSourceConfig wrist{ .mode = core::WristTrackingSourceMode::Controller, @@ -183,8 +177,8 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") .right_aim_to_wrist = { { 0.0f, 1.0f, 0.0f, 0.0f }, { -1.0f, 0.5f, 0.25f } } }; hello.requirements = { .schema_push = true, .hand_tracking_push = false, .wrist_tracking_pull = wrist }; - const wire::Hello decoded = wire::decode_hello(wire::encode(hello)); - REQUIRE(decoded.proto_version == wire::kHelloVersion); + const protocol::Hello decoded = protocol::decode_hello(protocol::encode_hello(hello)); + REQUIRE(decoded.proto_version == protocol::kHelloVersion); REQUIRE(decoded.app_name == "ManusHandPlugin"); REQUIRE(decoded.requirements.schema_push); REQUIRE_FALSE(decoded.requirements.hand_tracking_push); @@ -194,29 +188,30 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") REQUIRE(decoded.requirements.wrist_tracking_pull->right_aim_to_wrist.orientation.y == 1.0f); hello.requirements.wrist_tracking_pull.reset(); - REQUIRE_FALSE(wire::decode_hello(wire::encode(hello)).requirements.wrist_tracking_pull); + REQUIRE_FALSE(protocol::decode_hello(protocol::encode_hello(hello)).requirements.wrist_tracking_pull); hello.proto_version = 1; - REQUIRE_THROWS_AS(wire::decode_hello(wire::encode(hello)), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_hello(protocol::encode_hello(hello)), protocol::DecodeError); - const wire::HelloAck ack = wire::decode_hello_ack(wire::encode(wire::HelloAck{ false, "no runtime" })); + const protocol::HelloAck ack = + protocol::decode_hello_ack(protocol::encode_hello_ack(protocol::HelloAck{ false, "no runtime" })); REQUIRE_FALSE(ack.accepted); REQUIRE(ack.reason == "no runtime"); - const wire::HelloAck ok = wire::decode_hello_ack(wire::encode(wire::HelloAck{ true, "" })); + const protocol::HelloAck ok = protocol::decode_hello_ack(protocol::encode_hello_ack(protocol::HelloAck{ true, "" })); REQUIRE(ok.accepted); REQUIRE(ok.reason.empty()); } TEST_CASE("OPEN_HAND encodes both hands and rejects others", "[remote_device_bridge][unit]") { - REQUIRE(wire::encode(wire::OpenHand{ XR_HAND_LEFT_EXT }) == std::vector{ 0 }); - REQUIRE(wire::encode(wire::OpenHand{ XR_HAND_RIGHT_EXT }) == std::vector{ 1 }); - REQUIRE(wire::decode_open_hand({ 0 }).hand == XR_HAND_LEFT_EXT); - REQUIRE(wire::decode_open_hand({ 1 }).hand == XR_HAND_RIGHT_EXT); - REQUIRE_THROWS_AS(wire::decode_open_hand({ 2 }), wire::DecodeError); - REQUIRE_THROWS_AS(wire::decode_open_hand({}), wire::DecodeError); - REQUIRE_THROWS_AS(wire::decode_open_hand({ 0, 0 }), wire::DecodeError); + REQUIRE(protocol::encode_open_hand(XR_HAND_LEFT_EXT) == std::vector{ 0 }); + REQUIRE(protocol::encode_open_hand(XR_HAND_RIGHT_EXT) == std::vector{ 1 }); + REQUIRE(protocol::decode_open_hand({ 0 }) == XR_HAND_LEFT_EXT); + REQUIRE(protocol::decode_open_hand({ 1 }) == XR_HAND_RIGHT_EXT); + REQUIRE_THROWS_AS(protocol::decode_open_hand({ 2 }), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand({}), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand({ 0, 0 }), protocol::DecodeError); } TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][unit]") @@ -226,16 +221,16 @@ TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][ .tensor_identifier = "joint_state", .localized_name = "Manus Sensors Left", .app_name = "" }; - const core::SchemaPusherConfig decoded = wire::decode_open_schema(wire::encode(config)); + const core::SchemaPusherConfig decoded = protocol::decode_open_schema(protocol::encode_open_schema(config)); REQUIRE(decoded.collection_id == config.collection_id); REQUIRE(decoded.max_flatbuffer_size == 4096); REQUIRE(decoded.tensor_identifier == config.tensor_identifier); REQUIRE(decoded.localized_name == config.localized_name); REQUIRE(decoded.app_name.empty()); - std::vector truncated = wire::encode(config); + std::vector truncated = protocol::encode_open_schema(config); truncated.pop_back(); - REQUIRE_THROWS_AS(wire::decode_open_schema(truncated), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_schema(truncated), protocol::DecodeError); } TEST_CASE("OPEN_WRIST round-trips WristTrackingSourceConfig", "[remote_device_bridge][unit]") @@ -245,23 +240,23 @@ TEST_CASE("OPEN_WRIST round-trips WristTrackingSourceConfig", "[remote_device_br config.left_aim_to_wrist = make_pose(0.1f); config.right_aim_to_wrist = make_pose(0.7f); - const std::vector bytes = wire::encode(config); - REQUIRE(bytes.size() == wire::kWristConfigPayloadSize); - const core::WristTrackingSourceConfig decoded = wire::decode_open_wrist(bytes); + const std::vector bytes = protocol::encode_open_wrist(config); + REQUIRE(bytes.size() == protocol::kWristConfigPayloadSize); + const core::WristTrackingSourceConfig decoded = protocol::decode_open_wrist(bytes); REQUIRE(decoded.mode == core::WristTrackingSourceMode::Controller); REQUIRE(same_pose(decoded.left_aim_to_wrist, config.left_aim_to_wrist)); REQUIRE(same_pose(decoded.right_aim_to_wrist, config.right_aim_to_wrist)); - REQUIRE(wire::decode_open_wrist(wire::encode(core::WristTrackingSourceConfig{})).mode == + REQUIRE(protocol::decode_open_wrist(protocol::encode_open_wrist(core::WristTrackingSourceConfig{})).mode == core::WristTrackingSourceMode::Auto); std::vector bad_mode = bytes; bad_mode[0] = 7; - REQUIRE_THROWS_AS(wire::decode_open_wrist(bad_mode), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_wrist(bad_mode), protocol::DecodeError); } TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge][unit]") { - wire::HandSample sample; + protocol::HandSample sample; sample.sample_time_ns = 987654321012345LL; for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { @@ -271,9 +266,9 @@ TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge } const std::vector bytes = hand_payload(sample); - REQUIRE(bytes.size() == wire::kHandSamplePayloadSize); + REQUIRE(bytes.size() == protocol::kHandSamplePayloadSize); - const wire::HandSample decoded = wire::decode_hand_sample(bytes); + const protocol::HandSample decoded = protocol::decode_hand_sample(bytes); REQUIRE(decoded.sample_time_ns == sample.sample_time_ns); for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { @@ -283,94 +278,95 @@ TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge } std::vector truncated(bytes.begin(), bytes.end() - 1); - REQUIRE_THROWS_AS(wire::decode_hand_sample(truncated), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_hand_sample(truncated), protocol::DecodeError); std::vector extended = bytes; extended.push_back(0); - REQUIRE_THROWS_AS(wire::decode_hand_sample(extended), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_hand_sample(extended), protocol::DecodeError); } TEST_CASE("SCHEMA_SAMPLE round-trips bytes and timestamps", "[remote_device_bridge][unit]") { - wire::SchemaSample sample; + protocol::SchemaSample sample; sample.sample_time_local_common_clock_ns = 111; sample.sample_time_raw_device_clock_ns = 222; sample.bytes = { 0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01 }; - const wire::SchemaSample decoded = wire::decode_schema_sample(schema_payload(sample)); + const protocol::SchemaSample decoded = protocol::decode_schema_sample(schema_payload(sample)); REQUIRE(decoded.sample_time_local_common_clock_ns == 111); REQUIRE(decoded.sample_time_raw_device_clock_ns == 222); REQUIRE(decoded.bytes == sample.bytes); - const wire::SchemaSample empty = wire::decode_schema_sample(schema_payload(wire::SchemaSample{})); + const protocol::SchemaSample empty = protocol::decode_schema_sample(schema_payload(protocol::SchemaSample{})); REQUIRE(empty.bytes.empty()); std::vector lying = schema_payload(sample); lying[16] = 0xFF; // declared size larger than the remaining bytes - REQUIRE_THROWS_AS(wire::decode_schema_sample(lying), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_schema_sample(lying), protocol::DecodeError); } TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") { - wire::WristSample sample; + protocol::WristSample sample; sample.sample_time_ns = -5; - sample.is_left = false; + sample.hand = XR_HAND_RIGHT_EXT; sample.sample.valid = true; sample.sample.tracked = false; sample.sample.pose = make_pose(0.3f); - const std::vector bytes = wire::encode(sample); - REQUIRE(bytes.size() == wire::kWristSamplePayloadSize); - const wire::WristSample decoded = wire::decode_wrist_sample(bytes); + const std::vector bytes = protocol::encode_wrist_sample(sample); + REQUIRE(bytes.size() == protocol::kWristSamplePayloadSize); + REQUIRE(bytes[8] == 0); // byte 8 keeps its original meaning: 1 = left, 0 = right + const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); REQUIRE(decoded.sample_time_ns == -5); - REQUIRE_FALSE(decoded.is_left); + REQUIRE(decoded.hand == XR_HAND_RIGHT_EXT); REQUIRE(decoded.sample.valid); REQUIRE_FALSE(decoded.sample.tracked); REQUIRE(same_pose(decoded.sample.pose, sample.sample.pose)); std::vector bad_bool = bytes; bad_bool[9] = 2; - REQUIRE_THROWS_AS(wire::decode_wrist_sample(bad_bool), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_wrist_sample(bad_bool), protocol::DecodeError); } TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_bridge][unit]") { - REQUIRE(wire::decode_error(wire::encode(wire::Error{ "boom" })).message == "boom"); - REQUIRE(wire::decode_error(wire::encode(wire::Error{ "" })).message.empty()); - REQUIRE_THROWS_AS(wire::decode_error({ 4, 0, 0, 0, 'a' }), wire::DecodeError); - REQUIRE(std::string(wire::to_string(wire::FrameType::Heartbeat)) == "HEARTBEAT"); + REQUIRE(protocol::decode_error(protocol::encode_error("boom")) == "boom"); + REQUIRE(protocol::decode_error(protocol::encode_error("")).empty()); + REQUIRE_THROWS_AS(protocol::decode_error({ 4, 0, 0, 0, 'a' }), protocol::DecodeError); } TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remote_device_bridge][unit]") { - const std::vector ping = wire::encode(wire::Ping{ -123456789012345LL }); + const std::vector ping = protocol::encode_ping(-123456789012345LL); REQUIRE(ping.size() == 8); - REQUIRE(wire::decode_ping(ping).t1_ns == -123456789012345LL); - REQUIRE_THROWS_AS(wire::decode_ping({ 1, 2, 3 }), wire::DecodeError); + REQUIRE(protocol::decode_ping(ping) == -123456789012345LL); + REQUIRE_THROWS_AS(protocol::decode_ping({ 1, 2, 3 }), protocol::DecodeError); - const std::vector payload = wire::encode(wire::Pong{ 1, 2, 3 }); + const std::vector payload = protocol::encode_pong(protocol::Pong{ 1, 2, 3 }); REQUIRE(payload.size() == 24); - const wire::Pong pong = wire::decode_pong(payload); + const protocol::Pong pong = protocol::decode_pong(payload); REQUIRE(pong.t1_ns == 1); REQUIRE(pong.t2_ns == 2); REQUIRE(pong.t3_ns == 3); - REQUIRE_THROWS_AS(wire::decode_pong(std::vector(25, 0)), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(25, 0)), protocol::DecodeError); - std::vector frame = wire::encode_frame(wire::FrameType::Pong, wire::kSessionChannelId, payload); - wire::stamp_header(frame.data(), 7, 0x0102030405060708LL); - const wire::Frame split = wire::split_frame(frame); - REQUIRE(split.header.type == wire::FrameType::Pong); + std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, protocol::kSessionChannelId, payload); + protocol::stamp_header(frame.data(), 7, 0x0102030405060708LL); + const protocol::Frame split = protocol::split_frame(frame); + REQUIRE(split.header.type == protocol::FrameType::Pong); REQUIRE(split.header.t_send_monotonic_ns == 0x0102030405060708LL); - const wire::Pong stamped = wire::decode_pong(split.payload); + const protocol::Pong stamped = protocol::decode_pong(split.payload); REQUIRE(stamped.t1_ns == 1); REQUIRE(stamped.t2_ns == 2); REQUIRE(stamped.t3_ns == 0x0102030405060708LL); // stamp_header leaves the payload of every other frame type alone. - std::vector ping_frame = wire::encode_frame(wire::FrameType::Ping, wire::kSessionChannelId, ping); - wire::stamp_header(ping_frame.data(), 8, 42); - REQUIRE(wire::decode_ping(wire::split_frame(ping_frame).payload).t1_ns == -123456789012345LL); - REQUIRE(std::string(wire::to_string(wire::FrameType::Ping)) == "PING"); - REQUIRE(std::string(wire::to_string(wire::FrameType::Pong)) == "PONG"); + std::vector ping_frame = + protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, ping); + protocol::stamp_header(ping_frame.data(), 8, 42); + REQUIRE(protocol::decode_ping(protocol::split_frame(ping_frame).payload) == -123456789012345LL); + REQUIRE_THROWS_WITH(protocol::decode_ping({ 1, 2, 3 }), Catch::Matchers::ContainsSubstring("PING")); + REQUIRE_THROWS_WITH(protocol::decode_pong({ 1 }), Catch::Matchers::ContainsSubstring("PONG")); } TEST_CASE("Contiguous frame builders match header + payload encoder byte for byte", "[remote_device_bridge][unit]") @@ -379,7 +375,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt { const std::vector bytes = { 0xDE, 0xAD }; std::vector frame = - wire::encode_schema_sample_frame(3, bytes.data(), bytes.size(), 0x0102030405060708LL, -1); + protocol::encode_schema_sample_frame(3, bytes.data(), bytes.size(), 0x0102030405060708LL, -1); // clang-format off const std::vector golden = { 0x52, 0x50, 0x53, 0x30, // magic "RPS0" @@ -396,26 +392,26 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt // clang-format on REQUIRE(frame == golden); - wire::stamp_header(frame.data(), 0x11223344u, 0x0807060504030201LL); + protocol::stamp_header(frame.data(), 0x11223344u, 0x0807060504030201LL); REQUIRE(std::vector(frame.begin() + 8, frame.begin() + 12) == std::vector{ 0x44, 0x33, 0x22, 0x11 }); REQUIRE(std::vector(frame.begin() + 16, frame.begin() + 24) == std::vector{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 }); REQUIRE(std::equal(frame.begin() + 24, frame.end(), golden.begin() + 24)); // payload untouched - const wire::Frame split = wire::split_frame(frame); - REQUIRE(split.header.type == wire::FrameType::SchemaSample); + const protocol::Frame split = protocol::split_frame(frame); + REQUIRE(split.header.type == protocol::FrameType::SchemaSample); REQUIRE(split.header.channel_id == 3); REQUIRE(split.header.seq == 0x11223344u); REQUIRE(split.header.t_send_monotonic_ns == 0x0807060504030201LL); REQUIRE(split.payload == std::vector(golden.begin() + 24, golden.end())); - wire::SchemaSample decoded = wire::decode_schema_sample(split.payload); + protocol::SchemaSample decoded = protocol::decode_schema_sample(split.payload); REQUIRE(decoded.bytes == bytes); REQUIRE(decoded.sample_time_raw_device_clock_ns == -1); } SECTION("HAND_SAMPLE against the reference payload encoder") { - wire::HandSample sample; + protocol::HandSample sample; sample.sample_time_ns = -42; for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { @@ -424,29 +420,29 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt sample.joints[i].radius = 0.001f * static_cast(i); } const std::vector payload = reference_hand_payload(sample); - REQUIRE(payload.size() == wire::kHandSamplePayloadSize); - const std::vector frame = wire::encode_hand_sample_frame(0x0102, sample.joints.data(), -42); - REQUIRE(frame.size() == wire::kHeaderSize + wire::kHandSamplePayloadSize); - const wire::FrameHeader header = wire::decode_header(frame.data()); - REQUIRE(header.type == wire::FrameType::HandSample); + REQUIRE(payload.size() == protocol::kHandSamplePayloadSize); + const std::vector frame = protocol::encode_hand_sample_frame(0x0102, sample.joints.data(), -42); + REQUIRE(frame.size() == protocol::kHeaderSize + protocol::kHandSamplePayloadSize); + const protocol::FrameHeader header = protocol::decode_header(frame.data()); + REQUIRE(header.type == protocol::FrameType::HandSample); REQUIRE(header.channel_id == 0x0102); - REQUIRE(header.payload_size == wire::kHandSamplePayloadSize); + REQUIRE(header.payload_size == protocol::kHandSamplePayloadSize); REQUIRE(std::equal(frame.begin() + 24, frame.end(), payload.begin(), payload.end())); - REQUIRE(wire::encode_frame(wire::FrameType::HandSample, 0x0102, payload) == frame); + REQUIRE(protocol::encode_frame(protocol::FrameType::HandSample, 0x0102, payload) == frame); } SECTION("split_frame rejects short or inconsistent messages") { - REQUIRE_THROWS_AS(wire::split_frame(std::vector(10, 0)), wire::DecodeError); - std::vector frame = wire::encode_frame(wire::FrameType::Heartbeat, 0, {}); - REQUIRE(frame.size() == wire::kHeaderSize); - REQUIRE(wire::split_frame(frame).payload.empty()); + REQUIRE_THROWS_AS(protocol::split_frame(std::vector(10, 0)), protocol::DecodeError); + std::vector frame = protocol::encode_frame(protocol::FrameType::Heartbeat, 0, {}); + REQUIRE(frame.size() == protocol::kHeaderSize); + REQUIRE(protocol::split_frame(frame).payload.empty()); frame.push_back(0); - REQUIRE_THROWS_AS(wire::split_frame(frame), wire::DecodeError); + REQUIRE_THROWS_AS(protocol::split_frame(frame), protocol::DecodeError); } SECTION("payloads above the limit are refused at build time") { - std::vector too_big(wire::kMaxPayloadSize + 1); + std::vector too_big(protocol::kMaxPayloadSize + 1); REQUIRE_THROWS_AS( - wire::encode_schema_sample_frame(1, too_big.data(), too_big.size(), 0, 0), std::invalid_argument); + protocol::encode_schema_sample_frame(1, too_big.data(), too_big.size(), 0, 0), std::invalid_argument); } } From 8de7c8cba9d9e36403b30565fb9b7e6d2b24f036 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:21:52 -0700 Subject: [PATCH 04/18] review round 1 (pr01) Applied the fact-checked (VERIFIED) findings on code this branch adds: - Frame layer: kHeaderSize is derived from its fields; encode_header is a private detail that writes in place with named offsets; stamp_header takes the frame vector and only touches the header; decode_header's type bound follows kLastFrameType; FrameHeader::type has no default; split_frame's doc says the payload keeps the message buffer. - PONG t3 stamping moves out of the frame layer into set_pong_t3, called where the pong is sent. - Payload layer: FrameType comments keep only direction (layouts live with the builders); parsers pass the frame name to the reader directly, so the unreachable to_string is gone; builders share build_payload; HELLO accepts exactly kHelloVersion; history and future-tense comments go; size constants used only by tests move into the test; own private header first. - Build: the remote_device_bridge block sits with the other gated plugins; the session CMake comment duplicating AGENTS.md is gone; the test target does not re-link pusherio; AGENTS.md describes the split accurately. - Tests: no constant-against-literal checks; header goldens go through encode_frame + stamp_header. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/CMakeLists.txt | 7 +- src/plugins/remote_device_bridge/AGENTS.md | 2 +- .../session/CMakeLists.txt | 3 - .../remote_plugin_session/protocol_frame.hpp | 54 ++--- .../protocol_payloads.hpp | 19 +- .../session/protocol_frame.cpp | 69 ++++--- .../session/protocol_io.hpp | 3 + .../session/protocol_payloads.cpp | 192 ++++++++---------- .../remote_device_bridge/CMakeLists.txt | 1 - .../remote_device_bridge/test_wire_codec.cpp | 52 ++--- 10 files changed, 190 insertions(+), 212 deletions(-) diff --git a/src/plugins/CMakeLists.txt b/src/plugins/CMakeLists.txt index 3d3ae72dc5..60c15ae223 100644 --- a/src/plugins/CMakeLists.txt +++ b/src/plugins/CMakeLists.txt @@ -23,13 +23,14 @@ add_subdirectory(gamepad) add_subdirectory(xsens_full_body) add_subdirectory(so101_leader) add_subdirectory(rebot_devarm_leader) -if(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE) - add_subdirectory(remote_device_bridge) -endif() add_subdirectory(manus) add_subdirectory(manus_calibration) add_subdirectory(haptikos) +if(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE) + add_subdirectory(remote_device_bridge) +endif() + if(BUILD_PLUGIN_NOITOM_MOCAP) add_subdirectory(noitom_mocap) endif() diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index d9f35d471d..b3e26f12a3 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -7,5 +7,5 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. -- `session/protocol_frame.*` (header and frame layer) and `session/protocol_payloads.*` (one builder/parser pair per frame type) are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. +- `session/protocol_frame.*` (header and frame layer) and `session/protocol_payloads.*` (payload builders and parsers, sample frame builders, PONG t3 stamping) are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. - `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin using `--remote` must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/CMakeLists.txt b/src/plugins/remote_device_bridge/session/CMakeLists.txt index b13809cd7f..676dad270a 100644 --- a/src/plugins/remote_device_bridge/session/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/session/CMakeLists.txt @@ -3,9 +3,6 @@ cmake_minimum_required(VERSION 3.20) -# Transport-only library shared by the bridge, the synthetic sender and any -# plugin that offers --remote. It must never link the OpenXR loader or -# plugin_utils: plugin processes using it stay free of an OpenXR runtime. add_library(remote_plugin_session STATIC protocol_frame.cpp protocol_payloads.cpp diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 64352ffc8a..8df55f8430 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -13,38 +13,41 @@ namespace remote_plugin_protocol /*! * Remote plugin protocol v0: fixed little-endian frames over one connection per - * plugin session. Frame = 24-byte header + payload. Payload layouts live in + * plugin session. Frame = header + payload; payload layouts live in * protocol_payloads.hpp. */ constexpr uint32_t kMagic = 0x30535052u; // "RPS0" constexpr uint8_t kProtocolVersion = 0; -constexpr size_t kHeaderSize = 24; +//! magic u32, type u8, version u8, channel u16, seq u32, payload size u32, t_send i64. +constexpr size_t kHeaderSize = + sizeof(uint32_t) + 2 * sizeof(uint8_t) + sizeof(uint16_t) + 2 * sizeof(uint32_t) + sizeof(int64_t); constexpr uint16_t kSessionChannelId = 0; constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded +//! Direction is c->s (plugin to bridge) or s->c. OPEN_PULL, CLOSE and HEARTBEAT have empty payloads. enum class FrameType : uint8_t { - Hello = 1, // c->s: proto_version, app_name, requirements - HelloAck = 2, // s->c: accepted, reason - OpenHand = 3, // c->s: hand (0 left, 1 right) - OpenSchema = 4, // c->s: SchemaPusherConfig - OpenPull = 5, // c->s: empty - OpenWrist = 6, // c->s: WristTrackingSourceConfig on the pull channel id - Close = 7, // c->s: empty - HandSample = 8, // c->s: sample_time + 26 joints - SchemaSample = 9, // c->s: two timestamps + bytes - WristSample = 10, // s->c: sample_time, hand, valid, tracked, pose - Heartbeat = 11, // both: empty - Error = 12, // s->c: message; on channel 0 the connection closes afterwards, on a channel id only that - // channel is refused - Ping = 13, // s->c: t1 (bridge send time) - Pong = 14, // c->s: t1 echoed, t2 (client receive time), t3 (client send time) + Hello = 1, // c->s + HelloAck = 2, // s->c + OpenHand = 3, // c->s + OpenSchema = 4, // c->s + OpenPull = 5, // c->s + OpenWrist = 6, // c->s, on the pull channel id + Close = 7, // c->s + HandSample = 8, // c->s + SchemaSample = 9, // c->s + WristSample = 10, // s->c + Heartbeat = 11, // both + Error = 12, // s->c; on channel 0 the connection closes afterwards, on a channel id only that channel is refused + Ping = 13, // s->c + Pong = 14, // c->s }; +constexpr FrameType kLastFrameType = FrameType::Pong; struct FrameHeader { - FrameType type = FrameType::Heartbeat; + FrameType type; uint8_t version = kProtocolVersion; uint16_t channel_id = kSessionChannelId; uint32_t seq = 0; @@ -64,19 +67,16 @@ class DecodeError : public std::runtime_error using std::runtime_error::runtime_error; }; -static_assert(kHeaderSize == 4 + 1 + 1 + 2 + 4 + 4 + 8); - -//! `out` must hold kHeaderSize bytes. -void encode_header(const FrameHeader& header, uint8_t* out); -//! Throws DecodeError on bad magic, unknown type, unsupported version or an oversized payload. +//! Reads the first kHeaderSize bytes of `in`. Throws DecodeError on bad magic, unknown type, unsupported version or an +//! oversized payload. FrameHeader decode_header(const uint8_t* in); //! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(). std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); -//! Patches seq and t_send into an encoded frame's header in place; on a PONG also sets t3 = t_send, so t3 is -//! the time the frame actually left, not when it was queued. -void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns); -//! Splits one complete message into header and payload (payload moved, not copied). Throws DecodeError. +//! Patches seq and t_send into an encoded frame's header in place. +void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_monotonic_ns); +//! Splits one complete message into header and payload. The payload keeps `message`'s buffer (its bytes are +//! shifted down by the header size). Throws DecodeError. Frame split_frame(std::vector message); } // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 74faa7195e..236aa5643d 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -18,14 +18,12 @@ namespace remote_plugin_protocol { /*! - * Payload builders and parsers, one pair per frame type. `str` = u32 length + - * bytes, `pose` = 7 x f32 in XrPosef order (orientation x,y,z,w then position - * x,y,z). Swapping the hand payload for a FlatBuffer later only changes the - * HAND_SAMPLE pair here. + * Payload builders and parsers. `str` = u32 length + bytes, `pose` = 7 x f32 in + * XrPosef order (orientation x,y,z,w then position x,y,z). */ -//! HELLO proto_version: 2 = requirements carry the wrist source config (not a flag) and the client answers -//! PING with PONG. decode_hello rejects older versions, whose payload layout differs. +//! HELLO proto_version: the requirements carry the wrist source config, and the client answers PING with PONG. +//! decode_hello accepts only this version. constexpr uint16_t kHelloVersion = 2; struct Hello @@ -54,6 +52,7 @@ struct SchemaSample std::vector bytes; }; +//! On the wire the hand is one byte, 1 = left and 0 = right. struct WristSample { int64_t sample_time_ns = 0; @@ -72,15 +71,13 @@ struct Pong constexpr size_t kPoseSize = 7 * sizeof(float); constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; -constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + kPoseSize; -constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * kPoseSize; static_assert(kJointSize == 40); static_assert(kHandSamplePayloadSize == 1048); -static_assert(sizeof(XrSpaceLocationFlags) == sizeof(uint64_t)); std::vector encode_hello(const Hello& value); std::vector encode_hello_ack(const HelloAck& value); +//! One byte: 0 = left, 1 = right. std::vector encode_open_hand(XrHandEXT hand); std::vector encode_open_schema(const core::SchemaPusherConfig& value); std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value); @@ -88,6 +85,8 @@ std::vector encode_wrist_sample(const WristSample& value); std::vector encode_error(const std::string& message); std::vector encode_ping(int64_t t1_ns); std::vector encode_pong(const Pong& value); +//! Sets t3 in an encoded PONG frame; call where the frame is sent, so t3 is when it left, not when it was queued. +void set_pong_t3(std::vector& pong_frame, int64_t t3_ns); // Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. std::vector encode_hand_sample_frame(uint16_t channel_id, @@ -99,7 +98,7 @@ std::vector encode_schema_sample_frame(uint16_t channel_id, int64_t sample_time_local_common_clock_ns, int64_t sample_time_raw_device_clock_ns); -// Parsers throw DecodeError, naming the frame type, on truncated, over-long or out-of-range payloads. +// Parsers throw DecodeError, naming the frame, on truncated, over-long or out-of-range payloads. Hello decode_hello(const std::vector& payload); HelloAck decode_hello_ack(const std::vector& payload); XrHandEXT decode_open_hand(const std::vector& payload); diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 678a96fdc3..31491c6b12 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -5,7 +5,7 @@ #include "protocol_io.hpp" -#include +#include #include #include @@ -16,40 +16,50 @@ using detail::build_frame; using detail::Reader; using detail::Writer; -void encode_header(const FrameHeader& header, uint8_t* out) +namespace { - std::vector bytes; - Writer writer(bytes); - writer.u32(kMagic); - writer.u8(static_cast(header.type)); - writer.u8(header.version); - writer.u16(header.channel_id); - writer.u32(header.seq); - writer.u32(header.payload_size); - writer.i64(header.t_send_monotonic_ns); - std::memcpy(out, bytes.data(), kHeaderSize); -} -void stamp_header(uint8_t* frame, uint32_t seq, int64_t t_send_monotonic_ns) +constexpr size_t kTypeOffset = 4; +constexpr size_t kVersionOffset = 5; +constexpr size_t kChannelOffset = 6; +constexpr size_t kSeqOffset = 8; +constexpr size_t kPayloadSizeOffset = 12; +constexpr size_t kSendTimeOffset = 16; + +void store_le(uint8_t* out, uint64_t value, size_t size) { - // Byte offsets follow encode_header: seq at 8, t_send at 16. - for (int i = 0; i < 4; ++i) - { - frame[8 + i] = static_cast(seq >> (8 * i)); - } - const uint64_t t_send = static_cast(t_send_monotonic_ns); - for (int i = 0; i < 8; ++i) + for (size_t i = 0; i < size; ++i) { - frame[16 + i] = static_cast(t_send >> (8 * i)); + out[i] = static_cast(value >> (8 * i)); } - // Pong payload: t1, t2, t3 (i64 each); t3 at payload offset 16. - if (frame[4] == static_cast(FrameType::Pong) && decode_header(frame).payload_size == 3 * sizeof(int64_t)) +} + +} // namespace + +namespace detail +{ + +void encode_header(const FrameHeader& header, uint8_t* out) +{ + store_le(out, kMagic, sizeof(uint32_t)); + out[kTypeOffset] = static_cast(header.type); + out[kVersionOffset] = header.version; + store_le(out + kChannelOffset, header.channel_id, sizeof(uint16_t)); + store_le(out + kSeqOffset, header.seq, sizeof(uint32_t)); + store_le(out + kPayloadSizeOffset, header.payload_size, sizeof(uint32_t)); + store_le(out + kSendTimeOffset, static_cast(header.t_send_monotonic_ns), sizeof(int64_t)); +} + +} // namespace detail + +void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_monotonic_ns) +{ + if (frame.size() < kHeaderSize) { - for (int i = 0; i < 8; ++i) - { - frame[kHeaderSize + 16 + i] = static_cast(t_send >> (8 * i)); - } + throw std::invalid_argument("protocol: frame shorter than a header"); } + store_le(frame.data() + kSeqOffset, seq, sizeof(uint32_t)); + store_le(frame.data() + kSendTimeOffset, static_cast(t_send_monotonic_ns), sizeof(int64_t)); } Frame split_frame(std::vector message) @@ -84,7 +94,7 @@ FrameHeader decode_header(const uint8_t* in) } FrameHeader header; const uint8_t type = reader.u8(); - if (type < static_cast(FrameType::Hello) || type > static_cast(FrameType::Pong)) + if (type < static_cast(FrameType::Hello) || type > static_cast(kLastFrameType)) { throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } @@ -102,7 +112,6 @@ FrameHeader decode_header(const uint8_t* in) throw DecodeError("protocol: payload size " + std::to_string(header.payload_size) + " exceeds limit"); } header.t_send_monotonic_ns = reader.i64(); - reader.finish(); return header; } diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index bd4e8987e1..66ccbec81c 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -18,6 +18,9 @@ namespace remote_plugin_protocol namespace detail { +//! Writes the header into the first kHeaderSize bytes of `out`. +void encode_header(const FrameHeader& header, uint8_t* out); + //! Appends little-endian fields to a caller-owned buffer. class Writer { diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 3e84b98c67..788eadc954 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -17,42 +17,6 @@ using detail::Writer; namespace { -const char* to_string(FrameType type) -{ - switch (type) - { - case FrameType::Hello: - return "HELLO"; - case FrameType::HelloAck: - return "HELLO_ACK"; - case FrameType::OpenHand: - return "OPEN_HAND"; - case FrameType::OpenSchema: - return "OPEN_SCHEMA"; - case FrameType::OpenPull: - return "OPEN_PULL"; - case FrameType::OpenWrist: - return "OPEN_WRIST"; - case FrameType::Close: - return "CLOSE"; - case FrameType::HandSample: - return "HAND_SAMPLE"; - case FrameType::SchemaSample: - return "SCHEMA_SAMPLE"; - case FrameType::WristSample: - return "WRIST_SAMPLE"; - case FrameType::Heartbeat: - return "HEARTBEAT"; - case FrameType::Error: - return "ERROR"; - case FrameType::Ping: - return "PING"; - case FrameType::Pong: - return "PONG"; - } - return "UNKNOWN"; -} - uint8_t to_wire_hand(XrHandEXT hand) { switch (hand) @@ -79,7 +43,6 @@ XrHandEXT from_wire_hand(uint8_t hand) } } -// WRIST_SAMPLE keeps its original byte: 1 = left, 0 = right (OPEN_HAND uses 0 = left). uint8_t to_wire_is_left(XrHandEXT hand) { switch (hand) @@ -147,6 +110,16 @@ core::WristTrackingSourceConfig read_wrist_config(Reader& reader) return value; } +//! Runs `write` against a fresh payload buffer and returns it. +template +std::vector build_payload(Write write) +{ + std::vector out; + Writer writer(out); + write(writer); + return out; +} + } // namespace std::vector encode_hand_sample_frame(uint16_t channel_id, @@ -188,104 +161,111 @@ std::vector encode_schema_sample_frame(uint16_t channel_id, std::vector encode_hello(const Hello& value) { - std::vector out; - Writer writer(out); - writer.u16(value.proto_version); - writer.str(value.app_name); - writer.u8(value.requirements.schema_push ? 1 : 0); - writer.u8(value.requirements.hand_tracking_push ? 1 : 0); - writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); - if (value.requirements.wrist_tracking_pull) - { - write_wrist_config(writer, *value.requirements.wrist_tracking_pull); - } - return out; + return build_payload( + [&](Writer& writer) + { + writer.u16(value.proto_version); + writer.str(value.app_name); + writer.u8(value.requirements.schema_push ? 1 : 0); + writer.u8(value.requirements.hand_tracking_push ? 1 : 0); + writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); + if (value.requirements.wrist_tracking_pull) + { + write_wrist_config(writer, *value.requirements.wrist_tracking_pull); + } + }); } std::vector encode_hello_ack(const HelloAck& value) { - std::vector out; - Writer writer(out); - writer.u8(value.accepted ? 1 : 0); - writer.str(value.reason); - return out; + return build_payload( + [&](Writer& writer) + { + writer.u8(value.accepted ? 1 : 0); + writer.str(value.reason); + }); } std::vector encode_open_hand(XrHandEXT hand) { - std::vector out; - Writer writer(out); - writer.u8(to_wire_hand(hand)); - return out; + return build_payload([&](Writer& writer) { writer.u8(to_wire_hand(hand)); }); } std::vector encode_open_schema(const core::SchemaPusherConfig& value) { - std::vector out; - Writer writer(out); - writer.str(value.collection_id); - writer.u64(static_cast(value.max_flatbuffer_size)); - writer.str(value.tensor_identifier); - writer.str(value.localized_name); - writer.str(value.app_name); - return out; + return build_payload( + [&](Writer& writer) + { + writer.str(value.collection_id); + writer.u64(static_cast(value.max_flatbuffer_size)); + writer.str(value.tensor_identifier); + writer.str(value.localized_name); + writer.str(value.app_name); + }); } std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value) { - std::vector out; - Writer writer(out); - write_wrist_config(writer, value); - return out; + return build_payload([&](Writer& writer) { write_wrist_config(writer, value); }); } std::vector encode_wrist_sample(const WristSample& value) { - std::vector out; - Writer writer(out); - writer.i64(value.sample_time_ns); - writer.u8(to_wire_is_left(value.hand)); - writer.u8(value.sample.valid ? 1 : 0); - writer.u8(value.sample.tracked ? 1 : 0); - writer.pose(value.sample.pose); - return out; + return build_payload( + [&](Writer& writer) + { + writer.i64(value.sample_time_ns); + writer.u8(to_wire_is_left(value.hand)); + writer.u8(value.sample.valid ? 1 : 0); + writer.u8(value.sample.tracked ? 1 : 0); + writer.pose(value.sample.pose); + }); } std::vector encode_error(const std::string& message) { - std::vector out; - Writer writer(out); - writer.str(message); - return out; + return build_payload([&](Writer& writer) { writer.str(message); }); } std::vector encode_ping(int64_t t1_ns) { - std::vector out; - Writer writer(out); - writer.i64(t1_ns); - return out; + return build_payload([&](Writer& writer) { writer.i64(t1_ns); }); } std::vector encode_pong(const Pong& value) { - std::vector out; - Writer writer(out); - writer.i64(value.t1_ns); - writer.i64(value.t2_ns); - writer.i64(value.t3_ns); - return out; + return build_payload( + [&](Writer& writer) + { + writer.i64(value.t1_ns); + writer.i64(value.t2_ns); + writer.i64(value.t3_ns); + }); +} + +void set_pong_t3(std::vector& pong_frame, int64_t t3_ns) +{ + // PONG payload: t1, t2, t3 (i64 each). + constexpr size_t kT3Offset = kHeaderSize + 2 * sizeof(int64_t); + if (pong_frame.size() != kHeaderSize + 3 * sizeof(int64_t) || decode_header(pong_frame.data()).type != FrameType::Pong) + { + throw std::invalid_argument("protocol: not an encoded PONG frame"); + } + const uint64_t bits = static_cast(t3_ns); + for (size_t i = 0; i < sizeof(int64_t); ++i) + { + pong_frame[kT3Offset + i] = static_cast(bits >> (8 * i)); + } } Hello decode_hello(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::Hello)); + Reader reader(payload, "HELLO"); Hello value; value.proto_version = reader.u16(); - if (value.proto_version < kHelloVersion) + if (value.proto_version != kHelloVersion) { - throw DecodeError("protocol: HELLO version " + std::to_string(value.proto_version) + " is older than " + - std::to_string(kHelloVersion)); + throw DecodeError("protocol: unsupported HELLO version " + std::to_string(value.proto_version)); } value.app_name = reader.str(); value.requirements.schema_push = to_bool(reader.u8()); @@ -300,7 +280,7 @@ Hello decode_hello(const std::vector& payload) HelloAck decode_hello_ack(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::HelloAck)); + Reader reader(payload, "HELLO_ACK"); HelloAck value; value.accepted = to_bool(reader.u8()); value.reason = reader.str(); @@ -310,7 +290,7 @@ HelloAck decode_hello_ack(const std::vector& payload) XrHandEXT decode_open_hand(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::OpenHand)); + Reader reader(payload, "OPEN_HAND"); const XrHandEXT hand = from_wire_hand(reader.u8()); reader.finish(); return hand; @@ -318,7 +298,7 @@ XrHandEXT decode_open_hand(const std::vector& payload) core::SchemaPusherConfig decode_open_schema(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::OpenSchema)); + Reader reader(payload, "OPEN_SCHEMA"); core::SchemaPusherConfig value; value.collection_id = reader.str(); value.max_flatbuffer_size = static_cast(reader.u64()); @@ -331,7 +311,7 @@ core::SchemaPusherConfig decode_open_schema(const std::vector& payload) core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::OpenWrist)); + Reader reader(payload, "OPEN_WRIST"); const core::WristTrackingSourceConfig value = read_wrist_config(reader); reader.finish(); return value; @@ -339,7 +319,7 @@ core::WristTrackingSourceConfig decode_open_wrist(const std::vector& pa HandSample decode_hand_sample(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::HandSample)); + Reader reader(payload, "HAND_SAMPLE"); HandSample value; value.sample_time_ns = reader.i64(); for (XrHandJointLocationEXT& joint : value.joints) @@ -354,7 +334,7 @@ HandSample decode_hand_sample(const std::vector& payload) SchemaSample decode_schema_sample(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::SchemaSample)); + Reader reader(payload, "SCHEMA_SAMPLE"); SchemaSample value; value.sample_time_local_common_clock_ns = reader.i64(); value.sample_time_raw_device_clock_ns = reader.i64(); @@ -366,7 +346,7 @@ SchemaSample decode_schema_sample(const std::vector& payload) WristSample decode_wrist_sample(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::WristSample)); + Reader reader(payload, "WRIST_SAMPLE"); WristSample value; value.sample_time_ns = reader.i64(); value.hand = to_bool(reader.u8()) ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; @@ -379,7 +359,7 @@ WristSample decode_wrist_sample(const std::vector& payload) std::string decode_error(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::Error)); + Reader reader(payload, "ERROR"); std::string message = reader.str(); reader.finish(); return message; @@ -387,7 +367,7 @@ std::string decode_error(const std::vector& payload) int64_t decode_ping(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::Ping)); + Reader reader(payload, "PING"); const int64_t t1_ns = reader.i64(); reader.finish(); return t1_ns; @@ -395,7 +375,7 @@ int64_t decode_ping(const std::vector& payload) Pong decode_pong(const std::vector& payload) { - Reader reader(payload, to_string(FrameType::Pong)); + Reader reader(payload, "PONG"); Pong value; value.t1_ns = reader.i64(); value.t2_ns = reader.i64(); diff --git a/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt index 2d8fe4acf3..5f467d98ce 100644 --- a/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt +++ b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt @@ -9,7 +9,6 @@ add_executable(remote_plugin_session_tests target_link_libraries(remote_plugin_session_tests PRIVATE Teleop::remote_plugin_session - pusherio::pusherio Catch2::Catch2WithMain ) diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 0534a11a14..89d5538b06 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -18,6 +18,9 @@ namespace protocol = remote_plugin_protocol; namespace { +constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * protocol::kPoseSize; +constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + protocol::kPoseSize; + bool same_pose(const XrPosef& a, const XrPosef& b) { return std::memcmp(&a, &b, sizeof(XrPosef)) == 0; @@ -49,7 +52,7 @@ void put_f32(std::vector& out, float v) put_u32(out, bits); } -//! Reference payload encoder (the pre-frame-builder layout) kept as the golden for HAND_SAMPLE. +//! Field-by-field reference encoder, the golden for HAND_SAMPLE. std::vector reference_hand_payload(const protocol::HandSample& sample) { std::vector out; @@ -84,15 +87,10 @@ std::vector schema_payload(const protocol::SchemaSample& sample) TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit]") { - protocol::FrameHeader header; - header.type = protocol::FrameType::HandSample; - header.channel_id = 0xBEEF; - header.seq = 0x01020304; - header.payload_size = static_cast(protocol::kHandSamplePayloadSize); - header.t_send_monotonic_ns = -1234567890123LL; - - uint8_t bytes[protocol::kHeaderSize]; - protocol::encode_header(header, bytes); + std::vector frame = protocol::encode_frame( + protocol::FrameType::HandSample, 0xBEEF, std::vector(protocol::kHandSamplePayloadSize)); + protocol::stamp_header(frame, 0x01020304, -1234567890123LL); + uint8_t* bytes = frame.data(); REQUIRE(bytes[0] == 0x52); // little-endian "RPS0" REQUIRE(bytes[1] == 0x50); REQUIRE(bytes[2] == 0x53); @@ -128,7 +126,7 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit } } -TEST_CASE("Wire contract v1 is 12 message types plus PING and PONG in a 24-byte header", "[remote_device_bridge][unit]") +TEST_CASE("Wire contract is 14 frame types in a 24-byte header", "[remote_device_bridge][unit]") { // Frame type numbers are part of the wire contract. const std::vector contract = { @@ -143,22 +141,14 @@ TEST_CASE("Wire contract v1 is 12 message types plus PING and PONG in a 24-byte { REQUIRE(static_cast(contract[i]) == i + 1); } - REQUIRE(protocol::kHeaderSize == 24); - REQUIRE(protocol::kProtocolVersion == 0); - REQUIRE(protocol::kHelloVersion == 2); // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. - protocol::FrameHeader header; - header.type = protocol::FrameType::Pong; - header.channel_id = 0x0A0B; - header.seq = 0x0C0D0E0F; - header.payload_size = 24; - header.t_send_monotonic_ns = 0x1112131415161718LL; - uint8_t bytes[protocol::kHeaderSize]; - protocol::encode_header(header, bytes); + std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, 0x0A0B, std::vector(24, 0)); + protocol::stamp_header(frame, 0x0C0D0E0F, 0x1112131415161718LL); const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, 24, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; - REQUIRE(std::vector(bytes, bytes + protocol::kHeaderSize) == expected); + REQUIRE(std::vector(frame.begin(), frame.begin() + 24) == expected); + uint8_t* bytes = frame.data(); for (const uint8_t type : { 0, 15 }) { @@ -241,7 +231,7 @@ TEST_CASE("OPEN_WRIST round-trips WristTrackingSourceConfig", "[remote_device_br config.right_aim_to_wrist = make_pose(0.7f); const std::vector bytes = protocol::encode_open_wrist(config); - REQUIRE(bytes.size() == protocol::kWristConfigPayloadSize); + REQUIRE(bytes.size() == kWristConfigPayloadSize); const core::WristTrackingSourceConfig decoded = protocol::decode_open_wrist(bytes); REQUIRE(decoded.mode == core::WristTrackingSourceMode::Controller); REQUIRE(same_pose(decoded.left_aim_to_wrist, config.left_aim_to_wrist)); @@ -314,8 +304,8 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") sample.sample.pose = make_pose(0.3f); const std::vector bytes = protocol::encode_wrist_sample(sample); - REQUIRE(bytes.size() == protocol::kWristSamplePayloadSize); - REQUIRE(bytes[8] == 0); // byte 8 keeps its original meaning: 1 = left, 0 = right + REQUIRE(bytes.size() == kWristSamplePayloadSize); + REQUIRE(bytes[8] == 0); // hand byte: 1 = left, 0 = right const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); REQUIRE(decoded.sample_time_ns == -5); REQUIRE(decoded.hand == XR_HAND_RIGHT_EXT); @@ -351,7 +341,9 @@ TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remo REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(25, 0)), protocol::DecodeError); std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, protocol::kSessionChannelId, payload); - protocol::stamp_header(frame.data(), 7, 0x0102030405060708LL); + protocol::stamp_header(frame, 7, 0x0102030405060708LL); + REQUIRE(protocol::decode_pong(protocol::split_frame(frame).payload).t3_ns == 3); // header only + protocol::set_pong_t3(frame, 0x0102030405060708LL); const protocol::Frame split = protocol::split_frame(frame); REQUIRE(split.header.type == protocol::FrameType::Pong); REQUIRE(split.header.t_send_monotonic_ns == 0x0102030405060708LL); @@ -360,11 +352,9 @@ TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remo REQUIRE(stamped.t2_ns == 2); REQUIRE(stamped.t3_ns == 0x0102030405060708LL); - // stamp_header leaves the payload of every other frame type alone. std::vector ping_frame = protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, ping); - protocol::stamp_header(ping_frame.data(), 8, 42); - REQUIRE(protocol::decode_ping(protocol::split_frame(ping_frame).payload) == -123456789012345LL); + REQUIRE_THROWS_AS(protocol::set_pong_t3(ping_frame, 42), std::invalid_argument); REQUIRE_THROWS_WITH(protocol::decode_ping({ 1, 2, 3 }), Catch::Matchers::ContainsSubstring("PING")); REQUIRE_THROWS_WITH(protocol::decode_pong({ 1 }), Catch::Matchers::ContainsSubstring("PONG")); } @@ -392,7 +382,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt // clang-format on REQUIRE(frame == golden); - protocol::stamp_header(frame.data(), 0x11223344u, 0x0807060504030201LL); + protocol::stamp_header(frame, 0x11223344u, 0x0807060504030201LL); REQUIRE(std::vector(frame.begin() + 8, frame.begin() + 12) == std::vector{ 0x44, 0x33, 0x22, 0x11 }); REQUIRE(std::vector(frame.begin() + 16, frame.begin() + 24) == From db7fabb540735b0b7b61253c3f8f9864b2688ce6 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:25:36 -0700 Subject: [PATCH 05/18] rebase onto pr00 review: retire OPEN_WRIST pr00's sessions build the wrist source at construction from PluginSessionRequirements::wrist_tracking_pull, which HELLO now carries in full. OPEN_WRIST would only repeat that config, so frame type 6 is unassigned and the parser rejects it; the wrist config codec remains as part of HELLO. Other frame numbers, the 24-byte header and kProtocolVersion are unchanged; HELLO version 2 already fences off older peers. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_frame.hpp | 2 +- .../protocol_payloads.hpp | 2 - .../session/protocol_frame.cpp | 4 +- .../session/protocol_payloads.cpp | 13 ----- .../remote_device_bridge/test_wire_codec.cpp | 55 ++++++++----------- 5 files changed, 28 insertions(+), 48 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 8df55f8430..d547fd1d45 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -33,7 +33,7 @@ enum class FrameType : uint8_t OpenHand = 3, // c->s OpenSchema = 4, // c->s OpenPull = 5, // c->s - OpenWrist = 6, // c->s, on the pull channel id + // 6 is unassigned: the wrist source config travels in HELLO. Close = 7, // c->s HandSample = 8, // c->s SchemaSample = 9, // c->s diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 236aa5643d..db581dffec 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -80,7 +80,6 @@ std::vector encode_hello_ack(const HelloAck& value); //! One byte: 0 = left, 1 = right. std::vector encode_open_hand(XrHandEXT hand); std::vector encode_open_schema(const core::SchemaPusherConfig& value); -std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value); std::vector encode_wrist_sample(const WristSample& value); std::vector encode_error(const std::string& message); std::vector encode_ping(int64_t t1_ns); @@ -103,7 +102,6 @@ Hello decode_hello(const std::vector& payload); HelloAck decode_hello_ack(const std::vector& payload); XrHandEXT decode_open_hand(const std::vector& payload); core::SchemaPusherConfig decode_open_schema(const std::vector& payload); -core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload); HandSample decode_hand_sample(const std::vector& payload); SchemaSample decode_schema_sample(const std::vector& payload); WristSample decode_wrist_sample(const std::vector& payload); diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 31491c6b12..3a7ba15cec 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -19,6 +19,7 @@ using detail::Writer; namespace { +constexpr uint8_t kUnassignedFrameType = 6; constexpr size_t kTypeOffset = 4; constexpr size_t kVersionOffset = 5; constexpr size_t kChannelOffset = 6; @@ -94,7 +95,8 @@ FrameHeader decode_header(const uint8_t* in) } FrameHeader header; const uint8_t type = reader.u8(); - if (type < static_cast(FrameType::Hello) || type > static_cast(kLastFrameType)) + if (type < static_cast(FrameType::Hello) || type > static_cast(kLastFrameType) || + type == kUnassignedFrameType) { throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 788eadc954..fcd9842aee 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -204,11 +204,6 @@ std::vector encode_open_schema(const core::SchemaPusherConfig& value) }); } -std::vector encode_open_wrist(const core::WristTrackingSourceConfig& value) -{ - return build_payload([&](Writer& writer) { write_wrist_config(writer, value); }); -} - std::vector encode_wrist_sample(const WristSample& value) { return build_payload( @@ -309,14 +304,6 @@ core::SchemaPusherConfig decode_open_schema(const std::vector& payload) return value; } -core::WristTrackingSourceConfig decode_open_wrist(const std::vector& payload) -{ - Reader reader(payload, "OPEN_WRIST"); - const core::WristTrackingSourceConfig value = read_wrist_config(reader); - reader.finish(); - return value; -} - HandSample decode_hand_sample(const std::vector& payload) { Reader reader(payload, "HAND_SAMPLE"); diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 89d5538b06..a0594a2fbc 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -18,7 +18,6 @@ namespace protocol = remote_plugin_protocol; namespace { -constexpr size_t kWristConfigPayloadSize = sizeof(uint8_t) + 2 * protocol::kPoseSize; constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + protocol::kPoseSize; bool same_pose(const XrPosef& a, const XrPosef& b) @@ -126,20 +125,21 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit } } -TEST_CASE("Wire contract is 14 frame types in a 24-byte header", "[remote_device_bridge][unit]") +TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device_bridge][unit]") { - // Frame type numbers are part of the wire contract. - const std::vector contract = { - protocol::FrameType::Hello, protocol::FrameType::HelloAck, protocol::FrameType::OpenHand, - protocol::FrameType::OpenSchema, protocol::FrameType::OpenPull, protocol::FrameType::OpenWrist, - protocol::FrameType::Close, protocol::FrameType::HandSample, protocol::FrameType::SchemaSample, - protocol::FrameType::WristSample, protocol::FrameType::Heartbeat, protocol::FrameType::Error, - protocol::FrameType::Ping, // bridge -> sender, t1 - protocol::FrameType::Pong, // sender -> bridge, t1 t2 t3 + // Frame type numbers are part of the wire contract; 6 is unassigned. + const std::vector> contract = { + { protocol::FrameType::Hello, 1 }, { protocol::FrameType::HelloAck, 2 }, + { protocol::FrameType::OpenHand, 3 }, { protocol::FrameType::OpenSchema, 4 }, + { protocol::FrameType::OpenPull, 5 }, { protocol::FrameType::Close, 7 }, + { protocol::FrameType::HandSample, 8 }, { protocol::FrameType::SchemaSample, 9 }, + { protocol::FrameType::WristSample, 10 }, { protocol::FrameType::Heartbeat, 11 }, + { protocol::FrameType::Error, 12 }, { protocol::FrameType::Ping, 13 }, + { protocol::FrameType::Pong, 14 }, }; - for (size_t i = 0; i < contract.size(); ++i) + for (const auto& [type, number] : contract) { - REQUIRE(static_cast(contract[i]) == i + 1); + REQUIRE(static_cast(type) == number); } // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. @@ -150,7 +150,7 @@ TEST_CASE("Wire contract is 14 frame types in a 24-byte header", "[remote_device REQUIRE(std::vector(frame.begin(), frame.begin() + 24) == expected); uint8_t* bytes = frame.data(); - for (const uint8_t type : { 0, 15 }) + for (const uint8_t type : { 0, 6, 15 }) { bytes[4] = type; REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); @@ -223,25 +223,18 @@ TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][ REQUIRE_THROWS_AS(protocol::decode_open_schema(truncated), protocol::DecodeError); } -TEST_CASE("OPEN_WRIST round-trips WristTrackingSourceConfig", "[remote_device_bridge][unit]") +TEST_CASE("HELLO rejects an unknown wrist source mode", "[remote_device_bridge][unit]") { - core::WristTrackingSourceConfig config; - config.mode = core::WristTrackingSourceMode::Controller; - config.left_aim_to_wrist = make_pose(0.1f); - config.right_aim_to_wrist = make_pose(0.7f); - - const std::vector bytes = protocol::encode_open_wrist(config); - REQUIRE(bytes.size() == kWristConfigPayloadSize); - const core::WristTrackingSourceConfig decoded = protocol::decode_open_wrist(bytes); - REQUIRE(decoded.mode == core::WristTrackingSourceMode::Controller); - REQUIRE(same_pose(decoded.left_aim_to_wrist, config.left_aim_to_wrist)); - REQUIRE(same_pose(decoded.right_aim_to_wrist, config.right_aim_to_wrist)); - - REQUIRE(protocol::decode_open_wrist(protocol::encode_open_wrist(core::WristTrackingSourceConfig{})).mode == - core::WristTrackingSourceMode::Auto); - std::vector bad_mode = bytes; - bad_mode[0] = 7; - REQUIRE_THROWS_AS(protocol::decode_open_wrist(bad_mode), protocol::DecodeError); + protocol::Hello hello; + hello.requirements.wrist_tracking_pull = core::WristTrackingSourceConfig{ .mode = core::WristTrackingSourceMode::Auto, + .left_aim_to_wrist = make_pose(0.1f), + .right_aim_to_wrist = make_pose(0.7f) }; + std::vector bytes = protocol::encode_hello(hello); + // proto_version u16, app_name (u32 length, empty), three flags, then the wrist mode byte. + const size_t mode_offset = sizeof(uint16_t) + sizeof(uint32_t) + 3; + REQUIRE(bytes[mode_offset] == 0); + bytes[mode_offset] = 7; + REQUIRE_THROWS_AS(protocol::decode_hello(bytes), protocol::DecodeError); } TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge][unit]") From df19a10e605bfb76052a115b46f2e19273cad5b0 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:27:27 -0700 Subject: [PATCH 06/18] review round 2 (pr01) Applied the fact-checked (VERIFIED) findings on code this branch adds: - FrameHeader drops the version field (always kProtocolVersion) and value-initializes type to 0, which no frame uses. - Hello drops proto_version; encode_hello writes kHelloVersion and decode_hello compares against it. - Writer/Reader gain boolean(); encoders no longer spell out "? 1 : 0" and the parsers' to_bool helper is gone. - store_le lives once in protocol_io.hpp; set_pong_t3 uses it. - The ERROR comment no longer describes bridge behaviour; AGENTS.md keeps just the rule. - Tests use kHeaderSize instead of 24; the nested test CMakeLists drops cmake_minimum_required. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/remote_device_bridge/AGENTS.md | 2 +- .../remote_plugin_session/protocol_frame.hpp | 5 +- .../protocol_payloads.hpp | 3 +- .../session/protocol_frame.cpp | 17 ++----- .../session/protocol_io.hpp | 24 ++++++++++ .../session/protocol_payloads.cpp | 48 +++++++------------ .../remote_device_bridge/CMakeLists.txt | 2 - .../remote_device_bridge/test_wire_codec.cpp | 21 ++++---- 8 files changed, 61 insertions(+), 61 deletions(-) diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index b3e26f12a3..0f788cd2df 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -7,5 +7,5 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. -- `session/protocol_frame.*` (header and frame layer) and `session/protocol_payloads.*` (payload builders and parsers, sample frame builders, PONG t3 stamping) are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. +- `session/protocol_frame.*` and `session/protocol_payloads.*` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. - `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin using `--remote` must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index d547fd1d45..25d8781666 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -39,7 +39,7 @@ enum class FrameType : uint8_t SchemaSample = 9, // c->s WristSample = 10, // s->c Heartbeat = 11, // both - Error = 12, // s->c; on channel 0 the connection closes afterwards, on a channel id only that channel is refused + Error = 12, // s->c Ping = 13, // s->c Pong = 14, // c->s }; @@ -47,8 +47,7 @@ constexpr FrameType kLastFrameType = FrameType::Pong; struct FrameHeader { - FrameType type; - uint8_t version = kProtocolVersion; + FrameType type{}; // 0 is not a frame type uint16_t channel_id = kSessionChannelId; uint32_t seq = 0; uint32_t payload_size = 0; diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index db581dffec..b889e25cc0 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -22,13 +22,12 @@ namespace remote_plugin_protocol * XrPosef order (orientation x,y,z,w then position x,y,z). */ -//! HELLO proto_version: the requirements carry the wrist source config, and the client answers PING with PONG. +//! HELLO version: the requirements carry the wrist source config, and the client answers PING with PONG. //! decode_hello accepts only this version. constexpr uint16_t kHelloVersion = 2; struct Hello { - uint16_t proto_version = kHelloVersion; std::string app_name; core::PluginSessionRequirements requirements; }; diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 3a7ba15cec..ed49c2023e 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -14,6 +14,7 @@ namespace remote_plugin_protocol using detail::build_frame; using detail::Reader; +using detail::store_le; using detail::Writer; namespace @@ -27,14 +28,6 @@ constexpr size_t kSeqOffset = 8; constexpr size_t kPayloadSizeOffset = 12; constexpr size_t kSendTimeOffset = 16; -void store_le(uint8_t* out, uint64_t value, size_t size) -{ - for (size_t i = 0; i < size; ++i) - { - out[i] = static_cast(value >> (8 * i)); - } -} - } // namespace namespace detail @@ -44,7 +37,7 @@ void encode_header(const FrameHeader& header, uint8_t* out) { store_le(out, kMagic, sizeof(uint32_t)); out[kTypeOffset] = static_cast(header.type); - out[kVersionOffset] = header.version; + out[kVersionOffset] = kProtocolVersion; store_le(out + kChannelOffset, header.channel_id, sizeof(uint16_t)); store_le(out + kSeqOffset, header.seq, sizeof(uint32_t)); store_le(out + kPayloadSizeOffset, header.payload_size, sizeof(uint32_t)); @@ -101,10 +94,10 @@ FrameHeader decode_header(const uint8_t* in) throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } header.type = static_cast(type); - header.version = reader.u8(); - if (header.version != kProtocolVersion) + const uint8_t version = reader.u8(); + if (version != kProtocolVersion) { - throw DecodeError("protocol: unsupported protocol version " + std::to_string(header.version)); + throw DecodeError("protocol: unsupported protocol version " + std::to_string(version)); } header.channel_id = reader.u16(); header.seq = reader.u32(); diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index 66ccbec81c..83f021a4a5 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -18,6 +18,15 @@ namespace remote_plugin_protocol namespace detail { +//! Stores the low `size` bytes of `value` little-endian at `out` (in-place patching). +inline void store_le(uint8_t* out, uint64_t value, size_t size) +{ + for (size_t i = 0; i < size; ++i) + { + out[i] = static_cast(value >> (8 * i)); + } +} + //! Writes the header into the first kHeaderSize bytes of `out`. void encode_header(const FrameHeader& header, uint8_t* out); @@ -34,6 +43,11 @@ class Writer m_out.push_back(value); } + void boolean(bool value) + { + u8(value ? 1 : 0); + } + void u16(uint16_t value) { for (int i = 0; i < 2; ++i) @@ -118,6 +132,16 @@ class Reader return m_data[m_pos++]; } + bool boolean() + { + const uint8_t value = u8(); + if (value > 1) + { + throw DecodeError(std::string("protocol: ") + m_what + ": invalid boolean value " + std::to_string(value)); + } + return value == 1; + } + uint16_t u16() { need(2); diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index fcd9842aee..1fa2830921 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -85,15 +85,6 @@ core::WristTrackingSourceMode from_wire_mode(uint8_t mode) } } -bool to_bool(uint8_t value) -{ - if (value > 1) - { - throw DecodeError("protocol: invalid boolean value " + std::to_string(value)); - } - return value == 1; -} - void write_wrist_config(Writer& writer, const core::WristTrackingSourceConfig& value) { writer.u8(to_wire_mode(value.mode)); @@ -164,11 +155,11 @@ std::vector encode_hello(const Hello& value) return build_payload( [&](Writer& writer) { - writer.u16(value.proto_version); + writer.u16(kHelloVersion); writer.str(value.app_name); - writer.u8(value.requirements.schema_push ? 1 : 0); - writer.u8(value.requirements.hand_tracking_push ? 1 : 0); - writer.u8(value.requirements.wrist_tracking_pull ? 1 : 0); + writer.boolean(value.requirements.schema_push); + writer.boolean(value.requirements.hand_tracking_push); + writer.boolean(value.requirements.wrist_tracking_pull.has_value()); if (value.requirements.wrist_tracking_pull) { write_wrist_config(writer, *value.requirements.wrist_tracking_pull); @@ -181,7 +172,7 @@ std::vector encode_hello_ack(const HelloAck& value) return build_payload( [&](Writer& writer) { - writer.u8(value.accepted ? 1 : 0); + writer.boolean(value.accepted); writer.str(value.reason); }); } @@ -211,8 +202,8 @@ std::vector encode_wrist_sample(const WristSample& value) { writer.i64(value.sample_time_ns); writer.u8(to_wire_is_left(value.hand)); - writer.u8(value.sample.valid ? 1 : 0); - writer.u8(value.sample.tracked ? 1 : 0); + writer.boolean(value.sample.valid); + writer.boolean(value.sample.tracked); writer.pose(value.sample.pose); }); } @@ -246,26 +237,21 @@ void set_pong_t3(std::vector& pong_frame, int64_t t3_ns) { throw std::invalid_argument("protocol: not an encoded PONG frame"); } - const uint64_t bits = static_cast(t3_ns); - for (size_t i = 0; i < sizeof(int64_t); ++i) - { - pong_frame[kT3Offset + i] = static_cast(bits >> (8 * i)); - } + detail::store_le(pong_frame.data() + kT3Offset, static_cast(t3_ns), sizeof(int64_t)); } Hello decode_hello(const std::vector& payload) { Reader reader(payload, "HELLO"); Hello value; - value.proto_version = reader.u16(); - if (value.proto_version != kHelloVersion) + if (const uint16_t version = reader.u16(); version != kHelloVersion) { - throw DecodeError("protocol: unsupported HELLO version " + std::to_string(value.proto_version)); + throw DecodeError("protocol: unsupported HELLO version " + std::to_string(version)); } value.app_name = reader.str(); - value.requirements.schema_push = to_bool(reader.u8()); - value.requirements.hand_tracking_push = to_bool(reader.u8()); - if (to_bool(reader.u8())) + value.requirements.schema_push = reader.boolean(); + value.requirements.hand_tracking_push = reader.boolean(); + if (reader.boolean()) { value.requirements.wrist_tracking_pull = read_wrist_config(reader); } @@ -277,7 +263,7 @@ HelloAck decode_hello_ack(const std::vector& payload) { Reader reader(payload, "HELLO_ACK"); HelloAck value; - value.accepted = to_bool(reader.u8()); + value.accepted = reader.boolean(); value.reason = reader.str(); reader.finish(); return value; @@ -336,9 +322,9 @@ WristSample decode_wrist_sample(const std::vector& payload) Reader reader(payload, "WRIST_SAMPLE"); WristSample value; value.sample_time_ns = reader.i64(); - value.hand = to_bool(reader.u8()) ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; - value.sample.valid = to_bool(reader.u8()); - value.sample.tracked = to_bool(reader.u8()); + value.hand = reader.boolean() ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; + value.sample.valid = reader.boolean(); + value.sample.tracked = reader.boolean(); value.sample.pose = reader.pose(); reader.finish(); return value; diff --git a/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt index 5f467d98ce..fcac49524b 100644 --- a/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt +++ b/tests/cpp/plugins/remote_device_bridge/CMakeLists.txt @@ -1,8 +1,6 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -cmake_minimum_required(VERSION 3.20) - add_executable(remote_plugin_session_tests test_wire_codec.cpp ) diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index a0594a2fbc..f8e2bd6d12 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -97,7 +97,6 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit const protocol::FrameHeader decoded = protocol::decode_header(bytes); REQUIRE(decoded.type == protocol::FrameType::HandSample); - REQUIRE(decoded.version == protocol::kProtocolVersion); REQUIRE(decoded.channel_id == 0xBEEF); REQUIRE(decoded.seq == 0x01020304); REQUIRE(decoded.payload_size == protocol::kHandSamplePayloadSize); @@ -147,7 +146,7 @@ TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device protocol::stamp_header(frame, 0x0C0D0E0F, 0x1112131415161718LL); const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, 24, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; - REQUIRE(std::vector(frame.begin(), frame.begin() + 24) == expected); + REQUIRE(std::vector(frame.begin(), frame.begin() + protocol::kHeaderSize) == expected); uint8_t* bytes = frame.data(); for (const uint8_t type : { 0, 6, 15 }) @@ -168,7 +167,6 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") }; hello.requirements = { .schema_push = true, .hand_tracking_push = false, .wrist_tracking_pull = wrist }; const protocol::Hello decoded = protocol::decode_hello(protocol::encode_hello(hello)); - REQUIRE(decoded.proto_version == protocol::kHelloVersion); REQUIRE(decoded.app_name == "ManusHandPlugin"); REQUIRE(decoded.requirements.schema_push); REQUIRE_FALSE(decoded.requirements.hand_tracking_push); @@ -180,8 +178,9 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") hello.requirements.wrist_tracking_pull.reset(); REQUIRE_FALSE(protocol::decode_hello(protocol::encode_hello(hello)).requirements.wrist_tracking_pull); - hello.proto_version = 1; - REQUIRE_THROWS_AS(protocol::decode_hello(protocol::encode_hello(hello)), protocol::DecodeError); + std::vector old_version = protocol::encode_hello(hello); + old_version[0] = 1; // HELLO version u16 leads the payload + REQUIRE_THROWS_AS(protocol::decode_hello(old_version), protocol::DecodeError); const protocol::HelloAck ack = protocol::decode_hello_ack(protocol::encode_hello_ack(protocol::HelloAck{ false, "no runtime" })); @@ -230,7 +229,7 @@ TEST_CASE("HELLO rejects an unknown wrist source mode", "[remote_device_bridge][ .left_aim_to_wrist = make_pose(0.1f), .right_aim_to_wrist = make_pose(0.7f) }; std::vector bytes = protocol::encode_hello(hello); - // proto_version u16, app_name (u32 length, empty), three flags, then the wrist mode byte. + // version u16, app_name (u32 length, empty), three flags, then the wrist mode byte. const size_t mode_offset = sizeof(uint16_t) + sizeof(uint32_t) + 3; REQUIRE(bytes[mode_offset] == 0); bytes[mode_offset] = 7; @@ -378,16 +377,18 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt protocol::stamp_header(frame, 0x11223344u, 0x0807060504030201LL); REQUIRE(std::vector(frame.begin() + 8, frame.begin() + 12) == std::vector{ 0x44, 0x33, 0x22, 0x11 }); - REQUIRE(std::vector(frame.begin() + 16, frame.begin() + 24) == + REQUIRE(std::vector(frame.begin() + 16, frame.begin() + protocol::kHeaderSize) == std::vector{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 }); - REQUIRE(std::equal(frame.begin() + 24, frame.end(), golden.begin() + 24)); // payload untouched + REQUIRE(std::equal( + frame.begin() + protocol::kHeaderSize, frame.end(), golden.begin() + protocol::kHeaderSize)); // payload + // untouched const protocol::Frame split = protocol::split_frame(frame); REQUIRE(split.header.type == protocol::FrameType::SchemaSample); REQUIRE(split.header.channel_id == 3); REQUIRE(split.header.seq == 0x11223344u); REQUIRE(split.header.t_send_monotonic_ns == 0x0807060504030201LL); - REQUIRE(split.payload == std::vector(golden.begin() + 24, golden.end())); + REQUIRE(split.payload == std::vector(golden.begin() + protocol::kHeaderSize, golden.end())); protocol::SchemaSample decoded = protocol::decode_schema_sample(split.payload); REQUIRE(decoded.bytes == bytes); REQUIRE(decoded.sample_time_raw_device_clock_ns == -1); @@ -410,7 +411,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt REQUIRE(header.type == protocol::FrameType::HandSample); REQUIRE(header.channel_id == 0x0102); REQUIRE(header.payload_size == protocol::kHandSamplePayloadSize); - REQUIRE(std::equal(frame.begin() + 24, frame.end(), payload.begin(), payload.end())); + REQUIRE(std::equal(frame.begin() + protocol::kHeaderSize, frame.end(), payload.begin(), payload.end())); REQUIRE(protocol::encode_frame(protocol::FrameType::HandSample, 0x0102, payload) == frame); } SECTION("split_frame rejects short or inconsistent messages") From 3a7dc871d874c3fbd5ba37edfecb9b5d15d769d6 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Fri, 30 Oct 2026 10:35:17 -0700 Subject: [PATCH 07/18] review round 3 (pr01) Applied the fact-checked (VERIFIED) findings on code this branch adds: - decode_header takes a std::span and checks its length; valid frame types come from an exhaustive switch, so no kLastFrameType or unassigned-type constant has to be kept in step with the enum. - Header offsets are tied to the layout with a static_assert. - Writer/Reader share store_le/load_le instead of three hand loops each. - PONG fields are named ping_sent_ns / ping_received_ns / pong_sent_ns and set_pong_t3 becomes set_pong_sent_time. - Own private header first in both protocol sources. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_frame.hpp | 8 +-- .../protocol_payloads.hpp | 13 ++-- .../session/protocol_frame.cpp | 40 +++++++++-- .../session/protocol_io.hpp | 67 +++++++++---------- .../session/protocol_payloads.cpp | 22 +++--- .../remote_device_bridge/test_wire_codec.cpp | 34 +++++----- 6 files changed, 106 insertions(+), 78 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 25d8781666..980bacbdf6 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -5,6 +5,7 @@ #include #include +#include #include #include @@ -43,7 +44,6 @@ enum class FrameType : uint8_t Ping = 13, // s->c Pong = 14, // c->s }; -constexpr FrameType kLastFrameType = FrameType::Pong; struct FrameHeader { @@ -66,9 +66,9 @@ class DecodeError : public std::runtime_error using std::runtime_error::runtime_error; }; -//! Reads the first kHeaderSize bytes of `in`. Throws DecodeError on bad magic, unknown type, unsupported version or an -//! oversized payload. -FrameHeader decode_header(const uint8_t* in); +//! Reads the header from the first kHeaderSize bytes of `in`. Throws DecodeError if `in` is shorter, or on bad +//! magic, unknown type, unsupported version or an oversized payload. +FrameHeader decode_header(std::span in); //! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(). std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index b889e25cc0..d02b8dc547 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -59,12 +59,12 @@ struct WristSample core::WristTrackingSample sample; }; -//! Times are CLOCK_MONOTONIC ns of the side that took them. +//! Two-way clock exchange; times are CLOCK_MONOTONIC ns of the side that took them. struct Pong { - int64_t t1_ns = 0; - int64_t t2_ns = 0; - int64_t t3_ns = 0; + int64_t ping_sent_ns = 0; //!< bridge clock, echoed from the PING + int64_t ping_received_ns = 0; //!< client clock + int64_t pong_sent_ns = 0; //!< client clock, set by set_pong_sent_time when the frame is sent }; constexpr size_t kPoseSize = 7 * sizeof(float); @@ -83,8 +83,9 @@ std::vector encode_wrist_sample(const WristSample& value); std::vector encode_error(const std::string& message); std::vector encode_ping(int64_t t1_ns); std::vector encode_pong(const Pong& value); -//! Sets t3 in an encoded PONG frame; call where the frame is sent, so t3 is when it left, not when it was queued. -void set_pong_t3(std::vector& pong_frame, int64_t t3_ns); +//! Sets pong_sent_ns in an encoded PONG frame; call where the frame is sent, so it records when the frame left, +//! not when it was queued. +void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns); // Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. std::vector encode_hand_sample_frame(uint16_t channel_id, diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index ed49c2023e..03b12a72b2 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -20,13 +20,38 @@ using detail::Writer; namespace { -constexpr uint8_t kUnassignedFrameType = 6; constexpr size_t kTypeOffset = 4; constexpr size_t kVersionOffset = 5; constexpr size_t kChannelOffset = 6; constexpr size_t kSeqOffset = 8; constexpr size_t kPayloadSizeOffset = 12; constexpr size_t kSendTimeOffset = 16; +static_assert(kTypeOffset == sizeof(kMagic) && kVersionOffset == kTypeOffset + 1 && kChannelOffset == kVersionOffset + 1 && + kSeqOffset == kChannelOffset + sizeof(uint16_t) && kPayloadSizeOffset == kSeqOffset + sizeof(uint32_t) && + kSendTimeOffset == kPayloadSizeOffset + sizeof(uint32_t) && + kHeaderSize == kSendTimeOffset + sizeof(int64_t)); + +bool is_frame_type(uint8_t value) +{ + switch (static_cast(value)) + { + case FrameType::Hello: + case FrameType::HelloAck: + case FrameType::OpenHand: + case FrameType::OpenSchema: + case FrameType::OpenPull: + case FrameType::Close: + case FrameType::HandSample: + case FrameType::SchemaSample: + case FrameType::WristSample: + case FrameType::Heartbeat: + case FrameType::Error: + case FrameType::Ping: + case FrameType::Pong: + return true; + } + return false; +} } // namespace @@ -63,7 +88,7 @@ Frame split_frame(std::vector message) throw DecodeError("protocol: message shorter than a header"); } Frame frame; - frame.header = decode_header(message.data()); + frame.header = decode_header(message); if (message.size() != kHeaderSize + frame.header.payload_size) { throw DecodeError("protocol: message length does not match payload_size"); @@ -79,17 +104,20 @@ std::vector encode_frame(FrameType type, uint16_t channel_id, const std type, channel_id, payload.size(), [&payload](Writer& writer) { writer.bytes(payload.data(), payload.size()); }); } -FrameHeader decode_header(const uint8_t* in) +FrameHeader decode_header(std::span in) { - Reader reader(in, kHeaderSize, "header"); + if (in.size() < kHeaderSize) + { + throw DecodeError("protocol: header: truncated"); + } + Reader reader(in.data(), kHeaderSize, "header"); if (reader.u32() != kMagic) { throw DecodeError("protocol: bad frame magic"); } FrameHeader header; const uint8_t type = reader.u8(); - if (type < static_cast(FrameType::Hello) || type > static_cast(kLastFrameType) || - type == kUnassignedFrameType) + if (!is_frame_type(type)) { throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index 83f021a4a5..154e31396e 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -18,7 +18,7 @@ namespace remote_plugin_protocol namespace detail { -//! Stores the low `size` bytes of `value` little-endian at `out` (in-place patching). +//! Stores the low `size` bytes of `value` little-endian at `out`. inline void store_le(uint8_t* out, uint64_t value, size_t size) { for (size_t i = 0; i < size; ++i) @@ -27,6 +27,17 @@ inline void store_le(uint8_t* out, uint64_t value, size_t size) } } +//! Loads `size` little-endian bytes from `in`. +inline uint64_t load_le(const uint8_t* in, size_t size) +{ + uint64_t value = 0; + for (size_t i = 0; i < size; ++i) + { + value |= static_cast(in[i]) << (8 * i); + } + return value; +} + //! Writes the header into the first kHeaderSize bytes of `out`. void encode_header(const FrameHeader& header, uint8_t* out); @@ -50,26 +61,17 @@ class Writer void u16(uint16_t value) { - for (int i = 0; i < 2; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } + append(value, sizeof(value)); } void u32(uint32_t value) { - for (int i = 0; i < 4; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } + append(value, sizeof(value)); } void u64(uint64_t value) { - for (int i = 0; i < 8; ++i) - { - m_out.push_back(static_cast(value >> (8 * i))); - } + append(value, sizeof(value)); } void i64(int64_t value) @@ -111,6 +113,13 @@ class Writer } private: + void append(uint64_t value, size_t size) + { + const size_t at = m_out.size(); + m_out.resize(at + size); + store_le(m_out.data() + at, value, size); + } + std::vector& m_out; }; @@ -144,35 +153,17 @@ class Reader uint16_t u16() { - need(2); - uint16_t value = 0; - for (int i = 0; i < 2; ++i) - { - value = static_cast(value | (static_cast(m_data[m_pos++]) << (8 * i))); - } - return value; + return static_cast(take(sizeof(uint16_t))); } uint32_t u32() { - need(4); - uint32_t value = 0; - for (int i = 0; i < 4; ++i) - { - value |= static_cast(m_data[m_pos++]) << (8 * i); - } - return value; + return static_cast(take(sizeof(uint32_t))); } uint64_t u64() { - need(8); - uint64_t value = 0; - for (int i = 0; i < 8; ++i) - { - value |= static_cast(m_data[m_pos++]) << (8 * i); - } - return value; + return take(sizeof(uint64_t)); } int64_t i64() @@ -228,6 +219,14 @@ class Reader } private: + uint64_t take(size_t size) + { + need(size); + const uint64_t value = load_le(m_data + m_pos, size); + m_pos += size; + return value; + } + void need(size_t count) const { if (m_size - m_pos < count) diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 1fa2830921..720707e8b9 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -223,21 +223,21 @@ std::vector encode_pong(const Pong& value) return build_payload( [&](Writer& writer) { - writer.i64(value.t1_ns); - writer.i64(value.t2_ns); - writer.i64(value.t3_ns); + writer.i64(value.ping_sent_ns); + writer.i64(value.ping_received_ns); + writer.i64(value.pong_sent_ns); }); } -void set_pong_t3(std::vector& pong_frame, int64_t t3_ns) +void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns) { - // PONG payload: t1, t2, t3 (i64 each). - constexpr size_t kT3Offset = kHeaderSize + 2 * sizeof(int64_t); - if (pong_frame.size() != kHeaderSize + 3 * sizeof(int64_t) || decode_header(pong_frame.data()).type != FrameType::Pong) + // PONG payload: ping_sent, ping_received, pong_sent (i64 each). + constexpr size_t kPongSentOffset = kHeaderSize + 2 * sizeof(int64_t); + if (pong_frame.size() != kHeaderSize + 3 * sizeof(int64_t) || decode_header(pong_frame).type != FrameType::Pong) { throw std::invalid_argument("protocol: not an encoded PONG frame"); } - detail::store_le(pong_frame.data() + kT3Offset, static_cast(t3_ns), sizeof(int64_t)); + detail::store_le(pong_frame.data() + kPongSentOffset, static_cast(pong_sent_ns), sizeof(int64_t)); } Hello decode_hello(const std::vector& payload) @@ -350,9 +350,9 @@ Pong decode_pong(const std::vector& payload) { Reader reader(payload, "PONG"); Pong value; - value.t1_ns = reader.i64(); - value.t2_ns = reader.i64(); - value.t3_ns = reader.i64(); + value.ping_sent_ns = reader.i64(); + value.ping_received_ns = reader.i64(); + value.pong_sent_ns = reader.i64(); reader.finish(); return value; } diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index f8e2bd6d12..43e1673136 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -95,7 +95,7 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit REQUIRE(bytes[2] == 0x53); REQUIRE(bytes[3] == 0x30); - const protocol::FrameHeader decoded = protocol::decode_header(bytes); + const protocol::FrameHeader decoded = protocol::decode_header({ bytes, protocol::kHeaderSize }); REQUIRE(decoded.type == protocol::FrameType::HandSample); REQUIRE(decoded.channel_id == 0xBEEF); REQUIRE(decoded.seq == 0x01020304); @@ -105,22 +105,22 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit SECTION("bad magic is rejected") { bytes[0] ^= 0xFF; - REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } SECTION("unknown type is rejected") { bytes[4] = 200; - REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } SECTION("other protocol versions are rejected") { bytes[5] = 1; - REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } SECTION("oversized payloads are rejected") { std::memset(bytes + 12, 0xFF, 4); - REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } } @@ -152,7 +152,7 @@ TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device for (const uint8_t type : { 0, 6, 15 }) { bytes[4] = type; - REQUIRE_THROWS_AS(protocol::decode_header(bytes), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } } @@ -317,7 +317,7 @@ TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_b REQUIRE_THROWS_AS(protocol::decode_error({ 4, 0, 0, 0, 'a' }), protocol::DecodeError); } -TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remote_device_bridge][unit]") +TEST_CASE("PING and PONG round-trip and PONG records its send time", "[remote_device_bridge][unit]") { const std::vector ping = protocol::encode_ping(-123456789012345LL); REQUIRE(ping.size() == 8); @@ -327,26 +327,26 @@ TEST_CASE("PING and PONG round-trip and PONG t3 is stamped at send time", "[remo const std::vector payload = protocol::encode_pong(protocol::Pong{ 1, 2, 3 }); REQUIRE(payload.size() == 24); const protocol::Pong pong = protocol::decode_pong(payload); - REQUIRE(pong.t1_ns == 1); - REQUIRE(pong.t2_ns == 2); - REQUIRE(pong.t3_ns == 3); + REQUIRE(pong.ping_sent_ns == 1); + REQUIRE(pong.ping_received_ns == 2); + REQUIRE(pong.pong_sent_ns == 3); REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(25, 0)), protocol::DecodeError); std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, protocol::kSessionChannelId, payload); protocol::stamp_header(frame, 7, 0x0102030405060708LL); - REQUIRE(protocol::decode_pong(protocol::split_frame(frame).payload).t3_ns == 3); // header only - protocol::set_pong_t3(frame, 0x0102030405060708LL); + REQUIRE(protocol::decode_pong(protocol::split_frame(frame).payload).pong_sent_ns == 3); // header only + protocol::set_pong_sent_time(frame, 0x0102030405060708LL); const protocol::Frame split = protocol::split_frame(frame); REQUIRE(split.header.type == protocol::FrameType::Pong); REQUIRE(split.header.t_send_monotonic_ns == 0x0102030405060708LL); const protocol::Pong stamped = protocol::decode_pong(split.payload); - REQUIRE(stamped.t1_ns == 1); - REQUIRE(stamped.t2_ns == 2); - REQUIRE(stamped.t3_ns == 0x0102030405060708LL); + REQUIRE(stamped.ping_sent_ns == 1); + REQUIRE(stamped.ping_received_ns == 2); + REQUIRE(stamped.pong_sent_ns == 0x0102030405060708LL); std::vector ping_frame = protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, ping); - REQUIRE_THROWS_AS(protocol::set_pong_t3(ping_frame, 42), std::invalid_argument); + REQUIRE_THROWS_AS(protocol::set_pong_sent_time(ping_frame, 42), std::invalid_argument); REQUIRE_THROWS_WITH(protocol::decode_ping({ 1, 2, 3 }), Catch::Matchers::ContainsSubstring("PING")); REQUIRE_THROWS_WITH(protocol::decode_pong({ 1 }), Catch::Matchers::ContainsSubstring("PONG")); } @@ -407,7 +407,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt REQUIRE(payload.size() == protocol::kHandSamplePayloadSize); const std::vector frame = protocol::encode_hand_sample_frame(0x0102, sample.joints.data(), -42); REQUIRE(frame.size() == protocol::kHeaderSize + protocol::kHandSamplePayloadSize); - const protocol::FrameHeader header = protocol::decode_header(frame.data()); + const protocol::FrameHeader header = protocol::decode_header(frame); REQUIRE(header.type == protocol::FrameType::HandSample); REQUIRE(header.channel_id == 0x0102); REQUIRE(header.payload_size == protocol::kHandSamplePayloadSize); From 66c775e4619089e8c55982532bd72b616c93e545 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 12:42:21 -0800 Subject: [PATCH 08/18] review round 4 (pr01) Applied the fact-checked (VERIFIED) findings that stay inside this branch's files and do not change a symbol the stack above uses: - Header byte offsets live in protocol_frame.hpp, each derived from the previous field; kHeaderSize follows from them (value unchanged, 24). - decode_header lets Reader report a short buffer; split_frame relies on decode_header for it; encode_schema_sample_frame relies on build_frame's payload bound. Same exception types as before. - Tests index the header and payloads through named offsets; the "payload untouched" comment sits above its REQUIRE. - AGENTS.md names neither a test file nor the not-yet-existing --remote flag. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/remote_device_bridge/AGENTS.md | 4 +-- .../remote_plugin_session/protocol_frame.hpp | 11 ++++++-- .../session/protocol_frame.cpp | 21 +------------- .../session/protocol_payloads.cpp | 4 --- .../remote_device_bridge/test_wire_codec.cpp | 28 +++++++++++-------- 5 files changed, 27 insertions(+), 41 deletions(-) diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index 0f788cd2df..35311c3b7b 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -7,5 +7,5 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. -- `session/protocol_frame.*` and `session/protocol_payloads.*` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and `tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp` together. -- `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin using `--remote` must run without an OpenXR runtime. +- `session/protocol_frame.*` and `session/protocol_payloads.*` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and their codec tests together. +- `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin that talks to a bridge through this library must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 980bacbdf6..2a90a200aa 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -20,9 +20,14 @@ namespace remote_plugin_protocol constexpr uint32_t kMagic = 0x30535052u; // "RPS0" constexpr uint8_t kProtocolVersion = 0; -//! magic u32, type u8, version u8, channel u16, seq u32, payload size u32, t_send i64. -constexpr size_t kHeaderSize = - sizeof(uint32_t) + 2 * sizeof(uint8_t) + sizeof(uint16_t) + 2 * sizeof(uint32_t) + sizeof(int64_t); +//! Header byte offsets: magic u32, type u8, version u8, channel u16, seq u32, payload size u32, t_send i64. +constexpr size_t kTypeOffset = sizeof(kMagic); +constexpr size_t kVersionOffset = kTypeOffset + sizeof(uint8_t); +constexpr size_t kChannelOffset = kVersionOffset + sizeof(uint8_t); +constexpr size_t kSeqOffset = kChannelOffset + sizeof(uint16_t); +constexpr size_t kPayloadSizeOffset = kSeqOffset + sizeof(uint32_t); +constexpr size_t kSendTimeOffset = kPayloadSizeOffset + sizeof(uint32_t); +constexpr size_t kHeaderSize = kSendTimeOffset + sizeof(int64_t); constexpr uint16_t kSessionChannelId = 0; constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 03b12a72b2..ddb1139102 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -20,17 +20,6 @@ using detail::Writer; namespace { -constexpr size_t kTypeOffset = 4; -constexpr size_t kVersionOffset = 5; -constexpr size_t kChannelOffset = 6; -constexpr size_t kSeqOffset = 8; -constexpr size_t kPayloadSizeOffset = 12; -constexpr size_t kSendTimeOffset = 16; -static_assert(kTypeOffset == sizeof(kMagic) && kVersionOffset == kTypeOffset + 1 && kChannelOffset == kVersionOffset + 1 && - kSeqOffset == kChannelOffset + sizeof(uint16_t) && kPayloadSizeOffset == kSeqOffset + sizeof(uint32_t) && - kSendTimeOffset == kPayloadSizeOffset + sizeof(uint32_t) && - kHeaderSize == kSendTimeOffset + sizeof(int64_t)); - bool is_frame_type(uint8_t value) { switch (static_cast(value)) @@ -83,10 +72,6 @@ void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_mono Frame split_frame(std::vector message) { - if (message.size() < kHeaderSize) - { - throw DecodeError("protocol: message shorter than a header"); - } Frame frame; frame.header = decode_header(message); if (message.size() != kHeaderSize + frame.header.payload_size) @@ -106,11 +91,7 @@ std::vector encode_frame(FrameType type, uint16_t channel_id, const std FrameHeader decode_header(std::span in) { - if (in.size() < kHeaderSize) - { - throw DecodeError("protocol: header: truncated"); - } - Reader reader(in.data(), kHeaderSize, "header"); + Reader reader(in.data(), in.size(), "header"); if (reader.u32() != kMagic) { throw DecodeError("protocol: bad frame magic"); diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 720707e8b9..72abd73f98 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -136,10 +136,6 @@ std::vector encode_schema_sample_frame(uint16_t channel_id, int64_t sample_time_local_common_clock_ns, int64_t sample_time_raw_device_clock_ns) { - if (size > kMaxPayloadSize) - { - throw std::invalid_argument("protocol: schema sample too large"); - } return build_frame(FrameType::SchemaSample, channel_id, 2 * sizeof(int64_t) + sizeof(uint32_t) + size, [&](Writer& writer) { diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 43e1673136..28b840a658 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -19,6 +19,11 @@ namespace { constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + protocol::kPoseSize; +//! WRIST_SAMPLE payload: sample_time i64, then the hand byte, then `valid`. +constexpr size_t kWristHandOffset = sizeof(int64_t); +constexpr size_t kWristValidOffset = kWristHandOffset + sizeof(uint8_t); +//! SCHEMA_SAMPLE payload: two i64 sample times, then the u32 byte count. +constexpr size_t kSchemaByteCountOffset = 2 * sizeof(int64_t); bool same_pose(const XrPosef& a, const XrPosef& b) { @@ -109,17 +114,17 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit } SECTION("unknown type is rejected") { - bytes[4] = 200; + bytes[protocol::kTypeOffset] = 200; REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } SECTION("other protocol versions are rejected") { - bytes[5] = 1; + bytes[protocol::kVersionOffset] = 1; REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } SECTION("oversized payloads are rejected") { - std::memset(bytes + 12, 0xFF, 4); + std::memset(bytes + protocol::kPayloadSizeOffset, 0xFF, sizeof(uint32_t)); REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } } @@ -151,7 +156,7 @@ TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device for (const uint8_t type : { 0, 6, 15 }) { - bytes[4] = type; + bytes[protocol::kTypeOffset] = type; REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } } @@ -282,7 +287,7 @@ TEST_CASE("SCHEMA_SAMPLE round-trips bytes and timestamps", "[remote_device_brid REQUIRE(empty.bytes.empty()); std::vector lying = schema_payload(sample); - lying[16] = 0xFF; // declared size larger than the remaining bytes + lying[kSchemaByteCountOffset] = 0xFF; // declared size larger than the remaining bytes REQUIRE_THROWS_AS(protocol::decode_schema_sample(lying), protocol::DecodeError); } @@ -297,7 +302,7 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") const std::vector bytes = protocol::encode_wrist_sample(sample); REQUIRE(bytes.size() == kWristSamplePayloadSize); - REQUIRE(bytes[8] == 0); // hand byte: 1 = left, 0 = right + REQUIRE(bytes[kWristHandOffset] == 0); // 1 = left, 0 = right const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); REQUIRE(decoded.sample_time_ns == -5); REQUIRE(decoded.hand == XR_HAND_RIGHT_EXT); @@ -306,7 +311,7 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") REQUIRE(same_pose(decoded.sample.pose, sample.sample.pose)); std::vector bad_bool = bytes; - bad_bool[9] = 2; + bad_bool[kWristValidOffset] = 2; REQUIRE_THROWS_AS(protocol::decode_wrist_sample(bad_bool), protocol::DecodeError); } @@ -375,13 +380,12 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt REQUIRE(frame == golden); protocol::stamp_header(frame, 0x11223344u, 0x0807060504030201LL); - REQUIRE(std::vector(frame.begin() + 8, frame.begin() + 12) == + REQUIRE(std::vector(frame.begin() + protocol::kSeqOffset, frame.begin() + protocol::kPayloadSizeOffset) == std::vector{ 0x44, 0x33, 0x22, 0x11 }); - REQUIRE(std::vector(frame.begin() + 16, frame.begin() + protocol::kHeaderSize) == + REQUIRE(std::vector(frame.begin() + protocol::kSendTimeOffset, frame.begin() + protocol::kHeaderSize) == std::vector{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08 }); - REQUIRE(std::equal( - frame.begin() + protocol::kHeaderSize, frame.end(), golden.begin() + protocol::kHeaderSize)); // payload - // untouched + // payload untouched + REQUIRE(std::equal(frame.begin() + protocol::kHeaderSize, frame.end(), golden.begin() + protocol::kHeaderSize)); const protocol::Frame split = protocol::split_frame(frame); REQUIRE(split.header.type == protocol::FrameType::SchemaSample); From 7d0cf5ed114f5185d59410163ebe9f78835632bd Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 12:49:45 -0800 Subject: [PATCH 09/18] review round 5 (pr01) Applied the fact-checked (VERIFIED) findings that stay inside this branch's files and do not change a symbol the stack above uses: - Payload decoders go through parse_payload, the decode-side mirror of build_payload, so the trailing-bytes check cannot be forgotten. - AGENTS.md counts protocol_io.hpp's Reader/Writer among the serialization points and states the link rule without restating the link list. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/remote_device_bridge/AGENTS.md | 4 +- .../session/protocol_payloads.cpp | 184 ++++++++++-------- 2 files changed, 109 insertions(+), 79 deletions(-) diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index 35311c3b7b..ecd1ba6981 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -7,5 +7,5 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. -- `session/protocol_frame.*` and `session/protocol_payloads.*` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and their codec tests together. -- `Teleop::remote_plugin_session` links only `pusherio::pusherio` (OpenXR value types via headers). Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to it: a plugin that talks to a bridge through this library must run without an OpenXR runtime. +- `session/protocol_frame.*`, `session/protocol_payloads.*` and the `Reader`/`Writer` in `session/protocol_io.hpp` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and their codec tests together. +- Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to `Teleop::remote_plugin_session`: a plugin that talks to a bridge through this library must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 72abd73f98..68a2dba8fb 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -111,6 +111,16 @@ std::vector build_payload(Write write) return out; } +//! Runs `read` over `payload` and rejects trailing bytes; the payload-side mirror of build_payload. +template +auto parse_payload(const std::vector& payload, const char* what, Read read) +{ + Reader reader(payload, what); + auto value = read(reader); + reader.finish(); + return value; +} + } // namespace std::vector encode_hand_sample_frame(uint16_t channel_id, @@ -238,119 +248,139 @@ void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns) Hello decode_hello(const std::vector& payload) { - Reader reader(payload, "HELLO"); - Hello value; - if (const uint16_t version = reader.u16(); version != kHelloVersion) - { - throw DecodeError("protocol: unsupported HELLO version " + std::to_string(version)); - } - value.app_name = reader.str(); - value.requirements.schema_push = reader.boolean(); - value.requirements.hand_tracking_push = reader.boolean(); - if (reader.boolean()) - { - value.requirements.wrist_tracking_pull = read_wrist_config(reader); - } - reader.finish(); - return value; + return parse_payload(payload, "HELLO", + [](Reader& reader) + { + Hello value; + if (const uint16_t version = reader.u16(); version != kHelloVersion) + { + throw DecodeError("protocol: unsupported HELLO version " + std::to_string(version)); + } + value.app_name = reader.str(); + value.requirements.schema_push = reader.boolean(); + value.requirements.hand_tracking_push = reader.boolean(); + if (reader.boolean()) + { + value.requirements.wrist_tracking_pull = read_wrist_config(reader); + } + return value; + }); } HelloAck decode_hello_ack(const std::vector& payload) { - Reader reader(payload, "HELLO_ACK"); - HelloAck value; - value.accepted = reader.boolean(); - value.reason = reader.str(); - reader.finish(); - return value; + return parse_payload(payload, "HELLO_ACK", + [](Reader& reader) + { + HelloAck value; + value.accepted = reader.boolean(); + value.reason = reader.str(); + return value; + }); } XrHandEXT decode_open_hand(const std::vector& payload) { - Reader reader(payload, "OPEN_HAND"); - const XrHandEXT hand = from_wire_hand(reader.u8()); - reader.finish(); - return hand; + return parse_payload(payload, "OPEN_HAND", + [](Reader& reader) + { + const XrHandEXT hand = from_wire_hand(reader.u8()); + return hand; + }); } core::SchemaPusherConfig decode_open_schema(const std::vector& payload) { - Reader reader(payload, "OPEN_SCHEMA"); - core::SchemaPusherConfig value; - value.collection_id = reader.str(); - value.max_flatbuffer_size = static_cast(reader.u64()); - value.tensor_identifier = reader.str(); - value.localized_name = reader.str(); - value.app_name = reader.str(); - reader.finish(); - return value; + return parse_payload(payload, "OPEN_SCHEMA", + [](Reader& reader) + { + core::SchemaPusherConfig value; + value.collection_id = reader.str(); + value.max_flatbuffer_size = static_cast(reader.u64()); + value.tensor_identifier = reader.str(); + value.localized_name = reader.str(); + value.app_name = reader.str(); + return value; + }); } HandSample decode_hand_sample(const std::vector& payload) { - Reader reader(payload, "HAND_SAMPLE"); - HandSample value; - value.sample_time_ns = reader.i64(); - for (XrHandJointLocationEXT& joint : value.joints) - { - joint.locationFlags = reader.u64(); - joint.pose = reader.pose(); - joint.radius = reader.f32(); - } - reader.finish(); - return value; + return parse_payload(payload, "HAND_SAMPLE", + [](Reader& reader) + { + HandSample value; + value.sample_time_ns = reader.i64(); + for (XrHandJointLocationEXT& joint : value.joints) + { + joint.locationFlags = reader.u64(); + joint.pose = reader.pose(); + joint.radius = reader.f32(); + } + return value; + }); } SchemaSample decode_schema_sample(const std::vector& payload) { - Reader reader(payload, "SCHEMA_SAMPLE"); - SchemaSample value; - value.sample_time_local_common_clock_ns = reader.i64(); - value.sample_time_raw_device_clock_ns = reader.i64(); - const uint32_t size = reader.u32(); - value.bytes = reader.bytes(size); - reader.finish(); - return value; + return parse_payload(payload, "SCHEMA_SAMPLE", + [](Reader& reader) + { + SchemaSample value; + value.sample_time_local_common_clock_ns = reader.i64(); + value.sample_time_raw_device_clock_ns = reader.i64(); + const uint32_t size = reader.u32(); + value.bytes = reader.bytes(size); + return value; + }); } WristSample decode_wrist_sample(const std::vector& payload) { - Reader reader(payload, "WRIST_SAMPLE"); - WristSample value; - value.sample_time_ns = reader.i64(); - value.hand = reader.boolean() ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; - value.sample.valid = reader.boolean(); - value.sample.tracked = reader.boolean(); - value.sample.pose = reader.pose(); - reader.finish(); - return value; + return parse_payload(payload, "WRIST_SAMPLE", + [](Reader& reader) + { + WristSample value; + value.sample_time_ns = reader.i64(); + value.hand = reader.boolean() ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; + value.sample.valid = reader.boolean(); + value.sample.tracked = reader.boolean(); + value.sample.pose = reader.pose(); + return value; + }); } std::string decode_error(const std::vector& payload) { - Reader reader(payload, "ERROR"); - std::string message = reader.str(); - reader.finish(); - return message; + return parse_payload(payload, "ERROR", + [](Reader& reader) + { + std::string message = reader.str(); + return message; + }); } int64_t decode_ping(const std::vector& payload) { - Reader reader(payload, "PING"); - const int64_t t1_ns = reader.i64(); - reader.finish(); - return t1_ns; + return parse_payload(payload, "PING", + [](Reader& reader) + { + const int64_t t1_ns = reader.i64(); + return t1_ns; + }); } Pong decode_pong(const std::vector& payload) { - Reader reader(payload, "PONG"); - Pong value; - value.ping_sent_ns = reader.i64(); - value.ping_received_ns = reader.i64(); - value.pong_sent_ns = reader.i64(); - reader.finish(); - return value; + return parse_payload(payload, "PONG", + [](Reader& reader) + { + Pong value; + value.ping_sent_ns = reader.i64(); + value.ping_received_ns = reader.i64(); + value.pong_sent_ns = reader.i64(); + return value; + }); } } // namespace remote_plugin_protocol From e874aafe3e707e95f740413a03a55235ba848d26 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 14:33:33 -0800 Subject: [PATCH 10/18] review: name the SCHEMA_SAMPLE fixed size, one-line single-field decoders, quiet Windows skip (pr01) Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_device_bridge/CMakeLists.txt | 1 - .../protocol_payloads.hpp | 3 +++ .../session/protocol_payloads.cpp | 23 ++++--------------- 3 files changed, 7 insertions(+), 20 deletions(-) diff --git a/src/plugins/remote_device_bridge/CMakeLists.txt b/src/plugins/remote_device_bridge/CMakeLists.txt index 0e516622d0..5f3f9d8038 100644 --- a/src/plugins/remote_device_bridge/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/CMakeLists.txt @@ -4,7 +4,6 @@ cmake_minimum_required(VERSION 3.20) if(WIN32) - message(STATUS "Skipping remote_device_bridge (POSIX sockets only)") return() endif() diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index d02b8dc547..5d854d9d71 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -70,9 +70,12 @@ struct Pong constexpr size_t kPoseSize = 7 * sizeof(float); constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; +//! SCHEMA_SAMPLE payload before the schema bytes: two sample times (i64) and the byte count (u32). +constexpr size_t kSchemaSampleFixedSize = 2 * sizeof(int64_t) + sizeof(uint32_t); static_assert(kJointSize == 40); static_assert(kHandSamplePayloadSize == 1048); +static_assert(kSchemaSampleFixedSize == 20); std::vector encode_hello(const Hello& value); std::vector encode_hello_ack(const HelloAck& value); diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 68a2dba8fb..ca312a1f87 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -146,7 +146,7 @@ std::vector encode_schema_sample_frame(uint16_t channel_id, int64_t sample_time_local_common_clock_ns, int64_t sample_time_raw_device_clock_ns) { - return build_frame(FrameType::SchemaSample, channel_id, 2 * sizeof(int64_t) + sizeof(uint32_t) + size, + return build_frame(FrameType::SchemaSample, channel_id, kSchemaSampleFixedSize + size, [&](Writer& writer) { writer.i64(sample_time_local_common_clock_ns); @@ -281,12 +281,7 @@ HelloAck decode_hello_ack(const std::vector& payload) XrHandEXT decode_open_hand(const std::vector& payload) { - return parse_payload(payload, "OPEN_HAND", - [](Reader& reader) - { - const XrHandEXT hand = from_wire_hand(reader.u8()); - return hand; - }); + return parse_payload(payload, "OPEN_HAND", [](Reader& reader) { return from_wire_hand(reader.u8()); }); } core::SchemaPusherConfig decode_open_schema(const std::vector& payload) @@ -352,22 +347,12 @@ WristSample decode_wrist_sample(const std::vector& payload) std::string decode_error(const std::vector& payload) { - return parse_payload(payload, "ERROR", - [](Reader& reader) - { - std::string message = reader.str(); - return message; - }); + return parse_payload(payload, "ERROR", [](Reader& reader) { return reader.str(); }); } int64_t decode_ping(const std::vector& payload) { - return parse_payload(payload, "PING", - [](Reader& reader) - { - const int64_t t1_ns = reader.i64(); - return t1_ns; - }); + return parse_payload(payload, "PING", [](Reader& reader) { return reader.i64(); }); } Pong decode_pong(const std::vector& payload) From 6accac42af584c3ef316676200d2083d3d1a3a1f Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:19:02 -0800 Subject: [PATCH 11/18] review: typed little-endian helpers and one span Reader (pr01) store_le/load_le take the width from the value type so a size argument can no longer disagree with it; Reader has a single std::span constructor; the HELLO version comment describes the current format only. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../protocol_payloads.hpp | 3 +- .../session/protocol_frame.cpp | 16 ++--- .../session/protocol_io.hpp | 62 ++++++++++--------- .../session/protocol_payloads.cpp | 2 +- 4 files changed, 44 insertions(+), 39 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 5d854d9d71..f557952cdc 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -22,8 +22,7 @@ namespace remote_plugin_protocol * XrPosef order (orientation x,y,z,w then position x,y,z). */ -//! HELLO version: the requirements carry the wrist source config, and the client answers PING with PONG. -//! decode_hello accepts only this version. +//! HELLO payload format version, the payload's first field; decode_hello accepts only this version. constexpr uint16_t kHelloVersion = 2; struct Hello diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index ddb1139102..cec87efc26 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -49,13 +49,13 @@ namespace detail void encode_header(const FrameHeader& header, uint8_t* out) { - store_le(out, kMagic, sizeof(uint32_t)); + store_le(out, kMagic); out[kTypeOffset] = static_cast(header.type); out[kVersionOffset] = kProtocolVersion; - store_le(out + kChannelOffset, header.channel_id, sizeof(uint16_t)); - store_le(out + kSeqOffset, header.seq, sizeof(uint32_t)); - store_le(out + kPayloadSizeOffset, header.payload_size, sizeof(uint32_t)); - store_le(out + kSendTimeOffset, static_cast(header.t_send_monotonic_ns), sizeof(int64_t)); + store_le(out + kChannelOffset, header.channel_id); + store_le(out + kSeqOffset, header.seq); + store_le(out + kPayloadSizeOffset, header.payload_size); + store_le(out + kSendTimeOffset, header.t_send_monotonic_ns); } } // namespace detail @@ -66,8 +66,8 @@ void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_mono { throw std::invalid_argument("protocol: frame shorter than a header"); } - store_le(frame.data() + kSeqOffset, seq, sizeof(uint32_t)); - store_le(frame.data() + kSendTimeOffset, static_cast(t_send_monotonic_ns), sizeof(int64_t)); + store_le(frame.data() + kSeqOffset, seq); + store_le(frame.data() + kSendTimeOffset, t_send_monotonic_ns); } Frame split_frame(std::vector message) @@ -91,7 +91,7 @@ std::vector encode_frame(FrameType type, uint16_t channel_id, const std FrameHeader decode_header(std::span in) { - Reader reader(in.data(), in.size(), "header"); + Reader reader(in, "header"); if (reader.u32() != kMagic) { throw DecodeError("protocol: bad frame magic"); diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index 154e31396e..3b4eab7e50 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -9,8 +9,10 @@ #include #include +#include #include #include +#include #include namespace remote_plugin_protocol @@ -18,24 +20,30 @@ namespace remote_plugin_protocol namespace detail { -//! Stores the low `size` bytes of `value` little-endian at `out`. -inline void store_le(uint8_t* out, uint64_t value, size_t size) +//! Stores `value` little-endian at `out`; the byte count is sizeof(T). +template +inline void store_le(uint8_t* out, T value) { - for (size_t i = 0; i < size; ++i) + static_assert(std::is_integral_v); + const auto bits = static_cast>(value); + for (size_t i = 0; i < sizeof(T); ++i) { - out[i] = static_cast(value >> (8 * i)); + out[i] = static_cast(bits >> (8 * i)); } } -//! Loads `size` little-endian bytes from `in`. -inline uint64_t load_le(const uint8_t* in, size_t size) +//! Loads a little-endian T from the sizeof(T) bytes at `in`. +template +inline T load_le(const uint8_t* in) { - uint64_t value = 0; - for (size_t i = 0; i < size; ++i) + static_assert(std::is_integral_v); + using Bits = std::make_unsigned_t; + Bits bits = 0; + for (size_t i = 0; i < sizeof(T); ++i) { - value |= static_cast(in[i]) << (8 * i); + bits = static_cast(bits | (static_cast(in[i]) << (8 * i))); } - return value; + return static_cast(bits); } //! Writes the header into the first kHeaderSize bytes of `out`. @@ -61,17 +69,17 @@ class Writer void u16(uint16_t value) { - append(value, sizeof(value)); + append(value); } void u32(uint32_t value) { - append(value, sizeof(value)); + append(value); } void u64(uint64_t value) { - append(value, sizeof(value)); + append(value); } void i64(int64_t value) @@ -113,11 +121,12 @@ class Writer } private: - void append(uint64_t value, size_t size) + template + void append(T value) { const size_t at = m_out.size(); - m_out.resize(at + size); - store_le(m_out.data() + at, value, size); + m_out.resize(at + sizeof(T)); + store_le(m_out.data() + at, value); } std::vector& m_out; @@ -127,11 +136,7 @@ class Reader { public: //! `what` names the frame or header being read in DecodeError messages. - Reader(const uint8_t* data, size_t size, const char* what) : m_data(data), m_size(size), m_what(what) - { - } - - Reader(const std::vector& payload, const char* what) : Reader(payload.data(), payload.size(), what) + Reader(std::span data, const char* what) : m_data(data.data()), m_size(data.size()), m_what(what) { } @@ -153,17 +158,17 @@ class Reader uint16_t u16() { - return static_cast(take(sizeof(uint16_t))); + return take(); } uint32_t u32() { - return static_cast(take(sizeof(uint32_t))); + return take(); } uint64_t u64() { - return take(sizeof(uint64_t)); + return take(); } int64_t i64() @@ -219,11 +224,12 @@ class Reader } private: - uint64_t take(size_t size) + template + T take() { - need(size); - const uint64_t value = load_le(m_data + m_pos, size); - m_pos += size; + need(sizeof(T)); + const T value = load_le(m_data + m_pos); + m_pos += sizeof(T); return value; } diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index ca312a1f87..5301490cb2 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -243,7 +243,7 @@ void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns) { throw std::invalid_argument("protocol: not an encoded PONG frame"); } - detail::store_le(pong_frame.data() + kPongSentOffset, static_cast(pong_sent_ns), sizeof(int64_t)); + detail::store_le(pong_frame.data() + kPongSentOffset, pong_sent_ns); } Hello decode_hello(const std::vector& payload) From 8bac1330446fc3de217f8b2c0a3630cb05124e92 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:19:35 -0800 Subject: [PATCH 12/18] refactor(remote_device_bridge): codec API takes std::span (pr01) Encoders and decoders take std::span instead of pointer + size or const std::vector&, and HAND_SAMPLE takes HandJoints, a span with the fixed extent XR_HAND_JOINT_COUNT_EXT, so the joint count is in the signature. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_frame.hpp | 2 +- .../protocol_payloads.hpp | 31 ++++++------- .../session/protocol_frame.cpp | 5 +-- .../session/protocol_io.hpp | 4 +- .../session/protocol_payloads.cpp | 43 +++++++++---------- .../remote_device_bridge/test_wire_codec.cpp | 36 +++++++++------- 6 files changed, 61 insertions(+), 60 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 2a90a200aa..c9423e6e21 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -76,7 +76,7 @@ class DecodeError : public std::runtime_error FrameHeader decode_header(std::span in); //! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(). -std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload); +std::vector encode_frame(FrameType type, uint16_t channel_id, std::span payload); //! Patches seq and t_send into an encoded frame's header in place. void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_monotonic_ns); //! Splits one complete message into header and payload. The payload keeps `message`'s buffer (its bytes are diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index f557952cdc..dca9698513 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -11,6 +11,7 @@ #include #include #include +#include #include #include @@ -76,6 +77,9 @@ static_assert(kJointSize == 40); static_assert(kHandSamplePayloadSize == 1048); static_assert(kSchemaSampleFixedSize == 20); +//! One hand's joints, as IHandTrackingPushChannel::push receives them. +using HandJoints = std::span; + std::vector encode_hello(const Hello& value); std::vector encode_hello_ack(const HelloAck& value); //! One byte: 0 = left, 1 = right. @@ -90,25 +94,22 @@ std::vector encode_pong(const Pong& value); void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns); // Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. -std::vector encode_hand_sample_frame(uint16_t channel_id, - const XrHandJointLocationEXT* joints, - int64_t sample_time_ns); +std::vector encode_hand_sample_frame(uint16_t channel_id, HandJoints joints, int64_t sample_time_ns); std::vector encode_schema_sample_frame(uint16_t channel_id, - const uint8_t* bytes, - size_t size, + std::span bytes, int64_t sample_time_local_common_clock_ns, int64_t sample_time_raw_device_clock_ns); // Parsers throw DecodeError, naming the frame, on truncated, over-long or out-of-range payloads. -Hello decode_hello(const std::vector& payload); -HelloAck decode_hello_ack(const std::vector& payload); -XrHandEXT decode_open_hand(const std::vector& payload); -core::SchemaPusherConfig decode_open_schema(const std::vector& payload); -HandSample decode_hand_sample(const std::vector& payload); -SchemaSample decode_schema_sample(const std::vector& payload); -WristSample decode_wrist_sample(const std::vector& payload); -std::string decode_error(const std::vector& payload); -int64_t decode_ping(const std::vector& payload); -Pong decode_pong(const std::vector& payload); +Hello decode_hello(std::span payload); +HelloAck decode_hello_ack(std::span payload); +XrHandEXT decode_open_hand(std::span payload); +core::SchemaPusherConfig decode_open_schema(std::span payload); +HandSample decode_hand_sample(std::span payload); +SchemaSample decode_schema_sample(std::span payload); +WristSample decode_wrist_sample(std::span payload); +std::string decode_error(std::span payload); +int64_t decode_ping(std::span payload); +Pong decode_pong(std::span payload); } // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index cec87efc26..9f4f316b60 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -83,10 +83,9 @@ Frame split_frame(std::vector message) return frame; } -std::vector encode_frame(FrameType type, uint16_t channel_id, const std::vector& payload) +std::vector encode_frame(FrameType type, uint16_t channel_id, std::span payload) { - return build_frame( - type, channel_id, payload.size(), [&payload](Writer& writer) { writer.bytes(payload.data(), payload.size()); }); + return build_frame(type, channel_id, payload.size(), [payload](Writer& writer) { writer.bytes(payload); }); } FrameHeader decode_header(std::span in) diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index 3b4eab7e50..ccacac5ec3 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -104,9 +104,9 @@ class Writer m_out.insert(m_out.end(), value.begin(), value.end()); } - void bytes(const uint8_t* data, size_t size) + void bytes(std::span data) { - m_out.insert(m_out.end(), data, data + size); + m_out.insert(m_out.end(), data.begin(), data.end()); } void pose(const XrPosef& value) diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 5301490cb2..120c9a9b7d 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -113,7 +113,7 @@ std::vector build_payload(Write write) //! Runs `read` over `payload` and rejects trailing bytes; the payload-side mirror of build_payload. template -auto parse_payload(const std::vector& payload, const char* what, Read read) +auto parse_payload(std::span payload, const char* what, Read read) { Reader reader(payload, what); auto value = read(reader); @@ -123,36 +123,33 @@ auto parse_payload(const std::vector& payload, const char* what, Read r } // namespace -std::vector encode_hand_sample_frame(uint16_t channel_id, - const XrHandJointLocationEXT* joints, - int64_t sample_time_ns) +std::vector encode_hand_sample_frame(uint16_t channel_id, HandJoints joints, int64_t sample_time_ns) { return build_frame(FrameType::HandSample, channel_id, kHandSamplePayloadSize, [&](Writer& writer) { writer.i64(sample_time_ns); - for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + for (const XrHandJointLocationEXT& joint : joints) { - writer.u64(joints[i].locationFlags); - writer.pose(joints[i].pose); - writer.f32(joints[i].radius); + writer.u64(joint.locationFlags); + writer.pose(joint.pose); + writer.f32(joint.radius); } }); } std::vector encode_schema_sample_frame(uint16_t channel_id, - const uint8_t* bytes, - size_t size, + std::span bytes, int64_t sample_time_local_common_clock_ns, int64_t sample_time_raw_device_clock_ns) { - return build_frame(FrameType::SchemaSample, channel_id, kSchemaSampleFixedSize + size, + return build_frame(FrameType::SchemaSample, channel_id, kSchemaSampleFixedSize + bytes.size(), [&](Writer& writer) { writer.i64(sample_time_local_common_clock_ns); writer.i64(sample_time_raw_device_clock_ns); - writer.u32(static_cast(size)); - writer.bytes(bytes, size); + writer.u32(static_cast(bytes.size())); + writer.bytes(bytes); }); } @@ -246,7 +243,7 @@ void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns) detail::store_le(pong_frame.data() + kPongSentOffset, pong_sent_ns); } -Hello decode_hello(const std::vector& payload) +Hello decode_hello(std::span payload) { return parse_payload(payload, "HELLO", [](Reader& reader) @@ -267,7 +264,7 @@ Hello decode_hello(const std::vector& payload) }); } -HelloAck decode_hello_ack(const std::vector& payload) +HelloAck decode_hello_ack(std::span payload) { return parse_payload(payload, "HELLO_ACK", [](Reader& reader) @@ -279,12 +276,12 @@ HelloAck decode_hello_ack(const std::vector& payload) }); } -XrHandEXT decode_open_hand(const std::vector& payload) +XrHandEXT decode_open_hand(std::span payload) { return parse_payload(payload, "OPEN_HAND", [](Reader& reader) { return from_wire_hand(reader.u8()); }); } -core::SchemaPusherConfig decode_open_schema(const std::vector& payload) +core::SchemaPusherConfig decode_open_schema(std::span payload) { return parse_payload(payload, "OPEN_SCHEMA", [](Reader& reader) @@ -299,7 +296,7 @@ core::SchemaPusherConfig decode_open_schema(const std::vector& payload) }); } -HandSample decode_hand_sample(const std::vector& payload) +HandSample decode_hand_sample(std::span payload) { return parse_payload(payload, "HAND_SAMPLE", [](Reader& reader) @@ -316,7 +313,7 @@ HandSample decode_hand_sample(const std::vector& payload) }); } -SchemaSample decode_schema_sample(const std::vector& payload) +SchemaSample decode_schema_sample(std::span payload) { return parse_payload(payload, "SCHEMA_SAMPLE", [](Reader& reader) @@ -330,7 +327,7 @@ SchemaSample decode_schema_sample(const std::vector& payload) }); } -WristSample decode_wrist_sample(const std::vector& payload) +WristSample decode_wrist_sample(std::span payload) { return parse_payload(payload, "WRIST_SAMPLE", [](Reader& reader) @@ -345,17 +342,17 @@ WristSample decode_wrist_sample(const std::vector& payload) }); } -std::string decode_error(const std::vector& payload) +std::string decode_error(std::span payload) { return parse_payload(payload, "ERROR", [](Reader& reader) { return reader.str(); }); } -int64_t decode_ping(const std::vector& payload) +int64_t decode_ping(std::span payload) { return parse_payload(payload, "PING", [](Reader& reader) { return reader.i64(); }); } -Pong decode_pong(const std::vector& payload) +Pong decode_pong(std::span payload) { return parse_payload(payload, "PONG", [](Reader& reader) diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 28b840a658..c3e7fc31c2 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include @@ -25,6 +26,11 @@ constexpr size_t kWristValidOffset = kWristHandOffset + sizeof(uint8_t); //! SCHEMA_SAMPLE payload: two i64 sample times, then the u32 byte count. constexpr size_t kSchemaByteCountOffset = 2 * sizeof(int64_t); +std::vector bytes_of(std::initializer_list values) +{ + return values; +} + bool same_pose(const XrPosef& a, const XrPosef& b) { return std::memcmp(&a, &b, sizeof(XrPosef)) == 0; @@ -76,12 +82,12 @@ std::vector reference_hand_payload(const protocol::HandSample& sample) std::vector hand_payload(const protocol::HandSample& sample) { - return protocol::split_frame(protocol::encode_hand_sample_frame(1, sample.joints.data(), sample.sample_time_ns)).payload; + return protocol::split_frame(protocol::encode_hand_sample_frame(1, sample.joints, sample.sample_time_ns)).payload; } std::vector schema_payload(const protocol::SchemaSample& sample) { - return protocol::split_frame(protocol::encode_schema_sample_frame(1, sample.bytes.data(), sample.bytes.size(), + return protocol::split_frame(protocol::encode_schema_sample_frame(1, sample.bytes, sample.sample_time_local_common_clock_ns, sample.sample_time_raw_device_clock_ns)) .payload; @@ -201,11 +207,11 @@ TEST_CASE("OPEN_HAND encodes both hands and rejects others", "[remote_device_bri { REQUIRE(protocol::encode_open_hand(XR_HAND_LEFT_EXT) == std::vector{ 0 }); REQUIRE(protocol::encode_open_hand(XR_HAND_RIGHT_EXT) == std::vector{ 1 }); - REQUIRE(protocol::decode_open_hand({ 0 }) == XR_HAND_LEFT_EXT); - REQUIRE(protocol::decode_open_hand({ 1 }) == XR_HAND_RIGHT_EXT); - REQUIRE_THROWS_AS(protocol::decode_open_hand({ 2 }), protocol::DecodeError); - REQUIRE_THROWS_AS(protocol::decode_open_hand({}), protocol::DecodeError); - REQUIRE_THROWS_AS(protocol::decode_open_hand({ 0, 0 }), protocol::DecodeError); + REQUIRE(protocol::decode_open_hand(bytes_of({ 0 })) == XR_HAND_LEFT_EXT); + REQUIRE(protocol::decode_open_hand(bytes_of({ 1 })) == XR_HAND_RIGHT_EXT); + REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({ 2 })), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({})), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({ 0, 0 })), protocol::DecodeError); } TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][unit]") @@ -319,7 +325,7 @@ TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_b { REQUIRE(protocol::decode_error(protocol::encode_error("boom")) == "boom"); REQUIRE(protocol::decode_error(protocol::encode_error("")).empty()); - REQUIRE_THROWS_AS(protocol::decode_error({ 4, 0, 0, 0, 'a' }), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_error(bytes_of({ 4, 0, 0, 0, 'a' })), protocol::DecodeError); } TEST_CASE("PING and PONG round-trip and PONG records its send time", "[remote_device_bridge][unit]") @@ -327,7 +333,7 @@ TEST_CASE("PING and PONG round-trip and PONG records its send time", "[remote_de const std::vector ping = protocol::encode_ping(-123456789012345LL); REQUIRE(ping.size() == 8); REQUIRE(protocol::decode_ping(ping) == -123456789012345LL); - REQUIRE_THROWS_AS(protocol::decode_ping({ 1, 2, 3 }), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_ping(bytes_of({ 1, 2, 3 })), protocol::DecodeError); const std::vector payload = protocol::encode_pong(protocol::Pong{ 1, 2, 3 }); REQUIRE(payload.size() == 24); @@ -352,8 +358,8 @@ TEST_CASE("PING and PONG round-trip and PONG records its send time", "[remote_de std::vector ping_frame = protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, ping); REQUIRE_THROWS_AS(protocol::set_pong_sent_time(ping_frame, 42), std::invalid_argument); - REQUIRE_THROWS_WITH(protocol::decode_ping({ 1, 2, 3 }), Catch::Matchers::ContainsSubstring("PING")); - REQUIRE_THROWS_WITH(protocol::decode_pong({ 1 }), Catch::Matchers::ContainsSubstring("PONG")); + REQUIRE_THROWS_WITH(protocol::decode_ping(bytes_of({ 1, 2, 3 })), Catch::Matchers::ContainsSubstring("PING")); + REQUIRE_THROWS_WITH(protocol::decode_pong(bytes_of({ 1 })), Catch::Matchers::ContainsSubstring("PONG")); } TEST_CASE("Contiguous frame builders match header + payload encoder byte for byte", "[remote_device_bridge][unit]") @@ -361,8 +367,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt SECTION("SCHEMA_SAMPLE against a hand-built golden frame") { const std::vector bytes = { 0xDE, 0xAD }; - std::vector frame = - protocol::encode_schema_sample_frame(3, bytes.data(), bytes.size(), 0x0102030405060708LL, -1); + std::vector frame = protocol::encode_schema_sample_frame(3, bytes, 0x0102030405060708LL, -1); // clang-format off const std::vector golden = { 0x52, 0x50, 0x53, 0x30, // magic "RPS0" @@ -409,7 +414,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt } const std::vector payload = reference_hand_payload(sample); REQUIRE(payload.size() == protocol::kHandSamplePayloadSize); - const std::vector frame = protocol::encode_hand_sample_frame(0x0102, sample.joints.data(), -42); + const std::vector frame = protocol::encode_hand_sample_frame(0x0102, sample.joints, -42); REQUIRE(frame.size() == protocol::kHeaderSize + protocol::kHandSamplePayloadSize); const protocol::FrameHeader header = protocol::decode_header(frame); REQUIRE(header.type == protocol::FrameType::HandSample); @@ -430,7 +435,6 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt SECTION("payloads above the limit are refused at build time") { std::vector too_big(protocol::kMaxPayloadSize + 1); - REQUIRE_THROWS_AS( - protocol::encode_schema_sample_frame(1, too_big.data(), too_big.size(), 0, 0), std::invalid_argument); + REQUIRE_THROWS_AS(protocol::encode_schema_sample_frame(1, too_big, 0, 0), std::invalid_argument); } } From e4671524d6c79ee372d8cc1fd8b2007042f95087 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:19:42 -0800 Subject: [PATCH 13/18] refactor(remote_device_bridge): name sample times sample_time_local_common_clock_ns (pr01) HandSample and WristSample use the name IHandTrackingPushChannel::push and SchemaSample already use, so the clock domain is explicit. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_payloads.hpp | 8 +++++--- .../session/protocol_payloads.cpp | 12 +++++++----- .../remote_device_bridge/test_wire_codec.cpp | 16 +++++++++------- 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index dca9698513..686c2b6a1a 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -40,7 +40,7 @@ struct HelloAck struct HandSample { - int64_t sample_time_ns = 0; + int64_t sample_time_local_common_clock_ns = 0; std::array joints{}; }; @@ -54,7 +54,7 @@ struct SchemaSample //! On the wire the hand is one byte, 1 = left and 0 = right. struct WristSample { - int64_t sample_time_ns = 0; + int64_t sample_time_local_common_clock_ns = 0; XrHandEXT hand = XR_HAND_LEFT_EXT; core::WristTrackingSample sample; }; @@ -94,7 +94,9 @@ std::vector encode_pong(const Pong& value); void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns); // Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. -std::vector encode_hand_sample_frame(uint16_t channel_id, HandJoints joints, int64_t sample_time_ns); +std::vector encode_hand_sample_frame(uint16_t channel_id, + HandJoints joints, + int64_t sample_time_local_common_clock_ns); std::vector encode_schema_sample_frame(uint16_t channel_id, std::span bytes, int64_t sample_time_local_common_clock_ns, diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 120c9a9b7d..2c6facc9db 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -123,12 +123,14 @@ auto parse_payload(std::span payload, const char* what, Read read } // namespace -std::vector encode_hand_sample_frame(uint16_t channel_id, HandJoints joints, int64_t sample_time_ns) +std::vector encode_hand_sample_frame(uint16_t channel_id, + HandJoints joints, + int64_t sample_time_local_common_clock_ns) { return build_frame(FrameType::HandSample, channel_id, kHandSamplePayloadSize, [&](Writer& writer) { - writer.i64(sample_time_ns); + writer.i64(sample_time_local_common_clock_ns); for (const XrHandJointLocationEXT& joint : joints) { writer.u64(joint.locationFlags); @@ -203,7 +205,7 @@ std::vector encode_wrist_sample(const WristSample& value) return build_payload( [&](Writer& writer) { - writer.i64(value.sample_time_ns); + writer.i64(value.sample_time_local_common_clock_ns); writer.u8(to_wire_is_left(value.hand)); writer.boolean(value.sample.valid); writer.boolean(value.sample.tracked); @@ -302,7 +304,7 @@ HandSample decode_hand_sample(std::span payload) [](Reader& reader) { HandSample value; - value.sample_time_ns = reader.i64(); + value.sample_time_local_common_clock_ns = reader.i64(); for (XrHandJointLocationEXT& joint : value.joints) { joint.locationFlags = reader.u64(); @@ -333,7 +335,7 @@ WristSample decode_wrist_sample(std::span payload) [](Reader& reader) { WristSample value; - value.sample_time_ns = reader.i64(); + value.sample_time_local_common_clock_ns = reader.i64(); value.hand = reader.boolean() ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; value.sample.valid = reader.boolean(); value.sample.tracked = reader.boolean(); diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index c3e7fc31c2..91452b7222 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -66,7 +66,7 @@ void put_f32(std::vector& out, float v) std::vector reference_hand_payload(const protocol::HandSample& sample) { std::vector out; - put_u64(out, static_cast(sample.sample_time_ns)); + put_u64(out, static_cast(sample.sample_time_local_common_clock_ns)); for (const XrHandJointLocationEXT& joint : sample.joints) { put_u64(out, joint.locationFlags); @@ -82,7 +82,9 @@ std::vector reference_hand_payload(const protocol::HandSample& sample) std::vector hand_payload(const protocol::HandSample& sample) { - return protocol::split_frame(protocol::encode_hand_sample_frame(1, sample.joints, sample.sample_time_ns)).payload; + return protocol::split_frame( + protocol::encode_hand_sample_frame(1, sample.joints, sample.sample_time_local_common_clock_ns)) + .payload; } std::vector schema_payload(const protocol::SchemaSample& sample) @@ -250,7 +252,7 @@ TEST_CASE("HELLO rejects an unknown wrist source mode", "[remote_device_bridge][ TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge][unit]") { protocol::HandSample sample; - sample.sample_time_ns = 987654321012345LL; + sample.sample_time_local_common_clock_ns = 987654321012345LL; for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { sample.joints[static_cast(i)].locationFlags = 0xF000000000000000ULL | static_cast(i); @@ -262,7 +264,7 @@ TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge REQUIRE(bytes.size() == protocol::kHandSamplePayloadSize); const protocol::HandSample decoded = protocol::decode_hand_sample(bytes); - REQUIRE(decoded.sample_time_ns == sample.sample_time_ns); + REQUIRE(decoded.sample_time_local_common_clock_ns == sample.sample_time_local_common_clock_ns); for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { REQUIRE(decoded.joints[i].locationFlags == sample.joints[i].locationFlags); @@ -300,7 +302,7 @@ TEST_CASE("SCHEMA_SAMPLE round-trips bytes and timestamps", "[remote_device_brid TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") { protocol::WristSample sample; - sample.sample_time_ns = -5; + sample.sample_time_local_common_clock_ns = -5; sample.hand = XR_HAND_RIGHT_EXT; sample.sample.valid = true; sample.sample.tracked = false; @@ -310,7 +312,7 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") REQUIRE(bytes.size() == kWristSamplePayloadSize); REQUIRE(bytes[kWristHandOffset] == 0); // 1 = left, 0 = right const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); - REQUIRE(decoded.sample_time_ns == -5); + REQUIRE(decoded.sample_time_local_common_clock_ns == -5); REQUIRE(decoded.hand == XR_HAND_RIGHT_EXT); REQUIRE(decoded.sample.valid); REQUIRE_FALSE(decoded.sample.tracked); @@ -405,7 +407,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt SECTION("HAND_SAMPLE against the reference payload encoder") { protocol::HandSample sample; - sample.sample_time_ns = -42; + sample.sample_time_local_common_clock_ns = -42; for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { sample.joints[i].locationFlags = 0xA000000000000000ULL | i; From 731472da96133d757866cf5df758fdad7f0ac948 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:20:59 -0800 Subject: [PATCH 14/18] feat(remote_device_bridge)!: wire format v1 (pr01) One wire cleanup, so sender and bridge must be rebuilt together: - kProtocolVersion 0 -> 1 is the only version; the HELLO payload no longer carries its own version (kHelloVersion removed). decode_header checks the version before the type, so a version-0 peer is rejected with a readable reason naming both versions instead of being mis-decoded. - FrameType numbers are contiguous 1..13 (no hole at 6). - WRIST_SAMPLE encodes the hand like OPEN_HAND: 0 = left, 1 = right. - PING has no payload and PONG carries only ping_sent_ns (the PING header t_send) and ping_received_ns; the PONG send time is its header t_send. set_pong_sent_time, encode_ping and decode_ping are removed. - AGENTS.md describes the v1 format. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- src/plugins/remote_device_bridge/AGENTS.md | 2 + .../remote_plugin_session/protocol_frame.hpp | 35 +++--- .../protocol_payloads.hpp | 16 +-- .../session/protocol_frame.cpp | 12 ++- .../session/protocol_payloads.cpp | 45 +------- .../remote_device_bridge/test_wire_codec.cpp | 100 ++++++++++-------- 6 files changed, 89 insertions(+), 121 deletions(-) diff --git a/src/plugins/remote_device_bridge/AGENTS.md b/src/plugins/remote_device_bridge/AGENTS.md index ecd1ba6981..12e70cd249 100644 --- a/src/plugins/remote_device_bridge/AGENTS.md +++ b/src/plugins/remote_device_bridge/AGENTS.md @@ -8,4 +8,6 @@ SPDX-License-Identifier: Apache-2.0 **CRITICAL:** Complete the mandatory `AGENTS.md` preflight in [`../../../AGENTS.md`](../../../AGENTS.md) before editing here. - `session/protocol_frame.*`, `session/protocol_payloads.*` and the `Reader`/`Writer` in `session/protocol_io.hpp` are the only serialization points. Every frame is encoded and decoded there and nowhere else; changing the wire format means changing them and their codec tests together. +- Wire format v1 (`kProtocolVersion` = 1, the only version number): 24-byte header `RPS0` magic, type u8, version u8, channel u16, seq u32, payload size u32, `t_send` i64; frame types 1..13 with no gaps; the hand byte is 0 = left, 1 = right in every payload; PING has no payload and PONG carries the PING's header `t_send` and the client's receive time. Any change to a header, payload or type number bumps `kProtocolVersion`; `decode_header` rejects other versions before reading the type, so old senders and bridges fail with a readable reason instead of mis-decoding. +- A frame's `t_send` is its send time for clock exchange: call `stamp_header` where the frame is written to the transport, never when it is queued. - Never add `OpenXR::openxr_loader`, `Teleop::plugin_utils` or DeviceIO session libraries to `Teleop::remote_plugin_session`: a plugin that talks to a bridge through this library must run without an OpenXR runtime. diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index c9423e6e21..68962dcd0e 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -13,13 +13,15 @@ namespace remote_plugin_protocol { /*! - * Remote plugin protocol v0: fixed little-endian frames over one connection per + * Remote plugin protocol v1: fixed little-endian frames over one connection per * plugin session. Frame = header + payload; payload layouts live in - * protocol_payloads.hpp. + * protocol_payloads.hpp. kProtocolVersion is the only version number: any change + * to a header, payload or frame type number bumps it, and decode_header rejects + * every other version before it reads anything else. */ constexpr uint32_t kMagic = 0x30535052u; // "RPS0" -constexpr uint8_t kProtocolVersion = 0; +constexpr uint8_t kProtocolVersion = 1; //! Header byte offsets: magic u32, type u8, version u8, channel u16, seq u32, payload size u32, t_send i64. constexpr size_t kTypeOffset = sizeof(kMagic); constexpr size_t kVersionOffset = kTypeOffset + sizeof(uint8_t); @@ -31,7 +33,7 @@ constexpr size_t kHeaderSize = kSendTimeOffset + sizeof(int64_t); constexpr uint16_t kSessionChannelId = 0; constexpr uint32_t kMaxPayloadSize = 16u * 1024u * 1024u; // large tactile/sensor payloads; still bounded -//! Direction is c->s (plugin to bridge) or s->c. OPEN_PULL, CLOSE and HEARTBEAT have empty payloads. +//! Direction is c->s (plugin to bridge) or s->c. OPEN_PULL, CLOSE, HEARTBEAT and PING have empty payloads. enum class FrameType : uint8_t { Hello = 1, // c->s @@ -39,15 +41,14 @@ enum class FrameType : uint8_t OpenHand = 3, // c->s OpenSchema = 4, // c->s OpenPull = 5, // c->s - // 6 is unassigned: the wrist source config travels in HELLO. - Close = 7, // c->s - HandSample = 8, // c->s - SchemaSample = 9, // c->s - WristSample = 10, // s->c - Heartbeat = 11, // both - Error = 12, // s->c - Ping = 13, // s->c - Pong = 14, // c->s + Close = 6, // c->s + HandSample = 7, // c->s + SchemaSample = 8, // c->s + WristSample = 9, // s->c + Heartbeat = 10, // both + Error = 11, // s->c + Ping = 12, // s->c + Pong = 13, // c->s }; struct FrameHeader @@ -71,11 +72,13 @@ class DecodeError : public std::runtime_error using std::runtime_error::runtime_error; }; -//! Reads the header from the first kHeaderSize bytes of `in`. Throws DecodeError if `in` is shorter, or on bad -//! magic, unknown type, unsupported version or an oversized payload. +//! Reads the header from the first kHeaderSize bytes of `in`. Throws DecodeError, in the order the fields are read: +//! bad magic, another protocol version (checked before the type byte is interpreted), unknown type, oversized +//! payload; and if `in` ends before a field it reads. FrameHeader decode_header(std::span in); -//! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(). +//! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(), which the +//! sender calls at the moment it writes the frame: t_send is the send time PING/PONG clock exchanges use. std::vector encode_frame(FrameType type, uint16_t channel_id, std::span payload); //! Patches seq and t_send into an encoded frame's header in place. void stamp_header(std::vector& frame, uint32_t seq, int64_t t_send_monotonic_ns); diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 686c2b6a1a..9c6133eb0a 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -23,9 +23,6 @@ namespace remote_plugin_protocol * XrPosef order (orientation x,y,z,w then position x,y,z). */ -//! HELLO payload format version, the payload's first field; decode_hello accepts only this version. -constexpr uint16_t kHelloVersion = 2; - struct Hello { std::string app_name; @@ -51,7 +48,7 @@ struct SchemaSample std::vector bytes; }; -//! On the wire the hand is one byte, 1 = left and 0 = right. +//! On the wire the hand is one byte, 0 = left and 1 = right, as in OPEN_HAND. struct WristSample { int64_t sample_time_local_common_clock_ns = 0; @@ -59,12 +56,12 @@ struct WristSample core::WristTrackingSample sample; }; -//! Two-way clock exchange; times are CLOCK_MONOTONIC ns of the side that took them. +//! Two-way clock exchange; times are CLOCK_MONOTONIC ns of the side that took them. The PING carries no payload: +//! its send time is its header t_send. The PONG's own send time is the PONG header t_send. struct Pong { - int64_t ping_sent_ns = 0; //!< bridge clock, echoed from the PING + int64_t ping_sent_ns = 0; //!< bridge clock: the PING header t_send, echoed int64_t ping_received_ns = 0; //!< client clock - int64_t pong_sent_ns = 0; //!< client clock, set by set_pong_sent_time when the frame is sent }; constexpr size_t kPoseSize = 7 * sizeof(float); @@ -87,11 +84,7 @@ std::vector encode_open_hand(XrHandEXT hand); std::vector encode_open_schema(const core::SchemaPusherConfig& value); std::vector encode_wrist_sample(const WristSample& value); std::vector encode_error(const std::string& message); -std::vector encode_ping(int64_t t1_ns); std::vector encode_pong(const Pong& value); -//! Sets pong_sent_ns in an encoded PONG frame; call where the frame is sent, so it records when the frame left, -//! not when it was queued. -void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns); // Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. std::vector encode_hand_sample_frame(uint16_t channel_id, @@ -111,7 +104,6 @@ HandSample decode_hand_sample(std::span payload); SchemaSample decode_schema_sample(std::span payload); WristSample decode_wrist_sample(std::span payload); std::string decode_error(std::span payload); -int64_t decode_ping(std::span payload); Pong decode_pong(std::span payload); } // namespace remote_plugin_protocol diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 9f4f316b60..af5ca9b7de 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -97,16 +97,18 @@ FrameHeader decode_header(std::span in) } FrameHeader header; const uint8_t type = reader.u8(); + // Version before type: frame type numbers differ between versions. + if (const uint8_t version = reader.u8(); version != kProtocolVersion) + { + throw DecodeError("protocol: peer speaks protocol version " + std::to_string(version) + + ", this build speaks version " + std::to_string(kProtocolVersion) + + "; rebuild the sender and the bridge from the same source"); + } if (!is_frame_type(type)) { throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } header.type = static_cast(type); - const uint8_t version = reader.u8(); - if (version != kProtocolVersion) - { - throw DecodeError("protocol: unsupported protocol version " + std::to_string(version)); - } header.channel_id = reader.u16(); header.seq = reader.u32(); header.payload_size = reader.u32(); diff --git a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp index 2c6facc9db..4bd03df1e8 100644 --- a/src/plugins/remote_device_bridge/session/protocol_payloads.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_payloads.cpp @@ -43,19 +43,6 @@ XrHandEXT from_wire_hand(uint8_t hand) } } -uint8_t to_wire_is_left(XrHandEXT hand) -{ - switch (hand) - { - case XR_HAND_LEFT_EXT: - return 1; - case XR_HAND_RIGHT_EXT: - return 0; - default: - throw std::invalid_argument("protocol: unsupported XrHandEXT value"); - } -} - uint8_t to_wire_mode(core::WristTrackingSourceMode mode) { switch (mode) @@ -160,7 +147,6 @@ std::vector encode_hello(const Hello& value) return build_payload( [&](Writer& writer) { - writer.u16(kHelloVersion); writer.str(value.app_name); writer.boolean(value.requirements.schema_push); writer.boolean(value.requirements.hand_tracking_push); @@ -206,7 +192,7 @@ std::vector encode_wrist_sample(const WristSample& value) [&](Writer& writer) { writer.i64(value.sample_time_local_common_clock_ns); - writer.u8(to_wire_is_left(value.hand)); + writer.u8(to_wire_hand(value.hand)); writer.boolean(value.sample.valid); writer.boolean(value.sample.tracked); writer.pose(value.sample.pose); @@ -218,11 +204,6 @@ std::vector encode_error(const std::string& message) return build_payload([&](Writer& writer) { writer.str(message); }); } -std::vector encode_ping(int64_t t1_ns) -{ - return build_payload([&](Writer& writer) { writer.i64(t1_ns); }); -} - std::vector encode_pong(const Pong& value) { return build_payload( @@ -230,31 +211,15 @@ std::vector encode_pong(const Pong& value) { writer.i64(value.ping_sent_ns); writer.i64(value.ping_received_ns); - writer.i64(value.pong_sent_ns); }); } -void set_pong_sent_time(std::vector& pong_frame, int64_t pong_sent_ns) -{ - // PONG payload: ping_sent, ping_received, pong_sent (i64 each). - constexpr size_t kPongSentOffset = kHeaderSize + 2 * sizeof(int64_t); - if (pong_frame.size() != kHeaderSize + 3 * sizeof(int64_t) || decode_header(pong_frame).type != FrameType::Pong) - { - throw std::invalid_argument("protocol: not an encoded PONG frame"); - } - detail::store_le(pong_frame.data() + kPongSentOffset, pong_sent_ns); -} - Hello decode_hello(std::span payload) { return parse_payload(payload, "HELLO", [](Reader& reader) { Hello value; - if (const uint16_t version = reader.u16(); version != kHelloVersion) - { - throw DecodeError("protocol: unsupported HELLO version " + std::to_string(version)); - } value.app_name = reader.str(); value.requirements.schema_push = reader.boolean(); value.requirements.hand_tracking_push = reader.boolean(); @@ -336,7 +301,7 @@ WristSample decode_wrist_sample(std::span payload) { WristSample value; value.sample_time_local_common_clock_ns = reader.i64(); - value.hand = reader.boolean() ? XR_HAND_LEFT_EXT : XR_HAND_RIGHT_EXT; + value.hand = from_wire_hand(reader.u8()); value.sample.valid = reader.boolean(); value.sample.tracked = reader.boolean(); value.sample.pose = reader.pose(); @@ -349,11 +314,6 @@ std::string decode_error(std::span payload) return parse_payload(payload, "ERROR", [](Reader& reader) { return reader.str(); }); } -int64_t decode_ping(std::span payload) -{ - return parse_payload(payload, "PING", [](Reader& reader) { return reader.i64(); }); -} - Pong decode_pong(std::span payload) { return parse_payload(payload, "PONG", @@ -362,7 +322,6 @@ Pong decode_pong(std::span payload) Pong value; value.ping_sent_ns = reader.i64(); value.ping_received_ns = reader.i64(); - value.pong_sent_ns = reader.i64(); return value; }); } diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 91452b7222..a1ce87648d 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -125,10 +125,16 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit bytes[protocol::kTypeOffset] = 200; REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } - SECTION("other protocol versions are rejected") + SECTION("other protocol versions are rejected, naming both versions") { - bytes[protocol::kVersionOffset] = 1; - REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); + for (const uint8_t version : { 0, 2 }) + { + bytes[protocol::kVersionOffset] = version; + REQUIRE_THROWS_WITH( + protocol::decode_header({ bytes, protocol::kHeaderSize }), + Catch::Matchers::ContainsSubstring("peer speaks protocol version " + std::to_string(version) + + ", this build speaks version 1")); + } } SECTION("oversized payloads are rejected") { @@ -137,17 +143,35 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit } } +TEST_CASE("A version-0 peer's frames are rejected by version, never decoded", "[remote_device_bridge][unit]") +{ + // HELLO v2 inside a version-0 header, as the previous wire format sent it, and a version-0 PONG (type 14 there). + std::vector old_hello = { 0x52, 0x50, 0x53, 0x30, 1, 0, 0, 0, 0, 0, 0, 0, 9, 0, 0, 0 }; + old_hello.resize(protocol::kHeaderSize, 0); + for (const uint8_t b : { 2, 0, 0, 0, 0, 0, 0, 0, 0 }) + { + old_hello.push_back(b); // version u16 = 2, empty app_name, three false flags + } + REQUIRE_THROWS_WITH( + protocol::split_frame(old_hello), + Catch::Matchers::ContainsSubstring("peer speaks protocol version 0, this build speaks version 1")); + + std::vector old_pong = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0, 0, 0, 0, 0, 0, 24, 0, 0, 0 }; + old_pong.resize(protocol::kHeaderSize + 24, 0); + REQUIRE_THROWS_WITH(protocol::split_frame(old_pong), Catch::Matchers::ContainsSubstring("protocol version 0")); +} + TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device_bridge][unit]") { - // Frame type numbers are part of the wire contract; 6 is unassigned. + // Frame type numbers are part of the wire contract. const std::vector> contract = { - { protocol::FrameType::Hello, 1 }, { protocol::FrameType::HelloAck, 2 }, - { protocol::FrameType::OpenHand, 3 }, { protocol::FrameType::OpenSchema, 4 }, - { protocol::FrameType::OpenPull, 5 }, { protocol::FrameType::Close, 7 }, - { protocol::FrameType::HandSample, 8 }, { protocol::FrameType::SchemaSample, 9 }, - { protocol::FrameType::WristSample, 10 }, { protocol::FrameType::Heartbeat, 11 }, - { protocol::FrameType::Error, 12 }, { protocol::FrameType::Ping, 13 }, - { protocol::FrameType::Pong, 14 }, + { protocol::FrameType::Hello, 1 }, { protocol::FrameType::HelloAck, 2 }, + { protocol::FrameType::OpenHand, 3 }, { protocol::FrameType::OpenSchema, 4 }, + { protocol::FrameType::OpenPull, 5 }, { protocol::FrameType::Close, 6 }, + { protocol::FrameType::HandSample, 7 }, { protocol::FrameType::SchemaSample, 8 }, + { protocol::FrameType::WristSample, 9 }, { protocol::FrameType::Heartbeat, 10 }, + { protocol::FrameType::Error, 11 }, { protocol::FrameType::Ping, 12 }, + { protocol::FrameType::Pong, 13 }, }; for (const auto& [type, number] : contract) { @@ -155,14 +179,14 @@ TEST_CASE("Wire contract is 13 frame types in a 24-byte header", "[remote_device } // magic u32 @0, type u8 @4, version u8 @5, channel u16 @6, seq u32 @8, payload size u32 @12, t_send i64 @16. - std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, 0x0A0B, std::vector(24, 0)); + std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, 0x0A0B, std::vector(16, 0)); protocol::stamp_header(frame, 0x0C0D0E0F, 0x1112131415161718LL); - const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, - 24, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; + const std::vector expected = { 0x52, 0x50, 0x53, 0x30, 13, 1, 0x0B, 0x0A, 0x0F, 0x0E, 0x0D, 0x0C, + 16, 0, 0, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11 }; REQUIRE(std::vector(frame.begin(), frame.begin() + protocol::kHeaderSize) == expected); uint8_t* bytes = frame.data(); - for (const uint8_t type : { 0, 6, 15 }) + for (const uint8_t type : { 0, 14 }) { bytes[protocol::kTypeOffset] = type; REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); @@ -191,10 +215,6 @@ TEST_CASE("HELLO and HELLO_ACK round-trip", "[remote_device_bridge][unit]") hello.requirements.wrist_tracking_pull.reset(); REQUIRE_FALSE(protocol::decode_hello(protocol::encode_hello(hello)).requirements.wrist_tracking_pull); - std::vector old_version = protocol::encode_hello(hello); - old_version[0] = 1; // HELLO version u16 leads the payload - REQUIRE_THROWS_AS(protocol::decode_hello(old_version), protocol::DecodeError); - const protocol::HelloAck ack = protocol::decode_hello_ack(protocol::encode_hello_ack(protocol::HelloAck{ false, "no runtime" })); REQUIRE_FALSE(ack.accepted); @@ -242,8 +262,8 @@ TEST_CASE("HELLO rejects an unknown wrist source mode", "[remote_device_bridge][ .left_aim_to_wrist = make_pose(0.1f), .right_aim_to_wrist = make_pose(0.7f) }; std::vector bytes = protocol::encode_hello(hello); - // version u16, app_name (u32 length, empty), three flags, then the wrist mode byte. - const size_t mode_offset = sizeof(uint16_t) + sizeof(uint32_t) + 3; + // app_name (u32 length, empty), three flags, then the wrist mode byte. + const size_t mode_offset = sizeof(uint32_t) + 3; REQUIRE(bytes[mode_offset] == 0); bytes[mode_offset] = 7; REQUIRE_THROWS_AS(protocol::decode_hello(bytes), protocol::DecodeError); @@ -310,7 +330,7 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") const std::vector bytes = protocol::encode_wrist_sample(sample); REQUIRE(bytes.size() == kWristSamplePayloadSize); - REQUIRE(bytes[kWristHandOffset] == 0); // 1 = left, 0 = right + REQUIRE(bytes[kWristHandOffset] == 1); // 0 = left, 1 = right, as in OPEN_HAND const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); REQUIRE(decoded.sample_time_local_common_clock_ns == -5); REQUIRE(decoded.hand == XR_HAND_RIGHT_EXT); @@ -330,38 +350,28 @@ TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_b REQUIRE_THROWS_AS(protocol::decode_error(bytes_of({ 4, 0, 0, 0, 'a' })), protocol::DecodeError); } -TEST_CASE("PING and PONG round-trip and PONG records its send time", "[remote_device_bridge][unit]") +TEST_CASE("PONG carries the PING send time and receive time; send times live in headers", "[remote_device_bridge][unit]") { - const std::vector ping = protocol::encode_ping(-123456789012345LL); - REQUIRE(ping.size() == 8); - REQUIRE(protocol::decode_ping(ping) == -123456789012345LL); - REQUIRE_THROWS_AS(protocol::decode_ping(bytes_of({ 1, 2, 3 })), protocol::DecodeError); - - const std::vector payload = protocol::encode_pong(protocol::Pong{ 1, 2, 3 }); - REQUIRE(payload.size() == 24); + const std::vector payload = protocol::encode_pong(protocol::Pong{ 1, 2 }); + REQUIRE(payload.size() == 2 * sizeof(int64_t)); const protocol::Pong pong = protocol::decode_pong(payload); REQUIRE(pong.ping_sent_ns == 1); REQUIRE(pong.ping_received_ns == 2); - REQUIRE(pong.pong_sent_ns == 3); - REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(25, 0)), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(17, 0)), protocol::DecodeError); + REQUIRE_THROWS_WITH(protocol::decode_pong(bytes_of({ 1 })), Catch::Matchers::ContainsSubstring("PONG")); + + // PING has no payload; each side's send time is the t_send stamped when the frame is written. + std::vector ping = protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, {}); + REQUIRE(ping.size() == protocol::kHeaderSize); + protocol::stamp_header(ping, 3, -123456789012345LL); + REQUIRE(protocol::split_frame(ping).header.t_send_monotonic_ns == -123456789012345LL); std::vector frame = protocol::encode_frame(protocol::FrameType::Pong, protocol::kSessionChannelId, payload); protocol::stamp_header(frame, 7, 0x0102030405060708LL); - REQUIRE(protocol::decode_pong(protocol::split_frame(frame).payload).pong_sent_ns == 3); // header only - protocol::set_pong_sent_time(frame, 0x0102030405060708LL); const protocol::Frame split = protocol::split_frame(frame); REQUIRE(split.header.type == protocol::FrameType::Pong); REQUIRE(split.header.t_send_monotonic_ns == 0x0102030405060708LL); - const protocol::Pong stamped = protocol::decode_pong(split.payload); - REQUIRE(stamped.ping_sent_ns == 1); - REQUIRE(stamped.ping_received_ns == 2); - REQUIRE(stamped.pong_sent_ns == 0x0102030405060708LL); - - std::vector ping_frame = - protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, ping); - REQUIRE_THROWS_AS(protocol::set_pong_sent_time(ping_frame, 42), std::invalid_argument); - REQUIRE_THROWS_WITH(protocol::decode_ping(bytes_of({ 1, 2, 3 })), Catch::Matchers::ContainsSubstring("PING")); - REQUIRE_THROWS_WITH(protocol::decode_pong(bytes_of({ 1 })), Catch::Matchers::ContainsSubstring("PONG")); + REQUIRE(split.payload == payload); } TEST_CASE("Contiguous frame builders match header + payload encoder byte for byte", "[remote_device_bridge][unit]") @@ -373,7 +383,7 @@ TEST_CASE("Contiguous frame builders match header + payload encoder byte for byt // clang-format off const std::vector golden = { 0x52, 0x50, 0x53, 0x30, // magic "RPS0" - 0x09, 0x00, // type SCHEMA_SAMPLE, version 0 + 0x08, 0x01, // type SCHEMA_SAMPLE, version 1 0x03, 0x00, // channel 3 0x00, 0x00, 0x00, 0x00, // seq (unstamped) 0x16, 0x00, 0x00, 0x00, // payload_size 22 From d9960ff75225458700a377460d29e1892797eaa5 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:21:18 -0800 Subject: [PATCH 15/18] build(remote_device_bridge): option text says what this PR builds; codec is not skipped on Windows (pr01) The codec is portable C++ with no sockets; the WIN32 skip arrives with the POSIX socket code. The option default is unchanged. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- CMakeLists.txt | 2 +- src/plugins/remote_device_bridge/CMakeLists.txt | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0099554bbf..afc7ca3ee9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -71,7 +71,7 @@ option(BUILD_PLUGIN_NOITOM_MOCAP "Build Noitom mocap plugin (downloads MocapApi option(BUILD_PLUGIN_OGLO "Build OGLO tactile glove plugin (BLE, Linux only; fetches SimpleBLE + nlohmann/json)" OFF) option(BUILD_PLUGIN_WUJI_GLOVE "Build Wuji glove plugin (requires the wuji_sdk C SDK)" OFF) option(BUILD_PLUGIN_SHARPA_AVATAR "Build Sharpa AvatarExo Glove plugin (Linux; skips if the Avatar SDK is missing)" OFF) -option(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE "Build the remote device bridge, RemotePluginSession library and synthetic sender (POSIX sockets; skipped on Windows)" ON) +option(BUILD_PLUGIN_REMOTE_DEVICE_BRIDGE "Build the remote device bridge wire codec library (Teleop::remote_plugin_session)" ON) option(BUILD_EXAMPLES "Build examples" ON) option(BUILD_EXAMPLE_TELEOP_ROS2 "Build only the teleop_ros2 ROS 2 reference integration (e.g. for Docker)" OFF) option(BUILD_TESTING "Build unit tests" ON) diff --git a/src/plugins/remote_device_bridge/CMakeLists.txt b/src/plugins/remote_device_bridge/CMakeLists.txt index 5f3f9d8038..0fe27f4c7a 100644 --- a/src/plugins/remote_device_bridge/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/CMakeLists.txt @@ -3,8 +3,4 @@ cmake_minimum_required(VERSION 3.20) -if(WIN32) - return() -endif() - add_subdirectory(session) From ef1608367760ac9d992f9b3f2edb523d412fd4cb Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:27:09 -0800 Subject: [PATCH 16/18] feat(remote_device_bridge): frame_payload_size for framing of any version (pr01) Transports only need the payload size to cut frames. frame_payload_size checks the magic and the payload limit, which sit at the same offsets in every version, and leaves version and type to decode_header, so a frame from an old peer reaches the decoder and fails with the readable version reason instead of a bare malformed-transport result. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_frame.hpp | 6 ++++++ .../session/protocol_frame.cpp | 20 +++++++++++++++++++ .../remote_device_bridge/test_wire_codec.cpp | 14 +++++++++++++ 3 files changed, 40 insertions(+) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 68962dcd0e..873ebfc2c8 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -77,6 +77,12 @@ class DecodeError : public std::runtime_error //! payload; and if `in` ends before a field it reads. FrameHeader decode_header(std::span in); +//! What framing needs: the payload size from the first kHeaderSize bytes of `in`, checking only the magic and the +//! payload limit, which sit at the same offsets in every protocol version. Version and type are left to +//! decode_header, so a frame from another version still reaches the decoder and fails there with a readable reason. +//! Throws DecodeError if `in` is shorter than a header, on bad magic or an oversized payload. +uint32_t frame_payload_size(std::span in); + //! Writes header + payload into one contiguous buffer. seq and t_send stay zero until stamp_header(), which the //! sender calls at the moment it writes the frame: t_send is the send time PING/PONG clock exchanges use. std::vector encode_frame(FrameType type, uint16_t channel_id, std::span payload); diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index af5ca9b7de..6aea418270 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -88,6 +88,26 @@ std::vector encode_frame(FrameType type, uint16_t channel_id, std::span return build_frame(type, channel_id, payload.size(), [payload](Writer& writer) { writer.bytes(payload); }); } +uint32_t frame_payload_size(std::span in) +{ + Reader reader(in, "header"); + if (reader.u32() != kMagic) + { + throw DecodeError("protocol: bad frame magic"); + } + reader.u8(); // type + reader.u8(); // version + reader.u16(); // channel + reader.u32(); // seq + const uint32_t payload_size = reader.u32(); + reader.i64(); // t_send: the whole header must be there + if (payload_size > kMaxPayloadSize) + { + throw DecodeError("protocol: payload size " + std::to_string(payload_size) + " exceeds limit"); + } + return payload_size; +} + FrameHeader decode_header(std::span in) { Reader reader(in, "header"); diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index a1ce87648d..723da9372e 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -140,6 +140,17 @@ TEST_CASE("Frame header round-trips and validates", "[remote_device_bridge][unit { std::memset(bytes + protocol::kPayloadSizeOffset, 0xFF, sizeof(uint32_t)); REQUIRE_THROWS_AS(protocol::decode_header({ bytes, protocol::kHeaderSize }), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::frame_payload_size({ bytes, protocol::kHeaderSize }), protocol::DecodeError); + } + SECTION("framing reads the size and checks only magic and limit") + { + REQUIRE(protocol::frame_payload_size({ bytes, protocol::kHeaderSize }) == protocol::kHandSamplePayloadSize); + bytes[protocol::kTypeOffset] = 200; + bytes[protocol::kVersionOffset] = 0; + REQUIRE(protocol::frame_payload_size({ bytes, protocol::kHeaderSize }) == protocol::kHandSamplePayloadSize); + REQUIRE_THROWS_AS(protocol::frame_payload_size({ bytes, protocol::kHeaderSize - 1 }), protocol::DecodeError); + bytes[0] ^= 0xFF; + REQUIRE_THROWS_AS(protocol::frame_payload_size({ bytes, protocol::kHeaderSize }), protocol::DecodeError); } } @@ -158,6 +169,9 @@ TEST_CASE("A version-0 peer's frames are rejected by version, never decoded", "[ std::vector old_pong = { 0x52, 0x50, 0x53, 0x30, 14, 0, 0, 0, 0, 0, 0, 0, 24, 0, 0, 0 }; old_pong.resize(protocol::kHeaderSize + 24, 0); + // Framing still finds both frames' lengths, so a transport delivers them to the decoder above. + REQUIRE(protocol::frame_payload_size(old_hello) == 9); + REQUIRE(protocol::frame_payload_size(old_pong) == 24); REQUIRE_THROWS_WITH(protocol::split_frame(old_pong), Catch::Matchers::ContainsSubstring("protocol version 0")); } From 461a20fa9c5bb64ac0b354965a7e0687050b7d49 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:38:44 -0800 Subject: [PATCH 17/18] review gate round 1 (pr01) - protocol_frame.hpp: describe kProtocolVersion as versioning the whole format - decode_header reuses frame_payload_size for length, magic and payload limit - Reader keeps its std::span instead of a pointer + size - kWristSamplePayloadSize lives in protocol_payloads.hpp next to its siblings - HAND_SAMPLE test loop uses size_t No wire value or existing symbol changed. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_plugin_session/protocol_frame.hpp | 10 +++++----- .../protocol_payloads.hpp | 3 +++ .../session/protocol_frame.cpp | 16 +++++----------- .../session/protocol_io.hpp | 18 +++++++++--------- .../remote_device_bridge/test_wire_codec.cpp | 11 +++++------ 5 files changed, 27 insertions(+), 31 deletions(-) diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp index 873ebfc2c8..c727e0cdb8 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_frame.hpp @@ -15,9 +15,9 @@ namespace remote_plugin_protocol /*! * Remote plugin protocol v1: fixed little-endian frames over one connection per * plugin session. Frame = header + payload; payload layouts live in - * protocol_payloads.hpp. kProtocolVersion is the only version number: any change + * protocol_payloads.hpp. kProtocolVersion versions the whole format: any change * to a header, payload or frame type number bumps it, and decode_header rejects - * every other version before it reads anything else. + * every other version before it reads the type or anything after it. */ constexpr uint32_t kMagic = 0x30535052u; // "RPS0" @@ -72,9 +72,9 @@ class DecodeError : public std::runtime_error using std::runtime_error::runtime_error; }; -//! Reads the header from the first kHeaderSize bytes of `in`. Throws DecodeError, in the order the fields are read: -//! bad magic, another protocol version (checked before the type byte is interpreted), unknown type, oversized -//! payload; and if `in` ends before a field it reads. +//! Reads the header from the first kHeaderSize bytes of `in`. Throws DecodeError, checking in this order: `in` +//! shorter than a header, bad magic, oversized payload, another protocol version, unknown type. The version is +//! checked before the type byte is interpreted, since another version may number its frame types differently. FrameHeader decode_header(std::span in); //! What framing needs: the payload size from the first kHeaderSize bytes of `in`, checking only the magic and the diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 9c6133eb0a..0fbe6b595d 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -67,11 +67,14 @@ struct Pong constexpr size_t kPoseSize = 7 * sizeof(float); constexpr size_t kJointSize = sizeof(uint64_t) + kPoseSize + sizeof(float); constexpr size_t kHandSamplePayloadSize = sizeof(int64_t) + XR_HAND_JOINT_COUNT_EXT * kJointSize; +//! WRIST_SAMPLE payload: sample time i64, hand u8, valid u8, tracked u8, pose. +constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + kPoseSize; //! SCHEMA_SAMPLE payload before the schema bytes: two sample times (i64) and the byte count (u32). constexpr size_t kSchemaSampleFixedSize = 2 * sizeof(int64_t) + sizeof(uint32_t); static_assert(kJointSize == 40); static_assert(kHandSamplePayloadSize == 1048); +static_assert(kWristSamplePayloadSize == 39); static_assert(kSchemaSampleFixedSize == 20); //! One hand's joints, as IHandTrackingPushChannel::push receives them. diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index 6aea418270..bd40fc9b1a 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -110,14 +110,12 @@ uint32_t frame_payload_size(std::span in) FrameHeader decode_header(std::span in) { - Reader reader(in, "header"); - if (reader.u32() != kMagic) - { - throw DecodeError("protocol: bad frame magic"); - } FrameHeader header; + header.payload_size = frame_payload_size(in); // length, magic and payload limit + Reader reader(in, "header"); + reader.u32(); // magic const uint8_t type = reader.u8(); - // Version before type: frame type numbers differ between versions. + // Version before type: another version may number its frame types differently. if (const uint8_t version = reader.u8(); version != kProtocolVersion) { throw DecodeError("protocol: peer speaks protocol version " + std::to_string(version) + @@ -131,11 +129,7 @@ FrameHeader decode_header(std::span in) header.type = static_cast(type); header.channel_id = reader.u16(); header.seq = reader.u32(); - header.payload_size = reader.u32(); - if (header.payload_size > kMaxPayloadSize) - { - throw DecodeError("protocol: payload size " + std::to_string(header.payload_size) + " exceeds limit"); - } + reader.u32(); // payload size, read above header.t_send_monotonic_ns = reader.i64(); return header; } diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index ccacac5ec3..ed35c7815e 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -136,7 +136,7 @@ class Reader { public: //! `what` names the frame or header being read in DecodeError messages. - Reader(std::span data, const char* what) : m_data(data.data()), m_size(data.size()), m_what(what) + Reader(std::span data, const char* what) : m_data(data), m_what(what) { } @@ -188,7 +188,7 @@ class Reader { const uint32_t size = u32(); need(size); - std::string value(reinterpret_cast(m_data + m_pos), size); + std::string value(reinterpret_cast(m_data.data() + m_pos), size); m_pos += size; return value; } @@ -196,7 +196,8 @@ class Reader std::vector bytes(size_t size) { need(size); - std::vector value(m_data + m_pos, m_data + m_pos + size); + const auto field = m_data.subspan(m_pos, size); + std::vector value(field.begin(), field.end()); m_pos += size; return value; } @@ -216,9 +217,9 @@ class Reader void finish() const { - if (m_pos != m_size) + if (m_pos != m_data.size()) { - throw DecodeError(std::string("protocol: ") + m_what + ": " + std::to_string(m_size - m_pos) + + throw DecodeError(std::string("protocol: ") + m_what + ": " + std::to_string(m_data.size() - m_pos) + " trailing bytes"); } } @@ -228,21 +229,20 @@ class Reader T take() { need(sizeof(T)); - const T value = load_le(m_data + m_pos); + const T value = load_le(m_data.data() + m_pos); m_pos += sizeof(T); return value; } void need(size_t count) const { - if (m_size - m_pos < count) + if (m_data.size() - m_pos < count) { throw DecodeError(std::string("protocol: ") + m_what + ": truncated"); } } - const uint8_t* m_data; - size_t m_size; + std::span m_data; const char* m_what; size_t m_pos = 0; }; diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index 723da9372e..c7f74066a9 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -19,7 +19,6 @@ namespace protocol = remote_plugin_protocol; namespace { -constexpr size_t kWristSamplePayloadSize = sizeof(int64_t) + 3 * sizeof(uint8_t) + protocol::kPoseSize; //! WRIST_SAMPLE payload: sample_time i64, then the hand byte, then `valid`. constexpr size_t kWristHandOffset = sizeof(int64_t); constexpr size_t kWristValidOffset = kWristHandOffset + sizeof(uint8_t); @@ -287,11 +286,11 @@ TEST_CASE("HAND_SAMPLE is a bit-exact copy of 26 joints", "[remote_device_bridge { protocol::HandSample sample; sample.sample_time_local_common_clock_ns = 987654321012345LL; - for (int i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) + for (size_t i = 0; i < XR_HAND_JOINT_COUNT_EXT; ++i) { - sample.joints[static_cast(i)].locationFlags = 0xF000000000000000ULL | static_cast(i); - sample.joints[static_cast(i)].pose = make_pose(0.01f * static_cast(i + 1)); - sample.joints[static_cast(i)].radius = 0.001f * static_cast(i); + sample.joints[i].locationFlags = 0xF000000000000000ULL | i; + sample.joints[i].pose = make_pose(0.01f * static_cast(i + 1)); + sample.joints[i].radius = 0.001f * static_cast(i); } const std::vector bytes = hand_payload(sample); @@ -343,7 +342,7 @@ TEST_CASE("WRIST_SAMPLE round-trips", "[remote_device_bridge][unit]") sample.sample.pose = make_pose(0.3f); const std::vector bytes = protocol::encode_wrist_sample(sample); - REQUIRE(bytes.size() == kWristSamplePayloadSize); + REQUIRE(bytes.size() == protocol::kWristSamplePayloadSize); REQUIRE(bytes[kWristHandOffset] == 1); // 0 = left, 1 = right, as in OPEN_HAND const protocol::WristSample decoded = protocol::decode_wrist_sample(bytes); REQUIRE(decoded.sample_time_local_common_clock_ns == -5); From 930914faa2bf7a36159ae9d9d0db2b2da97e9cc7 Mon Sep 17 00:00:00 2001 From: Jonghyun Kim Date: Wed, 18 Nov 2026 15:44:59 -0800 Subject: [PATCH 18/18] review gate round 2 (pr01) - drop cmake_minimum_required from the two nested CMakeLists - frame_payload_size and decode_header read the header by the named offsets, once, instead of re-reading it sequentially - the 'only built this way' comment names HAND_SAMPLE and SCHEMA_SAMPLE - remove the unused Writer::u16, Reader::u16 and the bytes_of test helper No wire value or existing symbol used above changed. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Jonghyun Kim --- .../remote_device_bridge/CMakeLists.txt | 2 -- .../session/CMakeLists.txt | 2 -- .../protocol_payloads.hpp | 3 +- .../session/protocol_frame.cpp | 29 ++++++++----------- .../session/protocol_io.hpp | 10 ------- .../remote_device_bridge/test_wire_codec.cpp | 20 +++++-------- 6 files changed, 21 insertions(+), 45 deletions(-) diff --git a/src/plugins/remote_device_bridge/CMakeLists.txt b/src/plugins/remote_device_bridge/CMakeLists.txt index 0fe27f4c7a..f7c312b75a 100644 --- a/src/plugins/remote_device_bridge/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/CMakeLists.txt @@ -1,6 +1,4 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -cmake_minimum_required(VERSION 3.20) - add_subdirectory(session) diff --git a/src/plugins/remote_device_bridge/session/CMakeLists.txt b/src/plugins/remote_device_bridge/session/CMakeLists.txt index 676dad270a..c2f76d671f 100644 --- a/src/plugins/remote_device_bridge/session/CMakeLists.txt +++ b/src/plugins/remote_device_bridge/session/CMakeLists.txt @@ -1,8 +1,6 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -cmake_minimum_required(VERSION 3.20) - add_library(remote_plugin_session STATIC protocol_frame.cpp protocol_payloads.cpp diff --git a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp index 0fbe6b595d..05558c02f9 100644 --- a/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp +++ b/src/plugins/remote_device_bridge/session/inc/remote_plugin_session/protocol_payloads.hpp @@ -89,7 +89,8 @@ std::vector encode_wrist_sample(const WristSample& value); std::vector encode_error(const std::string& message); std::vector encode_pong(const Pong& value); -// Sample frames are only built this way: the builders read the plugin's buffers directly so a push copies once. +// HAND_SAMPLE and SCHEMA_SAMPLE frames are only built this way: the builders read the plugin's buffers directly so a +// push copies once. std::vector encode_hand_sample_frame(uint16_t channel_id, HandJoints joints, int64_t sample_time_local_common_clock_ns); diff --git a/src/plugins/remote_device_bridge/session/protocol_frame.cpp b/src/plugins/remote_device_bridge/session/protocol_frame.cpp index bd40fc9b1a..57f06bd9af 100644 --- a/src/plugins/remote_device_bridge/session/protocol_frame.cpp +++ b/src/plugins/remote_device_bridge/session/protocol_frame.cpp @@ -13,7 +13,7 @@ namespace remote_plugin_protocol { using detail::build_frame; -using detail::Reader; +using detail::load_le; using detail::store_le; using detail::Writer; @@ -90,17 +90,15 @@ std::vector encode_frame(FrameType type, uint16_t channel_id, std::span uint32_t frame_payload_size(std::span in) { - Reader reader(in, "header"); - if (reader.u32() != kMagic) + if (in.size() < kHeaderSize) + { + throw DecodeError("protocol: header: truncated"); + } + if (load_le(in.data()) != kMagic) { throw DecodeError("protocol: bad frame magic"); } - reader.u8(); // type - reader.u8(); // version - reader.u16(); // channel - reader.u32(); // seq - const uint32_t payload_size = reader.u32(); - reader.i64(); // t_send: the whole header must be there + const auto payload_size = load_le(in.data() + kPayloadSizeOffset); if (payload_size > kMaxPayloadSize) { throw DecodeError("protocol: payload size " + std::to_string(payload_size) + " exceeds limit"); @@ -112,25 +110,22 @@ FrameHeader decode_header(std::span in) { FrameHeader header; header.payload_size = frame_payload_size(in); // length, magic and payload limit - Reader reader(in, "header"); - reader.u32(); // magic - const uint8_t type = reader.u8(); // Version before type: another version may number its frame types differently. - if (const uint8_t version = reader.u8(); version != kProtocolVersion) + if (const uint8_t version = in[kVersionOffset]; version != kProtocolVersion) { throw DecodeError("protocol: peer speaks protocol version " + std::to_string(version) + ", this build speaks version " + std::to_string(kProtocolVersion) + "; rebuild the sender and the bridge from the same source"); } + const uint8_t type = in[kTypeOffset]; if (!is_frame_type(type)) { throw DecodeError("protocol: unknown frame type " + std::to_string(type)); } header.type = static_cast(type); - header.channel_id = reader.u16(); - header.seq = reader.u32(); - reader.u32(); // payload size, read above - header.t_send_monotonic_ns = reader.i64(); + header.channel_id = load_le(in.data() + kChannelOffset); + header.seq = load_le(in.data() + kSeqOffset); + header.t_send_monotonic_ns = load_le(in.data() + kSendTimeOffset); return header; } diff --git a/src/plugins/remote_device_bridge/session/protocol_io.hpp b/src/plugins/remote_device_bridge/session/protocol_io.hpp index ed35c7815e..b8163f6b61 100644 --- a/src/plugins/remote_device_bridge/session/protocol_io.hpp +++ b/src/plugins/remote_device_bridge/session/protocol_io.hpp @@ -67,11 +67,6 @@ class Writer u8(value ? 1 : 0); } - void u16(uint16_t value) - { - append(value); - } - void u32(uint32_t value) { append(value); @@ -156,11 +151,6 @@ class Reader return value == 1; } - uint16_t u16() - { - return take(); - } - uint32_t u32() { return take(); diff --git a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp index c7f74066a9..be5feb9c84 100644 --- a/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp +++ b/tests/cpp/plugins/remote_device_bridge/test_wire_codec.cpp @@ -9,7 +9,6 @@ #include #include #include -#include #include #include #include @@ -25,11 +24,6 @@ constexpr size_t kWristValidOffset = kWristHandOffset + sizeof(uint8_t); //! SCHEMA_SAMPLE payload: two i64 sample times, then the u32 byte count. constexpr size_t kSchemaByteCountOffset = 2 * sizeof(int64_t); -std::vector bytes_of(std::initializer_list values) -{ - return values; -} - bool same_pose(const XrPosef& a, const XrPosef& b) { return std::memcmp(&a, &b, sizeof(XrPosef)) == 0; @@ -242,11 +236,11 @@ TEST_CASE("OPEN_HAND encodes both hands and rejects others", "[remote_device_bri { REQUIRE(protocol::encode_open_hand(XR_HAND_LEFT_EXT) == std::vector{ 0 }); REQUIRE(protocol::encode_open_hand(XR_HAND_RIGHT_EXT) == std::vector{ 1 }); - REQUIRE(protocol::decode_open_hand(bytes_of({ 0 })) == XR_HAND_LEFT_EXT); - REQUIRE(protocol::decode_open_hand(bytes_of({ 1 })) == XR_HAND_RIGHT_EXT); - REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({ 2 })), protocol::DecodeError); - REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({})), protocol::DecodeError); - REQUIRE_THROWS_AS(protocol::decode_open_hand(bytes_of({ 0, 0 })), protocol::DecodeError); + REQUIRE(protocol::decode_open_hand(std::vector{ 0 }) == XR_HAND_LEFT_EXT); + REQUIRE(protocol::decode_open_hand(std::vector{ 1 }) == XR_HAND_RIGHT_EXT); + REQUIRE_THROWS_AS(protocol::decode_open_hand(std::vector{ 2 }), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand(std::vector{}), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_open_hand(std::vector{ 0, 0 }), protocol::DecodeError); } TEST_CASE("OPEN_SCHEMA round-trips SchemaPusherConfig", "[remote_device_bridge][unit]") @@ -360,7 +354,7 @@ TEST_CASE("ERROR carries a message and empty payloads decode", "[remote_device_b { REQUIRE(protocol::decode_error(protocol::encode_error("boom")) == "boom"); REQUIRE(protocol::decode_error(protocol::encode_error("")).empty()); - REQUIRE_THROWS_AS(protocol::decode_error(bytes_of({ 4, 0, 0, 0, 'a' })), protocol::DecodeError); + REQUIRE_THROWS_AS(protocol::decode_error(std::vector{ 4, 0, 0, 0, 'a' }), protocol::DecodeError); } TEST_CASE("PONG carries the PING send time and receive time; send times live in headers", "[remote_device_bridge][unit]") @@ -371,7 +365,7 @@ TEST_CASE("PONG carries the PING send time and receive time; send times live in REQUIRE(pong.ping_sent_ns == 1); REQUIRE(pong.ping_received_ns == 2); REQUIRE_THROWS_AS(protocol::decode_pong(std::vector(17, 0)), protocol::DecodeError); - REQUIRE_THROWS_WITH(protocol::decode_pong(bytes_of({ 1 })), Catch::Matchers::ContainsSubstring("PONG")); + REQUIRE_THROWS_WITH(protocol::decode_pong(std::vector{ 1 }), Catch::Matchers::ContainsSubstring("PONG")); // PING has no payload; each side's send time is the t_send stamped when the frame is written. std::vector ping = protocol::encode_frame(protocol::FrameType::Ping, protocol::kSessionChannelId, {});