sysand add seil-isr/ros2-sysmlv2
The first SysML v2 domain library for ROS2 robotics system architectures.
185 definitions across 17 source files covering message types, communication patterns, lifecycle, deployment, TF2, parameters, node archetypes, and the Nav2 navigation stack.
This library is the type vocabulary for modeling ROS2 systems in SysML v2. You import it from your own .sysml models to obtain typed handles on messages, topics, services, actions, nodes, lifecycle states, QoS profiles, TF frames, and parameters that map directly to ROS2 Jazzy semantics. Every definition is validated against actual ROS2 source.
This library is not a code generator. A companion pipeline (separate project) reads models written against this vocabulary and generates buildable ROS2 packages in Python (rclpy) and C++ (rclcpp). A manuscript preprint describing the library and the pipeline will be made available soon.
Beyond the core ROS2 interfaces, the library ships out-of-the-box support for Nav2: the parts of seven of its actions that the server definitions use (table below) and its Costmap, CostmapMetaData, and SpeedLimit messages as item defs; its fourteen server nodes (planner, controller, behavior-tree navigator, behavior, smoother, costmap, AMCL, map server, velocity smoother, collision monitor, lifecycle manager, waypoint follower, docking, and route servers) as part defs carrying their topic names and action servers; and a Nav2Stack composite that wires them together, all checked against the Nav2 Jazzy sources. We will extend coverage to other widely used ROS2 stacks in future releases.
| Action | Goal | Result | Feedback |
|---|---|---|---|
| ComputePathToPose | ComputePathToPoseGoal |
ComputePathToPoseResult |
empty in Jazzy |
| FollowPath | FollowPathGoal |
not modeled | FollowPathFeedback |
| NavigateToPose | NavigateToPoseGoal |
not modeled | NavigateToPoseFeedback |
| SmoothPath | SmoothPathGoal |
SmoothPathResult |
empty in Jazzy |
| Spin | SpinGoal |
not modeled | not modeled |
| BackUp | BackUpGoal |
not modeled | not modeled |
| Wait | WaitGoal |
not modeled | not modeled |
This library is the first in a series of SysML v2 libraries for robotics that we are building. It covers architecture and implementation: the ROS2 vocabulary a robot's software architecture is written against. Two companions are in preparation, a library for analysis, with the model elements for design space exploration of robot architectures, and a library for verification, with the elements for verifying them. We will publish each on the sysand index under our organization.
# From the public index
sysand add pkg:sysand/seil-isr/ros2-sysmlv2
# From a local archive built with `sysand build`
sysand add file:///path/to/ros2_sysmlv2-<version>.kpar
package MyRobot {
private import ros2_sysmlv2_lifecycle::*;
private import ros2_sysmlv2_comm::*;
private import ros2_sysmlv2_sensor_msgs::*;
private import ros2_sysmlv2_archetypes::*;
part def MyLidarNode :> SensorDriver {
:>> nodeName = "lidar_driver";
:>> updateRateHz = 10.0;
:>> frameId = "lidar_link";
port :>> sensorPub : TopicPublisher {
:>> topicName = "/scan";
:>> qos = sensorDataQoS;
out item :>> msg : LaserScan;
}
}
}
| Layer | File(s) | Definitions | Description |
|---|---|---|---|
| Foundation | foundation.sysml, std_msgs.sysml |
11 | Time, Duration, Header, StringMessage, ColorRGBA, etc. |
| Messages | geometry_msgs.sysml, sensor_msgs.sysml, nav_msgs.sysml, trajectory_msgs.sysml, diagnostic_msgs.sysml, shape_msgs.sysml, action_msgs.sysml, visualization_msgs.sysml |
87 | 85 ROS2 message types as item def |
| Communication | comm.sysml |
16 | QoS, TopicPublisher/Subscriber, ServiceServer/Client, ActionServer/Client, interfaces TopicConnection, ServiceBinding, ActionBinding |
| Lifecycle | lifecycle.sysml |
15 | Node, LifecycleNode, LifecycleStates (10 states, 25 transitions: 7 requested, 18 guarded on the callback result) |
| Deployment | deployment.sysml |
6 | Executor, Container, CallbackGroup, NodeDeployment |
| Parameters | params.sysml |
5 | ParameterTypeKind (10 values), ParameterDescriptor, ranges |
| TF2 | tf2.sysml |
8 | TFMessage, CoordinateFrame, StaticTransform, DynamicTransform, REP 105 frames |
| Archetypes | archetypes.sysml |
8 | 8 abstract node patterns (SensorDriver, Controller, Planner, etc.) |
| Nav2 | nav2.sysml |
29 | 14 Nav2 server nodes, the Nav2Stack composite, 14 action and message types |
| SysML v2 | ROS2 |
|---|---|
item def |
.msg type |
port def with out item |
Topic publisher |
port def with in item |
Topic subscriber |
port def with in + out items |
Service or Action |
part def |
Node class |
part usage |
Node instance |
interface def (TopicConnection, ServiceBinding, ActionBinding) |
Topic, service, or action binding between two ports |
connection def (StaticTransform, DynamicTransform) |
TF2 transform between two frames |
state def with transition |
Lifecycle state machine |
attribute def |
Parameter type |
Each endpoint kind has a port definition of its own, so a tool selects publishers, subscribers, servers, and clients by specialization alone. The subscriber and client definitions are not written as conjugates (~TopicPublisher): in KerML a conjugated port definition specializes its original, so a tool that selects by specialization would take a subscriber for a publisher. Each pair has the same features, with every in and out reversed.
The three port relations are interface definitions, the SysML v2 construct for a connection whose ends are ports. A usage is written with either keyword, connection : TopicConnection connect a.scanPub to b.scanSub; or interface : TopicConnection connect a.scanPub to b.scanSub;, and a user subtype specializes it, for example interface def ScanTopic :> TopicConnection;. The transforms are connection definitions, since frames are parts.
Each port states its own topic name, message type, and QoS profile, as a node does in its code. The two ends of a topic connection agree when they have the same topic name after namespace resolution, the same message type, and compatible QoS. syside check reports an end connected to a port of the wrong role, QoSCompatible states the QoS rule, and the doc comment of TopicConnection says where the companion pipeline checks the rest.
A message field keeps its ROS2 name in camelCase (frame_id becomes frameId). A field whose name is a reserved SysML v2 keyword, or collides with a feature the definition inherits, is renamed. Every item def inherits the features start and done of Items::Item.
| Message | ROS2 field | SysML field | Reason |
|---|---|---|---|
diagnostic_msgs/DiagnosticStatus |
message |
diagnosticMessage |
reserved keyword |
visualization_msgs/Marker |
action |
markerAction |
reserved keyword |
nav2_msgs/Costmap |
metadata |
costmapMetadata |
reserved keyword |
nav2_msgs/action/ComputePathToPose goal |
start |
startPose |
inherited Items::Item::start |
visualization_msgs/Marker |
id, type |
markerId, markerType |
same prefix as markerAction |
shape_msgs/SolidPrimitive |
type |
primitiveType |
same pattern as markerType |
rcl_interfaces/ParameterDescriptor |
type |
parameterType |
same pattern as markerType |
std_msgs/String is the item def StringMessage, since String is the KerML string type.
All definitions are validated against actual ROS2 Jazzy source code:
.msg files from ros2/common_interfaces and ros2/rcl_interfacesrclpy/qos.py, rclpy/node.py, rmw/qos_profiles.hlifecycle_msgs/msg/State.msg, Transition.msg, rcl_lifecycle/src/default_state_machine.c, rclpy/lifecycle/node.pyrcl_interfaces/msg/ParameterDescriptor.msg, ParameterType.msgnav2_msgs .action and .msg files (names after the renames above, types, arrays)0.2.10.10.1 (free) for authoring with this library0.10.1 (licensed, part of Syside Modeler) for programmatic model accessCHANGELOG.md.We thank Sensmetry for a free academic license for Syside Modeler, which we used to author, validate, and visualize this library, and for the Syside Automator API behind our companion pipeline. The library is validated with syside check at zero errors and zero warnings.
Apache-2.0
Sai Sandeep Damera (sdamera@terpmail.umd.edu) University of Maryland, College Park