ROS 2 Interface Exporter (ros2interface)

Exports a VSS model to a ROS 2 interface package: generates .msg files (per leaf or aggregated by parent branch) and optional .srv files for Get/Set operations. This exporter plugs into the vspec export CLI like other vss-tools exporters. For generic exporter usage and common arguments, see the vspec documentation.

Generated Output Structure

\<output>
└── <package-name>
    ├── msg  # generated .msg definitions
    |   └── \<MSG>.msg
    └── srv  # generated .srv (if setting is enabled)
        ├── Get\<MSG>.srv
        └── Set\<MSG>.srv

Example Output

OutputFolder
└── Vss-Interface
    ├── msg
    |   └── VehicleSpeed.msg
    └── srv
        ├── GetVehicleSpeed.srv
        └── SetVehicleSpeed.srv

• .msg files include VSS metadata as comments (description, unit, min/max, allowed values).
• Optional .srv files (Get<Msg>.srv, Set<Msg>.srv) that either nest the generated message or flatten its fields.

Datatypes mapping between VSS and ROS 2 Interface

VSS	ROS 2
boolean	bool
uint8	uint8
int8	int8
uint16	uint16
int16	int16
uint32	uint32
int32	int32
uint64	uint64
int64	int64
float	float32
double	float64
string	string

Command Options

Core

• --output <dir>: Output directory (required).
• --package-name <name>: Name of generated ROS 2 interface package (default: vss_interfaces).
• --mode {aggregate, leaf}:
  • aggregate: one .msg per direct parent branch containing all of its leaf signals.
  • leaf: one .msg per leaf signal.
• --srv {get, set, both}: Also generate .srv files.
  • get:
    • creates Get.srv files to retrieve data within a specified start and end time.
  • set:
    • creates Set.srv files to send the data and get true as response if the data gets saved.
  • both:
    • creates both the Get.srv and Set.srv files
• --srv-use-msg / --no-srv-use-msg: In services, use the generated message as a nested field (default: --srv-use-msg); otherwise flatten fields.
• --timestamp-struct-fqn <fqn>: Full FQN of the timestamp struct in the types tree loaded via --types. If not provided, falls back to built-in defaults.
• --output-vspec <file>: Optional path to write a transformed VSS model alongside the ROS 2 package. See VSS with Timestamp in the Output section.

Topic/Signal Selection

• --topics PATTERN (repeatable): Include filter patterns.
• --exclude-topics PATTERN (repeatable): Exclude filter patterns.
• --topics-file <file>: File with one pattern per line; # starts a comment.
• --topics-case-insensitive / --topics-case-sensitive: Case-insensitive matching (default: --topics-case-sensitive).

Pattern syntax

Following patterns are supported:

• Exact FQN: Vehicle.Speed
• Leaf name: Speed
• Glob: Vehicle.*.Speed, *.Speed
• Explicit prefix`:
  • regex: ^Vehicle\.Body\..*$
  • glob: *.Speed
  • fqn: Vehicle.Speed (exact or prefix match)
  • Name: Speed

Output

Timestamp fields

Timestamp fields come from the struct identified by --timestamp-struct-fqn in the types tree loaded via --types. If found, the struct's direct property children become the leading timestamp fields in every .msg and .srv file. When --timestamp-struct-fqn is not provided, the exporter falls back to built-in defaults; and if the struct is not found, an error is raised.

--types	--timestamp-struct-fqn	Result
none	none	use built-in defaults
none	any	Error(invalid option combination)
any	none	use built-in defaults
any	any	use that struct(if not found, Error)

int64 timestamp_seconds
int64 timestamp_nanoseconds

Messages (.msg)

• Aggregate mode one message per direct parent branch. Fields include leading int64 timestamp_seconds / int64 timestamp_nanoseconds fields, then one field per child leaf.

• Leaf mode one message per leaf. Fields include timestamp fields followed by a value field for the leaf value.

Example — VehicleSpeed.msg

# AUTO-GENERATED by VSS-TOOLS
# Signal: Vehicle.Speed

# Unix epoch seconds; unit=unix-time
int64 timestamp_seconds

# Nanoseconds [0, 999999999]
int64 timestamp_nanoseconds

# Vehicle speed.; unit=km/h
float32 value

Services (.srv)

Generated when --srv get|set|both is used.

• Get<Msg>.srv

  • Request: int64 start_time_seconds, int64 start_time_nanoseconds, int64 end_time_seconds, int64 end_time_nanoseconds
  • Response: <Msg>[] data (with --srv-use-msg) or flattened fields

• Set<Msg>.srv

  • Request: <Msg> data (with --srv-use-msg) or flattened fields
  • Response: bool success, string message

Transformed VSS (.vspec) — --output-vspec

When --output-vspec <file> is provided, a transformed VSS model is written alongside the ROS 2 package. Each selected signal is restructured as:

# Branch intermediaries are preserved
Vehicle:
  type: branch

Vehicle.Speed:
  type: struct

Vehicle.Speed.Timestamp:
  type: property
  datatype: <timestamp-struct-fqn>   # the FQN given via --timestamp-struct-fqn

Vehicle.Speed.Value:
  type: sensor
  datatype: float
  description: Vehicle speed.
  unit: km/h

The timestamp struct itself is not re-emitted — it is expected to already be present in the types tree.

Examples

• Export only Vehicle.Speed as leaf message + get/set services:

vspec export ros2interface \
  --vspec spec/VehicleSignalSpecification.vspec \
  -I spec \
  --output ./out \
  --package-name vss_speed_interfaces \
  --mode leaf \
  --srv both --srv-use-msg \
  --topics Vehicle.Speed

• Export all *.Speed signals, aggregated by their parent branches:

vspec export ros2interface \
  --vspec spec/VehicleSignalSpecification.vspec \
  -I spec \
  --output ./out \
  --package-name vss_speed_agg \
  --mode aggregate \
  --srv get \
  --topics '*.Speed'

• Export with a custom timestamp struct from the types tree:

vspec export ros2interface \
  --vspec spec/VehicleSignalSpecification.vspec \
  -I spec \
  --types path/to/MyTypes.vspec \
  --output ./out \
  --package-name vss_interfaces \
  --mode leaf \
  --srv both --srv-use-msg \
  --timestamp-struct-fqn MyTypes.Timestamp

• Exports and writes a transformed VSS model.
  • Each signal becomes <Signal>.time with datatype set to the FQN given via --timestamp-struct-fqn
  • and <Signal>.value carrying the original datatype.
  • The timestamp struct itself is NOT re-emitted.

vspec export ros2interface \
  --vspec spec/VehicleSignalSpecification.vspec \
  -I spec \
  --output ./out \
  --package-name vss_interfaces \
  --mode leaf \
  --output-vspec ./out/transformed.vspec

Full example using the vehicle_signal_specification repo side-by-side with vss-tools:

Assumes the following folder layout:

<parent-folder>/
├── vehicle_signal_specification/
└── vss-tools/

Adjust paths accordingly if your layout differs.

vspec export ros2interface \
  --vspec ../vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
  -I ../vehicle_signal_specification/spec/include \
  --types ../vehicle_signal_specification/spec/VehicleDataTypes.vspec \
  -q ../vehicle_signal_specification/spec/quantities.yaml \
  -u ../vehicle_signal_specification/spec/units.yaml \
  --output ./output \
  --package-name vss_speed_interfaces \
  --mode leaf \
  --srv both --srv-use-msg \
  --topics Vehicle.Speed \
  --output-vspec ./out/transformed.vspec \
  --timestamp-struct-fqn VehicleDataTypes.Timestamp

Usage

vspec export ros2interface \
  --vspec spec/VehicleSignalSpecification.vspec \
  -I spec \
  --types spec/MyTypes.vspec \
  --output ./out \
  --package-name vss_interfaces \
  --mode aggregate|leaf \
  --srv get|set|both \
  [--srv-use-msg | --no-srv-use-msg] \
  [--timestamp-struct-fqn <fqn>] \
  [--topics PATTERN ...] \
  [--exclude-topics PATTERN ...] \
  [--topics-file patterns.txt] \
  [--topics-case-insensitive] \
  [--output-vspec transformed.vspec]