makerspet--oomwoo/docs/SOFTWARE_INTERFACES.md

OOMWOO ROS2 Software Interfaces

Status: DRAFT. This is the shared software contract for simulation-first contributions. It reflects the current urdf-gazebo-sim package and should be updated whenever a module needs a new public topic, service, action, frame, or parameter.

Purpose

OOMWOO software modules are meant to be swappable. A contributor should be able to build clean-and-map, nav-localize, recovery-safety, dock-cycle, or cleaning-jobs without depending on another module's private implementation.

This document defines the public ROS2 surface area those modules can share while the hardware is still evolving. It is not a final hardware API.

Naming rules

• Public names below are shown as root topics, for example /scan. Launch files and node configs may use relative names such as scan when they resolve to the same root topic in the default launch.
• Use REP-103 frames and SI units.
• Prefer standard ROS2/Nav2 message types before adding custom OOMWOO messages.
• If a module introduces a new public interface, document the producer, consumer, message type, QoS expectation, and failure behavior in its README and update this file.
• Simulation-only details, such as Gazebo collision entity names, must not leak into cross-module contracts unless they are explicitly marked as simulation diagnostics.

Frames

Frame	Owner	Meaning
map	SLAM/localization	Global map frame used by SLAM, AMCL, Nav2, and saved maps.
odom	Base odometry	Locally continuous odometry frame.
base_footprint	Robot description / odometry	Planar base frame for navigation.
base_link	Robot description	Main robot body frame. Hardware modules should reference this once geometry is frozen.
base_scan	Robot description	2D LiDAR frame.

Open decision: base_link origin, reference plane, robot diameter, and height envelope are still defined in ARCHITECTURE.md.

Baseline Topics

These topics are provided by the current Gazebo simulation or standard Nav2/SLAM bringup and should be treated as the MVP baseline.

Topic	Type	Direction	Producer	Consumers
/cmd_vel	geometry_msgs/msg/Twist	Command	Teleop, Nav2 velocity smoother, recovery nodes	Gazebo diff-drive / base controller
/odom	nav_msgs/msg/Odometry	State	Gazebo odometry / base controller	SLAM, AMCL, Nav2, recovery and job logic
/tf	tf2_msgs/msg/TFMessage	State	Robot state publisher, odometry, SLAM/localization	All pose-aware modules
/joint_states	sensor_msgs/msg/JointState	State	Gazebo joint state publisher / hardware base	Robot state publisher, diagnostics
/scan	sensor_msgs/msg/LaserScan	Sensor	2D LiDAR / Gazebo LiDAR	SLAM, AMCL, Nav2 costmaps, wall following
/map	nav_msgs/msg/OccupancyGrid	State	SLAM or map server	Nav2, cleaning, zones, visualization
/bumper_left	ros_gz_interfaces/msg/Contacts in Gazebo	Sensor	Gazebo left contact sensor	Recovery, safety, clean-and-map obstacle handling
/bumper_right	ros_gz_interfaces/msg/Contacts in Gazebo	Sensor	Gazebo right contact sensor	Recovery, safety, clean-and-map obstacle handling

Bumper events

The current simulation publishes raw Gazebo contact messages:

• Message type: ros_gz_interfaces/msg/Contacts
• Contact list field: contacts
• Per-contact fields: collision1, collision2, positions, normals, depths, wrenches

Consumers should treat len(msg.contacts) > 0 as a bumper event after filtering out ground-plane contacts. Do not read a collisions field; that belongs to the single-contact message type and is not what the bridge publishes.

Hardware may eventually replace raw Gazebo contacts with a normalized bumper message. Until that decision is made, module submissions should isolate the Gazebo-specific parsing behind a small adapter.

Nav2 Interfaces

Modules should reuse Nav2 actions and servers where possible.

Interface	Type	Typical consumer
/navigate_to_pose	nav2_msgs/action/NavigateToPose	nav-localize, cleaning-jobs, dock-cycle
/navigate_through_poses	nav2_msgs/action/NavigateThroughPoses	Coverage, room jobs, dock approach
Nav2 behavior server	spin, backup, drive_on_heading, wait behaviors	Recovery and local fallback logic
Costmaps	Nav2 local/global costmap topics	Obstacle handling, zones, diagnostics
Map saver	Nav2 map saver service/CLI	clean-and-map, nav-localize

If a module needs to command motion directly, it must define how it arbitrates with Nav2 and recovery nodes so two nodes do not fight over /cmd_vel.

Module Contracts

Module	Inputs	Outputs / public behavior
urdf-gazebo-sim	/cmd_vel	Publishes /scan, /odom, /tf, /joint_states, /bumper_left, /bumper_right; provides worlds and robot description.
clean-and-map	/scan, /odom, /tf, bumper events, optional Nav2 actions	Drives first-pass coverage, produces a complete map, defines a done condition, saves map artifacts.
nav-localize	Saved map, /scan, /odom, /tf, Nav2 bringup	Provides known-map navigation, relocalization, and map-resume behavior.
recovery-safety	Bumper events, future cliff/wheel-drop/pickup/e-stop signals, Nav2 failures	Stops or gates motion, runs bounded recoveries, publishes clear pause/error status.
floor-care	/scan, map/coverage context, future surface sensor	Provides wall/edge following, surface classification, and mop actuator decisions.
cleaning-jobs	Saved map, zones, coverage progress, battery/bin/mop status, Nav2 actions	Provides start/pause/resume/cancel/status job behavior suitable for a future Home Assistant layer.
dock-cycle	Nav2/localization, dock marker, battery/service state	Provides undock, return-to-dock, precise docking, recharge/service completion, and find-dock fallback.
live-robot-bringup	Hardware drivers, same logical topics	Validates that hardware exposes the same public interfaces as the simulation.

Status and Errors

The final robot status API is still open. Until it is selected, modules that need status reporting should document:

• state: short machine-readable state, for example cleaning, recovering, paused, docked, or error
• reason_code: stable machine-readable reason, for example BUMPER_STUCK, LOCALIZATION_LOST, or LOW_BATTERY
• message: human-readable explanation
• recoverable: whether a resume command is expected to work
• source: module name that produced the status

Open decision: choose the transport and type for cross-module status, likely a standard diagnostic message or a small OOMWOO-specific message package.

QoS and Parameters

• use_sim_time should be true in simulation launch files.
• Sensor streams such as /scan should use sensor-data QoS where configurable.
• /map and saved-map metadata should be available to late joiners where the producer supports transient-local durability.
• Command topics should use small queues and should fail safe: stale commands must not keep the robot moving.

Validation Checklist

A module submission that depends on the MVP simulation should document how to check the interfaces it uses. At minimum:

ros2 topic list
ros2 topic echo /scan --once
ros2 topic echo /odom --once
ros2 topic echo /bumper_left
ros2 topic echo /bumper_right
ros2 run tf2_tools view_frames

For Nav2-based modules, also document how to send a NavigateToPose goal and how to confirm /cmd_vel arbitration is safe.

Miscellaneous

• PR your packages into the official distribution makerspet/oomwoo-install
• put your ROS2 packages under /ros_ws/src (don't create another colcon workspace under ~/)
• follow conventions of being able to select a robot package using kaia config robot.model oomwoo_one, see tutorial

Open Decisions

• Final hardware bumper/cliff/wheel-drop message shape.
• Robot-wide status/error message type and topic.
• Battery, dust-bin, mop, and dock service state interfaces.
• Localization-confidence interface for relocalization and kidnap detection.
• Job action/service API for start, pause, resume, cancel, and status.