Robot tool HTTP bridge

Purpose and exposure

The tool bridge lets external conversational providers call robot expression, arm gesture and visual-question tools. It shares a RobotToolExecutor with in-process provider tools. Schema exposure and execution are separate: /hr/interaction/chatbot/tools controls chatbot tool registration; /hr/llm_tools/server configures the local HTTP listener; /hr/llm_tools/natural_actions maps stable action names to the selected robot's animation library.

The default client URL is http://127.0.0.1:8005/tools/call, and the server's default host is loopback. Remote use requires an explicitly reachable deployment or forwarding. The inspected HTTP handler has no authentication mechanism. Do not expose the raw port publicly.

POST /tools/call

Content is JSON. The envelope is:

{"tool":"setExpression","parameters":{"expression":"CONFIGURED_EXPRESSION"}}

Supported names are exactly setExpression, playArmGesture, and answerFromVision. Parameters must be an object. The dispatcher executes synchronously and returns the executor's result. Application failure can still use HTTP 200; inspect success.

Condition	HTTP status	Response
Malformed/invalid UTF-8 JSON	400	success: false, invalid JSON message
Body not an object	400	Request body must be a JSON object
Missing tool	400	Missing tool
Unknown tool	404	Unknown tool with supplied name
Truthy non-object parameters	400	Tool parameters must be a JSON object
POST to another path	404	Unknown path
Any GET	405	Only POST is supported
Known tool execution	200	Executor result, including success: false failures

The dispatcher converts missing/null or other falsy parameters to {} before validation. It does not advertise a discovery endpoint, streaming response, cancellation, or idempotency key. The supplied client defaults to a five-second HTTP timeout, while a vision call can take longer; a client timeout is not proof the tool stopped.

setExpression

Parameter	Default / behavior
expression or name	Required resolvable natural action/name
magnitude	Default 1.0, bounded 0.9–1.0
duration	Default 3.0 seconds, bounded 0.1–10.0

Resolution combines configured expression_poses mappings with the runtime expression catalog. Failure lists available expressions. Success publishes SetExpression and returns success, resolved_name and a human-readable message. Publication is not physical-motion completion.

playArmGesture

Parameter	Default / bounds
gesture or name	Required resolvable gesture
magnitude	0.8; 0.0–1.0
speed	1.0; 0.1–3.0
repeat	1; integer 1–5

Resolution uses arm_gesture_animations and the animation catalog. Success publishes SetAnimation and returns the resolved name. Invalid actions return success: false. This operation can move the robot's arms; select a calibrated configuration and clear the motion area before using it.

# State-changing example: only run on the intended, prepared robot.
curl --fail-with-body http://TOOLS_HOST:TOOLS_PORT/tools/call \
  -H 'Content-Type: application/json' \
  --data '{"tool":"playArmGesture","parameters":{"gesture":"CONFIGURED_GESTURE","repeat":1,"speed":1,"magnitude":0.5}}'

answerFromVision

Parameter	Behavior
question	Defaults to What can you see?
detail	brief, normal or detailed; other values normalize to normal
instant_utterance	Optional text echoed in result

The executor retains the latest compressed camera frame. Default input is /hr/perception/jetson/realsense/camera/color/image_raw/compressed, overridable with LLM_TOOLS_CAMERA_TOPIC. It requires GROQ_API_KEY, sends the image plus question to the configured Groq vision model, and returns description, instant_utterance, image_time, source: groq_vision and success.

GROQ_VISION_MODEL selects the model; GROQ_VISION_TIMEOUT defaults to ten seconds. Missing credentials or camera data returns an application failure before the external call. External/API/parsing exceptions return a failure message. The executor uses the latest frame but does not impose a documented maximum frame age; callers should inspect image_time before treating an answer as current. The call transfers camera content to the provider and may incur provider usage.

Configuration and diagnosis

Natural action names are mappings rather than guaranteed animation filenames. When a tool is unavailable, inspect tool enablement, configured aliases, catalog availability and publisher dependencies separately. A successful tool HTTP response does not establish that a provider was given the tool schema or elected to call it.

Evidence: head-ros-nodes/ros/ros_chatbot/src/ros_chatbot/llm_tools/{http_api.py,robot_tools.py,natural_actions.py}, scripts/llm_tools_server.py and docs/llm_tools_architecture.md.