Skip to main content
If you previously published to beta.sysand.org, follow the migration guide to move your packages to sysand.com.

ros2-sysmlv2

published by seil-isr
111 released
Latest Validated
sysand add seil-isr/ros2-sysmlv2
README Source Changelog Licenses 0 usages 3 versions Validation

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.

Overview

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.

Nav2 support

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

Roadmap

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.

Installation

# 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

Quick start

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;
        }
    }
}

Contents

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

Mapping conventions

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.

Field names

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.

Validation

All definitions are validated against actual ROS2 Jazzy source code:

  • Message types: field-by-field against .msg files from ros2/common_interfaces and ros2/rcl_interfaces
  • Communication: against rclpy/qos.py, rclpy/node.py, rmw/qos_profiles.h
  • Lifecycle: against lifecycle_msgs/msg/State.msg, Transition.msg, rcl_lifecycle/src/default_state_machine.c, rclpy/lifecycle/node.py
  • Parameters: against rcl_interfaces/msg/ParameterDescriptor.msg, ParameterType.msg
  • Nav2 nodes: against Nav2 Jazzy server node C++ source (class inheritance, topic names, action servers)
  • Nav2 action and message types: field by field against the nav2_msgs .action and .msg files (names after the renames above, types, arrays)

Requirements

  • Sysand ≥ 0.2.1
  • Syside Editor ≥ 0.10.1 (free) for authoring with this library
  • Syside Automator ≥ 0.10.1 (licensed, part of Syside Modeler) for programmatic model access
  • Target runtime: ROS2 Jazzy: message, service, and action definitions follow the ROS2 Jazzy sources

Related projects

  • A companion pipeline (separate project) uses Syside Automator, Sensmetry's Python API for programmatic model access, to extract the ROS2 architecture from a SysML v2 model into a JSON intermediate representation and to generate buildable ROS2 packages in Python (rclpy) and C++ (rclcpp), launch files, and a runtime conformance monitor that checks the running system against the model.
  • Release history: see CHANGELOG.md.

Acknowledgements

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.

License

Apache-2.0

Maintainers

Sai Sandeep Damera (sdamera@terpmail.umd.edu) University of Maryland, College Park