Stream Switch Pro reports on Windows

Cache the latest native Switch Pro input report in the Windows backend and resend it every 15 ms to match the controller's native 0x30 report cadence. This coalesces separate motion updates, adjusts HID consumer tests to match reports by type instead of exact packet counters, and updates the related Windows support documentation.

Author: ReenigneArcher

docs/end-user-gamepad-guide.md

@@ -86,6 +86,10 @@ uses the `0x0210` hardware revision reported by a physical Nintendo controller,
 and the Windows VHF device exposes that revision to HID consumers. Full-state
 and subcommand-reply reports use the same per-device packet counter on Windows,
 matching the counter that a native controller advances for every input report.
+The Windows client backend caches the newest complete Switch Pro state and
+streams native `0x30` reports every 15 milliseconds. This coalesces separate
+acceleration and gyroscope API updates into the three-sample report cadence used
+by a physical USB controller.
 
 Windows VHF devices do not expose a Bluetooth transport identity to HIDAPI.
 The Windows backend therefore reports DualShock 4 and DualSense requests as

docs/platform-support.md

@@ -428,10 +428,13 @@ gamepad.
 DualShock 4 and DualSense answer the calibration, pairing, and firmware feature
 requests used by their Windows HIDAPI initialization paths. Switch Pro answers
 the native USB and subcommand handshake and submits native `0x30` input reports
-with three live IMU samples. Its Set Player Lights subcommand is normalized into
-solid and flashing player-indicator output states for the creating runtime, and
-its monochrome HOME light is normalized as equal RGB channels so existing
-streaming LED feedback paths can preserve its intensity.
+with three live IMU samples. The client backend caches the newest complete
+Switch state and submits it every 15 milliseconds, matching a physical USB
+controller's report cadence while coalescing separate acceleration and
+gyroscope updates. Its Set Player Lights subcommand is normalized into solid
+and flashing player-indicator output states for the creating runtime, and its
+monochrome HOME light is normalized as equal RGB channels so existing streaming
+LED feedback paths can preserve its intensity.
 The built-in Generic profile is presented to Windows as a DirectInput PID
 Joystick with the complete output-report set required for DirectInput
 enumeration. Constant Force and Sine output is normalized to the portable

docs/windows-driver.md

@@ -88,6 +88,8 @@ namespace lvh::detail {
     using SendInputFunction = std::function<UINT(std::span<INPUT>)>;
     using SyncThreadDesktopFunction = std::function<HDESK()>;
 
+    constexpr auto switch_pro_report_interval = std::chrono::milliseconds {15};
+
     /**
      * @brief Thread-local desktop identity used for SendInput retry decisions.
      */
@@ -956,13 +958,13 @@ namespace lvh::detail {
       OutputCallback output_callback;
       bool uses_generic_pid = false;
       windows::GenericPidRumbleState generic_pid_rumble;
+      std::vector<std::uint8_t> switch_pro_input_report;
     };
 
     class WindowsGamepad final: public BackendGamepad {
     public:
-      WindowsGamepad(std::shared_ptr<WindowsBackendContext> context, std::shared_ptr<WindowsVhfDeviceState> state):
-          context_ {std::move(context)},
-          state_ {std::move(state)} {}
+      WindowsGamepad(std::shared_ptr<WindowsBackendContext> context, std::shared_ptr<WindowsVhfDeviceState> state);
+      ~WindowsGamepad() override;
 
       OperationStatus submit(
         const GamepadState &state,
@@ -973,8 +975,14 @@ namespace lvh::detail {
       OperationStatus close() override;
 
     private:
+      void stream_switch_pro_reports(std::stop_token stop_token);
+      void stop_switch_pro_report_stream();
+
       std::shared_ptr<WindowsBackendContext> context_;
       std::shared_ptr<WindowsVhfDeviceState> state_;
+      std::condition_variable switch_pro_report_ready_;
+      std::mutex switch_pro_report_mutex_;
+      std::jthread switch_pro_report_thread_;
     };
 
     class WindowsBackendContext: public std::enable_shared_from_this<WindowsBackendContext> {
@@ -1294,6 +1302,66 @@ namespace lvh::detail {
       std::map<std::uint64_t, std::weak_ptr<WindowsVhfDeviceState>> devices_;
     };
 
+    WindowsGamepad::WindowsGamepad(
+      std::shared_ptr<WindowsBackendContext> context,
+      std::shared_ptr<WindowsVhfDeviceState> state
+    ):
+        context_ {std::move(context)},
+        state_ {std::move(state)} {
+      if (state_->profile.gamepad_kind == GamepadProfileKind::switch_pro) {
+        switch_pro_report_thread_ = std::jthread {[this](std::stop_token stop_token) {
+          stream_switch_pro_reports(stop_token);
+        }};
+      }
+    }
+
+    WindowsGamepad::~WindowsGamepad() {
+      stop_switch_pro_report_stream();
+    }
+
+    void WindowsGamepad::stream_switch_pro_reports(std::stop_token stop_token) {
+      auto next_report = std::chrono::steady_clock::now() + switch_pro_report_interval;
+      std::unique_lock report_lock {switch_pro_report_mutex_};
+      while (!stop_token.stop_requested()) {
+        static_cast<void>(switch_pro_report_ready_.wait_until(report_lock, next_report, [&stop_token] {
+          return stop_token.stop_requested();
+        }));
+        if (stop_token.stop_requested()) {
+          break;
+        }
+
+        report_lock.unlock();
+        std::vector<std::uint8_t> report;
+        {
+          std::lock_guard state_lock {state_->mutex_};
+          if (!state_->open) {
+            return;
+          }
+          report = state_->switch_pro_input_report;
+        }
+        if (!report.empty()) {
+          static_cast<void>(context_->submit_device_report(state_, report));
+        }
+        report_lock.lock();
+
+        next_report += switch_pro_report_interval;
+        const auto now = std::chrono::steady_clock::now();
+        if (next_report <= now) {
+          next_report = now + switch_pro_report_interval;
+        }
+      }
+    }
+
+    void WindowsGamepad::stop_switch_pro_report_stream() {
+      if (!switch_pro_report_thread_.joinable()) {
+        return;
+      }
+
+      switch_pro_report_thread_.request_stop();
+      switch_pro_report_ready_.notify_all();
+      switch_pro_report_thread_.join();
+    }
+
     OperationStatus WindowsGamepad::submit(
       const GamepadState & /*state*/,
       const std::vector<std::uint8_t> &report
@@ -1310,6 +1378,11 @@ namespace lvh::detail {
           return OperationStatus::failure(invalid_argument, "Windows gamepad input report exceeds protocol limit");
         }
 
+        if (state_->profile.gamepad_kind == GamepadProfileKind::switch_pro) {
+          state_->switch_pro_input_report = report;
+          return OperationStatus::success();
+        }
+
         if (state_->uses_generic_pid) {
           return context_->submit_device_report(state_, windows::make_generic_windows_input_report(report));
         }
@@ -1333,6 +1406,7 @@ namespace lvh::detail {
     }
 
     OperationStatus WindowsGamepad::close() {
+      stop_switch_pro_report_stream();
       return context_->close_device(state_);
     }
 

src/platform/windows/windows_backend.cpp

@@ -30,6 +30,15 @@ namespace lvh::detail::test {
     std::size_t destroy_requests = 0;
   };
 
+  struct WindowsSwitchReportStreamResult {
+    OperationStatus create_status;
+    OperationStatus submit_status;
+    OperationStatus close_status;
+    bool repeated_report = false;
+    std::vector<std::uint8_t> expected_report;
+    std::vector<std::vector<std::uint8_t>> submitted_reports;
+  };
+
   struct WindowsBackendFailureResult {
     OperationStatus invalid_argument_status;
     OperationStatus unsupported_profile_status;
@@ -239,6 +248,7 @@ namespace lvh::detail::test {
   };
 
   WindowsBackendLifecycleResult windows_backend_fake_channel_lifecycle();
+  WindowsSwitchReportStreamResult windows_backend_switch_report_stream();
   WindowsPlayStationTransportResult windows_backend_playstation_transport();
   WindowsGenericPidOrderingResult windows_backend_generic_pid_callback_ordering();
   WindowsHidKeyboardResult windows_backend_hid_keyboard();

tests/fixtures/include/fixtures/windows_backend_test_hooks.hpp

@@ -528,6 +528,29 @@ namespace lvh::detail {
       return result;
     }
 
+    WindowsSwitchReportStreamResult windows_backend_switch_report_stream() {
+      WindowsSwitchReportStreamResult result;
+      auto command_state = std::make_shared<FakeWindowsControlChannelState>();
+      auto backend = make_fake_windows_backend(command_state, std::make_shared<FakeWindowsControlChannelState>());
+
+      CreateGamepadOptions options;
+      options.profile = profiles::switch_pro();
+      auto created = backend->create_gamepad(8, options);
+      result.create_status = created.status;
+      if (created) {
+        result.expected_report.assign(options.profile.input_report_size, 0x5AU);
+        result.expected_report[0] = 0x30U;
+        result.submit_status = created.gamepad->submit({}, result.expected_report);
+        result.repeated_report = wait_until([&command_state] {
+          return command_state->submit_report_count() >= 2U;
+        });
+        result.close_status = created.gamepad->close();
+        result.submitted_reports = command_state->submit_reports();
+      }
+
+      return result;
+    }
+
     WindowsHidMouseResult windows_backend_hid_mouse() {
       using enum MouseEventKind;
 

tests/fixtures/windows_backend_test_hooks.cpp

@@ -105,6 +105,19 @@ TEST_F(WindowsBackendTest, FakeChannelExercisesLifecycleSubmitCloseAndOutput) {
   EXPECT_EQ(result.last_output.raw_report[0], 0x03U);
 }
 
+TEST_F(WindowsBackendTest, SwitchReportsStreamAtTheNativeCadence) {
+  const auto result = lvh::detail::test::windows_backend_switch_report_stream();
+
+  expect_ok(result.create_status);
+  expect_ok(result.submit_status);
+  ASSERT_TRUE(result.repeated_report);
+  expect_ok(result.close_status);
+  ASSERT_GE(result.submitted_reports.size(), 2U);
+  EXPECT_TRUE(std::ranges::all_of(result.submitted_reports, [&result](const auto &report) {
+    return report == result.expected_report;
+  }));
+}
+
 TEST_F(WindowsBackendTest, PlayStationDefaultsUseEffectiveUsbProfiles) {
   const auto result = lvh::detail::test::windows_backend_playstation_transport();
   const auto dualshock4_usb = lvh::profiles::dualshock4_usb();

tests/unit/test_windows_backend.cpp

@@ -320,6 +320,30 @@ namespace {
     return report;
   }
 
+  template<typename Predicate>
+  std::optional<std::vector<std::uint8_t>> read_hid_report_matching(
+    HANDLE hid,
+    std::size_t report_size,
+    std::chrono::milliseconds timeout,
+    Predicate predicate
+  ) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline) {
+      const auto remaining = std::chrono::duration_cast<std::chrono::milliseconds>(
+        deadline - std::chrono::steady_clock::now()
+      );
+      auto report = read_hid_report_with_timeout(hid, report_size, std::max(remaining, 1ms));
+      if (!report.has_value()) {
+        return std::nullopt;
+      }
+      if (predicate(*report)) {
+        return report;
+      }
+    }
+
+    return std::nullopt;
+  }
+
   HidInterfacePaths current_gamepad_interface_paths() {
     HidInterfacePaths paths;
     for (const auto &hid_interface : enumerate_gamepad_interfaces()) {
@@ -780,7 +804,14 @@ TEST_F(WindowsConsumerTest, NativeSwitchHandshakeAndInputReportReachHidClient) {
     )) << "Switch proprietary WriteFile failed: "
        << GetLastError();
     EXPECT_EQ(bytes_written, output.size());
-    return read_hid_report_with_timeout(reader.get(), hid_interface->input_report_size, 5s);
+    return read_hid_report_matching(
+      reader.get(),
+      hid_interface->input_report_size,
+      5s,
+      [command](const auto &report) {
+        return report.size() >= 2U && report[0] == 0x81U && report[1] == command;
+      }
+    );
   };
 
   const auto status_reply = send_proprietary_command(0x01);
@@ -854,11 +885,17 @@ TEST_F(WindowsConsumerTest, NativeSwitchHandshakeAndInputReportReachHidClient) {
      << GetLastError();
   ASSERT_EQ(bytes_written, player_lights_report.size());
 
-  const auto player_lights_reply = read_hid_report_with_timeout(reader.get(), hid_interface->input_report_size, 5s);
+  const auto player_lights_reply = read_hid_report_matching(
+    reader.get(),
+    hid_interface->input_report_size,
+    5s,
+    [](const auto &report) {
+      return report.size() >= 15U && report[0] == 0x21U && report[14] == 0x30U;
+    }
+  );
   ASSERT_TRUE(player_lights_reply.has_value()) << "No Switch player-light acknowledgement reached the HID client";
   ASSERT_GE(player_lights_reply->size(), 15U);
   EXPECT_EQ(player_lights_reply->at(0), 0x21U);
-  EXPECT_EQ(player_lights_reply->at(1), 0x00U);
   EXPECT_EQ(player_lights_reply->at(13), 0x80U);
   EXPECT_EQ(player_lights_reply->at(14), 0x30U);
 
@@ -881,11 +918,17 @@ TEST_F(WindowsConsumerTest, NativeSwitchHandshakeAndInputReportReachHidClient) {
   state.gyroscope = lvh::Vector3 {.x = 1.0F, .y = 2.0F, .z = -3.0F};
   ASSERT_TRUE(created.adapter->set_state(state).ok());
 
-  const auto input = read_hid_report_with_timeout(reader.get(), hid_interface->input_report_size, 5s);
+  const auto input = read_hid_report_matching(
+    reader.get(),
+    hid_interface->input_report_size,
+    5s,
+    [](const auto &report) {
+      return report.size() >= 6U && report[0] == 0x30U && report[3] == 0x08U && report[4] == 0x14U && report[5] == 0x08U;
+    }
+  );
   ASSERT_TRUE(input.has_value()) << "No native Switch 0x30 input report reached the HID client";
   ASSERT_EQ(input->size(), profile.input_report_size);
   EXPECT_EQ(input->at(0), 0x30U);
-  EXPECT_EQ(input->at(1), static_cast<std::uint8_t>(player_lights_reply->at(1) + 1U));
   EXPECT_EQ(input->at(3), 0x08U);  // Nintendo A in the native right-button byte.
   EXPECT_EQ(input->at(4), 0x14U);  // R3 and Home.
   EXPECT_EQ(input->at(5), 0x08U);  // D-pad left.
@@ -912,10 +955,17 @@ TEST_F(WindowsConsumerTest, NativeSwitchHandshakeAndInputReportReachHidClient) {
 
   state.gyroscope = lvh::Vector3 {.x = -4.0F, .y = 5.0F, .z = 6.0F};
   ASSERT_TRUE(created.adapter->set_state(state).ok());
-  const auto next_input = read_hid_report_with_timeout(reader.get(), hid_interface->input_report_size, 5s);
+  const auto next_input = read_hid_report_matching(
+    reader.get(),
+    hid_interface->input_report_size,
+    5s,
+    [&input](const auto &report) {
+      return report.size() > 19U && report[0] == 0x30U && report[19] != input->at(19);
+    }
+  );
   ASSERT_TRUE(next_input.has_value()) << "No second native Switch motion report reached the HID client";
   ASSERT_EQ(next_input->size(), profile.input_report_size);
-  EXPECT_EQ(next_input->at(1), static_cast<std::uint8_t>(input->at(1) + 1U));
+  EXPECT_NE(next_input->at(1), input->at(1));
   EXPECT_NE(next_input->at(19), input->at(19));
   ASSERT_TRUE(created.adapter->close().ok());
 }