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,334 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The Component side of the declarative API: a list of Bindings, and nothing overridden.
6
+
7
+ Mixed in ahead of opensmi's ``BaseComponent``, this turns the ``bindings`` class attribute into an
8
+ address space:
9
+
10
+ .. code-block:: python
11
+
12
+ class Platform(ROS2ComponentMixin, BaseComponent):
13
+ bindings = (
14
+ MonitoringBinding(
15
+ name="CurrentPose",
16
+ path="/current_pose",
17
+ message_type="geometry_msgs/msg/PoseStamped",
18
+ exclude=("header/stamp",),
19
+ ),
20
+ )
21
+
22
+ async def _write_identification(self) -> None: ...
23
+
24
+ A constructor may compute ``bindings`` (``self.bindings = [...]``), and ``bindings_toml`` adds
25
+ declarations from a file; the two sources union and a name collision is fatal
26
+ (:func:`opensmi.ros2.server.bindings.resolve_bindings`). A ``projections`` attribute lists the
27
+ recipes this Component renders its types with, ahead of its Machine's.
28
+
29
+ Each kind of Binding becomes a different part of the Component: Monitoring variables for a
30
+ ``MonitoringBinding`` and a ``KeyedBinding`` (:mod:`opensmi.ros2.server.keyed`), a Method for a
31
+ ``MethodBinding`` (:mod:`opensmi.ros2.server.method`), a finite Skill for an ``ActionBinding``
32
+ (:mod:`opensmi.ros2.server.skill`), ParameterSet entries for a ``ROS2ParameterBinding``
33
+ (:mod:`opensmi.ros2.server.parameters`) and a ``SpatialObject`` for a ``TFBinding``
34
+ (:mod:`opensmi.ros2.server.transforms`). The Component also gets a Notification for the events its
35
+ Bindings raise. A ``LifecycleBinding`` becomes the StartupSkill. Any declaration may be
36
+ marked ``required``: the Component then gets a StartupSkill that waits for it and halts if it is not
37
+ satisfied by its deadline (:mod:`opensmi.ros2.server.required`). A variable that is not a
38
+ message field is added the opensmi way, by overriding ``_init``.
39
+ """
40
+
41
+ from __future__ import annotations
42
+
43
+ from typing import TYPE_CHECKING, Any
44
+
45
+ from opensmi.server.base_startup_skill import BaseStartupSkill
46
+
47
+ from opensmi.ros2.server.bindings import (
48
+ ActionBinding,
49
+ KeyedBinding,
50
+ LifecycleBinding,
51
+ MethodBinding,
52
+ MonitoringBinding,
53
+ PublisherBinding,
54
+ ROS2ParameterBinding,
55
+ is_required,
56
+ resolve_bindings,
57
+ )
58
+ from opensmi.ros2.server.config import ROS2Config
59
+ from opensmi.ros2.server.errors import DeclarationError, ImplementationClassError
60
+ from opensmi.ros2.server.events import root_of
61
+ from opensmi.ros2.server.keyed import ROS2KeyedMirrorMixin
62
+ from opensmi.ros2.server.method import ROS2ServiceMethod
63
+ from opensmi.ros2.server.mirror import ROS2InwardMirrorMixin
64
+ from opensmi.ros2.server.parameters import ROS2ParameterMirrorMixin
65
+ from opensmi.ros2.server.projection import ProjectionContext
66
+ from opensmi.ros2.server.projections import DEFAULT_REGISTRY
67
+ from opensmi.ros2.server.publisher import ROS2PublisherSkill
68
+ from opensmi.ros2.server.required import ROS2StartupSkill, close_startup_skills
69
+ from opensmi.ros2.server.skill import ROS2ActionSkill
70
+ from opensmi.ros2.server.startup import ROS2LifecycleStartupSkill
71
+ from opensmi.ros2.server.transforms import ROS2SpatialMixin
72
+
73
+ if TYPE_CHECKING:
74
+ from collections.abc import Sequence
75
+ from pathlib import Path
76
+
77
+ from opensmi.ros2.runtime.interface import RuntimeInterface
78
+ from opensmi.ros2.server.bindings import Binding
79
+ from opensmi.ros2.server.projection import Projection, ProjectionRegistry
80
+
81
+ __all__ = ["ROS2ComponentMixin"]
82
+
83
+
84
+ class ROS2ComponentMixin(
85
+ ROS2ParameterMirrorMixin,
86
+ ROS2InwardMirrorMixin,
87
+ ROS2KeyedMirrorMixin,
88
+ ROS2SpatialMixin,
89
+ ):
90
+ """What a Component declares, and what becomes of it.
91
+
92
+ :cvar bindings: The Bindings this Component exposes. An instance may replace it in its
93
+ constructor.
94
+ :cvar bindings_toml: A Binding file whose declarations union with ``bindings``, or ``None``.
95
+ :cvar projections: The Projections this Component curates its own types with, ahead of its
96
+ Machine's. An instance may replace it in its constructor.
97
+ :cvar startup_skill_type: A subclass of the stock StartupSkill these declarations ask for, or
98
+ ``None`` for the stock one.
99
+ """
100
+
101
+ _resolved_bindings: tuple[Binding, ...] | None = None
102
+ _resolved_projections: ProjectionRegistry | None = None
103
+ _publisher_skills: tuple[ROS2PublisherSkill, ...] = ()
104
+
105
+ bindings: Sequence[Binding] = ()
106
+ bindings_toml: str | Path | None = None
107
+ projections: Sequence[Projection] = ()
108
+ startup_skill_type: type[ROS2StartupSkill] | None = None
109
+
110
+ @property
111
+ def runtime(self) -> RuntimeInterface:
112
+ """Return the Runtime this Component's Machine was injected with.
113
+
114
+ :raises DeclarationError: When the Machine carries no Runtime, which means it does
115
+ not use :class:`opensmi.ros2.server.machine.ROS2MachineMixin`.
116
+ """
117
+ runtime = getattr(root_of(self), "runtime", None)
118
+ if runtime is None:
119
+ message = (
120
+ f"{type(self).__name__} declares Bindings but its Machine carries no Runtime; a "
121
+ f"Machine gains one by mixing in ROS2MachineMixin and being constructed with "
122
+ f"runtime="
123
+ )
124
+ raise DeclarationError(message)
125
+ return runtime
126
+
127
+ @property
128
+ def ros2_bindings(self) -> tuple[Binding, ...]:
129
+ """Return the Bindings this Component resolved, both sources unioned.
130
+
131
+ Resolved once, on first use, and held, so a name collision is fatal at init and the
132
+ declarations cannot change under a running server.
133
+ """
134
+ if self._resolved_bindings is None:
135
+ self._resolved_bindings = resolve_bindings(self.bindings, self.bindings_toml)
136
+ return self._resolved_bindings
137
+
138
+ @property
139
+ def ros2_projections(self) -> ProjectionRegistry:
140
+ """Return the registry this Component renders its types through.
141
+
142
+ Derived from the Machine's registry with this Component's own entries ahead of it, so
143
+ precedence runs Component, Machine, shipped, generic walk. A Component whose Machine is
144
+ not a ROS2 one derives from the shipped catalogue; it cannot render anything anyway,
145
+ because its ``_init`` raises :class:`~opensmi.ros2.server.errors.DeclarationError`.
146
+ Resolved once and held, like ``ros2_bindings``.
147
+
148
+ :raises DuplicateProjectionError: When an entry covers a type the Machine already covers
149
+ and does not say ``override=True``.
150
+ """
151
+ if self._resolved_projections is None:
152
+ inherited: ProjectionRegistry = getattr(root_of(self), "ros2_projections", DEFAULT_REGISTRY)
153
+ self._resolved_projections = inherited.extended(self.projections)
154
+ return self._resolved_projections
155
+
156
+ @property
157
+ def ros2_config(self) -> ROS2Config:
158
+ """Return the ROS2 settings of the deployment this Component is part of.
159
+
160
+ A Component whose Machine is not a ROS2 one answers with the defaults.
161
+ """
162
+ return getattr(root_of(self), "ros2_config", None) or ROS2Config()
163
+
164
+ @property
165
+ def ros2_projection_context(self) -> ProjectionContext:
166
+ """Return the Projection context this Component renders through, with nothing selected.
167
+
168
+ A surface narrows it to the field paths its own selection kept.
169
+ """
170
+ return ProjectionContext(
171
+ registry=self.ros2_projections,
172
+ selected=frozenset(),
173
+ qualifier=self.ros2_projection_qualifier,
174
+ byte_string_ceiling=self._byte_string_ceiling,
175
+ )
176
+
177
+ async def _init(self) -> None:
178
+ """Let opensmi initialise the Component, then create its Binding nodes.
179
+
180
+ Every way a declaration can be wrong is fatal on this path. The StartupSkill comes first,
181
+ so it browses first in the SkillSet, then Methods, Skills, publishers, Monitoring
182
+ variables, keyed members and parameters. The SpatialObject is last, because a companion
183
+ specification's AddIn extends what the Component already is.
184
+ """
185
+ await super()._init() # pyright: ignore[reportAttributeAccessIssue]
186
+ await self._init_startup()
187
+ await self._init_methods()
188
+ await self._init_skills()
189
+ await self._init_publishers()
190
+ topics = [each for each in self.ros2_bindings if isinstance(each, MonitoringBinding)]
191
+ keyed = [each for each in self.ros2_bindings if isinstance(each, KeyedBinding)]
192
+ if topics:
193
+ await self._init_monitoring_mirror(topics, runtime=self.runtime, registry=self.ros2_projections)
194
+ if keyed:
195
+ await self._init_keyed_mirror(keyed, runtime=self.runtime, registry=self.ros2_projections)
196
+ tuned = [each for each in self.ros2_bindings if isinstance(each, ROS2ParameterBinding)]
197
+ if tuned:
198
+ await self._init_parameter_mirror(tuned, runtime=self.runtime)
199
+ await self._init_ros2_spatial_object()
200
+
201
+ async def _init_startup(self) -> None:
202
+ """Give this Component the one StartupSkill its declarations ask for, if any do.
203
+
204
+ A lifecycle Binding is the StartupSkill and a required Binding needs one to
205
+ wait for it. A Component declaring both gets the lifecycle class, which adds
206
+ the managed nodes to the other. Built here, not at the mutation chokepoint, because its
207
+ nodes exist from init and never move.
208
+
209
+ :raises DeclarationError: When this Component already carries a StartupSkill of its own.
210
+ :raises ImplementationClassError: When ``startup_skill_type`` names a class that is not a
211
+ subclass of the stock one these declarations ask for.
212
+ """
213
+ lifecycles = [each for each in self.ros2_bindings if isinstance(each, LifecycleBinding)]
214
+ required = [each for each in self.ros2_bindings if is_required(each)]
215
+ if not lifecycles and not required:
216
+ return
217
+ # One branch: which declaration asked decides the stock class, the count and the wording.
218
+ stock: type[ROS2StartupSkill]
219
+ if lifecycles:
220
+ stock, counted, asked = ROS2LifecycleStartupSkill, len(lifecycles), "lifecycle"
221
+ because = "a lifecycle Binding is the StartupSkill"
222
+ else:
223
+ stock, counted, asked = ROS2StartupSkill, len(required), "required"
224
+ because = "a required Binding is what the StartupSkill waits for"
225
+ self._require_no_startup_skill_yet(asked, counted, because)
226
+ skill_type: Any = self._require_a_startup_skill_class(stock, asked)
227
+ level = self.ros2_config.skill_access_level
228
+ if lifecycles:
229
+ skill = skill_type(bindings=tuple(lifecycles), runtime=self.runtime, minimum_access_level=level)
230
+ else:
231
+ skill = skill_type(minimum_access_level=level)
232
+ await self.add_skill(skill) # pyright: ignore[reportAttributeAccessIssue]
233
+
234
+ def _require_no_startup_skill_yet(self, asked: str, counted: int, because: str) -> None:
235
+ """Refuse a Component that registered a StartupSkill of its own and then declared one.
236
+
237
+ :param asked: What to call the declarations that asked for one, in the message.
238
+ :param counted: How many of them there are.
239
+ :param because: Why that declaration lands on the Skill this Component already has.
240
+ :raises DeclarationError: When one is already registered.
241
+ """
242
+ skills: Any = self.skill_set # pyright: ignore[reportAttributeAccessIssue]
243
+ if BaseStartupSkill.NAME not in skills:
244
+ return
245
+ existing = type(skills[BaseStartupSkill.NAME]).__name__
246
+ message = (
247
+ f"{type(self).__name__} declares {counted} {asked} Binding(s) and has already "
248
+ f"registered {existing} as its {BaseStartupSkill.NAME}; {because}, so add behaviour "
249
+ f"by naming a subclass in startup_skill_type rather than by registering a second one"
250
+ )
251
+ raise DeclarationError(message)
252
+
253
+ def _require_a_startup_skill_class(self, stock: type[ROS2StartupSkill], asked: str) -> type[ROS2StartupSkill]:
254
+ """Return the class to build this Component's StartupSkill from: its own, or the stock one.
255
+
256
+ :raises ImplementationClassError: When the named class is not a subclass of the stock one.
257
+ """
258
+ named = self.startup_skill_type
259
+ if named is None:
260
+ return stock
261
+ if not isinstance(named, type) or not issubclass(named, stock):
262
+ shown = getattr(named, "__name__", repr(named))
263
+ message = (
264
+ f"{type(self).__name__} declares {asked} Binding(s) and names {shown} as its "
265
+ f"startup_skill_type, and it is not a subclass of {stock.__name__}; a custom "
266
+ f"class adds behaviour to the stock one rather than replacing it"
267
+ )
268
+ raise ImplementationClassError(message)
269
+ return named
270
+
271
+ async def _init_methods(self) -> None:
272
+ """Add one Method per service declared, before any subscription is open."""
273
+ services = [each for each in self.ros2_bindings if isinstance(each, MethodBinding)]
274
+ if not services:
275
+ return
276
+ runtime = self.runtime
277
+ context = self.ros2_projection_context
278
+ level = self.ros2_config.skill_access_level
279
+ for binding in services:
280
+ method_type = binding.method_type or ROS2ServiceMethod
281
+ method = method_type(binding=binding, runtime=runtime, context=context, minimum_access_level=level)
282
+ await self.add_method(method) # pyright: ignore[reportAttributeAccessIssue]
283
+
284
+ async def _init_skills(self) -> None:
285
+ """Add one finite Skill per action declared, before any subscription is open."""
286
+ actions = [each for each in self.ros2_bindings if isinstance(each, ActionBinding)]
287
+ if not actions:
288
+ return
289
+ runtime = self.runtime
290
+ context = self.ros2_projection_context
291
+ config = self.ros2_config
292
+ for binding in actions:
293
+ skill_type = binding.skill_type or ROS2ActionSkill
294
+ skill = skill_type(
295
+ binding=binding,
296
+ runtime=runtime,
297
+ context=context,
298
+ config=config,
299
+ minimum_access_level=config.skill_access_level,
300
+ )
301
+ await self.add_skill(skill) # pyright: ignore[reportAttributeAccessIssue]
302
+
303
+ async def _init_publishers(self) -> None:
304
+ """Add one Skill per published topic declared, continuous or finite as it says.
305
+
306
+ The Skill advertises its publisher itself, last, so a refused declaration leaves no
307
+ endpoint behind.
308
+ """
309
+ publishers = [each for each in self.ros2_bindings if isinstance(each, PublisherBinding)]
310
+ if not publishers:
311
+ return
312
+ runtime = self.runtime
313
+ context = self.ros2_projection_context
314
+ level = self.ros2_config.skill_access_level
315
+ for binding in publishers:
316
+ skill_type = binding.skill_type or binding.stock_skill_type
317
+ skill = skill_type(binding=binding, runtime=runtime, context=context, minimum_access_level=level)
318
+ await self.add_skill(skill) # pyright: ignore[reportAttributeAccessIssue]
319
+ self._publisher_skills = (*self._publisher_skills, skill)
320
+
321
+ async def _shutdown(self) -> None:
322
+ """Stop following this Component's nodes and topics, then let opensmi shut it down.
323
+
324
+ A Component torn down inside a process that goes on serving has to release its own
325
+ endpoints; stopping the Runtime would release all of them.
326
+ """
327
+ await self._stop_parameter_mirror()
328
+ await self._stop_monitoring_mirror()
329
+ await self._stop_keyed_mirror()
330
+ await self._stop_spatial_object()
331
+ for skill in self._publisher_skills:
332
+ await skill.close_publisher()
333
+ await close_startup_skills(self)
334
+ await super()._shutdown() # pyright: ignore[reportAttributeAccessIssue]