Implementation:Facebookresearch Habitat lab ClientHelper

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Human_in_the_Loop
Last Updated	2026-02-15 00:00 GMT

Overview

ClientHelper tracks connected remote clients in a HITL networked application, monitoring display latency and automatically kicking idle clients after a configurable timeout.

Description

The ClientHelper class manages the lifecycle and health of remote client connections in the Habitat HITL networking layer. It registers callbacks for client connection and disconnection events, tracks per-user frame counters, computes display latency using an AverageHelper moving average, and enforces idle timeout policies.

When idle kick is active (configured via client_max_idle_duration), the helper monitors each user's last activity timestamp. It shows an idle warning when half the allowed idle time has elapsed, and disconnects (kicks) the user when the full duration is reached. The class also updates frame counters and computes display latency by comparing the most recent server keyframe ID acknowledged by the client against the current frame counter.

Usage

Use ClientHelper when building networked HITL applications that require tracking remote client state, displaying latency information, and managing idle user disconnection policies.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/core/client_helper.py
• Lines: 1-163

Signature

class ClientHelper:
    def __init__(
        self,
        hitl_config,
        remote_client_state,
        client_message_manager: ClientMessageManager,
        users: Users,
    ):
        ...

    def activate_users(self) -> None:
        ...

    def display_latency_ms(self, user_index: int) -> Optional[float]:
        ...

    def do_show_idle_kick_warning(self, user_index: int) -> Optional[bool]:
        ...

    def get_idle_time(self, user_index: int) -> int:
        ...

    def get_remaining_idle_time(self, user_index: int) -> int:
        ...

    def update(
        self, user_index: int, is_user_idle_this_frame: bool, server_sps: float
    ) -> None:
        ...

Import

from habitat_hitl.core.client_helper import ClientHelper

I/O Contract

Inputs

Name	Type	Required	Description
hitl_config	Config	Yes	HITL configuration object; must have networking.enable set to True and optionally networking.client_max_idle_duration.
remote_client_state	RemoteClientState	Yes	Remote client state manager that provides connection/disconnection callbacks and keyframe tracking.
client_message_manager	ClientMessageManager	Yes	Manager for sending messages (e.g., server keyframe IDs) to clients.
users	Users	Yes	User set that defines the maximum number of users.

Outputs

Name	Type	Description
display_latency_ms()	Optional[float]	The computed display latency in milliseconds for a given user.
do_show_idle_kick_warning()	Optional[bool]	Whether the idle kick warning should be displayed for a given user.
get_idle_time()	int	The current idle time in seconds for a given user.
get_remaining_idle_time()	int	The remaining time in seconds before the user will be kicked.

Usage Examples

Basic Usage

from habitat_hitl.core.client_helper import ClientHelper

# Initialize the client helper
client_helper = ClientHelper(
    hitl_config=hitl_config,
    remote_client_state=remote_client_state,
    client_message_manager=client_message_manager,
    users=users,
)

# Each frame, update for each connected user
for user_index in range(users.max_user_count):
    is_idle = not gui_input.get_any_input()
    client_helper.update(user_index, is_idle, server_sps=30.0)

    # Check latency
    latency = client_helper.display_latency_ms(user_index)
    if latency is not None:
        print(f"User {user_index} latency: {latency:.1f} ms")

    # Check if idle kick warning should be shown
    if client_helper.do_show_idle_kick_warning(user_index):
        remaining = client_helper.get_remaining_idle_time(user_index)
        print(f"User {user_index} will be kicked in {remaining}s")