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.
- opensmi/ros2/__init__.py +89 -0
- opensmi/ros2/__main__.py +11 -0
- opensmi/ros2/cli.py +143 -0
- opensmi/ros2/py.typed +0 -0
- opensmi/ros2/runtime/__init__.py +67 -0
- opensmi/ros2/runtime/_decode.py +101 -0
- opensmi/ros2/runtime/_encode.py +102 -0
- opensmi/ros2/runtime/_parser.py +147 -0
- opensmi/ros2/runtime/errors.py +141 -0
- opensmi/ros2/runtime/goal.py +232 -0
- opensmi/ros2/runtime/graph.py +288 -0
- opensmi/ros2/runtime/guard.py +213 -0
- opensmi/ros2/runtime/interface.py +140 -0
- opensmi/ros2/runtime/messages/__init__.py +503 -0
- opensmi/ros2/runtime/messages/industrial_msgs.py +62 -0
- opensmi/ros2/runtime/messages/industrial_msgs.pyi +159 -0
- opensmi/ros2/runtime/messages/motoros2_interfaces.py +79 -0
- opensmi/ros2/runtime/messages/motoros2_interfaces.pyi +307 -0
- opensmi/ros2/runtime/messages/neo_msgs2.py +55 -0
- opensmi/ros2/runtime/messages/neo_msgs2.pyi +138 -0
- opensmi/ros2/runtime/messages/neo_srvs2.py +72 -0
- opensmi/ros2/runtime/messages/neo_srvs2.pyi +224 -0
- opensmi/ros2/runtime/outcomes.py +103 -0
- opensmi/ros2/runtime/parameters.py +723 -0
- opensmi/ros2/runtime/publisher.py +125 -0
- opensmi/ros2/runtime/qos.py +394 -0
- opensmi/ros2/runtime/runtime.py +1171 -0
- opensmi/ros2/runtime/selection.py +150 -0
- opensmi/ros2/runtime/stamp.py +100 -0
- opensmi/ros2/runtime/subscription.py +354 -0
- opensmi/ros2/runtime/tf.py +714 -0
- opensmi/ros2/server/__init__.py +148 -0
- opensmi/ros2/server/access.py +109 -0
- opensmi/ros2/server/bindings/__init__.py +92 -0
- opensmi/ros2/server/bindings/_base.py +154 -0
- opensmi/ros2/server/bindings/action.py +133 -0
- opensmi/ros2/server/bindings/keyed.py +127 -0
- opensmi/ros2/server/bindings/lifecycle.py +131 -0
- opensmi/ros2/server/bindings/method.py +130 -0
- opensmi/ros2/server/bindings/monitoring.py +109 -0
- opensmi/ros2/server/bindings/parameter.py +133 -0
- opensmi/ros2/server/bindings/publisher.py +192 -0
- opensmi/ros2/server/bindings/registry.py +95 -0
- opensmi/ros2/server/bindings/tf.py +256 -0
- opensmi/ros2/server/browse_names.py +94 -0
- opensmi/ros2/server/component.py +334 -0
- opensmi/ros2/server/config.py +493 -0
- opensmi/ros2/server/containers.py +191 -0
- opensmi/ros2/server/drivers.py +421 -0
- opensmi/ros2/server/errors.py +159 -0
- opensmi/ros2/server/events.py +406 -0
- opensmi/ros2/server/introspection.py +850 -0
- opensmi/ros2/server/keyed.py +749 -0
- opensmi/ros2/server/lifecycle.py +238 -0
- opensmi/ros2/server/limits.py +66 -0
- opensmi/ros2/server/loader.py +977 -0
- opensmi/ros2/server/machine.py +225 -0
- opensmi/ros2/server/method.py +307 -0
- opensmi/ros2/server/mirror.py +582 -0
- opensmi/ros2/server/mutation.py +992 -0
- opensmi/ros2/server/nodesets/Opc.Ua.SmartFactory.ROS2.NodeSet2.xml +85 -0
- opensmi/ros2/server/nodesets/__init__.py +18 -0
- opensmi/ros2/server/nodesets/smart_factory_ros2.py +26 -0
- opensmi/ros2/server/parameters.py +704 -0
- opensmi/ros2/server/projection.py +1176 -0
- opensmi/ros2/server/projections/__init__.py +41 -0
- opensmi/ros2/server/projections/scope.py +222 -0
- opensmi/ros2/server/provenance.py +121 -0
- opensmi/ros2/server/publisher.py +781 -0
- opensmi/ros2/server/recipes.py +514 -0
- opensmi/ros2/server/required.py +633 -0
- opensmi/ros2/server/skill.py +363 -0
- opensmi/ros2/server/spatial.py +283 -0
- opensmi/ros2/server/startup.py +626 -0
- opensmi/ros2/server/status.py +107 -0
- opensmi/ros2/server/structures.py +135 -0
- opensmi/ros2/server/transforms/__init__.py +39 -0
- opensmi/ros2/server/transforms/conversions.py +58 -0
- opensmi/ros2/server/transforms/filing.py +340 -0
- opensmi/ros2/server/transforms/mirror.py +462 -0
- opensmi/ros2/server/transforms/outward.py +180 -0
- opensmi/ros2/server/transforms/records.py +195 -0
- opensmi/ros2/server/transforms/spatial.py +154 -0
- opensmi_ros2-0.1.0.dist-info/METADATA +183 -0
- opensmi_ros2-0.1.0.dist-info/RECORD +89 -0
- opensmi_ros2-0.1.0.dist-info/WHEEL +5 -0
- opensmi_ros2-0.1.0.dist-info/entry_points.txt +2 -0
- opensmi_ros2-0.1.0.dist-info/licenses/LICENSES/MIT.txt +18 -0
- 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
|