ros2-custom-interfaces

name	ros2-custom-interfaces
description	Generate ROS 2 custom message (.msg) and service (.srv) interface definitions for educational content. This skill should be used when creating lessons that teach interface design, writing exercises involving custom data types, or generating worked examples for robotics communication protocols.
version	1.0.0
status	active

ROS 2 Custom Interfaces Skill

Purpose: Generate accurate, educational ROS 2 custom message and service interface definitions following official ROS 2 Humble patterns for the Physical AI textbook.

When to Use

• Creating lessons in Chapter 5 (Communication Mastery - Lesson 3)
• Writing interface design exercises
• Generating worked examples for custom robot data types
• Teaching .msg and .srv file format and build process

Live Documentation Access

CRITICAL: Before generating any code, fetch current ROS 2 documentation using Context7 MCP:

Tool: mcp__context7__resolve-library-id
libraryName: "ros2 custom interfaces"

Then:
Tool: mcp__context7__get-library-docs
context7CompatibleLibraryID: [resolved ID]
topic: "custom msg srv interfaces"

This ensures interface patterns match current ROS 2 Humble conventions.

Interface Definition Patterns

Custom Message (.msg) Pattern

# File: msg/RobotStatus.msg
# Custom message for robot status reporting

# Header with timestamp
builtin_interfaces/Time stamp

# Robot identification
string robot_name
int32 robot_id

# Status information
bool is_active
float64 battery_level      # 0.0 to 100.0
float64[] joint_positions  # Array of joint angles in radians

# Nested message (from geometry_msgs)
geometry_msgs/Pose current_pose

Custom Service (.srv) Pattern

# File: srv/MoveRobot.srv
# Custom service for robot movement commands

# Request
string target_frame
geometry_msgs/Point target_position
float64 speed_factor  # 0.0 to 1.0
---
# Response
bool success
string message
float64 time_to_reach  # Estimated seconds

Package Structure for Interfaces

my_robot_interfaces/
├── CMakeLists.txt
├── package.xml
├── msg/
│   ├── RobotStatus.msg
│   └── SensorData.msg
└── srv/
    ├── MoveRobot.srv
    └── GetStatus.srv

CMakeLists.txt (Essential Parts)

cmake_minimum_required(VERSION 3.8)
project(my_robot_interfaces)

find_package(ament_cmake REQUIRED)
find_package(builtin_interfaces REQUIRED)
find_package(geometry_msgs REQUIRED)
find_package(rosidl_default_generators REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/RobotStatus.msg"
  "msg/SensorData.msg"
  "srv/MoveRobot.srv"
  "srv/GetStatus.srv"
  DEPENDENCIES builtin_interfaces geometry_msgs
)

ament_package()

package.xml (Essential Parts)

<?xml version="1.0"?>
<package format="3">
  <name>my_robot_interfaces</name>
  <version>0.1.0</version>
  <description>Custom interfaces for robot communication</description>
  <maintainer email="[e-mail]">Your Name</maintainer>
  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>
  <buildtool_depend>rosidl_default_generators</buildtool_depend>

  <depend>builtin_interfaces</depend>
  <depend>geometry_msgs</depend>

  <member_of_group>rosidl_interface_packages</member_of_group>
</package>

Built-in Types Reference

Primitive Types

Type	Description	Python Equivalent
bool	Boolean	bool
byte	8-bit unsigned	int
char	8-bit char	str (single char)
float32	32-bit float	float
float64	64-bit float	float
int8/16/32/64	Signed integers	int
uint8/16/32/64	Unsigned integers	int
string	UTF-8 string	str

Array Types

Syntax	Description
float64[]	Unbounded array
float64[3]	Fixed-size array (3 elements)
float64[<=10]	Bounded array (max 10)

Common Standard Message Types

• std_msgs/String, std_msgs/Int32, std_msgs/Bool
• geometry_msgs/Point, geometry_msgs/Pose, geometry_msgs/Twist
• sensor_msgs/Image, sensor_msgs/LaserScan, sensor_msgs/JointState
• builtin_interfaces/Time, builtin_interfaces/Duration

Educational Requirements

Layer 1 (Manual Foundation)

• Explain why custom interfaces needed (type safety, documentation)
• Walk through .msg/.srv file format
• Demonstrate build process with colcon

Layer 2 (AI Collaboration)

• Design interface from natural language requirements
• Iterate on interface design with AI feedback
• Generate boilerplate package structure (Three Roles INVISIBLE)

Layer 3 (Intelligence Design)

• Interface versioning strategies
• Designing for extensibility
• Standard vs custom interface decision framework

Hardware Tier Compatibility

Note: Interface packages require compilation with colcon.

• Tier 1: Cloud ROS 2 workspace with colcon build
• Tier 2+: Local ROS 2 Humble installation

Build commands:

cd ~/ros2_ws
colcon build --packages-select my_robot_interfaces
source install/setup.bash

Common Mistakes to Prevent

1. Missing DEPENDENCIES: Always list dependent packages in CMakeLists.txt
2. Wrong member_of_group: Must include rosidl_interface_packages
3. Type mismatches: Python uses float for float32/float64, int for all integers
4. Forgetting to source: Must source install/setup.bash after build

Interface Design Decision Framework

Create Custom Message When:

• Standard messages don't capture your data structure
• You need semantic meaning (RobotStatus vs generic struct)
• Multiple nodes will use the same data format
• Type checking prevents bugs

Use Standard Messages When:

• Data fits existing types (Point, Pose, Twist)
• Interoperability with existing tools needed
• Rapid prototyping (avoid build cycle)

Integration with Other Skills

• ros2-publisher-subscriber: Using custom messages in pub/sub
• ros2-service-pattern: Using custom services
• ros2-launch-system: Building interface packages in workspace

Authoritative Source

All patterns verified against: https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces.html