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,238 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The correspondence between lifecycle nodes and Skill states, written down as data.
6
+
7
+ A ROS2 lifecycle node's state machine and the SkillSet continuous-skill state machine are the same
8
+ machine:
9
+
10
+ ============= ================== =========== ==============================
11
+ Skill state Lifecycle state Trigger Lifecycle transition
12
+ ============= ================== =========== ==============================
13
+ ``Halted`` ``unconfigured`` ``reset`` ``configure``
14
+ ``Ready`` ``inactive`` ``start`` ``activate``
15
+ ``Running`` ``active`` ``halt`` ``deactivate`` + ``cleanup``
16
+ ============= ================== =========== ==============================
17
+
18
+ The row ``Suspended`` / ``inactive`` / ``suspend`` / ``deactivate`` is not offered, because the
19
+ StartupSkill is never suspendable. A node observed deactivating is still read as ``Suspended`` and
20
+ the Skill follows it down to ``Halted``. ``halt`` is never ``shutdown``: ``finalized`` is terminal,
21
+ so a shut-down node could never be reset, and the shutdown transitions are absent from
22
+ :class:`LifecycleNodeTransition`.
23
+
24
+ The Binding follows the state pair of a ``transition_event``, not its ``transition`` field, which
25
+ ``rcl_lifecycle`` leaves empty on every event (verified live on Jazzy). Entering ``inactive`` from
26
+ ``configuring`` is ``Ready``, from ``deactivating`` it is ``Suspended``, and from ``activating``
27
+ (a failed activation) it is ``Halted``. opensmi's ``SkillState`` is not ordered, so :data:`_RANKS`
28
+ names every state it covers.
29
+
30
+ Everything here is a pure function of integers and enumerations. The Drivers are in
31
+ :mod:`opensmi.ros2.server.drivers` and the Skill in :mod:`opensmi.ros2.server.startup`.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ from enum import IntEnum
37
+ from typing import TYPE_CHECKING, Final
38
+
39
+ from opensmi.core import SkillState
40
+
41
+ if TYPE_CHECKING:
42
+ from collections.abc import Iterable, Mapping
43
+
44
+ from opensmi.server.mixins.skill_logic_mixins import TRIGGER
45
+
46
+ __all__ = [
47
+ "PRIMARY_STATES",
48
+ "RESTING",
49
+ "TRANSITIONS_FOR",
50
+ "TRIGGERS",
51
+ "UNDONE_BY",
52
+ "LifecycleNodeState",
53
+ "LifecycleNodeTransition",
54
+ "aggregate",
55
+ "resting_skill_state",
56
+ "skill_state_for",
57
+ "trigger_toward",
58
+ ]
59
+
60
+
61
+ class LifecycleNodeState(IntEnum):
62
+ """The states of a ROS2 managed node, with the identifiers ``lifecycle_msgs/msg/State`` gives.
63
+
64
+ The four primary states are the ones a node rests in. The transition states are what it passes
65
+ through; a ``transition_event`` names one as the state the node came from, which tells ``Ready``
66
+ from ``Suspended``.
67
+ """
68
+
69
+ UNKNOWN = 0
70
+ UNCONFIGURED = 1
71
+ INACTIVE = 2
72
+ ACTIVE = 3
73
+ FINALIZED = 4
74
+ CONFIGURING = 10
75
+ CLEANING_UP = 11
76
+ SHUTTING_DOWN = 12
77
+ ACTIVATING = 13
78
+ DEACTIVATING = 14
79
+ ERROR_PROCESSING = 15
80
+
81
+
82
+ class LifecycleNodeTransition(IntEnum):
83
+ """The transitions this project ever commands, with ``lifecycle_msgs/msg/Transition``'s ids.
84
+
85
+ Four of the nine public transitions. The three ``shutdown`` transitions and ``destroy`` end in
86
+ ``finalized``, which is terminal, so commanding one would make ``Halted`` unrecoverable;
87
+ ``create`` is what constructing the node already did.
88
+ """
89
+
90
+ CONFIGURE = 1
91
+ CLEANUP = 2
92
+ ACTIVATE = 3
93
+ DEACTIVATE = 4
94
+
95
+
96
+ PRIMARY_STATES: Final = frozenset(
97
+ {
98
+ LifecycleNodeState.UNCONFIGURED,
99
+ LifecycleNodeState.INACTIVE,
100
+ LifecycleNodeState.ACTIVE,
101
+ LifecycleNodeState.FINALIZED,
102
+ }
103
+ )
104
+ """The states a node rests in, and therefore the only ones a Skill state is read off.
105
+
106
+ A node passing through ``configuring`` is not news: the Skill is already in its own intermediate
107
+ state for the same moment.
108
+ """
109
+
110
+
111
+ TRIGGERS: Final[Mapping[SkillState, TRIGGER]] = {
112
+ SkillState.HALTED: "halt",
113
+ SkillState.READY: "reset",
114
+ SkillState.RUNNING: "start",
115
+ }
116
+ """Which trigger reaches each of the three Skill states the Skill can rest in.
117
+
118
+ The triggers are named for the act, so ``reset`` is the only way into ``Ready`` and out of
119
+ ``Halted``. ``Suspended`` has no entry because there is no ``suspend`` trigger.
120
+ """
121
+
122
+
123
+ TRANSITIONS_FOR: Final[Mapping[TRIGGER, tuple[LifecycleNodeTransition, ...]]] = {
124
+ "reset": (LifecycleNodeTransition.CONFIGURE,),
125
+ "start": (LifecycleNodeTransition.ACTIVATE,),
126
+ "halt": (LifecycleNodeTransition.DEACTIVATE, LifecycleNodeTransition.CLEANUP),
127
+ }
128
+ """What each Skill trigger sends at the robot, in order.
129
+
130
+ ``halt`` is two ordered steps: an ``active`` node has to be deactivated before it can be cleaned
131
+ up, and an ``inactive`` one does not offer the first. The Driver's gate decides which go out.
132
+ """
133
+
134
+
135
+ UNDONE_BY: Final[Mapping[LifecycleNodeTransition, LifecycleNodeTransition]] = {
136
+ LifecycleNodeTransition.DEACTIVATE: LifecycleNodeTransition.ACTIVATE,
137
+ LifecycleNodeTransition.CLEANUP: LifecycleNodeTransition.CONFIGURE,
138
+ }
139
+ """Which transition a ``halt`` step rolls back: ``deactivate`` undoes ``activate``, ``cleanup``
140
+ undoes ``configure``.
141
+
142
+ A ``halt`` sends a step only when the StartupSkill itself performed the transition it undoes
143
+ , so a node that was already ``active`` is left as it was found.
144
+ """
145
+
146
+
147
+ _RANKS: Final[Mapping[SkillState, int]] = {
148
+ SkillState.HALTED: 0,
149
+ SkillState.READY: 1,
150
+ SkillState.SUSPENDED: 1,
151
+ SkillState.RUNNING: 2,
152
+ }
153
+ """How much each Skill state claims about a node, which is what "lowest wins" compares.
154
+
155
+ ``Ready`` and ``Suspended`` share a rank because both are ``inactive`` and both accept ``start``.
156
+ """
157
+
158
+
159
+ RESTING: Final = frozenset({SkillState.HALTED, SkillState.READY, SkillState.RUNNING})
160
+ """The three Skill states a StartupSkill rests in.
161
+
162
+ ``Suspended`` can be observed on a node (it ranks in :data:`_RANKS`) but never entered.
163
+ """
164
+
165
+
166
+ def resting_skill_state(state: LifecycleNodeState | int) -> SkillState | None:
167
+ """Return the Skill state one resting lifecycle state means, with no route to read.
168
+
169
+ ``unconfigured`` and ``finalized`` are ``Halted``, ``active`` is ``Running`` and ``inactive``
170
+ is ``Ready``. A node in a transition state answers ``None`` (no opinion). ``finalized`` differs
171
+ from ``unconfigured`` only by the Binding being Terminal, which refuses ``Reset``.
172
+ """
173
+ if state == LifecycleNodeState.ACTIVE:
174
+ return SkillState.RUNNING
175
+ if state == LifecycleNodeState.INACTIVE:
176
+ return SkillState.READY
177
+ if state in (LifecycleNodeState.UNCONFIGURED, LifecycleNodeState.FINALIZED):
178
+ return SkillState.HALTED
179
+ return None
180
+
181
+
182
+ def skill_state_for(*, start: LifecycleNodeState | int, goal: LifecycleNodeState | int) -> SkillState | None:
183
+ """Return the Skill state one observed transition puts a node in, from the pair alone.
184
+
185
+ :param start: The state the node left, as ``transition_event.start_state.id``.
186
+ :param goal: The state it entered, as ``transition_event.goal_state.id``.
187
+ :return: The Skill state, or ``None`` when the node merely entered a transition state.
188
+ """
189
+ if goal != LifecycleNodeState.INACTIVE:
190
+ return resting_skill_state(goal)
191
+ if start == LifecycleNodeState.DEACTIVATING:
192
+ return SkillState.SUSPENDED
193
+ if start == LifecycleNodeState.ACTIVATING:
194
+ # A failed activation lands Halted, like a failed command of ours.
195
+ return SkillState.HALTED
196
+ # `errorprocessing` has no branch: ROS2 resolves it to `unconfigured` or `finalized`.
197
+ return SkillState.READY
198
+
199
+
200
+ def _rank(state: SkillState) -> int:
201
+ """Return how much a Skill state claims: ``0`` halted, ``1`` inactive, ``2`` running.
202
+
203
+ :raises KeyError: For a state outside the correspondence (intermediate states, ``Completed``).
204
+ """
205
+ return _RANKS[state]
206
+
207
+
208
+ def aggregate(states: Iterable[SkillState | None]) -> SkillState | None:
209
+ """Return what several nodes under one Skill say together: lowest wins.
210
+
211
+ ``Running`` means every node is active. A node nobody has heard from contributes
212
+ ``None`` and is skipped, so a node that vanishes while the Skill is ``Running`` does not halt
213
+ it. Between equal ranks the answer is ``Suspended`` if any node reported one.
214
+
215
+ :return: The lowest-ranked state anything reported, or ``None`` when nothing has.
216
+ """
217
+ known = [state for state in states if state is not None]
218
+ if not known:
219
+ return None
220
+ lowest = min(_rank(state) for state in known)
221
+ tied = [state for state in known if _rank(state) == lowest]
222
+ return SkillState.SUSPENDED if SkillState.SUSPENDED in tied else tied[0]
223
+
224
+
225
+ def trigger_toward(current: SkillState, target: SkillState) -> TRIGGER | None:
226
+ """Return the trigger that moves a Skill from where it is toward what its nodes report.
227
+
228
+ Only downward, and always ``halt``. Following a robot down keeps the
229
+ address space truthful; following it up would start a Skill nobody asked to start.
230
+
231
+ :param current: The state the Skill is in. An intermediate state answers ``None``, because a
232
+ handler is already in flight.
233
+ :param target: What :func:`aggregate` says the nodes are.
234
+ :return: ``halt``, or ``None`` when the Skill is at or below the nodes.
235
+ """
236
+ if current not in RESTING or _rank(target) >= _rank(current):
237
+ return None
238
+ return TRIGGERS[SkillState.HALTED]
@@ -0,0 +1,66 @@
1
+ # SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ """The byte-string ceiling: one number, published once and applied once.
6
+
7
+ A bulk payload (an occupancy grid, an image) is as large as its source, not as large as this package
8
+ chooses. OPC UA says how much a server can carry in
9
+ ``Server/ServerCapabilities/MaxByteStringLength`` (OPC UA Part 5). The effective ceiling, derived
10
+ from the transport limits the server actually runs with, is written there at init, and our own
11
+ outbound values are capped at it inside the Projection that produces the bytes
12
+ (:mod:`opensmi.ros2.server.recipes`). The send path has no second check.
13
+
14
+ The ceiling is smaller than the message size, because a byte string travels inside a DataValue, a
15
+ Variant, a response and a chunked message. :data:`ENVELOPE_MARGIN` holds back an allowance for that
16
+ envelope.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from typing import TYPE_CHECKING, Any, Final
22
+
23
+ from asyncua import ua
24
+ from asyncua.ua.object_ids import ObjectIds
25
+
26
+ if TYPE_CHECKING:
27
+ from asyncua.server.server import Server
28
+
29
+ __all__ = ["ENVELOPE_MARGIN", "byte_string_ceiling", "publish_byte_string_ceiling"]
30
+
31
+ ENVELOPE_MARGIN: Final = 65_536
32
+ """What is held back from the message budget for everything wrapped around the value itself."""
33
+
34
+ NO_CEILING: Final = 0
35
+ """What OPC UA writes in a capability variable to say a limit does not apply."""
36
+
37
+
38
+ def byte_string_ceiling(*, max_message_size: int) -> int:
39
+ """Return the largest byte string this server can carry, given its message budget.
40
+
41
+ A pure function of one number. A small budget gets a small ceiling and never zero: the envelope
42
+ allowance is capped at half the budget, because zero in this capability variable means that no
43
+ limit applies.
44
+
45
+ :param max_message_size: The transport's limit in bytes, or ``0`` for no limit.
46
+ """
47
+ if max_message_size <= NO_CEILING:
48
+ return NO_CEILING
49
+ margin = min(ENVELOPE_MARGIN, max_message_size // 2)
50
+ return max(max_message_size - margin, 1)
51
+
52
+
53
+ async def publish_byte_string_ceiling(server: Server) -> int:
54
+ """Write this server's effective ceiling into its capability variable, and return it.
55
+
56
+ Idempotent. The limits are read off the server, not off our configuration, so a client reads the
57
+ number the transport will accept.
58
+
59
+ :param server: The asyncua server the Machine was built on.
60
+ """
61
+ limits: Any = server.limits
62
+ ceiling = byte_string_ceiling(max_message_size=int(limits.max_message_size))
63
+ identifier = ua.Int32(ObjectIds.Server_ServerCapabilities_MaxByteStringLength)
64
+ node = server.get_node(ua.NodeId(identifier))
65
+ await node.write_value(ua.Variant(ua.UInt32(ceiling), ua.VariantType.UInt32))
66
+ return ceiling