ROS API Reference

The production mobile path uses the versioned hb2_api_bridge allowlist below. The historical /pat/* topics remain documented only for the legacy firmware/provider and are not reachable from the HB2 runtime.

HB2 public API (`hb2_api_bridge` 1.0)

Rosbridge is a WebSocket on port 9090. Advertise the five command topics before publishing and subscribe only to /hb2/app/status and /hb2/app/command_result. The Go robot-agent exposes a separate read-only HTTP identity/health API on port 8080.

Direction	Name	Type
Publish	`/hb2/app/heartbeat`	`hb2_api_bridge/Heartbeat`
Publish	`/hb2/app/drive_command`	`hb2_api_bridge/DriveCommand`
Publish	`/hb2/app/fan_command`	`hb2_api_bridge/FanCommand`
Publish	`/hb2/app/static_camera_command`	`hb2_api_bridge/StaticCameraCommand`
Publish	`/hb2/app/attachment_command`	`hb2_api_bridge/AttachmentCommand`
Service	`/hb2/app/acquire_control`	`hb2_api_bridge/AcquireControl`
Service	`/hb2/app/release_control`	`hb2_api_bridge/ReleaseControl`
Subscribe	`/hb2/app/status`	`hb2_api_bridge/TabletStatus`
Subscribe	`/hb2/app/command_result`	`hb2_api_bridge/CommandResult`

Acquire accepts owner and a stable per-device client_id; its documented response is accepted, lease_id, control_owner, lease_timeout, and reason. Send an explicit fan command before any drive command. Drive and heartbeat deadlines are independent (300 ms and approximately one second), and the stop sequence is neutral drive followed by release. Fan output is retained on stop, disconnect, and timeout. Attachment pairs are exactly MIRA TRIGGER|CANCEL, PUNDIT ENABLE|DISABLE|CANCEL, and LIFTER LIFT|FLAT|LOWER|CANCEL.

The native client controls readiness from fresh TabletStatus, not merely an open socket or control_owned alone. Unsupported PTZ, raster, spray, configuration, rosapi, and internal telemetry endpoints are intentionally not part of this API.

Historical pre-HB2 API (rollback reference only)

The /pat/* topics and telemetry listed below belong to the legacy provider and are retained solely to explain compatibility of archived rollback APKs. They are not imported, advertised, subscribed, or published by the production HB2 runtime. A rollback must use an APK/firmware pair tested against that legacy contract; it is not a runtime fallback for a current robot.

This document defines the communication interface (topics and message types) between the React Native application and the robot’s ROS environment. This “contract” allows the frontend to control the robot and receive real-time telemetry.

graph TD
    subgraph App [Mobile Application]
        Publishers[Publishers]
        Subscribers[Subscribers]
    end

    subgraph Control [Control Commands]
        CMD["/pat/control/pat_cmd"]
        CAM["/pat/camera/control"]
        RA["/pat/control/raster_arm"]
    end

    subgraph Telemetry [Robot Telemetry]
        MON["/pat/info/device_monitor"]
        MC["/pat/info/mc_data"]
        LIVE["/pat/control/live_data"]
        SCAN["/scan"]
    end

    Publishers --> CMD
    Publishers --> CAM
    Publishers --> RA
    MON --> Subscribers
    MC --> Subscribers
    LIVE --> Subscribers
    SCAN --> Subscribers

Command Topics (App -> Robot)

The application publishes the following topics to control various robot subsystems.

Topic Name	Message Type	Description
`/pat/control/pat_cmd`	`pat_custom_msgs/PatJoyControl`	Primary driving and fan control commands.
`/pat/camera/control`	`pat_custom_msgs/CameraControl`	Pan, tilt, zoom, and lighting controls for the PTZ camera.
`/pat/control/raster_arm`	`pat_custom_msgs/RasterArmControl`	Controls for the scanning raster arm.
`/pat/control/motor_speed`	`pat_custom_msgs/MotorSpeed`	Sets the global scalar for motor speed.
`/pat/control/fan_override`	`std_msgs/Bool`	Emergency command to stop all fans.
`/pat/control/ra_mode`	`std_msgs/String`	Toggles between Manual and Automatic robot arm modes.

Telemetry Topics (Robot -> App)

The application subscribes to these topics to update the user interface with real-time data.

Topic Name	Message Type	Description
`/pat/info/device_monitor`	`pat_custom_msgs/DeviceMonitor`	Physical connection status (Ethernet, Controller, SBC).
`/pat/info/mc_data`	`pat_custom_msgs/McData`	Battery voltages and driveline motor status.
`/pat/control/live_data`	`pat_custom_msgs/PatLiveData`	Real-time telemetry (temp, power, rpm, pressure).
`/scan`	`sensor_msgs/LaserScan`	Raw LIDAR data for visualization.
`/imu_acc_ar`	`sensor_msgs/Imu`	Accelerometer and Gyroscope data.
`/pat/control/raster_arm_feedback`	`pat_custom_msgs/RasterArmFeedback`	Status updates from the raster scanning process.

Key Message Definitions

PatJoyControl (`pat_custom_msgs/PatJoyControl`)

The primary structure for user input.

throttle (float64): Linear velocity.
steering (float64): Angular velocity.
fan_value (int8): Target power level for adhesion fans.
control_mode (string): Current operating mode (MANUAL, AUTOMATIC).

PatLiveData (`pat_custom_msgs/PatLiveData`)

Used for the high-fidelity telemetry dashboard.

v_in (float64): Input voltage.
current (float64): Total current draw.
temp_fet (float64): Temperature of the motor controller FETs.
pressure (float64): Suction pressure from the crawler fans.