mapoi_interfaces

English version (primary): README.md 本ファイルは日本語スナップショットです。最新の内容は英語版を参照してください。

mapoi パッケージ群で使用するメッセージとサービスの定義パッケージです。

メッセージ (msg)

Tolerance.msg

POI の到達判定 tolerance（Nav2 SimpleGoalChecker の xy_goal_tolerance / yaw_goal_tolerance と align）。

PointOfInterest.msg

POI（Point of Interest）を表すメッセージです。

PoiEvent.msg

route 走行中に route 登録 POI への侵入 / 退出、および pause タグ付き POI で navigation 停止が発生した時に publish されるイベントメッセージです (#220 で 4 種別 → 3 種別に簡素化)。

ライフサイクル:

EVENT_ENTER -> [EVENT_PAUSED (only if pause-tagged + nav stops)] -> EVENT_EXIT

EVENT_PAUSED の前提:

• 採用 controller が navigation 停止中も cmd_vel = 0 を継続 publish する こと (Nav2 default の挙動)。controller が静止時に cmd_vel publish を止める実装の場合、EVENT_PAUSED は発火しません。
• pause 自動 trigger (と EVENT_PAUSED の publish) は mapoi_nav2_bridge 側で実施し、resume は client 側 mapoi/nav/resume request で発動するため、RESUMED 相当の event は本仕様に含めません (resume は status topic で観測可能)。

TagDefinition.msg

POI 分類タグ (system tag / user tag) の単一定義を表すメッセージです。GetTagDefinitions.srv のレスポンス成分としても使えるよう PR #193 で導入されました。

InitialPoseRequest.msg

operator の map switch / reload に伴う「初期姿勢候補 POI」通知メッセージ (#149 round 8 で文字列ペアから型化)。唯一の writer である mapoi_server が mapoi/request_initial_pose service 経由の依頼を受けて publish するほか (#211。例: mapoi_nav2_bridge が Nav2 LoadMap 成功後に依頼)、起動時の default POI 採用・reload 時の stale clear でも自発 publish し、localization bridge 群が subscribe します。詳細・stale 排除戦略は msg/InitialPoseRequest.msg の冒頭コメント参照。

QoS は transient_local (depth=1) で後起動 subscriber も latched 値を受信できます。

NavigationBackendStatus.msg

Navigation bridge (Nav2 bridge / 自前 bridge) が 1 Hz で mapoi/nav/backend_status に publish する readiness メッセージです。UI 側 (mapoi_webui, mapoi_rviz_plugins) は backend_ready を見て navigation 操作を gate します。

QoS contract (issue #208)

publisher / subscriber 双方で以下を必ず指定:

• durability: TRANSIENT_LOCAL (late-joiner UI が最新 status を受信できる)
• reliability: RELIABLE
• liveliness (publisher): MANUAL_BY_TOPIC (publish() ごとに liveliness assert)
• liveliness (subscriber): AUTOMATIC (pub MANUAL_BY_TOPIC × sub AUTOMATIC のみ互換)
• liveliness_lease_duration: 5 s (両側、pub.lease <= sub.lease を満たす)

詳細・違反パターンは msg/NavigationBackendStatus.msg の冒頭コメント参照。

Custom bridge 実装者向けガイダンス (issue #207)

backend_ready の算出は bridge ごとに「実際に expose する capability の AND」とすること。mapoi_nav2_bridge (Nav2 bridge) の goal_ready && route_ready && switch_map_ready は 3 capability 全部を expose する bridge にのみ正しい。片機能 bridge (例: NavigateToPose のみ) でこれを真似ると、expose していない capability が常に false → backend_ready も常に false → UI が常に “Navigation unavailable” になる。

具体例とフィールド populate 方針 (reason の慣習表記含む) は msg/NavigationBackendStatus.msg の冒頭コメントに記載。

File truncated at 100 lines see the full file

Changelog for package mapoi_interfaces

This per-package file lists only the changes affecting mapoi_interfaces, in the flat format expected by bloom / buildfarm. Full project-level narrative: root CHANGELOG.rst / the GitHub Releases page.

Forthcoming

0.6.0 (2026-07-15)

• No changes for this package in this release.

0.5.0 (2026-07-10)

• Add service RequestInitialPose ({map_name, poi_name} -> {success, error_message}) for the new mapoi_server initial-pose request flow (#211).
• GetRoutePois response gains bool success / string error_message ahead of the pois_list / landmark_pois fields; recompile all clients (#342).
• PointOfInterest drops the always-zero int32 id field; key on name instead (#338).
• SelectMap response field initial_poi_name renamed to resolved_initial_poi_name (request field unchanged) (#343).
• PoiEvent simplified from four event types to three: remove EVENT_STOPPED / EVENT_RESUMED, add EVENT_PAUSED (value 2), shifting EVENT_EXIT from 2 to 3 (#220, #227). Note the numeric values 2 and 3 are both reused (2: old EVENT_EXIT -> new EVENT_PAUSED; 3: old EVENT_STOPPED -> new EVENT_EXIT): rosbags recorded before 0.5.0 and clients comparing hardcoded numbers will silently misinterpret events; always compare against the named constants after recompiling.

0.4.0 (2026-05-08)

• Add NavigationBackendStatus message (backend_type / backend_ready / reason) for the navigation backend readiness contract (#198).
• Add LocalizationBackendStatus message for the localization readiness contract, published by the new AMCL localization bridge (#209).
• Document backend_ready computation guidance and reason-string privacy rules in the .msg headers and README.md (#207).
• Add a docs-vs-implementation consistency lint that verifies every generated msg/srv has a matching README.md section (#216).

0.3.0 (2026-05-02)

• Add Tolerance.msg (xy / yaw) and migrate PointOfInterest from float64 radius to the Tolerance tolerance struct (#87).
• Tolerance semantics: both xy and yaw are required to be >= 0.001; zero/negative disallowed, out-of-range clamped at YAML load (#138).
• Add EVENT_STOPPED=3 / EVENT_RESUMED=4 constants to PoiEvent.msg (publish logic deferred) (#87).
• GetRoutePois.srv response gains a landmark_pois field for radius-monitoring / route-scoped pause POIs (#143).
• mapoi/initialpose_poi payload type changed from std_msgs/String to InitialPoseRequest ({map_name, poi_name}) as part of the initial_pose system tag removal (#89, #144).

0.2.0 (2026-04-29)

• No changes for this package in this release.