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,148 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""The OPC UA half: a thin layer on opensmi.server that renders a Runtime as a Machine.
|
|
6
|
+
|
|
7
|
+
UA-facing classes inherit from opensmi's base classes with this project's mixins in front. The
|
|
8
|
+
Runtime is injected through the Machine's constructor. Everything exported here is what a server
|
|
9
|
+
author touches when declaring or starting a server; anything else is importable from its module but
|
|
10
|
+
not part of the public surface (see CONTRIBUTING.md).
|
|
11
|
+
|
|
12
|
+
Public names:
|
|
13
|
+
|
|
14
|
+
* Binding declarations and the callback types their fields take, the Machine and Component mixins.
|
|
15
|
+
* ``ROS2Config`` and ``TransformConfig``.
|
|
16
|
+
* The TOML loader: ``load_bindings``, ``resolve_bindings``, ``TOML_KINDS``, ``load_machine``.
|
|
17
|
+
* The Projection engine with its plan types. The recipes that curate a Component's types are the
|
|
18
|
+
namespace ``recipes`` (``recipes.Enum``), since ``Enum`` would shadow ``enum.Enum``.
|
|
19
|
+
* The three access-level constants, ``Severity`` and ``SmartFactoryROS2NodeIds``.
|
|
20
|
+
* The lifecycle drivers with ``LifecycleNodeState`` and ``LifecycleNodeTransition``. A custom driver
|
|
21
|
+
subclasses ``LifecycleDriver`` and is given as a Binding's ``driver``.
|
|
22
|
+
|
|
23
|
+
Errors raised for a bad declaration are in :mod:`opensmi.ros2.server.errors`. The command line is
|
|
24
|
+
public as a command (``opensmi-ros2 serve``, ``--server-config``, the exit status), not as a module.
|
|
25
|
+
``load_toml`` and ``from_dict`` share names with ``opensmi.core.config`` but behave differently and
|
|
26
|
+
are internal.
|
|
27
|
+
|
|
28
|
+
What a client sees:
|
|
29
|
+
|
|
30
|
+
* A write to a ROS2 parameter is answered by the owning node. A refused write comes back as a Bad
|
|
31
|
+
status code and the variable keeps the node's value.
|
|
32
|
+
* Skills and Methods need the Lock, which times out after ten minutes without activity, as in
|
|
33
|
+
opensmi. Introspection listings do not need it.
|
|
34
|
+
* A message is a complex variable with one child variable per field, named from the ROS2 field in
|
|
35
|
+
PascalCase (``Odom/Pose/Pose/Position/X``). A repeated field is one array variable whose element is
|
|
36
|
+
a structure type named after the ROS2 type.
|
|
37
|
+
* The address space grows but never shrinks while the server runs.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
from opensmi.ros2.server import recipes
|
|
43
|
+
from opensmi.ros2.server.access import LISTING_ACCESS_LEVEL, MUTATOR_ACCESS_LEVEL, SKILL_ACCESS_LEVEL
|
|
44
|
+
from opensmi.ros2.server.bindings import (
|
|
45
|
+
TOML_KINDS,
|
|
46
|
+
ActionBinding,
|
|
47
|
+
Binding,
|
|
48
|
+
GoalFunction,
|
|
49
|
+
KeyedBinding,
|
|
50
|
+
LifecycleBinding,
|
|
51
|
+
MessageFunction,
|
|
52
|
+
MethodBinding,
|
|
53
|
+
MonitoringBinding,
|
|
54
|
+
PublishedFrame,
|
|
55
|
+
PublisherBinding,
|
|
56
|
+
RequestFunction,
|
|
57
|
+
ResponseFunction,
|
|
58
|
+
ResultFunction,
|
|
59
|
+
ROS2ParameterBinding,
|
|
60
|
+
TFBinding,
|
|
61
|
+
load_bindings,
|
|
62
|
+
resolve_bindings,
|
|
63
|
+
)
|
|
64
|
+
from opensmi.ros2.server.component import ROS2ComponentMixin
|
|
65
|
+
from opensmi.ros2.server.config import ROS2Config, TransformConfig
|
|
66
|
+
from opensmi.ros2.server.drivers import (
|
|
67
|
+
DRIVERS,
|
|
68
|
+
LifecycleDriver,
|
|
69
|
+
Nav2ManagerDriver,
|
|
70
|
+
NodeTransition,
|
|
71
|
+
StandardLifecycleDriver,
|
|
72
|
+
)
|
|
73
|
+
from opensmi.ros2.server.events import Severity
|
|
74
|
+
from opensmi.ros2.server.lifecycle import LifecycleNodeState, LifecycleNodeTransition
|
|
75
|
+
from opensmi.ros2.server.loader import ConfiguredComponent, ConfiguredMachine, load_machine
|
|
76
|
+
from opensmi.ros2.server.machine import ROS2MachineMixin
|
|
77
|
+
from opensmi.ros2.server.nodesets import SmartFactoryROS2NodeIds
|
|
78
|
+
from opensmi.ros2.server.projection import (
|
|
79
|
+
DecodeFunction,
|
|
80
|
+
EncodeFunction,
|
|
81
|
+
EnumDataType,
|
|
82
|
+
PlanDataType,
|
|
83
|
+
PlanEntry,
|
|
84
|
+
PlanObject,
|
|
85
|
+
PlanVariable,
|
|
86
|
+
ProjectDataType,
|
|
87
|
+
Projection,
|
|
88
|
+
ProjectionContext,
|
|
89
|
+
ProjectionRegistry,
|
|
90
|
+
ShapeFunction,
|
|
91
|
+
StandardDataType,
|
|
92
|
+
)
|
|
93
|
+
from opensmi.ros2.server.provenance import BindingQoS
|
|
94
|
+
|
|
95
|
+
__all__ = [
|
|
96
|
+
"DRIVERS",
|
|
97
|
+
"LISTING_ACCESS_LEVEL",
|
|
98
|
+
"MUTATOR_ACCESS_LEVEL",
|
|
99
|
+
"SKILL_ACCESS_LEVEL",
|
|
100
|
+
"TOML_KINDS",
|
|
101
|
+
"ActionBinding",
|
|
102
|
+
"Binding",
|
|
103
|
+
"BindingQoS",
|
|
104
|
+
"ConfiguredComponent",
|
|
105
|
+
"ConfiguredMachine",
|
|
106
|
+
"DecodeFunction",
|
|
107
|
+
"EncodeFunction",
|
|
108
|
+
"EnumDataType",
|
|
109
|
+
"GoalFunction",
|
|
110
|
+
"KeyedBinding",
|
|
111
|
+
"LifecycleBinding",
|
|
112
|
+
"LifecycleDriver",
|
|
113
|
+
"LifecycleNodeState",
|
|
114
|
+
"LifecycleNodeTransition",
|
|
115
|
+
"MessageFunction",
|
|
116
|
+
"MethodBinding",
|
|
117
|
+
"MonitoringBinding",
|
|
118
|
+
"Nav2ManagerDriver",
|
|
119
|
+
"NodeTransition",
|
|
120
|
+
"PlanDataType",
|
|
121
|
+
"PlanEntry",
|
|
122
|
+
"PlanObject",
|
|
123
|
+
"PlanVariable",
|
|
124
|
+
"ProjectDataType",
|
|
125
|
+
"Projection",
|
|
126
|
+
"ProjectionContext",
|
|
127
|
+
"ProjectionRegistry",
|
|
128
|
+
"PublishedFrame",
|
|
129
|
+
"PublisherBinding",
|
|
130
|
+
"ROS2ComponentMixin",
|
|
131
|
+
"ROS2Config",
|
|
132
|
+
"ROS2MachineMixin",
|
|
133
|
+
"ROS2ParameterBinding",
|
|
134
|
+
"RequestFunction",
|
|
135
|
+
"ResponseFunction",
|
|
136
|
+
"ResultFunction",
|
|
137
|
+
"Severity",
|
|
138
|
+
"ShapeFunction",
|
|
139
|
+
"SmartFactoryROS2NodeIds",
|
|
140
|
+
"StandardDataType",
|
|
141
|
+
"StandardLifecycleDriver",
|
|
142
|
+
"TFBinding",
|
|
143
|
+
"TransformConfig",
|
|
144
|
+
"load_bindings",
|
|
145
|
+
"load_machine",
|
|
146
|
+
"recipes",
|
|
147
|
+
"resolve_bindings",
|
|
148
|
+
]
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""Access control for this half: three levels and two overrides.
|
|
6
|
+
|
|
7
|
+
Every write and every call passes two separate gates: an access level and ownership of the Machine's
|
|
8
|
+
Lock. Reading needs neither. opensmi answers a refusal with ``BadUserAccessDenied`` for the level and
|
|
9
|
+
``BadRequiresLock`` for a call without the Lock.
|
|
10
|
+
|
|
11
|
+
============================================= =========================================================
|
|
12
|
+
Introspection listings and the report :data:`LISTING_ACCESS_LEVEL`, Lock bypassed
|
|
13
|
+
Skills, including the StartupSkill :data:`SKILL_ACCESS_LEVEL`, plus the Lock
|
|
14
|
+
Methods backed by a ROS2 service :data:`SKILL_ACCESS_LEVEL`, plus the Lock
|
|
15
|
+
Mutators such as ``BindTopic`` :data:`MUTATOR_ACCESS_LEVEL` by default, plus the Lock
|
|
16
|
+
============================================= =========================================================
|
|
17
|
+
|
|
18
|
+
The numbers are opensmi's default user table (0 visitor, 10 orchestrator, 20 operator). A site with a
|
|
19
|
+
different table overrides them in :class:`~opensmi.ros2.server.config.ROS2Config`.
|
|
20
|
+
|
|
21
|
+
The listings skip the Lock through :class:`ROS2GatedMethod` (overrides the callable's access
|
|
22
|
+
condition) and :class:`ROS2ArgumentVariable` (overrides the variable's access check).
|
|
23
|
+
|
|
24
|
+
opensmi releases the Lock after ten minutes without a call to ``InitLock``, ``BreakLock`` or
|
|
25
|
+
``RenewLock``; a variable write does not count. A client holding the Lock calls ``RenewLock`` at
|
|
26
|
+
least every ten minutes.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
from typing import TYPE_CHECKING, Any, ClassVar, Final
|
|
32
|
+
|
|
33
|
+
from asyncua import ua
|
|
34
|
+
from asyncua.crypto.permission_rules import UserRole
|
|
35
|
+
from asyncua.ua.status_codes import StatusCodes
|
|
36
|
+
from opensmi.server import BaseMethod, UaVariable
|
|
37
|
+
from typing_extensions import override
|
|
38
|
+
|
|
39
|
+
if TYPE_CHECKING:
|
|
40
|
+
from opensmi.server.protocols import UserAuthorization
|
|
41
|
+
|
|
42
|
+
__all__ = [
|
|
43
|
+
"LISTING_ACCESS_LEVEL",
|
|
44
|
+
"MUTATOR_ACCESS_LEVEL",
|
|
45
|
+
"SKILL_ACCESS_LEVEL",
|
|
46
|
+
"ROS2ArgumentVariable",
|
|
47
|
+
"ROS2GatedMethod",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
LISTING_ACCESS_LEVEL: Final = 0
|
|
51
|
+
"""What a read-only introspection listing requires: nothing beyond being authenticated."""
|
|
52
|
+
|
|
53
|
+
SKILL_ACCESS_LEVEL: Final = 10
|
|
54
|
+
"""What a Skill, a service Method and a publishing Binding's Parameters require: the orchestrator."""
|
|
55
|
+
|
|
56
|
+
MUTATOR_ACCESS_LEVEL: Final = 20
|
|
57
|
+
"""What changing the address space from a client requires by default: the operator."""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class ROS2GatedMethod(BaseMethod):
|
|
61
|
+
"""A Method that can answer without the Lock.
|
|
62
|
+
|
|
63
|
+
opensmi checks a callable's level and the Lock in one condition and offers no bypass, so this class
|
|
64
|
+
overrides that condition. A subclass that leaves :attr:`bypasses_the_lock` alone behaves like
|
|
65
|
+
``BaseMethod``.
|
|
66
|
+
|
|
67
|
+
:cvar bypasses_the_lock: Whether the Machine's Lock is skipped. ``True`` only on the read-only
|
|
68
|
+
introspection listings: nothing they expose changes the robot, the address space or the
|
|
69
|
+
server state.
|
|
70
|
+
"""
|
|
71
|
+
|
|
72
|
+
bypasses_the_lock: ClassVar[bool] = False
|
|
73
|
+
|
|
74
|
+
@override
|
|
75
|
+
async def _condition_access_allowed(self, user: UserAuthorization) -> bool:
|
|
76
|
+
"""Check the level, and the Lock unless this Method bypasses it.
|
|
77
|
+
|
|
78
|
+
:raises UaStatusCodeError: ``BadUserAccessDenied`` when the level is too low, and, where the
|
|
79
|
+
Lock is not bypassed, ``BadRequiresLock`` when the caller does not hold it.
|
|
80
|
+
"""
|
|
81
|
+
if not self.bypasses_the_lock:
|
|
82
|
+
return await super()._condition_access_allowed(user)
|
|
83
|
+
if user.role == UserRole.Admin or user.current_access_level >= self.minimum_access_level:
|
|
84
|
+
return True
|
|
85
|
+
await self.ua_log_error(
|
|
86
|
+
f"Denied, user '{user.name}' has no access to '{self.path}' "
|
|
87
|
+
f"(minimum access level of {self.minimum_access_level} required)!"
|
|
88
|
+
)
|
|
89
|
+
raise ua.UaStatusCodeError(StatusCodes.BadUserAccessDenied)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class ROS2ArgumentVariable(UaVariable[Any]):
|
|
93
|
+
"""An argument of a Lock-bypassing Method, writable at its own level and without the Lock.
|
|
94
|
+
|
|
95
|
+
Arguments are Parameters, so using a listing is a write and then a call. Without this class the
|
|
96
|
+
write would go through opensmi's variable check, which asks for the Lock, and a visitor could not
|
|
97
|
+
use the listings. An Admin always passes, anyone else needs this variable's own minimum level.
|
|
98
|
+
Writing a scratch input on a read-only Method changes nothing about the robot or the server.
|
|
99
|
+
|
|
100
|
+
Two clients using one listing at once overwrite each other's arguments and read each other's
|
|
101
|
+
answers. That holds for every opensmi Method, which has one ParameterSet and one FinalResultData,
|
|
102
|
+
not one per session.
|
|
103
|
+
"""
|
|
104
|
+
|
|
105
|
+
@override
|
|
106
|
+
def access_allowed(self, user: UserAuthorization, *, lock_required: bool | None = None) -> bool:
|
|
107
|
+
"""Let an Admin through always, and anyone else at this variable's own level."""
|
|
108
|
+
del lock_required # this variable is never behind the Lock, whatever the caller asks
|
|
109
|
+
return user.role == UserRole.Admin or user.current_access_level >= self.minimum_access_level
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""Binding declarations: what a Component exposes, written down rather than assembled.
|
|
6
|
+
|
|
7
|
+
A Binding connects one ROS2 noun (a topic, service, action or node path) to one OPC UA object. It is a
|
|
8
|
+
frozen dataclass listed on a Component's ``bindings`` class attribute; no lifecycle hook is overridden
|
|
9
|
+
to add a variable. The class attribute is the instance default, so a constructor may compute the list
|
|
10
|
+
from injected configuration. Every kind that names a ROS2 path says ``path=``. A TOML source unions
|
|
11
|
+
with the class attribute and a name collision is fatal; neither source may change a Binding the other
|
|
12
|
+
wrote.
|
|
13
|
+
|
|
14
|
+
Kinds are named for their OPC UA target, or for the ROS2 side where two kinds share one:
|
|
15
|
+
:class:`MonitoringBinding` (topic read into Monitoring variables), :class:`KeyedBinding` (one member per
|
|
16
|
+
key of a repeated field), :class:`MethodBinding` (service), :class:`ActionBinding` (action as a finite
|
|
17
|
+
Skill), :class:`PublisherBinding` (topic published from a Skill), :class:`ROS2ParameterBinding` (node
|
|
18
|
+
parameters), :class:`LifecycleBinding` (lifecycle node behind the StartupSkill) and :class:`TFBinding`
|
|
19
|
+
(TF tree as RSL Locations).
|
|
20
|
+
|
|
21
|
+
A TOML Binding file has one table per kind: ``monitoring``, ``keyed``, ``method``, ``ros2_parameter``,
|
|
22
|
+
``action``, ``tf``, ``publisher`` and ``lifecycle``. A Component picks the file up through
|
|
23
|
+
``bindings_toml``. A name may be declared only once across Python and TOML.
|
|
24
|
+
|
|
25
|
+
.. code-block:: toml
|
|
26
|
+
|
|
27
|
+
[[monitoring]]
|
|
28
|
+
name = "Chatter"
|
|
29
|
+
path = "/chatter"
|
|
30
|
+
message_type = "std_msgs/msg/String"
|
|
31
|
+
|
|
32
|
+
[[method]]
|
|
33
|
+
name = "AddTwoInts"
|
|
34
|
+
path = "/add_two_ints"
|
|
35
|
+
service_type = "example_interfaces/srv/AddTwoInts"
|
|
36
|
+
|
|
37
|
+
A Binding's ``name`` becomes a browse name, so an empty name or one that breaks opensmi's
|
|
38
|
+
browse-name rule ``^[A-Z][A-Za-z0-9]*$`` is refused with
|
|
39
|
+
:class:`~opensmi.ros2.server.errors.BindingNameError` (a ``/`` in a field path stays legal).
|
|
40
|
+
|
|
41
|
+
Keywords that name Python objects (implementation classes, callables) are Python-only. The loader
|
|
42
|
+
refuses a TOML value for any field a TOML file cannot produce
|
|
43
|
+
(:func:`opensmi.ros2.server.config.from_dict`).
|
|
44
|
+
|
|
45
|
+
``required=True`` makes the StartupSkill of the declaring item wait until the Binding is satisfied, and
|
|
46
|
+
halt if its deadline passes first. Every Binding is optional otherwise.
|
|
47
|
+
|
|
48
|
+
A topic's ``qos=`` is a contract. Declared, it is honoured exactly for the life of the endpoint, even
|
|
49
|
+
when provably incompatible with a publisher (reported, never fatal). Left out on a
|
|
50
|
+
:class:`MonitoringBinding`, a profile is discovered: the most permissive one compatible with every
|
|
51
|
+
publisher. Depth is a separate keyword (:mod:`opensmi.ros2.runtime.qos`). A Monitoring Binding without
|
|
52
|
+
``message_type`` is the graph-driven case.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
from opensmi.ros2.server.bindings.action import ActionBinding, GoalFunction, ResultFunction
|
|
56
|
+
from opensmi.ros2.server.bindings.keyed import KeyedBinding
|
|
57
|
+
from opensmi.ros2.server.bindings.lifecycle import LifecycleBinding
|
|
58
|
+
from opensmi.ros2.server.bindings.method import MethodBinding, RequestFunction, ResponseFunction
|
|
59
|
+
from opensmi.ros2.server.bindings.monitoring import MonitoringBinding
|
|
60
|
+
from opensmi.ros2.server.bindings.parameter import WRITE_TIMEOUT, ROS2ParameterBinding
|
|
61
|
+
from opensmi.ros2.server.bindings.publisher import MessageFunction, PublisherBinding
|
|
62
|
+
from opensmi.ros2.server.bindings.registry import (
|
|
63
|
+
TOML_KINDS,
|
|
64
|
+
Binding,
|
|
65
|
+
is_required,
|
|
66
|
+
load_bindings,
|
|
67
|
+
resolve_bindings,
|
|
68
|
+
)
|
|
69
|
+
from opensmi.ros2.server.bindings.tf import PublishedFrame, TFBinding
|
|
70
|
+
|
|
71
|
+
__all__ = [
|
|
72
|
+
"TOML_KINDS",
|
|
73
|
+
"WRITE_TIMEOUT",
|
|
74
|
+
"ActionBinding",
|
|
75
|
+
"Binding",
|
|
76
|
+
"GoalFunction",
|
|
77
|
+
"KeyedBinding",
|
|
78
|
+
"LifecycleBinding",
|
|
79
|
+
"MessageFunction",
|
|
80
|
+
"MethodBinding",
|
|
81
|
+
"MonitoringBinding",
|
|
82
|
+
"PublishedFrame",
|
|
83
|
+
"PublisherBinding",
|
|
84
|
+
"ROS2ParameterBinding",
|
|
85
|
+
"RequestFunction",
|
|
86
|
+
"ResponseFunction",
|
|
87
|
+
"ResultFunction",
|
|
88
|
+
"TFBinding",
|
|
89
|
+
"is_required",
|
|
90
|
+
"load_bindings",
|
|
91
|
+
"resolve_bindings",
|
|
92
|
+
]
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""What every Binding kind repeats: the name, the wait, and the checks on both."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import TYPE_CHECKING, ClassVar, Final
|
|
11
|
+
|
|
12
|
+
from opensmi.core.paths import check_name
|
|
13
|
+
|
|
14
|
+
from opensmi.ros2.server.browse_names import suggested_name
|
|
15
|
+
from opensmi.ros2.server.errors import (
|
|
16
|
+
BindingNameError,
|
|
17
|
+
DeclarationError,
|
|
18
|
+
ImplementationClassError,
|
|
19
|
+
RequiredDeclarationError,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
if TYPE_CHECKING:
|
|
23
|
+
from collections.abc import Mapping
|
|
24
|
+
|
|
25
|
+
__all__ = ["AwaitedBinding", "NamedBinding"]
|
|
26
|
+
|
|
27
|
+
_MACHINERY_MONITORING: Final = ("Status", "Health", "Process", "Consumption")
|
|
28
|
+
"""The sub-structures OPC 40001-1 gives a machinery item's Monitoring (section 16.2), kept free for them."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
32
|
+
class NamedBinding:
|
|
33
|
+
"""A declaration with a name, which becomes a browse name.
|
|
34
|
+
|
|
35
|
+
:cvar kind: What the messages call this declaration, such as ``"Monitoring Binding"``.
|
|
36
|
+
:ivar name: The Binding's name.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
kind: ClassVar[str] = "Binding"
|
|
40
|
+
|
|
41
|
+
name: str
|
|
42
|
+
|
|
43
|
+
def _require_a_name_that_can_be_browsed(self) -> None:
|
|
44
|
+
"""Refuse an empty name or one that breaks the naming rule, which opensmi would only refuse at start.
|
|
45
|
+
|
|
46
|
+
:raises BindingNameError: When the name is empty or breaks the rule. The message suggests a name.
|
|
47
|
+
"""
|
|
48
|
+
if not self.name:
|
|
49
|
+
message = f"the {self.kind} has an empty name; give it one, because it is what the Binding is browsed as"
|
|
50
|
+
raise BindingNameError(message)
|
|
51
|
+
try:
|
|
52
|
+
check_name(self.name)
|
|
53
|
+
except ValueError:
|
|
54
|
+
message = f"Name {self.name!r} breaks the naming rule"
|
|
55
|
+
if (suggestion := suggested_name(self.name)) is not None:
|
|
56
|
+
message = f"{message}; try {suggestion!r}"
|
|
57
|
+
raise BindingNameError(message) from None
|
|
58
|
+
|
|
59
|
+
def _require_a_name_machinery_monitoring_leaves_free(self) -> None:
|
|
60
|
+
"""Refuse a name OPC 40001-1 keeps for a sub-structure of a Machine's or Component's Monitoring.
|
|
61
|
+
|
|
62
|
+
For the kinds whose name is a top-level node of that Monitoring. The match is exact, so
|
|
63
|
+
``StatusCode`` is free, and a name below the top level is not affected.
|
|
64
|
+
|
|
65
|
+
:raises DeclarationError: When the name is ``Status``, ``Health``, ``Process`` or ``Consumption``.
|
|
66
|
+
"""
|
|
67
|
+
if self.name not in _MACHINERY_MONITORING:
|
|
68
|
+
return
|
|
69
|
+
message = (
|
|
70
|
+
f"the {self.kind} {self.name!r} takes a name reserved in a Machine's or Component's Monitoring: "
|
|
71
|
+
f"OPC 40001-1 keeps {', '.join(_MACHINERY_MONITORING)} for the Machinery Monitoring "
|
|
72
|
+
f"sub-structures; choose another name"
|
|
73
|
+
)
|
|
74
|
+
raise DeclarationError(message)
|
|
75
|
+
|
|
76
|
+
def _require_a_machinery_group(self, group: str | None) -> None:
|
|
77
|
+
"""Refuse a ``group`` that is not one of the Machinery Monitoring sub-structures.
|
|
78
|
+
|
|
79
|
+
:raises DeclarationError: When ``group`` is given and is not ``Status``, ``Health``, ``Process`` or
|
|
80
|
+
``Consumption``.
|
|
81
|
+
"""
|
|
82
|
+
if group is None or group in _MACHINERY_MONITORING:
|
|
83
|
+
return
|
|
84
|
+
message = (
|
|
85
|
+
f"the {self.kind} {self.name!r} names the group {group!r}; a group is one of the Machinery "
|
|
86
|
+
f"Monitoring sub-structures {', '.join(_MACHINERY_MONITORING)} (OPC 40001-1), or left out"
|
|
87
|
+
)
|
|
88
|
+
raise DeclarationError(message)
|
|
89
|
+
|
|
90
|
+
def _require_a_subclass(self, given: object, stock: type, why: str) -> None:
|
|
91
|
+
"""Refuse an implementation class that is not a subclass of the stock one.
|
|
92
|
+
|
|
93
|
+
:raises ImplementationClassError: When ``given`` is not a class derived from ``stock``.
|
|
94
|
+
"""
|
|
95
|
+
if isinstance(given, type) and issubclass(given, stock):
|
|
96
|
+
return
|
|
97
|
+
named = getattr(given, "__name__", repr(given))
|
|
98
|
+
message = (
|
|
99
|
+
f"the Binding {self.name!r} names {named} as its implementation class, and it is "
|
|
100
|
+
f"not a subclass of {stock.__name__}; {why}"
|
|
101
|
+
)
|
|
102
|
+
raise ImplementationClassError(message)
|
|
103
|
+
|
|
104
|
+
def _require_new_names_that_follow_the_rule(self, option: str, rename: Mapping[str, str]) -> None:
|
|
105
|
+
"""Refuse a ``rename`` value that breaks the naming rule. It is taken as is, never converted.
|
|
106
|
+
|
|
107
|
+
:raises BindingNameError: When a new name is not a valid browse name.
|
|
108
|
+
"""
|
|
109
|
+
for path, new_name in rename.items():
|
|
110
|
+
try:
|
|
111
|
+
check_name(new_name)
|
|
112
|
+
except ValueError:
|
|
113
|
+
message = (
|
|
114
|
+
f"the {self.kind} {self.name!r} gives {path!r} the new name {new_name!r} in {option}, "
|
|
115
|
+
f"which breaks the naming rule"
|
|
116
|
+
)
|
|
117
|
+
if (suggestion := suggested_name(new_name)) is not None:
|
|
118
|
+
message = f"{message}; try {suggestion!r}"
|
|
119
|
+
raise BindingNameError(message) from None
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
123
|
+
class AwaitedBinding(NamedBinding):
|
|
124
|
+
"""A declaration the StartupSkill may wait for.
|
|
125
|
+
|
|
126
|
+
:ivar required: Whether the StartupSkill waits for it before ``Running``.
|
|
127
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for the deployment's default.
|
|
128
|
+
"""
|
|
129
|
+
|
|
130
|
+
required: bool = False
|
|
131
|
+
startup_timeout: float | None = None
|
|
132
|
+
|
|
133
|
+
def _require_a_deadline_that_means_something(self) -> None:
|
|
134
|
+
"""Refuse a ``startup_timeout`` on a Binding that is not required, or one that is not positive.
|
|
135
|
+
|
|
136
|
+
:raises RequiredDeclarationError: On either contradiction.
|
|
137
|
+
"""
|
|
138
|
+
timeout = self.startup_timeout
|
|
139
|
+
if timeout is None:
|
|
140
|
+
return
|
|
141
|
+
if not self.required:
|
|
142
|
+
message = (
|
|
143
|
+
f"the {self.kind} {self.name!r} declares startup_timeout={timeout!r} and is not required; a "
|
|
144
|
+
f"deadline is how long a StartupSkill waits for a required Binding, so one on an "
|
|
145
|
+
f"optional Binding is a guard nobody is standing"
|
|
146
|
+
)
|
|
147
|
+
raise RequiredDeclarationError(message)
|
|
148
|
+
if timeout <= 0:
|
|
149
|
+
message = (
|
|
150
|
+
f"the {self.kind} {self.name!r} declares startup_timeout={timeout!r}; it is how many seconds a "
|
|
151
|
+
f"StartupSkill waits for this Binding, so it is a positive number of seconds and "
|
|
152
|
+
f"there is no way to spell a deadline that has already passed"
|
|
153
|
+
)
|
|
154
|
+
raise RequiredDeclarationError(message)
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: 2026 Technologie-Initiative SmartFactory KL e.V.
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
|
|
5
|
+
"""A ROS2 action run as a finite Skill."""
|
|
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
|
+
GoalFunction: TypeAlias = Callable[[type[Message], Mapping[str, object], ProjectionContext], Message]
|
|
19
|
+
"""Builds a goal message from a Skill's Parameters, as a pure function.
|
|
20
|
+
|
|
21
|
+
The default is :func:`opensmi.ros2.server.skill.default_goal_from`.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
ResultFunction: TypeAlias = Callable[[Message, ProjectionContext], Mapping[str, object]]
|
|
25
|
+
"""Turns a result message into the values of a Skill's FinalResultData, by variable name.
|
|
26
|
+
|
|
27
|
+
The default is :func:`opensmi.ros2.server.skill.default_result_to`.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
32
|
+
class ActionBinding(AwaitedBinding):
|
|
33
|
+
"""A ROS2 action exposed as a finite Skill on the declaring Component.
|
|
34
|
+
|
|
35
|
+
The goal becomes the Skill's Parameters (written before ``Start``), the feedback its Monitoring
|
|
36
|
+
(written while the goal runs) and the result its FinalResultData. The outcome drives the state
|
|
37
|
+
machine and is not data of its own. Each message is narrowed by its own include/exclude pair.
|
|
38
|
+
|
|
39
|
+
:ivar name: The Binding's name, also the Skill's name. Its variables are named for the field path
|
|
40
|
+
alone.
|
|
41
|
+
:ivar path: The ROS2 action.
|
|
42
|
+
:ivar action_type: The ROS2 action type, ``package/action/Name``. Required, so the address space does
|
|
43
|
+
not depend on start-up timing. A type whose package is not installed is fatal at init.
|
|
44
|
+
:ivar include: Field patterns narrowing the goal; empty means every field.
|
|
45
|
+
:ivar exclude: Field patterns removing goal fields, after ``include`` has narrowed. A selection that
|
|
46
|
+
leaves the goal unbuildable is refused at init instead of filled from a default.
|
|
47
|
+
:ivar rename: New browse names by field path, as on :class:`MonitoringBinding`.
|
|
48
|
+
:ivar feedback_include: Field patterns narrowing the feedback.
|
|
49
|
+
:ivar feedback_exclude: Field patterns removing feedback fields.
|
|
50
|
+
:ivar feedback_rename: New browse names for feedback fields, as :attr:`rename` does.
|
|
51
|
+
:ivar result_include: Field patterns narrowing the result.
|
|
52
|
+
:ivar result_exclude: Field patterns removing result fields.
|
|
53
|
+
:ivar result_rename: New browse names for result fields, as :attr:`rename` does.
|
|
54
|
+
:ivar feedback_depth: How many feedback messages the goal handle buffers before the oldest is
|
|
55
|
+
dropped.
|
|
56
|
+
:ivar server_timeout: Seconds ``Start`` waits for an action server before halting, so a Skill does
|
|
57
|
+
not sit in ``Starting`` against a robot that is off.
|
|
58
|
+
:ivar skill_type: A subclass of :class:`opensmi.ros2.server.skill.ROS2ActionSkill`, or ``None`` for
|
|
59
|
+
the stock one. Python-only; refused when the Binding is constructed if it is not a
|
|
60
|
+
subclass.
|
|
61
|
+
:ivar goal_from: Builds the goal message from the Parameters, or ``None`` for the default.
|
|
62
|
+
Python-only.
|
|
63
|
+
:ivar result_to: Turns the result message into FinalResultData values, or ``None`` for the default.
|
|
64
|
+
Python-only.
|
|
65
|
+
:ivar required: Whether the StartupSkill waits for the action server to be discovered before
|
|
66
|
+
``Running``.
|
|
67
|
+
:ivar startup_timeout: Seconds that wait lasts, or ``None`` for the deployment's default. Refused when the
|
|
68
|
+
Binding is constructed without ``required``.
|
|
69
|
+
"""
|
|
70
|
+
|
|
71
|
+
kind: ClassVar[str] = "action Binding"
|
|
72
|
+
|
|
73
|
+
path: str
|
|
74
|
+
action_type: str
|
|
75
|
+
include: tuple[str, ...] = ()
|
|
76
|
+
exclude: tuple[str, ...] = ()
|
|
77
|
+
rename: dict[str, str] = field(default_factory=dict)
|
|
78
|
+
feedback_include: tuple[str, ...] = ()
|
|
79
|
+
feedback_exclude: tuple[str, ...] = ()
|
|
80
|
+
feedback_rename: dict[str, str] = field(default_factory=dict)
|
|
81
|
+
result_include: tuple[str, ...] = ()
|
|
82
|
+
result_exclude: tuple[str, ...] = ()
|
|
83
|
+
result_rename: dict[str, str] = field(default_factory=dict)
|
|
84
|
+
feedback_depth: int = 10
|
|
85
|
+
server_timeout: float = 10.0
|
|
86
|
+
skill_type: type | None = None
|
|
87
|
+
goal_from: GoalFunction | None = None
|
|
88
|
+
result_to: ResultFunction | None = None
|
|
89
|
+
|
|
90
|
+
def __post_init__(self) -> None:
|
|
91
|
+
"""Refuse a custom implementation class that is not a subclass of the stock one.
|
|
92
|
+
|
|
93
|
+
:raises ImplementationClassError: When ``skill_type`` does not derive from
|
|
94
|
+
:class:`opensmi.ros2.server.skill.ROS2ActionSkill`.
|
|
95
|
+
:raises RequiredDeclarationError: When ``startup_timeout`` is declared without ``required``, or
|
|
96
|
+
is not positive.
|
|
97
|
+
"""
|
|
98
|
+
self._require_a_name_that_can_be_browsed()
|
|
99
|
+
self._require_new_names_that_follow_the_rule("rename", self.rename)
|
|
100
|
+
self._require_new_names_that_follow_the_rule("feedback_rename", self.feedback_rename)
|
|
101
|
+
self._require_new_names_that_follow_the_rule("result_rename", self.result_rename)
|
|
102
|
+
self._require_a_deadline_that_means_something()
|
|
103
|
+
if self.skill_type is None:
|
|
104
|
+
return
|
|
105
|
+
# Imported here: the Skill annotates against this declaration.
|
|
106
|
+
from opensmi.ros2.server.skill import ROS2ActionSkill
|
|
107
|
+
|
|
108
|
+
self._require_a_subclass(
|
|
109
|
+
self.skill_type,
|
|
110
|
+
ROS2ActionSkill,
|
|
111
|
+
"a custom class adds behaviour to the stock one rather than replacing it, "
|
|
112
|
+
"and a TOML file cannot name one at all",
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
@property
|
|
116
|
+
def selection(self) -> FieldSelection:
|
|
117
|
+
"""Return the goal's field selection."""
|
|
118
|
+
return FieldSelection(include=self.include, exclude=self.exclude, rename=self.rename)
|
|
119
|
+
|
|
120
|
+
@property
|
|
121
|
+
def feedback_selection(self) -> FieldSelection:
|
|
122
|
+
"""Return the feedback's field selection."""
|
|
123
|
+
return FieldSelection(include=self.feedback_include, exclude=self.feedback_exclude, rename=self.feedback_rename)
|
|
124
|
+
|
|
125
|
+
@property
|
|
126
|
+
def result_selection(self) -> FieldSelection:
|
|
127
|
+
"""Return the result's field selection."""
|
|
128
|
+
return FieldSelection(include=self.result_include, exclude=self.result_exclude, rename=self.result_rename)
|
|
129
|
+
|
|
130
|
+
@property
|
|
131
|
+
def needs_the_graph(self) -> bool:
|
|
132
|
+
"""Return ``False``: the declaration carries its type."""
|
|
133
|
+
return False
|