HID ROS 2

Getting Started

  • Installation
    • Prerequisites
      • System Requirements
      • Required Dependencies
    • Installing ROS 2
    • Installing Build Tools
    • Installing HID ROS 2
      • From Source
    • Installing USB HID Libraries
    • Installing Python Dependencies
    • Verifying Installation
    • Setting Up USB Permissions
    • Optional: Install Pre-commit Hooks
    • Next Steps
    • Troubleshooting
      • Build Failures
      • USB Permission Denied
      • Missing Python Modules
  • Quick Start Guide
    • Overview
    • Step 1: Create a Package
    • Step 2: Define Your Device Schema
    • Step 3: Configure CMake
    • Step 4: Build
    • Step 5: Verify Generated Files
    • Step 6: Prepare Your Firmware
    • Step 7: Launch Your Device
    • Step 8: Monitor Data
    • Debugging Your Device
      • List Connected HID Devices
      • Monitor Raw USB Reports
      • Validate Your Schema
    • Next Steps
    • Common Issues
      • Device Not Found
      • Permission Denied
      • Wrong Data Values
      • Build Errors
    • Complete Example
  • Tutorial: Create Your Custom HID Device Integration
    • What You’ll Build
    • Prerequisites
    • Step 1: Clone and Build the Base Repository
      • 1.1 Create Workspace and Clone
      • 1.2 Install Dependencies
      • 1.3 Build the Base Packages
    • Step 2: Create Your Custom Device Package
      • 2.1 Create Package Structure
      • 2.2 Configure CMakeLists.txt
      • 2.3 Update package.xml
    • Step 3: Define Your Device Schema
      • 3.1 Create Schema File
      • 3.2 Understanding the Schema
    • Step 4: Build Your Package
      • 4.1 Validate Schema (Optional but Recommended)
      • 4.2 Build Package
      • 4.3 Verify Generated Files
      • 4.4 Inspect Generated Files
    • Step 5: Set Up USB Permissions
      • 5.1 Find Your Device
      • 5.2 Create udev Rule
    • Step 6: Test Without Hardware (Optional)
      • 6.1 Inspect HID Devices
    • Step 7: Launch Your Device
      • 7.1 Launch with Generic Broadcaster
      • 7.2 Monitor Data
      • 7.3 Check State Interfaces
    • Step 8: Debug and Verify
      • 8.1 Monitor Raw USB Data
      • 8.2 Compare with ROS Topic
    • Step 9: Customize the Integration
      • 9.1 Modify Controller Configuration
      • 9.2 Add Custom Launch Arguments
      • 9.3 Create Custom Controllers
    • Troubleshooting
      • Device Not Found
      • No Data on Topics
      • Wrong Values
    • Next Steps
      • Integrate with Your Firmware
      • Add Command Interface
      • Process Data
    • Summary
    • Additional Resources
  • Basic Concepts
    • Architecture Overview
      • Single Source of Truth
    • Core Components
      • 1. YAML Schema
      • 2. Code Generator (hid_descriptor_generator)
      • 3. Hardware Interface (hid_hardware)
      • 4. Controllers
      • 5. Developer Tools (hid_tools)
    • Data Flow
      • Input Reports (Device → ROS 2)
      • Output Reports (ROS 2 → Device)
    • Type System
      • Supported Types
      • Byte Order
      • Type Conversion
    • State and Command Interfaces
      • State Interfaces (Read-Only)
      • Command Interfaces (Write)
    • Report IDs
      • Input Reports
      • Output Reports
      • Why Different IDs?
    • Hardware Interface Lifecycle
      • Update Cycle
    • YAML Schema Structure
      • 1. Device Identification
      • 2. ROS 2 Configuration
      • 3. Data Fields
    • Generated Files
      • For ROS 2
      • For Firmware
    • Integration with ros2_control
      • Benefits
      • ros2_control Components
    • Next Steps

User Guide

  • Schema Reference
    • Overview
    • Required Fields
      • Device Information
        • device_name
        • vendor_id
        • product_id
      • ROS 2 Configuration
        • sensor_name
        • frame_id
        • update_rate
    • Optional Fields
      • Report IDs
        • input_report_id
        • output_report_id
    • Field Definitions
      • Input Fields
        • Field Properties
      • Output Fields
    • Complete Example
    • Type Reference
      • Integer Types
      • Floating-Point Types
      • Type Selection Guidelines
    • Array Fields
      • Single Value
      • Array Value
    • Validation
      • Common Errors
    • Best Practices
      • Naming Conventions
      • Field Ordering
      • Type Selection
      • Documentation
      • Report IDs
    • See Also
  • Code Generation
    • Overview
    • How It Works
      • Build-Time Generation
      • The CMake Function
      • Regeneration
    • Generated Files
      • ROS 2 Side
      • Firmware Side
    • Generation Process Details
      • Step 1: Schema Parsing
      • Step 2: HID Descriptor Generation
      • Step 3: URDF Generation
      • Step 4: Controller Configuration
      • Step 5: Launch File Generation
    • File Locations
      • Build Directory
      • Install Directory
    • Type Mapping
      • YAML to HID Descriptor
      • YAML to C Types
    • Advanced Usage
      • Multiple Schemas
      • Custom Output Directories
      • Manual Invocation
    • Customization
      • Modifying Generated Files
      • Example: Custom Launch File
    • Debugging Generation
      • Verbose Output
      • Check Generated Files
      • Validate Schema First
    • Troubleshooting
      • Generation Not Running
      • Files Not Installed
      • Wrong Content
    • See Also
  • Hardware Interface
    • Overview
    • Features
    • Configuration
    • Lifecycle
    • Implementation Details
  • Controllers
    • hid_generic_broadcaster
    • hid_diagnostic_broadcaster
    • signal_command_controller
  • Developer Tools
    • Overview
    • validate_schema
      • Usage
      • Features
    • inspect_device
      • Usage
      • Features
    • generate_hid_descriptor
      • Usage
      • Features

Examples

  • Dummy Pose Device Example
    • Overview
    • Schema
    • Building
    • Running
    • Source Code
  • Signal Generator Example
    • Overview
    • Schema
    • How It Works
    • Building
    • Running
    • Monitoring
      • Monitor Generated Signal
      • Monitor Current Parameters
    • Source Code

Advanced Topics

  • Understanding HID Report Descriptors
    • What is a HID Report Descriptor?
    • Report Structure Overview
      • Reports vs. Descriptors
    • Interactive Example: Temperature Sensor
    • Interactive Example: 3-Axis Accelerometer
    • Understanding Item Types
      • Main Items (Red)
      • Global Items (Blue)
      • Local Items (Green)
    • Byte-Level Item Format
      • Prefix Byte Breakdown
    • Report Size vs Report Count
      • Report Size
      • Report Count
      • The Math
    • Input vs Output Reports
      • Input Reports (Device → Host)
      • Output Reports (Host → Device)
      • Bidirectional Example
    • Main Item Flags
    • Usage Pages Reference
    • Common Mistakes
      • ❌ Wrong: Report Size in bytes
      • ✅ Correct: Report Size in bits
      • ❌ Wrong: Forgetting padding
      • ✅ Correct: Add padding to byte boundary
    • Quick Reference
      • Building a Descriptor
      • Type Quick Reference
    • See Also
  • Firmware Integration
    • Overview
    • Supported Platforms
    • Using the Generated Header
      • Include the Header
      • USB HID Descriptor
      • Report Structures
      • Receiving Output Reports
    • Platform-Specific Examples
      • Arduino
      • ESP32
    • Important Considerations
      • Structure Packing
      • Byte Order
      • Report Size
      • Timing
    • Debugging
      • Verify Descriptor
      • Test with inspect_device
    • Example Projects
  • Custom Controllers
    • Overview
    • Controller Basics
    • Creating a Controller
      • 1. Package Setup
      • 2. Controller Class
      • 3. Specify Interfaces
      • 4. Implement Update
    • Examples
    • Best Practices
  • Type System
    • Overview
    • Type Conversions
      • Integer Types
      • Floating-Point Types
    • Byte Packing
      • Report Structure
      • Firmware Struct
    • ros2_control Interface
    • Type Safety
      • Schema Validation
      • Runtime Checks
    • Performance
      • Optimization
      • Latency
    • Platform Considerations
      • Endianness
      • Alignment
      • Floating-Point
    • Advanced Topics
      • Custom Types
      • Compressed Data
    • Debugging Type Issues
      • Verify Byte Order
      • Check Alignment
      • Test Conversion
  • Debugging
    • Debugging Tools
      • 1. inspect_device
      • 2. ros2 control CLI
      • 3. ROS 2 Topic Tools
    • Common Issues
      • No Data Received
      • Wrong Values
      • Performance Issues
    • Debugging Workflow
    • Advanced Debugging
      • USB Packet Capture
      • Firmware Debugging
      • GDB Debugging
      • Logging
    • Validation Tools
      • Schema Validation
      • Report Size Calculation
    • Getting Help

Development

  • Contributing Guide
    • Code of Conduct
    • Ways to Contribute
    • Development Setup
    • Making Changes
  • Architecture
    • System Architecture
    • Component Details
    • Code Organization
  • API Reference
    • CMake API
      • hid_generate()
    • Python API
    • C++ API
      • hid_hardware::HidHardware
    • ROS 2 Interfaces
      • State Interfaces
      • Command Interfaces
    • Command-Line Tools
      • validate_schema
      • inspect_device
      • generate_hid_descriptor

Additional Resources

  • Troubleshooting
    • Device Connection Issues
      • Device Not Found
      • Permission Denied
    • Build Issues
      • Generator Not Found
      • Python Import Errors
    • Runtime Issues
      • No Data on Topics
      • Wrong Values
    • Getting Help
  • Frequently Asked Questions
    • General
      • What is HID ROS 2?
      • Why use HID instead of serial/Ethernet?
      • What devices are supported?
    • Schema and Configuration
      • Can I change the schema after deployment?
      • Do I need to write URDF?
      • Can I have multiple HID devices?
    • Development
      • How do I debug my device?
      • My values are wrong, what’s the issue?
      • Can I use this with Arduino?
    • Advanced Usage
      • Can I create custom controllers?
      • What’s the maximum data rate?
      • Can I send commands to the device?
    • More Questions?
  • Changelog
    • [Unreleased]
      • Added
      • Documentation
    • [0.1.0] - 2025-10-29
      • Added
HID ROS 2
  • Search

© Copyright 2025, Adnan Saood.

Built with Sphinx using a theme provided by Read the Docs.