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,213 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The type-mismatch guard: what may be put into a ROS2 message, and what aborts the process.
6
+
7
+ A ROS2 message field given a value of the wrong Python type does not raise in ``rclpy``. The C
8
+ conversion that runs when the message is sent dies on ``Assertion 'PyFloat_Check(field)' failed``,
9
+ a ``SIGABRT`` that takes down every Component and the OPC UA endpoint (pinned by a Jazzy test).
10
+ The check therefore uses exact types, not ``isinstance``: ``1`` is not a ``float64`` and ``True``
11
+ is not an ``int32``.
12
+
13
+ A value out of its field's range is refused too: ``2**31`` into an ``int32`` goes onto the wire
14
+ wrong. Declared bounds (``string<256>``, ``sequence<double, 3>``, ``double[9]``) are enforced here
15
+ as well, since OPC UA advertises a bound and enforces none.
16
+
17
+ The guard is a pure function of a message dataclass. The Runtime calls it on every goal it sends
18
+ and every message it publishes; the server half calls it at declaration time on the initial
19
+ values, so defaults that could never be sent fail at init.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ from typing import TYPE_CHECKING, Final
25
+
26
+ from opensmi.ros2.runtime.errors import FieldTypeMismatchError, FieldValueOutOfRangeError
27
+ from opensmi.ros2.runtime.messages import (
28
+ ArrayType,
29
+ Message,
30
+ NestedType,
31
+ PrimitiveType,
32
+ SequenceType,
33
+ StringType,
34
+ is_byte_container,
35
+ )
36
+ from opensmi.ros2.runtime.selection import SEPARATOR
37
+
38
+ if TYPE_CHECKING:
39
+ from collections.abc import Mapping, Sized
40
+
41
+ from opensmi.ros2.runtime.messages import ElementType, FieldType, PrimitiveName
42
+
43
+ __all__ = ["INTEGER_RANGES", "require_sendable"]
44
+
45
+ INTEGER_RANGES: Final[Mapping[str, tuple[int, int]]] = {
46
+ "byte": (0, 255),
47
+ "int8": (-(2**7), 2**7 - 1),
48
+ "int16": (-(2**15), 2**15 - 1),
49
+ "int32": (-(2**31), 2**31 - 1),
50
+ "int64": (-(2**63), 2**63 - 1),
51
+ "uint8": (0, 2**8 - 1),
52
+ "uint16": (0, 2**16 - 1),
53
+ "uint32": (0, 2**32 - 1),
54
+ "uint64": (0, 2**64 - 1),
55
+ }
56
+ """What each ROS2 integer type holds. ``rclpy`` checks none of these at the boundary that matters."""
57
+
58
+ # `char` and `wchar` are `str` because that is how the message dataclass annotates them.
59
+ _SCALAR_TYPES: Final[Mapping[str, type]] = {
60
+ "bool": bool,
61
+ "char": str,
62
+ "wchar": str,
63
+ "float32": float,
64
+ "float64": float,
65
+ }
66
+
67
+
68
+ def require_sendable(message: Message, *, path: str = "") -> None:
69
+ """Refuse a payload ``rclpy`` would abort the process over, or put wrong on the wire.
70
+
71
+ :param message: The payload, as an instance of the dataclass built for its ROS2 type.
72
+ :param path: The field path of this message, used in nested refusals. Empty at the root.
73
+ :raises FieldTypeMismatchError: When a value is not the Python type its ROS2 field is.
74
+ :raises FieldValueOutOfRangeError: When a value does not fit its integer width, or exceeds a
75
+ length its ROS2 field declares.
76
+ """
77
+ description = message.ros2
78
+ for field in description.fields:
79
+ _require_field(
80
+ getattr(message, field.name),
81
+ field.field_type,
82
+ message.ros2_nested.get(field.name),
83
+ _joined(path, field.name),
84
+ description.type_name,
85
+ )
86
+
87
+
88
+ def _require_field(
89
+ value: object,
90
+ field_type: FieldType,
91
+ nested: type[Message] | None,
92
+ path: str,
93
+ type_name: str,
94
+ ) -> None:
95
+ """Refuse one field's value, whatever shape the field has."""
96
+ if isinstance(field_type, (ArrayType, SequenceType)) and is_byte_container(field_type):
97
+ _require_type(value, (bytes, bytearray), "a byte container", path, type_name)
98
+ _require_length(value, field_type, path, type_name)
99
+ return
100
+ if isinstance(field_type, (ArrayType, SequenceType)):
101
+ _require_type(value, (tuple, list), f"a container of {_named(field_type.element)}", path, type_name)
102
+ _require_length(value, field_type, path, type_name)
103
+ for index, element in enumerate(value): # type: ignore[union-attr]
104
+ _require_element(element, field_type.element, nested, f"{path}[{index}]", type_name)
105
+ return
106
+ _require_element(value, field_type, nested, path, type_name)
107
+
108
+
109
+ def _require_element(
110
+ value: object,
111
+ element: ElementType,
112
+ nested: type[Message] | None,
113
+ path: str,
114
+ type_name: str,
115
+ ) -> None:
116
+ """Refuse one scalar value: a number, a string, or a whole nested message."""
117
+ match element:
118
+ case NestedType():
119
+ _require_message(value, element, nested, path, type_name)
120
+ case StringType(maximum_length=bound):
121
+ _require_type(value, (str,), _named(element), path, type_name)
122
+ _require_within(len(value), bound, "characters", path, type_name) # type: ignore[arg-type]
123
+ case PrimitiveType(name=name):
124
+ _require_primitive(value, name, path, type_name)
125
+
126
+
127
+ def _require_message(
128
+ value: object,
129
+ element: NestedType,
130
+ nested: type[Message] | None,
131
+ path: str,
132
+ type_name: str,
133
+ ) -> None:
134
+ """Refuse a nested field that does not hold the message dataclass its type says it does."""
135
+ if nested is None or not isinstance(value, nested): # pragma: no branch
136
+ _refuse_the_type(value, element.type_name, path, type_name)
137
+ require_sendable(value, path=path) # type: ignore[arg-type]
138
+
139
+
140
+ def _require_primitive(value: object, name: PrimitiveName, path: str, type_name: str) -> None:
141
+ """Refuse a number, a boolean or a character that is not exactly what its field holds."""
142
+ bounds = INTEGER_RANGES.get(name)
143
+ if bounds is None:
144
+ _require_type(value, (_SCALAR_TYPES[name],), name, path, type_name)
145
+ return
146
+ # Identity check: `bool` is a subclass of `int`, and `isinstance` would let `True` through.
147
+ if type(value) is not int:
148
+ _refuse_the_type(value, name, path, type_name)
149
+ low, high = bounds
150
+ if not low <= value <= high: # type: ignore[operator]
151
+ message = (
152
+ f"{type_name} field {path!r} is a {name}, which holds {low} to {high}, and the value "
153
+ f"is {value!r}; ROS2 takes a value past that outright and puts it on the wire wrong"
154
+ )
155
+ raise FieldValueOutOfRangeError(message)
156
+
157
+
158
+ def _require_type(value: object, expected: tuple[type, ...], named: str, path: str, type_name: str) -> None:
159
+ """Refuse a value whose Python type is not exactly one of the ones a field accepts."""
160
+ if type(value) not in expected:
161
+ _refuse_the_type(value, named, path, type_name)
162
+
163
+
164
+ def _refuse_the_type(value: object, named: str, path: str, type_name: str) -> None:
165
+ """Refuse one value, naming the field, what ROS2 wants there and what arrived."""
166
+ message = (
167
+ f"{type_name} field {path!r} is {named}, and the value is a {type(value).__name__} "
168
+ f"({value!r}); ROS2 does not raise on this, it aborts the process when the message is sent"
169
+ )
170
+ raise FieldTypeMismatchError(message)
171
+
172
+
173
+ def _require_length(value: object, field_type: ArrayType | SequenceType, path: str, type_name: str) -> None:
174
+ """Refuse a container that is not the length its ROS2 field declares."""
175
+ sized: Sized = value # type: ignore[assignment]
176
+ if isinstance(field_type, ArrayType):
177
+ if len(sized) != field_type.length:
178
+ message = (
179
+ f"{type_name} field {path!r} is a fixed-size array of {field_type.length}, and "
180
+ f"the value has {len(sized)} elements"
181
+ )
182
+ raise FieldValueOutOfRangeError(message)
183
+ return
184
+ _require_within(len(sized), field_type.maximum_length, "elements", path, type_name)
185
+
186
+
187
+ def _require_within(length: int, bound: int | None, what: str, path: str, type_name: str) -> None:
188
+ """Refuse a length past a bound the ROS2 definition declared, if it declared one."""
189
+ if bound is None or length <= bound:
190
+ return
191
+ message = (
192
+ f"{type_name} field {path!r} is bounded at {bound} {what}, and the value has {length}; "
193
+ f"OPC UA advertises a bound and enforces none, so it is enforced here"
194
+ )
195
+ raise FieldValueOutOfRangeError(message)
196
+
197
+
198
+ def _named(element: ElementType) -> str:
199
+ """Return how a refusal names the ROS2 type a value was supposed to be."""
200
+ match element:
201
+ case PrimitiveType(name=name):
202
+ return name
203
+ case StringType(wide=True):
204
+ return "a wstring"
205
+ case StringType():
206
+ return "a string"
207
+ case NestedType(type_name=type_name):
208
+ return type_name
209
+
210
+
211
+ def _joined(path: str, name: str) -> str:
212
+ """Return one field path below another, with the separator every path here uses."""
213
+ return f"{path}{SEPARATOR}{name}" if path else name
@@ -0,0 +1,140 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The seam, written down: what a Runtime is, to everything that is not one.
6
+
7
+ The Runtime's interface as a type, so the server half can name what it was injected without
8
+ importing :class:`opensmi.ros2.runtime.runtime.Runtime` (the only module that imports ``rclpy``).
9
+ A ``Protocol``, so a test double satisfies it by shape; tests compare the fake's surface against
10
+ the real Runtime's signatures.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import TYPE_CHECKING, Protocol, runtime_checkable
16
+
17
+ if TYPE_CHECKING:
18
+ from opensmi.ros2.runtime.goal import Goal
19
+ from opensmi.ros2.runtime.graph import GraphFacet
20
+ from opensmi.ros2.runtime.messages import ActionTypes, Message, ServiceTypes
21
+ from opensmi.ros2.runtime.outcomes import StopOutcome
22
+ from opensmi.ros2.runtime.parameters import ParameterFacet
23
+ from opensmi.ros2.runtime.publisher import Publisher
24
+ from opensmi.ros2.runtime.qos import EndpointInfo, QoSProfile
25
+ from opensmi.ros2.runtime.subscription import Subscription
26
+ from opensmi.ros2.runtime.tf import TFFacet
27
+
28
+ __all__ = ["RuntimeInterface"]
29
+
30
+
31
+ @runtime_checkable
32
+ class RuntimeInterface(Protocol):
33
+ """All ROS2 access for one Machine, as the rest of the package sees it.
34
+
35
+ The docstrings of :class:`~opensmi.ros2.runtime.runtime.Runtime` describe the behaviour.
36
+ """
37
+
38
+ @property
39
+ def domain_id(self) -> int:
40
+ """Return the ROS2 Domain ID this Runtime is confined to."""
41
+ ...
42
+
43
+ @property
44
+ def node_name(self) -> str:
45
+ """Return the name of the single ``rclpy`` Node this Runtime owns."""
46
+ ...
47
+
48
+ @property
49
+ def started(self) -> bool:
50
+ """Return whether the Context, Node and executor thread are up."""
51
+ ...
52
+
53
+ @property
54
+ def graph(self) -> GraphFacet:
55
+ """Return the facet answering what is on the ROS2 graph."""
56
+ ...
57
+
58
+ @property
59
+ def parameters(self) -> ParameterFacet:
60
+ """Return the facet answering what a ROS2 node's parameters are, and writing them."""
61
+ ...
62
+
63
+ @property
64
+ def tf(self) -> TFFacet:
65
+ """Return the facet answering what the TF frame network looks like, and where a frame sits."""
66
+ ...
67
+
68
+ async def start(self) -> None:
69
+ """Bring up the Context, the Node and the executor thread."""
70
+ ...
71
+
72
+ async def stop(self) -> StopOutcome:
73
+ """Close every open subscription, then tear the ROS2 objects down."""
74
+ ...
75
+
76
+ async def subscribe(
77
+ self,
78
+ *,
79
+ topic: str,
80
+ message_type: str | type[Message],
81
+ depth: int = 10,
82
+ qos: QoSProfile | None = None,
83
+ ) -> Subscription:
84
+ """Subscribe to a ROS2 topic, and return the handle that owns the subscription."""
85
+ ...
86
+
87
+ async def advertise(
88
+ self,
89
+ *,
90
+ topic: str,
91
+ message_type: str | type[Message],
92
+ depth: int = 10,
93
+ qos: QoSProfile | None = None,
94
+ ) -> Publisher:
95
+ """Advertise a ROS2 topic, and return the handle that owns the publisher."""
96
+ ...
97
+
98
+ def publishers_on(self, topic: str) -> tuple[EndpointInfo, ...]:
99
+ """Return what every publisher on a topic offers, as the QoS resolver takes it."""
100
+ ...
101
+
102
+ def describe_message(self, message_type: str) -> type[Message]:
103
+ """Return the message dataclass of a ROS2 message type."""
104
+ ...
105
+
106
+ def default_message(self, message_type: type[Message]) -> Message:
107
+ """Return a message of a type as its generated ROS2 class constructs it, with no arguments."""
108
+ ...
109
+
110
+ def describe_action(self, action_type: str) -> ActionTypes:
111
+ """Return the goal, feedback and result message dataclasses of a ROS2 action type."""
112
+ ...
113
+
114
+ def describe_service(self, service_type: str) -> ServiceTypes:
115
+ """Return the request and response message dataclasses of a ROS2 service type."""
116
+ ...
117
+
118
+ async def call_service(
119
+ self,
120
+ *,
121
+ service: str,
122
+ service_type: str | ServiceTypes,
123
+ request: Message,
124
+ server_timeout: float = 10.0,
125
+ call_timeout: float = 30.0,
126
+ ) -> Message:
127
+ """Call one ROS2 service and return the response it answered with."""
128
+ ...
129
+
130
+ async def send_goal(
131
+ self,
132
+ *,
133
+ action: str,
134
+ action_type: str | ActionTypes,
135
+ goal: Message,
136
+ depth: int = 10,
137
+ server_timeout: float = 10.0,
138
+ ) -> Goal:
139
+ """Send one goal to a ROS2 action server, and return the handle that owns it."""
140
+ ...