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,127 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""A repeated message field rendered as one member per key."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from typing import ClassVar
|
|
11
|
+
|
|
12
|
+
from opensmi.ros2.runtime.qos import QoSProfile
|
|
13
|
+
from opensmi.ros2.runtime.selection import FieldSelection
|
|
14
|
+
from opensmi.ros2.server.bindings._base import AwaitedBinding
|
|
15
|
+
from opensmi.ros2.server.errors import (
|
|
16
|
+
DeclarationError,
|
|
17
|
+
)
|
|
18
|
+
from opensmi.ros2.server.events import Severity
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
22
|
+
class KeyedBinding(AwaitedBinding):
|
|
23
|
+
"""A ROS2 topic whose repeated field becomes one OPC UA member per key.
|
|
24
|
+
|
|
25
|
+
``/diagnostics`` keyed by ``status[]`` on ``hardware_id`` and ``name`` is the real instance. The
|
|
26
|
+
repeated field and the key fields are declared; membership is taken from
|
|
27
|
+
the messages. The TF tree is keyed in the same sense but has its own declaration,
|
|
28
|
+
:class:`TFBinding`, because its members are OPC 10000-210 Locations. It renders the members only: for
|
|
29
|
+
the fields beside the repeated one, declare a :class:`MonitoringBinding` narrowed to them.
|
|
30
|
+
|
|
31
|
+
The number of members is capped by
|
|
32
|
+
:attr:`~opensmi.ros2.server.mutation.ROS2MutationMixin.mutation_node_cap` on the Component and its
|
|
33
|
+
Machine's total. A Binding whose members stop appearing has reached one of them and reports a
|
|
34
|
+
BindingEvent.
|
|
35
|
+
|
|
36
|
+
:ivar name: The Binding's name, the group its members sit in. A member browses as
|
|
37
|
+
``<name>/<key>`` (a variable group) with each of ``/ . < > : # ! &`` in the key replaced by ``_``, shows the raw
|
|
38
|
+
key as its DisplayName, and holds its variables below it. The names reserved on
|
|
39
|
+
:class:`MonitoringBinding` are reserved here too.
|
|
40
|
+
:ivar group: The Machinery Monitoring sub-structure the Binding's group is filed in, as on
|
|
41
|
+
:class:`MonitoringBinding`. A member then browses as ``<group>/<name>/<key>``.
|
|
42
|
+
:ivar path: The ROS2 topic.
|
|
43
|
+
:ivar message_type: The ROS2 type, ``package/Name`` or ``package/kind/Name``. Required, since the
|
|
44
|
+
member shape and the aggregate come from the element type.
|
|
45
|
+
:ivar repeated_field: The field whose elements become members. Anything but a repeated message
|
|
46
|
+
field of ``message_type`` is fatal at init.
|
|
47
|
+
:ivar key: The fields of one element that together name its member, in browse-name order. A
|
|
48
|
+
sequence, since ``hardware_id`` tells two identical units apart.
|
|
49
|
+
:ivar state_field: The one field of a member whose change is worth an event, or ``None``.
|
|
50
|
+
Declaring it gives a BindingEvent on every write that moves it, and a variable
|
|
51
|
+
``Worst<StateField>`` with the highest value any member holds.
|
|
52
|
+
:ivar states: What each value of ``state_field`` is called, which mints the enumeration a client
|
|
53
|
+
reads labels from. The value is the ROS2 constant's own.
|
|
54
|
+
:ivar severities: The band a transition into each state is reported at. Without it every
|
|
55
|
+
transition is information.
|
|
56
|
+
:ivar include: Field patterns narrowing the element; empty means every field.
|
|
57
|
+
:ivar exclude: Field patterns removing element fields, after ``include`` has narrowed.
|
|
58
|
+
:ivar rename: New browse names by field path, as on :class:`MonitoringBinding`.
|
|
59
|
+
:ivar depth: How many messages the subscription buffers.
|
|
60
|
+
:ivar qos: The QoS profile to request, or ``None`` to discover one, as on :class:`MonitoringBinding`.
|
|
61
|
+
:ivar required: Whether the StartupSkill waits for a publisher on this topic before ``Running``.
|
|
62
|
+
Presence only, never membership.
|
|
63
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for
|
|
64
|
+
:attr:`~opensmi.ros2.server.config.ROS2Config.startup_timeout`.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
kind: ClassVar[str] = "Keyed Binding"
|
|
68
|
+
|
|
69
|
+
path: str
|
|
70
|
+
message_type: str
|
|
71
|
+
repeated_field: str
|
|
72
|
+
key: tuple[str, ...]
|
|
73
|
+
state_field: str | None = None
|
|
74
|
+
states: dict[int, str] = field(default_factory=dict)
|
|
75
|
+
severities: dict[int, Severity] = field(default_factory=dict)
|
|
76
|
+
include: tuple[str, ...] = ()
|
|
77
|
+
exclude: tuple[str, ...] = ()
|
|
78
|
+
rename: dict[str, str] = field(default_factory=dict)
|
|
79
|
+
depth: int = 10
|
|
80
|
+
qos: QoSProfile | None = None
|
|
81
|
+
group: str | None = None
|
|
82
|
+
|
|
83
|
+
def __post_init__(self) -> None:
|
|
84
|
+
"""Refuse a contradictory declaration, and re-key the two maps to integers.
|
|
85
|
+
|
|
86
|
+
TOML table keys are strings, and a state value is a number.
|
|
87
|
+
|
|
88
|
+
:raises DeclarationError: When the Binding keys on nothing, names state labels or severities
|
|
89
|
+
without a state field, takes a name the Machinery Monitoring reserves, or names a ``group``
|
|
90
|
+
that is not one of its four.
|
|
91
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
92
|
+
is not positive.
|
|
93
|
+
"""
|
|
94
|
+
self._require_a_name_that_can_be_browsed()
|
|
95
|
+
self._require_a_name_machinery_monitoring_leaves_free()
|
|
96
|
+
self._require_a_machinery_group(self.group)
|
|
97
|
+
self._require_new_names_that_follow_the_rule("rename", self.rename)
|
|
98
|
+
self._require_a_deadline_that_means_something()
|
|
99
|
+
if not self.key:
|
|
100
|
+
message = (
|
|
101
|
+
f"the Keyed Binding {self.name!r} keys on nothing; the key is what names a "
|
|
102
|
+
f"member, and a set whose elements have no names is a list"
|
|
103
|
+
)
|
|
104
|
+
raise DeclarationError(message)
|
|
105
|
+
if self.state_field is None and (self.states or self.severities):
|
|
106
|
+
message = (
|
|
107
|
+
f"the Keyed Binding {self.name!r} declares what its states mean and names no "
|
|
108
|
+
f"state_field; labels and severities describe the one field whose change is an "
|
|
109
|
+
f"event, so without it they describe nothing"
|
|
110
|
+
)
|
|
111
|
+
raise DeclarationError(message)
|
|
112
|
+
object.__setattr__(self, "states", {int(value): label for value, label in self.states.items()})
|
|
113
|
+
object.__setattr__(
|
|
114
|
+
self,
|
|
115
|
+
"severities",
|
|
116
|
+
{int(value): Severity(band) for value, band in self.severities.items()},
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
@property
|
|
120
|
+
def selection(self) -> FieldSelection:
|
|
121
|
+
"""Return the field selection, which narrows one element and not the message."""
|
|
122
|
+
return FieldSelection(include=self.include, exclude=self.exclude, rename=self.rename)
|
|
123
|
+
|
|
124
|
+
@property
|
|
125
|
+
def needs_the_graph(self) -> bool:
|
|
126
|
+
"""Return ``False``: the member plan is known at init and membership comes from the messages."""
|
|
127
|
+
return False
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""A ROS2 lifecycle node behind the StartupSkill."""
|
|
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
|
+
ImplementationClassError,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
20
|
+
class LifecycleBinding(AwaitedBinding):
|
|
21
|
+
"""A ROS2 lifecycle node driving the declaring Component's StartupSkill.
|
|
22
|
+
|
|
23
|
+
A managed node's state machine and the continuous-skill state machine are the same, so this lands on
|
|
24
|
+
the StartupSkill opensmi already has. ``Halted``, ``Ready`` and ``Running`` are
|
|
25
|
+
``unconfigured``, ``inactive`` and ``active``. The triggers ``reset``, ``start`` and ``halt`` send
|
|
26
|
+
``configure``, ``activate`` and ``deactivate`` then ``cleanup``. ``halt`` is never ``shutdown``, because
|
|
27
|
+
``finalized`` is terminal and the Skill could not be ``Reset``. There is no ``suspend``, since the
|
|
28
|
+
StartupSkill is not suspendable.
|
|
29
|
+
|
|
30
|
+
The Binding is two-way. Transitions somebody else caused move the Skill, downward only, because
|
|
31
|
+
starting is a client-driven contract. Several of these on one Component drive the one
|
|
32
|
+
StartupSkill, with a lowest-wins aggregate: ``Running`` means every node is active.
|
|
33
|
+
|
|
34
|
+
The coordinator flavour is a :class:`~opensmi.ros2.server.drivers.LifecycleDriver` (the standard
|
|
35
|
+
``lifecycle_msgs`` services, or a nav2-style manager), and the OPC UA surface is the same for each.
|
|
36
|
+
|
|
37
|
+
:ivar name: The Binding's name. It is not a Skill name (the Skill is the Component's StartupSkill);
|
|
38
|
+
it keeps declarations apart, prefixes this Binding's variables and names the ``BindingEvent``
|
|
39
|
+
source.
|
|
40
|
+
:ivar path: The ROS2 node this declaration commands through: the managed node itself for the standard
|
|
41
|
+
flavour, the manager for a nav2-style one.
|
|
42
|
+
:ivar nodes: The lifecycle nodes observed and gated on, when ``path`` is a coordinator. Empty for the
|
|
43
|
+
standard flavour; required (fatal at init if empty) for a flavour that coordinates a set.
|
|
44
|
+
:ivar driver: The coordinator flavour: a name in :data:`~opensmi.ros2.server.drivers.DRIVERS`
|
|
45
|
+
(``lifecycle``, the ROS2 standard, or ``nav2``) or a subclass of
|
|
46
|
+
:class:`~opensmi.ros2.server.drivers.LifecycleDriver`. A Binding file gives a name; a machine
|
|
47
|
+
file can give a class as ``driver_type``, by import path. Fatal at init when it is neither.
|
|
48
|
+
:ivar depth: The ROS2 queue depth of the ``transition_event`` subscription of each node.
|
|
49
|
+
:ivar server_timeout: Seconds a question or command waits for the node's services before giving up on
|
|
50
|
+
that attempt. A node that is off is a runtime condition and the next appearance looks again.
|
|
51
|
+
:ivar call_timeout: Seconds to wait for an answer once the request has gone.
|
|
52
|
+
:ivar required: Whether the StartupSkill waits for its nodes to be on the graph before ``Running``.
|
|
53
|
+
A managed node is present when it publishes ``transition_event``, so a ``finalized``
|
|
54
|
+
node still counts.
|
|
55
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for the deployment's default. Refused when the
|
|
56
|
+
Binding is constructed without ``required``.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
kind: ClassVar[str] = "lifecycle Binding"
|
|
60
|
+
|
|
61
|
+
path: str
|
|
62
|
+
nodes: tuple[str, ...] = ()
|
|
63
|
+
driver: str | type = "lifecycle"
|
|
64
|
+
depth: int = 10
|
|
65
|
+
server_timeout: float = 10.0
|
|
66
|
+
call_timeout: float = 30.0
|
|
67
|
+
|
|
68
|
+
def __post_init__(self) -> None:
|
|
69
|
+
"""Refuse a declaration that names a coordinator that cannot be built.
|
|
70
|
+
|
|
71
|
+
:raises ImplementationClassError: When ``driver`` is a class that is not a LifecycleDriver subclass.
|
|
72
|
+
:raises DeclarationError: When ``driver`` names no registered flavour, or a flavour whose ``path``
|
|
73
|
+
is a coordinator is given no nodes to drive.
|
|
74
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
75
|
+
is not positive.
|
|
76
|
+
"""
|
|
77
|
+
self._require_a_name_that_can_be_browsed()
|
|
78
|
+
self._require_a_deadline_that_means_something()
|
|
79
|
+
# Imported here to keep this module cheap to import.
|
|
80
|
+
from opensmi.ros2.server.drivers import DRIVERS, LifecycleDriver
|
|
81
|
+
|
|
82
|
+
driver = self.driver
|
|
83
|
+
if isinstance(driver, str):
|
|
84
|
+
if driver not in DRIVERS:
|
|
85
|
+
listed = ", ".join(sorted(DRIVERS))
|
|
86
|
+
message = (
|
|
87
|
+
f"the lifecycle Binding {self.name!r} names the coordinator flavour "
|
|
88
|
+
f"{driver!r}, and the flavours that ship are: {listed}; a third one is a "
|
|
89
|
+
f"LifecycleDriver subclass given as driver="
|
|
90
|
+
)
|
|
91
|
+
raise DeclarationError(message)
|
|
92
|
+
elif isinstance(driver, type):
|
|
93
|
+
if not issubclass(driver, LifecycleDriver):
|
|
94
|
+
message = (
|
|
95
|
+
f"the lifecycle Binding {self.name!r} names {driver.__name__} as its Driver, and it is "
|
|
96
|
+
f"not a subclass of LifecycleDriver; a Driver knows one coordinator flavour "
|
|
97
|
+
f"and holds no state machine"
|
|
98
|
+
)
|
|
99
|
+
raise ImplementationClassError(message)
|
|
100
|
+
else:
|
|
101
|
+
message = (
|
|
102
|
+
f"the lifecycle Binding {self.name!r} gives {driver!r} as its driver, and it is "
|
|
103
|
+
f"neither a name nor a LifecycleDriver subclass"
|
|
104
|
+
)
|
|
105
|
+
raise DeclarationError(message)
|
|
106
|
+
# Read off the resolved class, so a custom Driver answers it too.
|
|
107
|
+
resolved = self.driver_class
|
|
108
|
+
if resolved.coordinates_a_set and not self.nodes:
|
|
109
|
+
message = (
|
|
110
|
+
f"the lifecycle Binding {self.name!r} is driven by {resolved.__name__}, whose "
|
|
111
|
+
f"path is the coordinator rather than a managed node, and it lists no nodes; a "
|
|
112
|
+
f"coordinator has no lifecycle state of its own to follow"
|
|
113
|
+
)
|
|
114
|
+
raise DeclarationError(message)
|
|
115
|
+
|
|
116
|
+
@property
|
|
117
|
+
def driver_class(self) -> type:
|
|
118
|
+
"""Return the Driver class ``driver`` selects, looking a name up in the registry."""
|
|
119
|
+
from opensmi.ros2.server.drivers import DRIVERS
|
|
120
|
+
|
|
121
|
+
return DRIVERS[self.driver] if isinstance(self.driver, str) else self.driver
|
|
122
|
+
|
|
123
|
+
@property
|
|
124
|
+
def observed(self) -> tuple[str, ...]:
|
|
125
|
+
"""Return the lifecycle nodes this Binding follows: ``nodes``, or ``path`` when that is empty."""
|
|
126
|
+
return self.nodes or (self.path,)
|
|
127
|
+
|
|
128
|
+
@property
|
|
129
|
+
def needs_the_graph(self) -> bool:
|
|
130
|
+
"""Return ``False``; whether a node is there comes from ``transition_event`` match events."""
|
|
131
|
+
return False
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""A ROS2 service called as a Method."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from collections.abc import Callable, Mapping
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from typing import ClassVar, TypeAlias
|
|
12
|
+
|
|
13
|
+
from opensmi.ros2.runtime.messages import Message
|
|
14
|
+
from opensmi.ros2.runtime.selection import FieldSelection
|
|
15
|
+
from opensmi.ros2.server.bindings._base import AwaitedBinding
|
|
16
|
+
from opensmi.ros2.server.projection import ProjectionContext
|
|
17
|
+
|
|
18
|
+
RequestFunction: TypeAlias = Callable[[type[Message], Mapping[str, object], ProjectionContext], Message]
|
|
19
|
+
"""Builds a service request from a Method's Parameters, as a pure function.
|
|
20
|
+
|
|
21
|
+
The default is :func:`opensmi.ros2.server.method.default_request_from`.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
ResponseFunction: TypeAlias = Callable[[Message, ProjectionContext], Mapping[str, object]]
|
|
25
|
+
"""Turns a service response into the values of a Method's FinalResultData, by variable name.
|
|
26
|
+
|
|
27
|
+
The default is :func:`opensmi.ros2.server.method.default_response_to`.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
32
|
+
class MethodBinding(AwaitedBinding):
|
|
33
|
+
"""A ROS2 service exposed as a Method on the declaring Component.
|
|
34
|
+
|
|
35
|
+
The request becomes the Method's Parameters (written before ``Call``) and the response its
|
|
36
|
+
FinalResultData. There is no Monitoring, since a service has no feedback. opensmi's ``Call`` takes no
|
|
37
|
+
input arguments and returns a bare status code, so anything richer than a status is in FinalResultData
|
|
38
|
+
when the call returns.
|
|
39
|
+
|
|
40
|
+
Two failures reach a client differently. A transport failure (nobody serving the path, or a server
|
|
41
|
+
that went quiet) means the call did not happen and returns a real UA status code. An application
|
|
42
|
+
failure (the service answered no) is ``Good`` plus the response in FinalResultData, unless
|
|
43
|
+
``success_field`` names the field carrying the verdict.
|
|
44
|
+
|
|
45
|
+
:ivar name: The Binding's name, also the Method's name. Its variables are named for the field path
|
|
46
|
+
alone.
|
|
47
|
+
:ivar path: The ROS2 service.
|
|
48
|
+
:ivar service_type: The ROS2 service type, ``package/srv/Name``. Required, so the address space does
|
|
49
|
+
not depend on start-up timing. A type whose package is not installed is fatal at init.
|
|
50
|
+
:ivar include: Field patterns narrowing the request; empty means every field.
|
|
51
|
+
:ivar exclude: Field patterns removing request fields, after ``include`` has narrowed. A selection
|
|
52
|
+
that leaves the request unbuildable is refused at init instead of filled from a default.
|
|
53
|
+
:ivar rename: New browse names by field path, as on :class:`MonitoringBinding`.
|
|
54
|
+
:ivar response_include: Field patterns narrowing the response.
|
|
55
|
+
:ivar response_exclude: Field patterns removing response fields.
|
|
56
|
+
:ivar response_rename: New browse names for response fields, as :attr:`rename` does.
|
|
57
|
+
:ivar success_field: The name of a ``bool`` response field carrying the service's own verdict, or
|
|
58
|
+
``None``. Never auto-detected: ROS2 has no standard success field. A field the response lacks, or
|
|
59
|
+
one that is not a ``bool``, is fatal at init.
|
|
60
|
+
:ivar server_timeout: Seconds ``Call`` waits for a service server before giving up.
|
|
61
|
+
:ivar call_timeout: Seconds to wait for the answer once the request has gone. Separate from
|
|
62
|
+
``server_timeout`` because "nothing is there" and "it is stuck" reach a client as different
|
|
63
|
+
status codes.
|
|
64
|
+
:ivar method_type: A subclass of :class:`opensmi.ros2.server.method.ROS2ServiceMethod`, or ``None``
|
|
65
|
+
for the stock one. Python-only; refused when the Binding is constructed if it is not a
|
|
66
|
+
subclass.
|
|
67
|
+
:ivar request_from: Builds the request from the Parameters, or ``None`` for the default. Python-only.
|
|
68
|
+
:ivar response_to: Turns the response into FinalResultData values, or ``None`` for the default.
|
|
69
|
+
Python-only.
|
|
70
|
+
:ivar required: Whether the StartupSkill waits for the service server to be discovered before
|
|
71
|
+
``Running``.
|
|
72
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for the deployment's default. Refused when the
|
|
73
|
+
Binding is constructed without ``required``.
|
|
74
|
+
"""
|
|
75
|
+
|
|
76
|
+
kind: ClassVar[str] = "Method Binding"
|
|
77
|
+
|
|
78
|
+
path: str
|
|
79
|
+
service_type: str
|
|
80
|
+
include: tuple[str, ...] = ()
|
|
81
|
+
exclude: tuple[str, ...] = ()
|
|
82
|
+
rename: dict[str, str] = field(default_factory=dict)
|
|
83
|
+
response_include: tuple[str, ...] = ()
|
|
84
|
+
response_exclude: tuple[str, ...] = ()
|
|
85
|
+
response_rename: dict[str, str] = field(default_factory=dict)
|
|
86
|
+
success_field: str | None = None
|
|
87
|
+
server_timeout: float = 10.0
|
|
88
|
+
call_timeout: float = 30.0
|
|
89
|
+
method_type: type | None = None
|
|
90
|
+
request_from: RequestFunction | None = None
|
|
91
|
+
response_to: ResponseFunction | None = None
|
|
92
|
+
|
|
93
|
+
def __post_init__(self) -> None:
|
|
94
|
+
"""Refuse a custom implementation class that is not a subclass of the stock one.
|
|
95
|
+
|
|
96
|
+
:raises ImplementationClassError: When ``method_type`` does not derive from
|
|
97
|
+
:class:`opensmi.ros2.server.method.ROS2ServiceMethod`.
|
|
98
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
99
|
+
is not positive.
|
|
100
|
+
"""
|
|
101
|
+
self._require_a_name_that_can_be_browsed()
|
|
102
|
+
self._require_new_names_that_follow_the_rule("rename", self.rename)
|
|
103
|
+
self._require_new_names_that_follow_the_rule("response_rename", self.response_rename)
|
|
104
|
+
self._require_a_deadline_that_means_something()
|
|
105
|
+
if self.method_type is None:
|
|
106
|
+
return
|
|
107
|
+
# Imported here: the Method annotates against this declaration.
|
|
108
|
+
from opensmi.ros2.server.method import ROS2ServiceMethod
|
|
109
|
+
|
|
110
|
+
self._require_a_subclass(
|
|
111
|
+
self.method_type,
|
|
112
|
+
ROS2ServiceMethod,
|
|
113
|
+
"a custom class adds behaviour to the stock one rather than replacing it, "
|
|
114
|
+
"and a TOML file cannot name one at all",
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
@property
|
|
118
|
+
def selection(self) -> FieldSelection:
|
|
119
|
+
"""Return the request's field selection."""
|
|
120
|
+
return FieldSelection(include=self.include, exclude=self.exclude, rename=self.rename)
|
|
121
|
+
|
|
122
|
+
@property
|
|
123
|
+
def response_selection(self) -> FieldSelection:
|
|
124
|
+
"""Return the response's field selection."""
|
|
125
|
+
return FieldSelection(include=self.response_include, exclude=self.response_exclude, rename=self.response_rename)
|
|
126
|
+
|
|
127
|
+
@property
|
|
128
|
+
def needs_the_graph(self) -> bool:
|
|
129
|
+
"""Return ``False``: the declaration carries its type."""
|
|
130
|
+
return False
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""A ROS2 topic read into Monitoring variables."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from typing import ClassVar
|
|
11
|
+
|
|
12
|
+
from opensmi.ros2.runtime.qos import QoSProfile
|
|
13
|
+
from opensmi.ros2.runtime.selection import FieldSelection
|
|
14
|
+
from opensmi.ros2.server.bindings._base import AwaitedBinding
|
|
15
|
+
from opensmi.ros2.server.errors import (
|
|
16
|
+
DeclarationError,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
21
|
+
class MonitoringBinding(AwaitedBinding):
|
|
22
|
+
"""A ROS2 topic read into Monitoring variables on the declaring Component.
|
|
23
|
+
|
|
24
|
+
:ivar name: The Binding's name. The message is one complex Variable of that name, and a
|
|
25
|
+
field browses below it as ``<name>/<field path>``. ``Status``, ``Health``, ``Process``
|
|
26
|
+
and ``Consumption`` are reserved for the Machinery Monitoring sub-structures (OPC 40001-1).
|
|
27
|
+
:ivar group: The Machinery Monitoring sub-structure the Binding is filed in, one of ``Status``,
|
|
28
|
+
``Health``, ``Process`` and ``Consumption`` (OPC 40001-1), or ``None`` to sit directly in the
|
|
29
|
+
Monitoring. With it the message browses as ``<group>/<name>/<field path>``, in a FolderType Object
|
|
30
|
+
the Component's Bindings share.
|
|
31
|
+
:ivar path: The ROS2 topic.
|
|
32
|
+
:ivar message_type: The ROS2 type, ``package/Name`` or ``package/kind/Name``, or ``None`` to take it
|
|
33
|
+
from the graph. Declaring it gives the Binding its nodes at boot, so the address space does not
|
|
34
|
+
depend on start-up timing. A type whose package is not installed is fatal at init. Leaving it
|
|
35
|
+
out is the graph-driven case: no nodes until the topic appears, and the only kind
|
|
36
|
+
that makes the Machine poll the graph.
|
|
37
|
+
:ivar include: Field patterns narrowing the message; empty means every field.
|
|
38
|
+
:ivar exclude: Field patterns removing fields, after ``include`` has narrowed.
|
|
39
|
+
:ivar rename: New browse names by field path, such as ``{"pose/position/x": "East"}``. A name is taken as is
|
|
40
|
+
and must already follow the naming rule; a path that is not rendered is refused at init. Fixes a
|
|
41
|
+
name collision without a Projection.
|
|
42
|
+
:ivar depth: How many messages the subscription buffers. It is the slack a slow event loop gets
|
|
43
|
+
before the oldest sample is dropped.
|
|
44
|
+
:ivar qos: The QoS profile to request, or ``None`` to discover one: the most permissive request
|
|
45
|
+
compatible with every current publisher, re-resolved once if the topic was empty when the
|
|
46
|
+
Binding opened, and relaxed when the middleware reports a publisher it cannot accept. Declared,
|
|
47
|
+
it is honoured exactly and never adapted. Neither is fatal or blocks startup.
|
|
48
|
+
:ivar required: Whether the StartupSkill waits for a publisher on this topic before ``Running``.
|
|
49
|
+
Presence only, never first data.
|
|
50
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for
|
|
51
|
+
:attr:`~opensmi.ros2.server.config.ROS2Config.startup_timeout`. Refused when the Binding is
|
|
52
|
+
constructed without ``required``.
|
|
53
|
+
:ivar max_rate: The most messages per second written to the variables, in hertz, or ``None`` to
|
|
54
|
+
mirror every message. The limit is per Binding, so one message's fields stay one snapshot. The
|
|
55
|
+
first message after a quiet spell is written at once, then at most one per ``1 / max_rate`` (the
|
|
56
|
+
newest), and a message still waiting when the topic stops is written at the end of its window.
|
|
57
|
+
Unwritten messages are not decoded. Above zero and at most
|
|
58
|
+
:data:`~opensmi.ros2.server.publisher.MAXIMUM_RATE`.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
kind: ClassVar[str] = "Monitoring Binding"
|
|
62
|
+
|
|
63
|
+
path: str
|
|
64
|
+
message_type: str | None = None
|
|
65
|
+
include: tuple[str, ...] = ()
|
|
66
|
+
exclude: tuple[str, ...] = ()
|
|
67
|
+
rename: dict[str, str] = field(default_factory=dict)
|
|
68
|
+
depth: int = 10
|
|
69
|
+
qos: QoSProfile | None = None
|
|
70
|
+
max_rate: float | None = None
|
|
71
|
+
group: str | None = None
|
|
72
|
+
|
|
73
|
+
def __post_init__(self) -> None:
|
|
74
|
+
"""Refuse a startup deadline nothing waits on, and a rate the server cannot keep.
|
|
75
|
+
|
|
76
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
77
|
+
is not positive.
|
|
78
|
+
:raises DeclarationError: When ``max_rate`` is not above zero and at most the publisher's ceiling,
|
|
79
|
+
the name is one the Machinery Monitoring reserves, or ``group`` is not one of its four.
|
|
80
|
+
"""
|
|
81
|
+
# Imported here: the publishing side annotates against the declarations.
|
|
82
|
+
from opensmi.ros2.server.publisher import MAXIMUM_RATE
|
|
83
|
+
|
|
84
|
+
if self.max_rate is not None and not 0 < self.max_rate <= MAXIMUM_RATE:
|
|
85
|
+
message = (
|
|
86
|
+
f"the Monitoring Binding {self.name!r} declares max_rate={self.max_rate!r}, and a "
|
|
87
|
+
f"rate limit is a positive number of writes a second no greater than "
|
|
88
|
+
f"{MAXIMUM_RATE}; leave it out to mirror every message"
|
|
89
|
+
)
|
|
90
|
+
raise DeclarationError(message)
|
|
91
|
+
self._require_a_name_that_can_be_browsed()
|
|
92
|
+
self._require_a_name_machinery_monitoring_leaves_free()
|
|
93
|
+
self._require_a_machinery_group(self.group)
|
|
94
|
+
self._require_new_names_that_follow_the_rule("rename", self.rename)
|
|
95
|
+
self._require_a_deadline_that_means_something()
|
|
96
|
+
|
|
97
|
+
@property
|
|
98
|
+
def selection(self) -> FieldSelection:
|
|
99
|
+
"""Return this Binding's field selection."""
|
|
100
|
+
return FieldSelection(include=self.include, exclude=self.exclude, rename=self.rename)
|
|
101
|
+
|
|
102
|
+
@property
|
|
103
|
+
def needs_the_graph(self) -> bool:
|
|
104
|
+
"""Return whether this Binding learns its shape only by watching the ROS2 graph.
|
|
105
|
+
|
|
106
|
+
A Binding with a declared type never reads the graph, so a Machine whose declarations all answer
|
|
107
|
+
``False`` polls zero times.
|
|
108
|
+
"""
|
|
109
|
+
return self.message_type is None
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""The parameters of a ROS2 node."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import ClassVar, Final
|
|
11
|
+
|
|
12
|
+
from opensmi.ros2.runtime.parameters import ParameterType
|
|
13
|
+
from opensmi.ros2.server.bindings._base import AwaitedBinding
|
|
14
|
+
from opensmi.ros2.server.browse_names import browse_name
|
|
15
|
+
from opensmi.ros2.server.errors import (
|
|
16
|
+
ParameterDeclarationError,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
WRITE_TIMEOUT: Final = 3.0
|
|
20
|
+
"""Seconds a client's write of a ROS2 parameter waits for the node, by default.
|
|
21
|
+
|
|
22
|
+
Below asyncua's client timeout of four seconds, so the client sees this server's ``BadTimeout`` and not
|
|
23
|
+
a timeout of its own.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
28
|
+
class ROS2ParameterBinding(AwaitedBinding):
|
|
29
|
+
"""The ROS2 parameters of one node, exposed as Parameters on the declaring Component.
|
|
30
|
+
|
|
31
|
+
One declaration per ROS2 node: its parameter services share one path and its changes arrive on
|
|
32
|
+
``/parameter_events`` under one node name. A Component that tunes two nodes declares two. The ROS2
|
|
33
|
+
qualifier is in the name because bare Parameter is opensmi vocabulary for the OPC UA variable.
|
|
34
|
+
|
|
35
|
+
Names, types and read-only marks are declared, never discovered. The nine-way
|
|
36
|
+
``rcl_interfaces/msg/ParameterValue`` union never reaches OPC UA: the declaration names one typed
|
|
37
|
+
field and the Parameter is a scalar of that type. A UA Parameter's access level is fixed when the node
|
|
38
|
+
is created, so read-only cannot be learned from the robot later. A parameter the node marks
|
|
39
|
+
read-only itself still has every write refused with ``BadNotWritable``.
|
|
40
|
+
|
|
41
|
+
A client's write is checked against the node's descriptor and sent with ``set_parameters``. The client
|
|
42
|
+
is answered ``Good`` and the value stored only when the node took it. Declaring a
|
|
43
|
+
parameter here is the only way to make it writable; the introspection Component only lists and
|
|
44
|
+
describes them.
|
|
45
|
+
|
|
46
|
+
:ivar name: The Binding's name, the group its Parameters sit in. A ROS2 name such as
|
|
47
|
+
``FollowPath.max_vel_x`` is one group per namespace level and then the variable:
|
|
48
|
+
``<name>/FollowPath/MaxVelX``, with each segment converted to a browse name.
|
|
49
|
+
:ivar path: The ROS2 node, fully qualified. A missing leading ``/`` is added.
|
|
50
|
+
:ivar parameters: Map from ROS2 parameter name to type. An empty map is fatal at init. This is the
|
|
51
|
+
one Binding with a mapping field and so the one that is not hashable; nothing here hashes a
|
|
52
|
+
Binding.
|
|
53
|
+
:ivar read_only: Names among ``parameters`` that a client may not write. A name not declared in
|
|
54
|
+
``parameters`` is fatal at init.
|
|
55
|
+
:ivar retry_interval: Seconds before a parameter not yet confirmed on the node is read again. It lifts
|
|
56
|
+
``BadNoCommunication`` from a node that was off at boot, which ``/parameter_events`` would never
|
|
57
|
+
announce. Nothing is read while every name is confirmed.
|
|
58
|
+
:ivar write_timeout: Seconds a client's write waits for the node before ``BadTimeout``. The default,
|
|
59
|
+
:data:`WRITE_TIMEOUT`, is below the client's own timeout.
|
|
60
|
+
:ivar required: Whether the StartupSkill waits for this Binding before ``Running``. Unlike other
|
|
61
|
+
kinds it is satisfied only when every declared name is confirmed on the node, so a typo leaves it
|
|
62
|
+
unsatisfied.
|
|
63
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for the deployment's default. Refused when the
|
|
64
|
+
Binding is constructed without ``required``.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
kind: ClassVar[str] = "ROS2-parameter Binding"
|
|
68
|
+
|
|
69
|
+
path: str
|
|
70
|
+
parameters: dict[str, ParameterType]
|
|
71
|
+
read_only: tuple[str, ...] = ()
|
|
72
|
+
retry_interval: float = 5.0
|
|
73
|
+
write_timeout: float = WRITE_TIMEOUT
|
|
74
|
+
|
|
75
|
+
def __post_init__(self) -> None:
|
|
76
|
+
"""Refuse a contradictory declaration.
|
|
77
|
+
|
|
78
|
+
:raises ParameterDeclarationError: When the declaration exposes nothing, marks a name read-only
|
|
79
|
+
that it does not expose, or has a retry interval or write timeout that is not positive.
|
|
80
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
81
|
+
is not positive.
|
|
82
|
+
"""
|
|
83
|
+
self._require_a_name_that_can_be_browsed()
|
|
84
|
+
self._require_a_deadline_that_means_something()
|
|
85
|
+
for parameter in self.parameters:
|
|
86
|
+
self.node_path(parameter)
|
|
87
|
+
if not self.parameters:
|
|
88
|
+
message = (
|
|
89
|
+
f"the ROS2-parameter Binding {self.name!r} declares no parameters; the names and "
|
|
90
|
+
f"their types are declared and never discovered, so a Binding with an empty map "
|
|
91
|
+
f"would expose nothing at all"
|
|
92
|
+
)
|
|
93
|
+
raise ParameterDeclarationError(message)
|
|
94
|
+
undeclared = sorted(set(self.read_only) - set(self.parameters))
|
|
95
|
+
if undeclared:
|
|
96
|
+
listed = ", ".join(repr(each) for each in undeclared)
|
|
97
|
+
them = "them" if len(undeclared) > 1 else "it"
|
|
98
|
+
message = (
|
|
99
|
+
f"the ROS2-parameter Binding {self.name!r} marks {listed} read-only and does not "
|
|
100
|
+
f"declare {them}; a read-only mark on a name this Binding does not expose is a "
|
|
101
|
+
f"Parameter somebody believes is protected"
|
|
102
|
+
)
|
|
103
|
+
raise ParameterDeclarationError(message)
|
|
104
|
+
for setting, seconds, meaning in (
|
|
105
|
+
("retry_interval", self.retry_interval, "pass before an unconfirmed name is read again"),
|
|
106
|
+
("write_timeout", self.write_timeout, "a client's write waits for the node"),
|
|
107
|
+
):
|
|
108
|
+
if seconds > 0:
|
|
109
|
+
continue
|
|
110
|
+
message = (
|
|
111
|
+
f"the ROS2-parameter Binding {self.name!r} declares {setting}={seconds!r}; it is "
|
|
112
|
+
f"how many seconds {meaning}, so it is a positive number of seconds"
|
|
113
|
+
)
|
|
114
|
+
raise ParameterDeclarationError(message)
|
|
115
|
+
|
|
116
|
+
def node_path(self, parameter: str) -> tuple[str, ...]:
|
|
117
|
+
"""Return the browse names of a parameter's namespace groups, then the variable itself.
|
|
118
|
+
|
|
119
|
+
:raises BindingNameError: When a segment does not convert, see :func:`browse_name`.
|
|
120
|
+
"""
|
|
121
|
+
return tuple(browse_name(segment) for segment in parameter.split("."))
|
|
122
|
+
|
|
123
|
+
def writable(self, parameter: str) -> bool:
|
|
124
|
+
"""Return whether a client may write one of this Binding's declared parameters."""
|
|
125
|
+
return parameter not in self.read_only
|
|
126
|
+
|
|
127
|
+
@property
|
|
128
|
+
def needs_the_graph(self) -> bool:
|
|
129
|
+
"""Return ``False``: names and types are declared.
|
|
130
|
+
|
|
131
|
+
Whether the node is there is answered by reading a parameter, not the graph.
|
|
132
|
+
"""
|
|
133
|
+
return False
|