spatialdds-ros 0.3.0__py3-none-any.whl

spatialdds_ros/robot_node.py

@@ -0,0 +1,287 @@
+"""
+The ROS 2 node: one process holding both stacks.
+
+**rclpy is imported inside `main`, not at module scope.** That is not
+tidiness. It keeps every other module in this package importable — and
+therefore testable — on a machine with no ROS, which is where this library's
+unit tests run and where its CI runs. The prototype does the same thing for
+the same reason.
+
+**Both stacks in one process is the proven pattern, not a gamble.** ROS
+Humble's middleware is CycloneDDS 0.10.5 while the Python binding here is
+11.0.1, which sounds like it cannot work and does: the binding loads its own
+`libddsc` and shares no symbols with `rmw_cyclonedds_cpp`'s. SpatialDDS and
+ROS meet on the wire because both are DDS — here, in one process, with the
+model read as model and ROS read as ROS. Nothing is relayed and nothing is
+translated into an envelope type and back.
+"""
+from __future__ import annotations
+
+import math
+import sys
+from typing import Optional
+
+from spatialdds_ros.config import Anchor, Config, ConfigError
+
+
+def _declare(node) -> Config:
+    """
+    Read the parameter surface off the node, and let `Config` judge it.
+
+    Every parameter is declared with a *sentinel* default rather than a real
+    one for the three that must refuse to start, so "not set" is
+    distinguishable from "set to the empty string". `Config` is the single
+    place that decides what is acceptable; this function only collects.
+    """
+    node.declare_parameter("scene", "")
+    node.declare_parameter("entity_id", "")
+    node.declare_parameter("frame_id", "")
+    node.declare_parameter("source_id", "")
+    node.declare_parameter("label", "")
+    node.declare_parameter("domain", 0)
+    node.declare_parameter("ground_z", 0.0)
+    node.declare_parameter("pose_source", "tf")
+    node.declare_parameter("nav2_action", "navigate_to_pose")
+    node.declare_parameter("type_uri", "")
+    # String arrays, because that is what a launch file can express. Declared
+    # with empty defaults: an adapter states only what the operator
+    # configured, so "not set" has to be distinguishable from "set to
+    # nothing" — and both mean the same published empty sequence.
+    node.declare_parameter("content_refs", [""])
+    node.declare_parameter("external_refs", [""])
+    node.declare_parameter("base_frame", "base_link")
+    node.declare_parameter("map_frame", "map")
+    node.declare_parameter("odom_topic", "/odom")
+    node.declare_parameter("amcl_topic", "/amcl_pose")
+    node.declare_parameter("rate_hz", 10.0)
+    # Three separate parameters rather than one array, so a launch file that
+    # sets two of them fails on the third instead of silently shipping a
+    # two-element anchor.
+    node.declare_parameter("anchor_lat_deg", float("nan"))
+    node.declare_parameter("anchor_lon_deg", float("nan"))
+    node.declare_parameter("anchor_height_m", float("nan"))
+
+    def text(name: str) -> str:
+        return str(node.get_parameter(name).value or "")
+
+    def number(name: str) -> float:
+        return float(node.get_parameter(name).value)
+
+    lat, lon, height = (number("anchor_lat_deg"), number("anchor_lon_deg"),
+                        number("anchor_height_m"))
+    given = [not math.isnan(v) for v in (lat, lon, height)]
+    if any(given) and not all(given):
+        raise ConfigError(
+            "an anchor needs all three of anchor_lat_deg, anchor_lon_deg and "
+            "anchor_height_m; a partial anchor is not a weaker claim about "
+            "where the frame is, it is an unusable one. Set all three, or none "
+            "— none is a supported mode and publishes no FrameTransform")
+    anchor = Anchor(lat, lon, height) if all(given) else None
+
+    kwargs = dict(
+        scene=text("scene"),
+        entity_id=text("entity_id"),
+        frame_id=text("frame_id"),
+        anchor=anchor,
+        domain=int(node.get_parameter("domain").value),
+        ground_z=number("ground_z"),
+        pose_source=text("pose_source") or "tf",
+        nav2_action=text("nav2_action") or "navigate_to_pose",
+    )
+    if text("source_id"):
+        kwargs["source_id"] = text("source_id")
+    if text("label"):
+        kwargs["label"] = text("label")
+    if text("type_uri"):
+        kwargs["type_uri"] = text("type_uri")
+
+    def strings(name: str) -> list:
+        raw = node.get_parameter(name).value or []
+        return [str(v).strip() for v in raw if str(v).strip()]
+
+    refs = strings("content_refs")
+    if refs:
+        kwargs["content_refs"] = refs
+    external = []
+    for item in strings("external_refs"):
+        if "=" not in item:
+            raise ConfigError(
+                f"external_refs entries are key=value; got {item!r}. A "
+                f"reference without a namespace cannot be resolved by "
+                f"anyone, which is worse than publishing none")
+        key, _, value = item.partition("=")
+        external.append((key.strip(), value.strip()))
+    if external:
+        kwargs["external_refs"] = external
+    return Config(**kwargs)
+
+
+def main(argv=None) -> int:                                   # pragma: no cover
+    import rclpy
+    from rclpy.node import Node
+
+    from cyclonedds.domain import DomainParticipant
+
+    from spatialdds_ros.adapter import RobotAdapter, already_published
+
+    rclpy.init(args=argv)
+
+    class SpatialDdsRobot(Node):
+        def __init__(self) -> None:
+            super().__init__("spatialdds_robot")
+            self.config = _declare(self)
+            for note in self.config.startup_notes():
+                self.get_logger().info(note)
+
+            self.participant = DomainParticipant(self.config.domain)
+            existing = already_published(self.participant, self.config)
+            if existing is not None:
+                raise SystemExit(
+                    f"{self.config.entity_id} is already being published by "
+                    f"{existing}. Refusing to start: one writer per key, and "
+                    f"two of us would put one robot in two places with "
+                    f"nothing reporting the conflict")
+
+            self.adapter = RobotAdapter(
+                self.participant, self.config,
+                navigator=_Nav2Navigator(self, self.config.nav2_action))
+            note = self.adapter.publish_georeference()
+            if note:
+                self.get_logger().info(note)
+
+            self._subscribe_to_the_pose()
+            period = 1.0 / float(self.get_parameter("rate_hz").value)
+            self.create_timer(period, self._tick)
+            self.get_logger().info(
+                f"owns {self.config.entity_id} on DDS domain "
+                f"{self.config.domain}; driving through "
+                f"{self.config.nav2_action}")
+
+        # --- the pose in ------------------------------------------------
+
+        def _subscribe_to_the_pose(self) -> None:
+            """
+            **A map-frame pose, and that is the whole of this method's care.**
+
+            The prototype read `nav_msgs/Odometry` on `/odom`, which is
+            map-frame *only* in its simulator, where `map -> odom` is static
+            and identity. On a localizing robot odom drifts against map — that
+            drift is the entire reason AMCL publishes a correction — so reading
+            it would publish a slowly-diverging claim about where the robot is
+            on the earth, with every number looking plausible. The census files
+            that against the demo; here the default simply is not `/odom`.
+
+            `tf` is the default because it is what nav2 itself consumes, works
+            whatever the localizer is, and assumes no topic name.
+            """
+            source = self.config.pose_source
+            if source == "tf":
+                from tf2_ros import Buffer, TransformListener
+                self._tf_buffer = Buffer()
+                self._tf_listener = TransformListener(self._tf_buffer, self)
+                self._read_pose = self._pose_from_tf
+            elif source == "amcl":
+                from geometry_msgs.msg import PoseWithCovarianceStamped
+                self.create_subscription(
+                    PoseWithCovarianceStamped,
+                    str(self.get_parameter("amcl_topic").value),
+                    self._on_amcl, 10)
+                self._read_pose = lambda: None
+            else:                                   # odom, warned about above
+                from nav_msgs.msg import Odometry
+                self.create_subscription(
+                    Odometry, str(self.get_parameter("odom_topic").value),
+                    self._on_odom, 20)
+                self._read_pose = lambda: None
+
+        def _pose_from_tf(self) -> None:
+            from rclpy.time import Time as RosTime
+            map_frame = str(self.get_parameter("map_frame").value)
+            base_frame = str(self.get_parameter("base_frame").value)
+            try:
+                tf = self._tf_buffer.lookup_transform(
+                    map_frame, base_frame, RosTime())
+            except Exception:                                 # noqa: BLE001
+                # Not an error worth logging every tick: a localizer that has
+                # not converged yet simply has no transform, and the adapter's
+                # own silence handling already describes that state correctly.
+                return
+            t = tf.transform.translation
+            self.adapter.observed(t.x, t.y, _yaw_of(tf.transform.rotation))
+
+        def _on_amcl(self, msg) -> None:
+            p = msg.pose.pose
+            self.adapter.observed(p.position.x, p.position.y,
+                                  _yaw_of(p.orientation))
+
+        def _on_odom(self, msg) -> None:
+            p = msg.pose.pose
+            self.adapter.observed(p.position.x, p.position.y,
+                                  _yaw_of(p.orientation))
+
+        # --- housekeeping ------------------------------------------------
+
+        def _tick(self) -> None:
+            self._read_pose()
+            for note in self.adapter.poll_commands():
+                self.get_logger().info(note)
+            note = self.adapter.tick()
+            if note:
+                self.get_logger().info(note)
+
+    class _Nav2Navigator:
+        """nav2, asked properly and reported honestly."""
+
+        def __init__(self, node, action_name: str) -> None:
+            from nav2_msgs.action import NavigateToPose
+            from rclpy.action import ActionClient
+            self._node = node
+            self._goal_type = NavigateToPose
+            self._client = ActionClient(node, NavigateToPose, action_name)
+            self._action_name = action_name
+
+        def available(self) -> Optional[str]:
+            if not self._client.server_is_ready():
+                # One reason, said plainly. "nav2 is down" and "nav2 is up but
+                # inactive" look identical from here and lead to the same
+                # place: nothing will drive.
+                return (f"nav2 is not accepting goals (no {self._action_name} "
+                        f"server)")
+            return None
+
+        def send(self, x: float, y: float) -> str:
+            goal = self._goal_type.Goal()
+            goal.pose.header.frame_id = str(
+                self._node.get_parameter("map_frame").value)
+            goal.pose.header.stamp = self._node.get_clock().now().to_msg()
+            goal.pose.pose.position.x = x
+            goal.pose.pose.position.y = y
+            goal.pose.pose.position.z = self._node.config.ground_z
+            goal.pose.pose.orientation.w = 1.0
+            self._client.send_goal_async(goal)
+            return f"nav2 accepted a goal at ({x:.2f}, {y:.2f})"
+
+    try:
+        node = SpatialDdsRobot()
+    except ConfigError as error:
+        print(str(error), file=sys.stderr)
+        rclpy.shutdown()
+        return 2
+    try:
+        rclpy.spin(node)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        node.destroy_node()
+        rclpy.shutdown()
+    return 0
+
+
+def _yaw_of(q) -> float:
+    """Yaw from a ROS quaternion message."""
+    return math.atan2(2.0 * (q.w * q.z + q.x * q.y),
+                      1.0 - 2.0 * (q.y * q.y + q.z * q.z))
+
+
+if __name__ == "__main__":                                    # pragma: no cover
+    sys.exit(main())

spatialdds_ros/standalone.py

@@ -0,0 +1,221 @@
+"""
+The no-hardware mode, wired up and runnable.
+
+    python3 -m spatialdds_ros.standalone --scene bare-scene \
+        --entity-id ent:robot:r1 --frame-id map/bare-scene
+
+A robot on the bus in one command, with no ROS, no nav2 and no hardware. It is
+the try-it story, and it is also the harness the acceptance run drives — the
+same code path a person follows from the README, rather than a test-only
+scaffold that could pass while the documented path was broken.
+
+Everything here is wiring. The behaviour lives in `RobotAdapter` (what is
+published, what is declined, what is refused), `KinematicSource` (how it
+moves) and `Announcer` (how it is found).
+"""
+from __future__ import annotations
+
+import argparse
+import signal
+import sys
+import time
+from typing import Optional
+
+from cyclonedds.domain import DomainParticipant
+
+from spatialdds_ros.adapter import RobotAdapter, already_published
+from spatialdds_ros.announce import Announcer
+from spatialdds_ros.config import Anchor, Config, ConfigError
+from spatialdds_ros.kinematic import (
+    Bounds, KinematicNavigator, KinematicSource)
+
+DEFAULT_RATE_HZ = 10.0
+
+
+class Runner:
+    """
+    One robot, driven by the kinematic source, for as long as it is stepped.
+
+    Split from `main` so the acceptance test drives exactly what a person
+    running the command drives — `main` only parses arguments and loops.
+    """
+
+    def __init__(self, config: Config, *, rate_hz: float = DEFAULT_RATE_HZ,
+                 start: tuple = (0.0, 0.0), speed: Optional[float] = None,
+                 bounds: Optional[Bounds] = None,
+                 announce_kind: str = "OTHER") -> None:
+        self.config = config
+        self.rate_hz = rate_hz
+        self.interval = 1.0 / rate_hz
+        self.participant = DomainParticipant(config.domain)
+
+        existing = already_published(self.participant, config)
+        if existing is not None:
+            raise SystemExit(
+                f"{config.entity_id} is already being published by "
+                f"{existing}. Refusing to start: one writer per key, and two "
+                f"of us would put one robot in two places with nothing "
+                f"reporting the conflict")
+
+        self.source = KinematicSource(
+            start=start, speed=speed or 0.6, bounds=bounds)
+        self.adapter = RobotAdapter(
+            self.participant, config,
+            navigator=KinematicNavigator(self.source))
+        self.announcer = Announcer(self.participant, config, announce_kind)
+        self._announced_at = 0.0
+        self.notes: list[str] = []
+
+    def start(self) -> list[str]:
+        """Say what mode this is, announce, and publish the georeference."""
+        notes = list(self.config.startup_notes())
+        notes.append(self.announcer.publish())
+        self._announced_at = time.monotonic()
+        georeference = self.adapter.publish_georeference()
+        if georeference:
+            notes.append(georeference)
+        self.notes.extend(notes)
+        return notes
+
+    def step(self, dt: Optional[float] = None) -> list[str]:
+        """One iteration. Returns whatever is worth logging."""
+        dt = self.interval if dt is None else dt
+        notes = list(self.adapter.poll_commands())
+
+        x, y, yaw = self.source.step(dt)
+        abandoned = self.source.abandoned
+        if abandoned:
+            self.source.abandoned = None
+        self.adapter.observed(x, y, yaw)
+        if abandoned:
+            # After `observed`, so the amended record carries the current pose
+            # rather than being overwritten by it on the next line.
+            self.adapter.refused(abandoned)
+            notes.append(abandoned)
+
+        note = self.adapter.tick()
+        if note:
+            notes.append(note)
+
+        # Re-announce well inside the TTL, so one missed refresh is not an
+        # outage.
+        if (time.monotonic() - self._announced_at
+                > self.announcer.refresh_interval_s):
+            notes.append(self.announcer.publish())
+            self._announced_at = time.monotonic()
+
+        self.notes.extend(notes)
+        return notes
+
+    def run(self) -> int:                                     # pragma: no cover
+        stop = False
+
+        def _stop(_signum, _frame):
+            nonlocal stop
+            stop = True
+
+        signal.signal(signal.SIGINT, _stop)
+        signal.signal(signal.SIGTERM, _stop)
+
+        for note in self.start():
+            print(f"robot: {note}", flush=True)
+        reported = 0
+        while not stop:
+            for note in self.step():
+                print(f"robot: {note}", flush=True)
+            reported += 1
+            if reported % int(self.rate_hz * 20) == 0:
+                print(f"robot: {reported} poses; at "
+                      f"({self.source.x:.2f}, {self.source.y:.2f})", flush=True)
+            time.sleep(self.interval)
+        print("robot: stopping.", flush=True)
+        return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        description="Put a kinematic robot on a SpatialDDS bus, with no ROS")
+    # The three with no default, per the ruling. argparse does not mark them
+    # required: `Config` is the single place that decides, and its refusal
+    # explains *why* each has no default, which `argparse` cannot.
+    p.add_argument("--scene", default="")
+    p.add_argument("--entity-id", default="")
+    p.add_argument("--frame-id", default="")
+    p.add_argument("--source-id", default="")
+    p.add_argument("--label", default="")
+    p.add_argument("--domain", type=int, default=0)
+    p.add_argument("--ground-z", type=float, default=0.0)
+    p.add_argument("--rate-hz", type=float, default=DEFAULT_RATE_HZ)
+    p.add_argument("--speed", type=float, default=0.6)
+    p.add_argument("--start", default="0,0", metavar="X,Y")
+    p.add_argument("--anchor", default="", metavar="LAT,LON,HEIGHT",
+                   help="publish a FrameTransform for this frame. Omitted, "
+                        "none is published and the robot is simply not "
+                        "earth-referenced — a supported mode")
+    p.add_argument("--bounds", default="", metavar="MINX,MINY,MAXX,MAXY",
+                   help="a box this source will not leave, so the late-refusal "
+                        "path can be exercised without hardware")
+    p.add_argument("--announce-kind", default="OTHER")
+    p.add_argument("--content-ref", action="append", default=[],
+                   metavar="catalog:ID",
+                   help="what this robot is, for a consumer that wants to "
+                        "draw it. Repeatable. Omitted, the record carries an "
+                        "empty sequence and a consumer renders a marker")
+    p.add_argument("--external-ref", action="append", default=[],
+                   metavar="KEY=VALUE",
+                   help="what it is also known as, e.g. wikidata=Q4810574. "
+                        "Repeatable")
+    return p
+
+
+def _config_from(args) -> tuple:
+    anchor = None
+    if args.anchor:
+        parts = [float(v) for v in args.anchor.split(",")]
+        if len(parts) != 3:
+            raise ConfigError(
+                "--anchor needs LAT,LON,HEIGHT — all three. A partial anchor "
+                "is not a weaker claim about where the frame is, it is an "
+                "unusable one; omit it entirely for the no-georeference mode")
+        anchor = Anchor(*parts)
+    bounds = None
+    if args.bounds:
+        parts = [float(v) for v in args.bounds.split(",")]
+        if len(parts) != 4:
+            raise ConfigError("--bounds needs MINX,MINY,MAXX,MAXY")
+        bounds = Bounds(*parts)
+    start = tuple(float(v) for v in args.start.split(","))
+    external = []
+    for item in (args.external_ref or []):
+        if "=" not in item:
+            raise ConfigError(
+                f"--external-ref takes KEY=VALUE; got {item!r}. A reference "
+                f"without a namespace cannot be resolved by anyone, which is "
+                f"worse than publishing none")
+        key, _, value = item.partition("=")
+        external.append((key.strip(), value.strip()))
+    kwargs = dict(scene=args.scene, entity_id=args.entity_id,
+                  frame_id=args.frame_id, anchor=anchor, domain=args.domain,
+                  ground_z=args.ground_z,
+                  content_refs=tuple(args.content_ref or ()),
+                  external_refs=tuple(external))
+    if args.source_id:
+        kwargs["source_id"] = args.source_id
+    if args.label:
+        kwargs["label"] = args.label
+    return Config(**kwargs), start, bounds
+
+
+def main(argv=None) -> int:                                   # pragma: no cover
+    args = _parser().parse_args(argv)
+    try:
+        config, start, bounds = _config_from(args)
+    except ConfigError as error:
+        print(str(error), file=sys.stderr)
+        return 2
+    return Runner(config, rate_hz=args.rate_hz, start=start, speed=args.speed,
+                  bounds=bounds, announce_kind=args.announce_kind).run()
+
+
+if __name__ == "__main__":                                    # pragma: no cover
+    sys.exit(main())

spatialdds_ros/tempo.py

@@ -0,0 +1,114 @@
+"""
+When to refresh a latched record, and when to call a feed silent.
+
+**The derivation is the convention, not any of the numbers.** A fixed silence
+threshold shorter than the update interval makes every gap between updates
+look like a stop. Measured in the prototype: a one-second threshold against a
+mover giving each duck a turn every 1.5 s produced 94 "it stopped moving"
+flushes while nothing had stopped, and "the fast tier quietly became the slow
+one" (`spatialdds_demo/tempo.py`).
+
+That is why this is not a parameter. A robot's publish rate is whatever ROS
+publishes at — 20 Hz from a simulator, 5 Hz from an AMCL, something else on
+hardware under load — and a library cannot know it. So it is measured per key
+and the threshold follows it.
+
+No I/O and no DDS: this answers questions and the caller decides what to
+write, which keeps the single-writer rule with whoever owns the instance and
+keeps this testable with no bus.
+"""
+from __future__ import annotations
+
+import time
+from typing import Dict, List, Optional
+
+#: A FAST entity's every update goes out on the pose lane; its latched record
+#: is refreshed every Nth, so a late joiner is at most N-1 updates stale and
+#: converges on the next pose.
+LATCH_EVERY_N = 5
+
+#: The floor under the idle threshold, and the multiple of an entity's own
+#: observed interval taken as evidence it has stopped. A thing updating every
+#: 100 ms is idle after a beat; a thing updating every ten seconds is not idle
+#: after eleven.
+IDLE_FLOOR_S = 1.0
+IDLE_FACTOR = 3.0
+
+#: How much of the observed interval survives each new measurement. Low enough
+#: to follow a cadence change within a few updates, high enough that one late
+#: sample does not convince it everything stopped.
+GAP_SMOOTHING = 0.7
+
+
+class Tempo:
+    """Per-key bookkeeping for a fast lane."""
+
+    def __init__(self, latch_every: int = LATCH_EVERY_N,
+                 idle_floor: float = IDLE_FLOOR_S,
+                 idle_factor: float = IDLE_FACTOR,
+                 smoothing: float = GAP_SMOOTHING) -> None:
+        self.latch_every = latch_every
+        self.idle_floor = idle_floor
+        self.idle_factor = idle_factor
+        self.smoothing = smoothing
+        self._pending: Dict[str, int] = {}
+        self._last: Dict[str, float] = {}
+        self._gap: Dict[str, float] = {}
+
+    def observed(self, key: str, now: Optional[float] = None) -> bool:
+        """
+        Record an update. Returns whether the latched record is now due.
+
+        The caller publishes the fast sample either way; this decides only
+        about the expensive one.
+        """
+        now = time.time() if now is None else now
+        previous = self._last.get(key)
+        if previous is not None:
+            gap = now - previous
+            known = self._gap.get(key)
+            self._gap[key] = (gap if known is None
+                              else self.smoothing * known
+                              + (1 - self.smoothing) * gap)
+        self._last[key] = now
+
+        pending = self._pending.get(key, 0) + 1
+        if pending >= self.latch_every:
+            self._pending[key] = 0
+            return True
+        self._pending[key] = pending
+        return False
+
+    def threshold(self, key: str) -> float:
+        """How long without an update means this key has stopped."""
+        gap = self._gap.get(key)
+        if gap is None:
+            # One update is not a cadence. Until there are two, the floor is
+            # all there is to go on — which costs a slow feed one uneconomical
+            # but correct flush while its cadence is learned.
+            return self.idle_floor
+        return max(self.idle_floor, self.idle_factor * gap)
+
+    def idle(self, now: Optional[float] = None) -> List[str]:
+        """
+        Keys with pending changes that have gone quiet, marked clean.
+
+        So calling it every tick republishes a still world exactly once rather
+        than every tick.
+        """
+        now = time.time() if now is None else now
+        due = []
+        for key, pending in list(self._pending.items()):
+            if pending == 0:
+                continue
+            if now - self._last.get(key, 0.0) < self.threshold(key):
+                continue
+            self._pending[key] = 0
+            due.append(key)
+        return due
+
+    def forget(self, key: str) -> None:
+        """Stop tracking a key — it retired, or was disposed."""
+        self._pending.pop(key, None)
+        self._last.pop(key, None)
+        self._gap.pop(key, None)

spatialdds_ros/topics.py

@@ -0,0 +1,64 @@
+"""
+Topic names, derived from the scene and never configured.
+
+§3.3.1's five-segment grammar: `spatialdds/{scene}/{group}/{type}/{version}`.
+The scene is the only free variable; the names below are that grammar applied
+to it.
+
+**Why these are not parameters.** A topic name is the whole of interop — two
+participants meet because they chose the same string and for no other reason.
+Exposing the strings would let an operator produce a name nothing else looks
+for, and the symptom is an empty bus: no error, no warning, no mismatch
+reported anywhere, just a robot publishing into a topic with no readers and a
+scene that never sees it. There is one right answer per scene, so the library
+fills it.
+
+The prototype had the same four names with the scene baked into module-level
+constants (`spatialdds_demo/topics.py`), which is the same decision made for a
+single scene.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+#: The frame that `earth-fixed` names, shared by every participant that
+#: georeferences anything. Not a parameter: it is the one frame name that must
+#: agree across the whole bus, and the prototype, the catalogue and the spec
+#: all spell it this way.
+EARTH_FIXED_FQN = "earth-fixed"
+
+
+@dataclass(frozen=True)
+class Topics:
+    """The four lanes this library uses, for one scene."""
+
+    scene: str
+
+    @property
+    def entity(self) -> str:
+        """Latched records: what exists, and what it is."""
+        return f"spatialdds/{self.scene}/world/entity/v1"
+
+    @property
+    def pose(self) -> str:
+        """The fast lane: where it is now."""
+        return f"spatialdds/{self.scene}/world/model_pose/v1"
+
+    @property
+    def command(self) -> str:
+        """Requests addressed to something in the scene."""
+        return f"spatialdds/{self.scene}/world/model_command/v1"
+
+    @property
+    def frame_transform(self) -> str:
+        """Where the scene's frames sit relative to one another."""
+        return f"spatialdds/{self.scene}/frames/frame_transform/v1"
+
+    def all(self) -> dict[str, str]:
+        """Every name, for a startup banner and for the tests to check."""
+        return {
+            "entity": self.entity,
+            "pose": self.pose,
+            "command": self.command,
+            "frame_transform": self.frame_transform,
+        }