OpenSMI-ROS2 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. opensmi/ros2/__init__.py +89 -0
  2. opensmi/ros2/__main__.py +11 -0
  3. opensmi/ros2/cli.py +143 -0
  4. opensmi/ros2/py.typed +0 -0
  5. opensmi/ros2/runtime/__init__.py +67 -0
  6. opensmi/ros2/runtime/_decode.py +101 -0
  7. opensmi/ros2/runtime/_encode.py +102 -0
  8. opensmi/ros2/runtime/_parser.py +147 -0
  9. opensmi/ros2/runtime/errors.py +141 -0
  10. opensmi/ros2/runtime/goal.py +232 -0
  11. opensmi/ros2/runtime/graph.py +288 -0
  12. opensmi/ros2/runtime/guard.py +213 -0
  13. opensmi/ros2/runtime/interface.py +140 -0
  14. opensmi/ros2/runtime/messages/__init__.py +503 -0
  15. opensmi/ros2/runtime/messages/industrial_msgs.py +62 -0
  16. opensmi/ros2/runtime/messages/industrial_msgs.pyi +159 -0
  17. opensmi/ros2/runtime/messages/motoros2_interfaces.py +79 -0
  18. opensmi/ros2/runtime/messages/motoros2_interfaces.pyi +307 -0
  19. opensmi/ros2/runtime/messages/neo_msgs2.py +55 -0
  20. opensmi/ros2/runtime/messages/neo_msgs2.pyi +138 -0
  21. opensmi/ros2/runtime/messages/neo_srvs2.py +72 -0
  22. opensmi/ros2/runtime/messages/neo_srvs2.pyi +224 -0
  23. opensmi/ros2/runtime/outcomes.py +103 -0
  24. opensmi/ros2/runtime/parameters.py +723 -0
  25. opensmi/ros2/runtime/publisher.py +125 -0
  26. opensmi/ros2/runtime/qos.py +394 -0
  27. opensmi/ros2/runtime/runtime.py +1171 -0
  28. opensmi/ros2/runtime/selection.py +150 -0
  29. opensmi/ros2/runtime/stamp.py +100 -0
  30. opensmi/ros2/runtime/subscription.py +354 -0
  31. opensmi/ros2/runtime/tf.py +714 -0
  32. opensmi/ros2/server/__init__.py +148 -0
  33. opensmi/ros2/server/access.py +109 -0
  34. opensmi/ros2/server/bindings/__init__.py +92 -0
  35. opensmi/ros2/server/bindings/_base.py +154 -0
  36. opensmi/ros2/server/bindings/action.py +133 -0
  37. opensmi/ros2/server/bindings/keyed.py +127 -0
  38. opensmi/ros2/server/bindings/lifecycle.py +131 -0
  39. opensmi/ros2/server/bindings/method.py +130 -0
  40. opensmi/ros2/server/bindings/monitoring.py +109 -0
  41. opensmi/ros2/server/bindings/parameter.py +133 -0
  42. opensmi/ros2/server/bindings/publisher.py +192 -0
  43. opensmi/ros2/server/bindings/registry.py +95 -0
  44. opensmi/ros2/server/bindings/tf.py +256 -0
  45. opensmi/ros2/server/browse_names.py +94 -0
  46. opensmi/ros2/server/component.py +334 -0
  47. opensmi/ros2/server/config.py +493 -0
  48. opensmi/ros2/server/containers.py +191 -0
  49. opensmi/ros2/server/drivers.py +421 -0
  50. opensmi/ros2/server/errors.py +159 -0
  51. opensmi/ros2/server/events.py +406 -0
  52. opensmi/ros2/server/introspection.py +850 -0
  53. opensmi/ros2/server/keyed.py +749 -0
  54. opensmi/ros2/server/lifecycle.py +238 -0
  55. opensmi/ros2/server/limits.py +66 -0
  56. opensmi/ros2/server/loader.py +977 -0
  57. opensmi/ros2/server/machine.py +225 -0
  58. opensmi/ros2/server/method.py +307 -0
  59. opensmi/ros2/server/mirror.py +582 -0
  60. opensmi/ros2/server/mutation.py +992 -0
  61. opensmi/ros2/server/nodesets/Opc.Ua.SmartFactory.ROS2.NodeSet2.xml +85 -0
  62. opensmi/ros2/server/nodesets/__init__.py +18 -0
  63. opensmi/ros2/server/nodesets/smart_factory_ros2.py +26 -0
  64. opensmi/ros2/server/parameters.py +704 -0
  65. opensmi/ros2/server/projection.py +1176 -0
  66. opensmi/ros2/server/projections/__init__.py +41 -0
  67. opensmi/ros2/server/projections/scope.py +222 -0
  68. opensmi/ros2/server/provenance.py +121 -0
  69. opensmi/ros2/server/publisher.py +781 -0
  70. opensmi/ros2/server/recipes.py +514 -0
  71. opensmi/ros2/server/required.py +633 -0
  72. opensmi/ros2/server/skill.py +363 -0
  73. opensmi/ros2/server/spatial.py +283 -0
  74. opensmi/ros2/server/startup.py +626 -0
  75. opensmi/ros2/server/status.py +107 -0
  76. opensmi/ros2/server/structures.py +135 -0
  77. opensmi/ros2/server/transforms/__init__.py +39 -0
  78. opensmi/ros2/server/transforms/conversions.py +58 -0
  79. opensmi/ros2/server/transforms/filing.py +340 -0
  80. opensmi/ros2/server/transforms/mirror.py +462 -0
  81. opensmi/ros2/server/transforms/outward.py +180 -0
  82. opensmi/ros2/server/transforms/records.py +195 -0
  83. opensmi/ros2/server/transforms/spatial.py +154 -0
  84. opensmi_ros2-0.1.0.dist-info/METADATA +183 -0
  85. opensmi_ros2-0.1.0.dist-info/RECORD +89 -0
  86. opensmi_ros2-0.1.0.dist-info/WHEEL +5 -0
  87. opensmi_ros2-0.1.0.dist-info/entry_points.txt +2 -0
  88. opensmi_ros2-0.1.0.dist-info/licenses/LICENSES/MIT.txt +18 -0
  89. opensmi_ros2-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,192 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """A ROS2 topic published from a Skill."""
6
+
7
+ from __future__ import annotations
8
+
9
+ import math
10
+ from collections.abc import Callable, Mapping
11
+ from dataclasses import dataclass, field
12
+ from typing import ClassVar, TypeAlias
13
+
14
+ from opensmi.ros2.runtime.messages import Message
15
+ from opensmi.ros2.runtime.qos import QoSProfile
16
+ from opensmi.ros2.runtime.selection import FieldSelection
17
+ from opensmi.ros2.server.bindings._base import NamedBinding
18
+ from opensmi.ros2.server.errors import DeclarationError
19
+ from opensmi.ros2.server.projection import ProjectionContext
20
+
21
+ MessageFunction: TypeAlias = Callable[[type[Message], Mapping[str, object], ProjectionContext], Message]
22
+ """Builds the message to publish from a Skill's Parameters, as a pure function.
23
+
24
+ The default is :func:`opensmi.ros2.server.publisher.default_message_from`. A replacement that needs
25
+ the instance is :meth:`~opensmi.ros2.server.publisher.ROS2PublisherSkill.build_message` on a custom
26
+ Skill class.
27
+ """
28
+
29
+
30
+ @dataclass(frozen=True, slots=True, kw_only=True)
31
+ class PublisherBinding(NamedBinding):
32
+ """A ROS2 topic published from a Skill on the declaring Component.
33
+
34
+ Publishing is an activity: a ``/cmd_vel`` stream runs while someone is driving, a map push happens
35
+ once. The declaration becomes a Skill whose Parameters are the message fields, and ``Start`` is the
36
+ only thing that publishes, so a client writes every field in any order and commits once.
37
+ There is no debouncing or dirty tracking.
38
+
39
+ The direction is UA to ROS2 only. The echo of a published topic is always our own message, so a
40
+ readback would confirm the last value published, not the last delivered. To watch the topic, declare
41
+ a :class:`MonitoringBinding` on it.
42
+
43
+ This kind is never required: it carries neither ``required`` nor ``startup_timeout``, because the
44
+ publisher is this server itself. To wait for the other end, declare a required
45
+ :class:`MonitoringBinding` on the topic that answers.
46
+
47
+ The continuity is declared, not inferred from ``rate``, so omitting ``rate`` by accident cannot
48
+ silently give a one-shot. A continuous Skill never reaches ``Completed`` and a finite one has no
49
+ ``Halt`` to close a stream. A second push on a finite Skill is ``Reset``, write, ``Start``.
50
+
51
+ :ivar name: The Binding's name, also the Skill's name. Its variables are named for the field path
52
+ alone.
53
+ :ivar path: The ROS2 topic.
54
+ :ivar message_type: The ROS2 type, ``package/Name`` or ``package/kind/Name``. Required, since the
55
+ Parameters exist before anything is on the graph. A type whose package is not installed is fatal
56
+ at init.
57
+ :ivar continuous: Whether the Skill streams the current snapshot of its Parameters on every tick
58
+ until ``Halt``, or publishes once and reaches ``Completed``. No default.
59
+ :ivar include: Field patterns narrowing the message; empty means every field.
60
+ :ivar exclude: Field patterns removing fields, after ``include`` has narrowed. A selection that
61
+ leaves the message unbuildable is refused at init instead of filled from a default.
62
+ :ivar rename: New browse names by field path, as on :class:`MonitoringBinding`.
63
+ :ivar rate: Publishes per second of a continuous Skill. Required there and fatal on a finite
64
+ Binding. It is the initial value of a client-writable ``rate`` Parameter bounded by
65
+ :data:`~opensmi.ros2.server.publisher.MINIMUM_RATE` and
66
+ :data:`~opensmi.ros2.server.publisher.MAXIMUM_RATE`, and takes effect on the next tick.
67
+ :ivar qos: The QoS profile to offer, or ``None`` for the middleware's reliable, volatile default.
68
+ Never discovered or adapted, because this declaration is how a publisher comes to exist.
69
+ :ivar depth: The ROS2 queue depth for subscribers that have not taken messages yet.
70
+ :ivar stale_after: Seconds a running stream may go without a client write to any of its
71
+ Parameters before it halts itself with ``SETPOINT_STALE``, or ``None`` for never. Every write
72
+ starts the interval again, a rewrite of the same value too, and so does ``Start``. It guards
73
+ against a client that died or lost its connection while its session and the Lock live on,
74
+ which would leave a robot driving on the last ``/cmd_vel``. Continuous only, and a positive,
75
+ finite number.
76
+ :ivar halt_message: The message a stream publishes once when it ends, whatever ended it, or
77
+ ``None`` to just stop publishing. A table of ROS2 field names (not browse names; the
78
+ selection and ``rename`` do not apply), nested for a nested message: ``{"linear": {"x": 0.0}}``.
79
+ A field it does not name keeps the default the message type's generated class gives it.
80
+ Checked against the message type at init. Continuous only.
81
+ :ivar tolerated_failures: Consecutive publish failures a continuous Skill absorbs before halting;
82
+ zero halts on the first. Non-zero on a finite Skill is fatal at init.
83
+ :ivar skill_type: A subclass of :class:`~opensmi.ros2.server.publisher.ROS2ContinuousPublisherSkill`
84
+ or :class:`~opensmi.ros2.server.publisher.ROS2FinitePublisherSkill` matching ``continuous``, or
85
+ ``None`` for the stock one. Python-only; refused when the Binding is constructed if it is not a
86
+ subclass.
87
+ :ivar message_from: Builds the message from the Parameters, or ``None`` for the default.
88
+ Python-only.
89
+ """
90
+
91
+ kind: ClassVar[str] = "Publishing Binding"
92
+
93
+ path: str
94
+ message_type: str
95
+ continuous: bool
96
+ include: tuple[str, ...] = ()
97
+ exclude: tuple[str, ...] = ()
98
+ rename: dict[str, str] = field(default_factory=dict)
99
+ rate: float | None = None
100
+ depth: int = 10
101
+ qos: QoSProfile | None = None
102
+ stale_after: float | None = None
103
+ halt_message: Mapping[str, object] | None = None
104
+ tolerated_failures: int = 0
105
+ skill_type: type | None = None
106
+ message_from: MessageFunction | None = None
107
+
108
+ def __post_init__(self) -> None:
109
+ """Refuse a contradictory declaration.
110
+
111
+ Checks that need the message type (the reserved ``rate`` name, a Projection that cannot invert)
112
+ are left to the Skill's constructor, which is still init.
113
+
114
+ :raises BindingNameError: When ``name`` is empty or not a valid browse name.
115
+ :raises DeclarationError: When a keyword belonging to one continuity is declared on the other, or
116
+ a continuous declaration has no rate.
117
+ :raises ImplementationClassError: When ``skill_type`` is not a subclass of the stock class for
118
+ this continuity.
119
+ """
120
+ self._require_a_name_that_can_be_browsed()
121
+ self._require_new_names_that_follow_the_rule("rename", self.rename)
122
+ self._require_the_continuity_agrees()
123
+ if self.skill_type is None:
124
+ return
125
+ self._require_a_subclass(
126
+ self.skill_type,
127
+ self.stock_skill_type,
128
+ "a publishing Skill's continuity decides which stock class it adds to, a custom class "
129
+ "adds behaviour rather than replacing it, and a TOML file cannot name one at all",
130
+ )
131
+
132
+ def _require_the_continuity_agrees(self) -> None:
133
+ """Refuse a keyword that means nothing on the chosen continuity.
134
+
135
+ :raises DeclarationError: On any disagreement between a keyword and the continuity.
136
+ """
137
+ # Imported here for the same reason as in ``MonitoringBinding``.
138
+ from opensmi.ros2.server.publisher import MAXIMUM_RATE, MINIMUM_RATE
139
+
140
+ if not self.continuous:
141
+ for keyword, value in (
142
+ ("rate", self.rate),
143
+ ("stale_after", self.stale_after),
144
+ ("halt_message", self.halt_message),
145
+ ):
146
+ if value is not None:
147
+ self._refuse(f"declares {keyword}={value!r}, and that exists only on a stream")
148
+ if self.tolerated_failures:
149
+ self._refuse(
150
+ f"declares tolerated_failures={self.tolerated_failures!r}, and a Skill that "
151
+ f"publishes once has no consecutive failures to tolerate -- it raises on the "
152
+ f"one it can have"
153
+ )
154
+ return
155
+ if self.rate is None:
156
+ self._refuse("streams and declares no rate; a tick needs a period, so say how often")
157
+ elif not MINIMUM_RATE <= self.rate <= MAXIMUM_RATE:
158
+ self._refuse(
159
+ f"declares rate={self.rate!r}, and a publish rate is a positive number of times a "
160
+ f"second between {MINIMUM_RATE} and {MAXIMUM_RATE}"
161
+ )
162
+ if self.stale_after is not None and not (math.isfinite(self.stale_after) and self.stale_after > 0):
163
+ self._refuse(
164
+ f"declares stale_after={self.stale_after!r}; it is the number of seconds a stream may "
165
+ f"go without a write before it halts, so a positive, finite number, and leaving it "
166
+ f"out is how it is turned off"
167
+ )
168
+ if self.tolerated_failures < 0:
169
+ self._refuse(f"declares tolerated_failures={self.tolerated_failures!r}, which is not a count")
170
+
171
+ def _refuse(self, why: str) -> None:
172
+ """Raise a :class:`DeclarationError` naming the Binding."""
173
+ shape = "continuous" if self.continuous else "finite"
174
+ message = f"the {shape} publishing Binding {self.name!r} {why}"
175
+ raise DeclarationError(message)
176
+
177
+ @property
178
+ def stock_skill_type(self) -> type:
179
+ """Return the stock Skill class this declaration's continuity builds."""
180
+ from opensmi.ros2.server.publisher import ROS2ContinuousPublisherSkill, ROS2FinitePublisherSkill
181
+
182
+ return ROS2ContinuousPublisherSkill if self.continuous else ROS2FinitePublisherSkill
183
+
184
+ @property
185
+ def selection(self) -> FieldSelection:
186
+ """Return this Binding's field selection."""
187
+ return FieldSelection(include=self.include, exclude=self.exclude, rename=self.rename)
188
+
189
+ @property
190
+ def needs_the_graph(self) -> bool:
191
+ """Return ``False``: we are the publisher, so the shape comes from the declaration."""
192
+ return False
@@ -0,0 +1,95 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """Every Binding kind, the TOML kinds table and the loaders."""
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Mapping
10
+ from typing import TYPE_CHECKING, Any, Final, TypeAlias
11
+
12
+ from opensmi.ros2.server.bindings.action import ActionBinding
13
+ from opensmi.ros2.server.bindings.keyed import KeyedBinding
14
+ from opensmi.ros2.server.bindings.lifecycle import LifecycleBinding
15
+ from opensmi.ros2.server.bindings.method import MethodBinding
16
+ from opensmi.ros2.server.bindings.monitoring import MonitoringBinding
17
+ from opensmi.ros2.server.bindings.parameter import ROS2ParameterBinding
18
+ from opensmi.ros2.server.bindings.publisher import PublisherBinding
19
+ from opensmi.ros2.server.bindings.tf import TFBinding
20
+ from opensmi.ros2.server.config import from_dict, load_toml
21
+ from opensmi.ros2.server.errors import DuplicateBindingNameError
22
+
23
+ if TYPE_CHECKING:
24
+ from collections.abc import Iterable
25
+ from pathlib import Path
26
+
27
+ Binding: TypeAlias = (
28
+ MonitoringBinding
29
+ | KeyedBinding
30
+ | MethodBinding
31
+ | ROS2ParameterBinding
32
+ | ActionBinding
33
+ | TFBinding
34
+ | PublisherBinding
35
+ | LifecycleBinding
36
+ )
37
+ """Every declaration kind. Later kinds widen the alias rather than the mechanism."""
38
+
39
+ TOML_KINDS: Final[Mapping[str, type[Any]]] = {
40
+ "monitoring": MonitoringBinding,
41
+ "keyed": KeyedBinding,
42
+ "method": MethodBinding,
43
+ # Qualified because bare ``parameter`` is opensmi vocabulary for the OPC UA variable.
44
+ "ros2_parameter": ROS2ParameterBinding,
45
+ "action": ActionBinding,
46
+ "tf": TFBinding,
47
+ "publisher": PublisherBinding,
48
+ "lifecycle": LifecycleBinding,
49
+ }
50
+ """Which table of a Binding file declares which kind. A file chooses among these and cannot add one."""
51
+
52
+
53
+ def is_required(binding: Binding) -> bool:
54
+ """Return whether a declaration is a prerequisite its StartupSkill waits for.
55
+
56
+ Works for every kind, including :class:`PublisherBinding`, which has no ``required`` field.
57
+ """
58
+ return bool(getattr(binding, "required", False))
59
+
60
+
61
+ def load_bindings(path: str | Path) -> tuple[Binding, ...]:
62
+ """Read a Binding file, in the order its tables appear.
63
+
64
+ :raises ValueError: When a table carries a key its kind does not declare, or names a kind that does
65
+ not exist.
66
+ """
67
+ declared: list[Binding] = []
68
+ for table, entries in load_toml(path).items():
69
+ kind = TOML_KINDS.get(table)
70
+ if kind is None:
71
+ listed = ", ".join(sorted(TOML_KINDS))
72
+ message = f"{table!r} is not a Binding kind; a Binding file declares one of: {listed}"
73
+ raise ValueError(message)
74
+ declared.extend(from_dict(kind, entry) for entry in entries)
75
+ return tuple(declared)
76
+
77
+
78
+ def resolve_bindings(declared: Iterable[Binding], toml: str | Path | None = None) -> tuple[Binding, ...]:
79
+ """Union what a Component declared in Python with what a deployment declared in TOML.
80
+
81
+ The Python declarations come first and the file's follow. Neither source may overwrite the other.
82
+
83
+ :raises DuplicateBindingNameError: When one name appears twice, in either source or across both.
84
+ """
85
+ resolved = (*declared, *(load_bindings(toml) if toml is not None else ()))
86
+ seen: set[str] = set()
87
+ for binding in resolved:
88
+ if binding.name in seen:
89
+ message = (
90
+ f"the Binding name {binding.name!r} is declared twice; a name is what its "
91
+ f"variables are called, so the second declaration would take the first's nodes"
92
+ )
93
+ raise DuplicateBindingNameError(message)
94
+ seen.add(binding.name)
95
+ return resolved
@@ -0,0 +1,256 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The TF tree as RSL Locations."""
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+ from typing import ClassVar
11
+
12
+ from opensmi.ros2.server.bindings._base import AwaitedBinding
13
+ from opensmi.ros2.server.errors import (
14
+ DeclarationError,
15
+ FrameDirectionError,
16
+ )
17
+ from opensmi.ros2.server.spatial import excluded
18
+
19
+
20
+ @dataclass(frozen=True, slots=True, kw_only=True)
21
+ class PublishedFrame:
22
+ """One frame this object puts on the ROS2 frame network, and the pose it starts at.
23
+
24
+ The outward half of a TF Binding. Inward, which frames exist is discovered. Outward each transform an
25
+ operator wants to assert is named here, which creates a client-writable Location and a link on
26
+ ``/tf``. It reads like an alternative: where ``frame`` sits in ``base``, answered by a client for the
27
+ robot.
28
+
29
+ :ivar base: The frame this one's pose is relative to, becoming ``header.frame_id``. It is the frame's TF
30
+ parent and what the Location's ``Base`` resolves through. Declared, since nobody else publishes
31
+ this frame.
32
+ :ivar frame: The frame this declaration owns, becoming ``child_frame_id``. It may not be declared
33
+ twice, be its own parent, or be any object's head frame.
34
+ :ivar static: Whether it goes on ``/tf_static`` instead of ``/tf``. A static frame is published when its
35
+ value changes, not every tick. Our own publisher is used because
36
+ ``tf2_ros.StaticTransformBroadcaster`` silently drops an update to a frame it already sent.
37
+ :ivar position: Where the frame sits in its base until a client says otherwise, in metres. Declared so
38
+ that "nobody wrote it yet" is distinguishable from "at the origin"; leaving it out means identity.
39
+ :ivar orientation: The ``A``, ``B`` and ``C`` angles RSL holds, in degrees: roll about X, pitch about
40
+ Y, yaw about Z. The conversion to the quaternion ROS2 wants is ours.
41
+ """
42
+
43
+ base: str
44
+ frame: str
45
+ static: bool = False
46
+ position: tuple[float, float, float] = (0.0, 0.0, 0.0)
47
+ orientation: tuple[float, float, float] = (0.0, 0.0, 0.0)
48
+
49
+
50
+ @dataclass(frozen=True, slots=True, kw_only=True)
51
+ class TFBinding(AwaitedBinding):
52
+ """The TF tree, rendered as RSL Locations inside the SpatialObject of whatever owns them.
53
+
54
+ The second keyed Binding: one ROS2 path, many OPC UA objects, membership taken from the messages. It
55
+ is not a :class:`KeyedBinding` because a frame is a ``SpatialLocationType`` Variable in a folder
56
+ OPC 10000-210 names, with a ``Base`` pointing at another Location, and a companion specification does
57
+ not belong in the generic mechanism. Named for its ROS2 side.
58
+
59
+ One declaration per object, and its content is one frame name. The declaring machinery item gains a
60
+ SpatialObject whose ``PositionFrame`` is ``head``, and every frame under that head belongs to it, down
61
+ to the next declared head. A Machine declares one for itself and so does a Component; the
62
+ Machine's mirror runs the whole partition.
63
+
64
+ Where TF is read from and how often are facts about the Machine, declared once in
65
+ :attr:`ROS2Config.transforms <opensmi.ros2.server.config.ROS2Config.transforms>`. The keywords
66
+ ``path``, ``static_path``, ``depth``, ``interval`` and ``quiet_after`` stay here only so that writing
67
+ one is refused with a message saying where it went.
68
+
69
+ :ivar name: The Binding's name, used in BindingEvents and the mutation cap. It is not a prefix on any
70
+ browse name: a frame's raw ``child_frame_id`` is the ``DisplayName`` and a sanitised form the
71
+ BrowseName.
72
+ :ivar head: The one frame this object is. It becomes the SpatialObject's mandatory ``PositionFrame``;
73
+ ownership of everything else follows from the tree.
74
+ :ivar alternatives: The composed poses this object publishes, each a ``(base, frame)`` pair. Each
75
+ becomes a Location in ``AlternativeFrames`` holding where ``frame`` sits in ``base`` (OPC 10000-210,
76
+ section 6.1.1). Declared, since nothing in a frame tree says which compositions are wanted.
77
+ :ivar publishes: The frames this object puts on the frame network instead of reading, each a
78
+ :class:`PublishedFrame`. None may also be read inward (:class:`FrameDirectionError`). A declaration
79
+ that publishes nothing never advertises ``/tf``.
80
+ :ivar exclude: ``fnmatch`` globs over whole frame ids that are not rendered. A frame removed from the
81
+ middle of a chain re-bases its children onto the nearest surviving ancestor.
82
+ :ivar required: Whether the StartupSkill waits for a publisher on a transform topic before ``Running``.
83
+ Presence only, never a particular frame.
84
+ :ivar startup_timeout: Seconds that wait lasts, or ``None`` for
85
+ :attr:`~opensmi.ros2.server.config.ROS2Config.startup_timeout`.
86
+ :ivar path: Machine-wide; refused here.
87
+ :ivar static_path: Machine-wide; refused here.
88
+ :ivar depth: Machine-wide; refused here.
89
+ :ivar interval: Machine-wide; refused here.
90
+ :ivar quiet_after: Machine-wide; refused here.
91
+ """
92
+
93
+ kind: ClassVar[str] = "TF Binding"
94
+
95
+ head: str
96
+ alternatives: tuple[tuple[str, str], ...] = ()
97
+ publishes: tuple[PublishedFrame, ...] = ()
98
+ exclude: tuple[str, ...] = ()
99
+ # The five Machine-wide settings are fields only so that writing one gets a message saying where it
100
+ # went. None is the only allowed value.
101
+ path: str | None = None
102
+ static_path: str | None = None
103
+ depth: int | None = None
104
+ interval: float | None = None
105
+ quiet_after: float | None = None
106
+
107
+ def __post_init__(self) -> None:
108
+ """Refuse a contradictory declaration.
109
+
110
+ :raises DeclarationError: When it names no head frame, excludes its own head, declares an
111
+ alternative that is not a pair of two different frames, or publishes a frame that names no
112
+ pair, is its own parent, is declared twice or is one of its own exclusions.
113
+ :raises FrameDirectionError: When it publishes its own head frame, which is read inward.
114
+ :raises DeclarationError: When it declares where TF is read from or how often it is
115
+ polled.
116
+ :raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
117
+ is not positive.
118
+ """
119
+ self._require_a_deadline_that_means_something()
120
+ self._require_nothing_the_machine_decides()
121
+ if not self.head:
122
+ message = (
123
+ f"the TF Binding {self.name!r} names no head frame; the head is the one frame "
124
+ f"this object *is*, and without it nothing in the tree belongs to it"
125
+ )
126
+ raise DeclarationError(message)
127
+ if excluded(self.head, self.exclude):
128
+ message = (
129
+ f"the TF Binding {self.name!r} excludes its own head frame {self.head!r}; the "
130
+ f"head is this object's mandatory PositionFrame, so excluding it asks for a "
131
+ f"SpatialObject that OPC 10000-210 does not allow"
132
+ )
133
+ raise DeclarationError(message)
134
+ for alternative in self.alternatives:
135
+ self._require_a_composable_pair(alternative)
136
+ self._require_publishable_frames()
137
+
138
+ @property
139
+ def broadcasts(self) -> bool:
140
+ """Return whether this declaration puts anything on the frame network.
141
+
142
+ A Machine that publishes no frame must not appear on ``/tf`` as a publisher, since every TF
143
+ Binding reads that presence as a transform source being up.
144
+ """
145
+ return bool(self.publishes)
146
+
147
+ @property
148
+ def published_frames(self) -> frozenset[str]:
149
+ """Return the frames this declaration publishes."""
150
+ return frozenset(published.frame for published in self.publishes)
151
+
152
+ def _require_publishable_frames(self) -> None:
153
+ """Refuse outward frames that contradict each other or the declaration.
154
+
155
+ :raises DeclarationError: When a published frame names no pair, is its own parent, is declared
156
+ twice, or is excluded by this declaration.
157
+ :raises FrameDirectionError: When a published frame is this object's own head.
158
+ """
159
+ seen: set[str] = set()
160
+ for published in self.publishes:
161
+ self._require_a_publishable_pair(published)
162
+ if published.frame == self.head:
163
+ message = (
164
+ f"the TF Binding {self.name!r} publishes {published.frame!r} and that is its "
165
+ f"own head frame; the head is read *inward* -- it is the SpatialObject's "
166
+ f"mandatory PositionFrame and the poll writes it from whatever the tree says "
167
+ f"-- so a frame is inward or outward and never both. Publish a frame of its "
168
+ f"own above or below the head instead"
169
+ )
170
+ raise FrameDirectionError(message)
171
+ if excluded(published.frame, self.exclude):
172
+ message = (
173
+ f"the TF Binding {self.name!r} publishes {published.frame!r} and also excludes "
174
+ f"it; an exclusion says this object does not render that frame and publishing "
175
+ f"it says this object decides where it is, and one declaration cannot mean both"
176
+ )
177
+ raise DeclarationError(message)
178
+ if published.frame in seen:
179
+ message = (
180
+ f"the TF Binding {self.name!r} publishes {published.frame!r} twice; a frame has "
181
+ f"one parent and one publisher, so two entries are two answers to one question "
182
+ f"and which of them reached the robot would be the order they were typed in"
183
+ )
184
+ raise DeclarationError(message)
185
+ seen.add(published.frame)
186
+
187
+ def _require_a_publishable_pair(self, published: PublishedFrame) -> None:
188
+ """Refuse a published frame that is not a transform.
189
+
190
+ :raises DeclarationError: When either name is empty, or the two are one frame.
191
+ """
192
+ if published.frame and published.base and published.frame != published.base:
193
+ return
194
+ if not published.frame or not published.base:
195
+ message = (
196
+ f"the TF Binding {self.name!r} publishes (base={published.base!r}, "
197
+ f"frame={published.frame!r}), which names no transform; a published frame is "
198
+ f"*where this frame sits in that base*, so both halves are frames"
199
+ )
200
+ raise DeclarationError(message)
201
+ message = (
202
+ f"the TF Binding {self.name!r} publishes {published.frame!r} relative to itself, so it "
203
+ f"would be its own parent; tf2 gives a frame one parent and it is never the frame, and "
204
+ f"there is no transform here to put on the wire"
205
+ )
206
+ raise DeclarationError(message)
207
+
208
+ def _require_nothing_the_machine_decides(self) -> None:
209
+ """Refuse a value that belongs to the whole Machine.
210
+
211
+ :raises DeclarationError: When any of the five Machine-wide keywords carries a value.
212
+ """
213
+ written = {
214
+ name: value
215
+ for name, value in (
216
+ ("path", self.path),
217
+ ("static_path", self.static_path),
218
+ ("depth", self.depth),
219
+ ("interval", self.interval),
220
+ ("quiet_after", self.quiet_after),
221
+ )
222
+ if value is not None
223
+ }
224
+ if not written:
225
+ return
226
+ listed = ", ".join(f"{name}={value!r}" for name, value in written.items())
227
+ message = (
228
+ f"the TF Binding {self.name!r} declares {listed}; where TF is read from, how often "
229
+ f"the frame network is polled and how long a frame may go unpublished before its "
230
+ f"Location says so are facts about the Machine -- one Runtime is one Domain ID and "
231
+ f"one frame network, and one Machine runs one poll over the "
232
+ f"partition every declared head takes part in -- so they are declared once, in the "
233
+ f"[ros2.transforms] table of the machine file (ROS2Config.transforms). What stays here "
234
+ f"is what is true of this object: its head frame, its exclusions, its alternatives"
235
+ )
236
+ raise DeclarationError(message)
237
+
238
+ def _require_a_composable_pair(self, alternative: tuple[str, str]) -> None:
239
+ """Refuse an alternative that is not two different, non-empty frame names.
240
+
241
+ :raises DeclarationError: When the pair is invalid.
242
+ """
243
+ base, frame = alternative
244
+ if base and frame and base != frame:
245
+ return
246
+ message = (
247
+ f"the TF Binding {self.name!r} declares the alternative {alternative!r}; an "
248
+ f"alternative is a (base, frame) pair asking where one frame sits in another, so the "
249
+ f"two are different frames and neither of them is empty"
250
+ )
251
+ raise DeclarationError(message)
252
+
253
+ @property
254
+ def needs_the_graph(self) -> bool:
255
+ """Return ``False``: both topics carry ``tf2_msgs/msg/TFMessage`` and the frames are content."""
256
+ return False
@@ -0,0 +1,94 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """Turning names from ROS2 into browse names.
6
+
7
+ A message field or a parameter segment such as ``child_frame_id`` is browsed as ``ChildFrameId``,
8
+ which follows the opensmi naming rule. The raw ROS2 name stays as the DisplayName. A name that does
9
+ not convert is refused, never fixed silently.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from collections import defaultdict
16
+ from functools import cache
17
+ from typing import TYPE_CHECKING
18
+
19
+ from opensmi.core.paths import check_name
20
+
21
+ from opensmi.ros2.server.errors import BindingNameError, DuplicateVariableNameError
22
+
23
+ if TYPE_CHECKING:
24
+ from collections.abc import Iterable, Mapping
25
+
26
+ __all__ = ["browse_name", "browse_names", "suggested_name"]
27
+
28
+ _CONVERTIBLE = re.compile(r"[A-Za-z0-9]+(_[A-Za-z0-9]+)*")
29
+ _NOT_NAME_CHARACTERS = re.compile(r"[^A-Za-z0-9]+")
30
+
31
+
32
+ def pascal_case(parts: Iterable[str]) -> str:
33
+ """Return name parts capitalised and joined, which is how opensmi derives a browse name from a field name."""
34
+ return "".join(part[:1].upper() + part[1:] for part in parts)
35
+
36
+
37
+ def suggested_name(name: str) -> str | None:
38
+ """Return the name that follows the rule and is closest to ``name``, or ``None`` if there is none."""
39
+ suggestion = pascal_case(_NOT_NAME_CHARACTERS.split(name))
40
+ try:
41
+ check_name(suggestion)
42
+ except ValueError:
43
+ return None
44
+ return suggestion
45
+
46
+
47
+ @cache
48
+ def browse_name(ros2_name: str) -> str:
49
+ """Return the browse name for a ROS2 name: split on ``_``, capitalise each part, join.
50
+
51
+ ``child_frame_id`` gives ``ChildFrameId`` and ``FollowPath`` stays as it is. Use ``ros2_name``
52
+ itself as the DisplayName.
53
+
54
+ :raises BindingNameError: When the name has a character other than letters, digits and ``_``,
55
+ an empty part, or does not give a valid browse name (it starts with a digit, or is ``None``,
56
+ ``True`` or ``False``). The message suggests a name where one can be derived.
57
+ """
58
+ result = pascal_case(ros2_name.split("_"))
59
+ try:
60
+ if not _CONVERTIBLE.fullmatch(ros2_name):
61
+ raise ValueError(ros2_name) # noqa: TRY301
62
+ check_name(result)
63
+ except ValueError:
64
+ suggestion = suggested_name(ros2_name)
65
+ message = f"the ROS2 name {ros2_name!r} cannot be a browse name"
66
+ if suggestion is not None:
67
+ message = f"{message}; try {suggestion!r}"
68
+ raise BindingNameError(message) from None
69
+ return result
70
+
71
+
72
+ def browse_names(ros2_names: Iterable[str], renamed: Mapping[str, str] | None = None) -> dict[str, str]:
73
+ """Return the browse name of each ROS2 name among siblings, keyed by the ROS2 name.
74
+
75
+ A name in ``renamed`` takes its new name as it is, which already follows the rule.
76
+
77
+ :raises BindingNameError: When one name does not convert, see :func:`browse_name`.
78
+ :raises DuplicateVariableNameError: When two names give one browse name, such as ``x_1`` and
79
+ ``x1``. The error names both ROS2 names; the author fixes it with the ``rename`` option of the Binding.
80
+ """
81
+ new_names = renamed or {}
82
+ converted = {name: new_names.get(name) or browse_name(name) for name in ros2_names}
83
+ by_browse_name: defaultdict[str, list[str]] = defaultdict(list)
84
+ for name, browse in converted.items():
85
+ by_browse_name[browse].append(name)
86
+ for browse, names in by_browse_name.items():
87
+ if len(names) > 1:
88
+ quoted = " and ".join(repr(name) for name in names)
89
+ message = (
90
+ f"the ROS2 names {quoted} both become the browse name {browse!r}; "
91
+ f"give one of them a new name with the rename option"
92
+ )
93
+ raise DuplicateVariableNameError(message)
94
+ return converted