ros2_medkit

User Guide

  • Introduction
    • ros2_medkit
    • What is ros2_medkit?
    • Packages
    • Next Steps
    • Community
  • Installation
    • System Requirements
    • Prerequisites
    • Installation from Source
    • Verifying Installation
    • Docker Installation
    • Development Installation
    • Troubleshooting
    • Experimental: Pixi
    • Next Steps
  • Getting Started
    • Overview
    • Prerequisites
    • Step 1: Launch the Gateway
    • Step 2: Explore the API
    • Step 3: Discover Areas and Components
    • Step 4: Read Sensor Data
    • Step 5: Call Services and Actions
    • Step 6: Manage Parameters
    • Step 7: Monitor Faults
    • Using with Web UI
    • Using with LLMs (MCP)
    • Using with Postman
    • Next Steps
  • Tutorials
    • Demos Overview
      • Sensor Diagnostics Demo
        • Overview
        • Prerequisites
        • Starting the Demo
        • Exploring the Demo
        • Reading Sensor Data
        • Managing Configurations
        • Fault Injection
        • Stopping the Demo
        • Architecture
        • See Also
      • TurtleBot3 Demo
        • Overview
        • Prerequisites
        • Starting the Demo
        • Exploring the System
        • Reading Sensor Data
        • Sending Navigation Goals
        • Managing Parameters
        • Fault Injection
        • Stopping the Demo
        • See Also
      • Learning Path
      • Choose Your Demo
    • Heuristic Runtime Discovery
      • Overview
      • When to Use Heuristic Discovery
      • Quick Start
      • Understanding the Entity Hierarchy
      • Configuration Options
        • create_synthetic_components
        • grouping_strategy
      • Handling Topic-Only Namespaces
        • Example: Filtering Noise
      • API Endpoints
        • Apps Endpoints
        • Components Endpoints
      • Migrating to Manifest Discovery
      • See Also
    • Manifest-Based Discovery
      • Introduction
      • Discovery Modes Comparison
      • Writing Your First Manifest
      • Enabling Manifest Mode
        • Option 1: Using Launch File
        • Option 2: Using Parameter File
        • Option 3: Command Line Parameters
      • Verifying the Configuration
      • Understanding Hybrid Mode
        • Merge Report
        • Runtime Linking
        • ROS Binding Configuration
        • Checking Linking Status
      • Entity Hierarchy
        • With Areas (Complex Robots)
        • Without Areas (Simple Robots)
        • Common Elements
      • Controlling Gap-Fill in Hybrid Mode
      • Hot Reloading
      • REST API Endpoints
      • Next Steps
    • Migration Guide: Runtime to Hybrid Mode
      • Overview
      • Step 1: Audit Your System
      • Step 2: Define Areas
      • Step 3: Define Components
      • Step 4: Define Apps
      • Step 5: Define Functions
      • Step 6: Create the Manifest File
      • Step 7: Test in Hybrid Mode
      • Step 8: Iterate and Refine
      • Validation Checklist
      • Common Issues
      • Best Practices
      • Next Steps
    • Configuring Authentication
      • Overview
      • Authentication Modes
      • Roles and Permissions
      • Basic Setup
      • Using Authentication
      • Production Recommendations
      • Troubleshooting
      • See Also
    • Configuring HTTPS/TLS
      • Overview
      • Quick Start (Development)
      • Generating Development Certificates
      • Manual Configuration
      • Configuration Options
      • Using with curl
      • Using with Postman
      • Production Certificates
      • Security Best Practices
      • Troubleshooting
      • See Also
    • Resource Locking
      • Overview
      • Quick Example
      • Lock Enforcement
      • Per-Entity Configuration
      • Lock Expiry
      • Plugin Integration
      • Configuration Reference
      • See Also
    • Diagnostic Scripts
      • Overview
      • Quick Example
      • Script Formats
      • Manifest-Defined Scripts
      • Execution Lifecycle
        • Starting an Execution
        • Polling Status
        • Controlling a Running Execution
        • Deleting an Execution Record
        • Timeouts
        • Concurrency
      • Security
        • Disabling Uploads
        • RBAC Roles
        • File Size Limits
      • ScriptProvider Plugins
      • Configuration Reference
    • Configuring Snapshot Capture
      • Overview
      • Quick Start
      • Configuration Options
      • Advanced Configuration
      • Querying Snapshots
      • Example Workflow
      • Troubleshooting
      • Rosbag Capture (Time-Window Recording)
        • Enabling Rosbag Capture
        • Rosbag Configuration Options
        • Understanding lazy_start Mode
        • Downloading Rosbag Files
        • Example: Production Configuration
        • Example: Debugging Configuration
      • See Also
      • Migration from Legacy Endpoints
    • Configuring Fault Correlation
      • Overview
        • How It Works
      • Quick Start
      • Configuration Reference
        • Top-Level Settings
        • Patterns Section
      • Hierarchical Mode
      • Auto-Cluster Mode
      • Querying Correlation Data
      • Example: Complete Configuration
      • Troubleshooting
      • See Also
    • Docker Deployment
      • Overview
      • Quick Start with Demo
      • Building the Gateway Image
      • Docker Compose Configuration
      • Network Configuration
      • CORS for Web UI
      • Volume Mounts
      • Health Checks
      • Production Considerations
      • Running with Simulation
      • Troubleshooting
      • See Also
    • Development Container
      • Overview
      • Prerequisites
      • Quick Start
      • Container Configuration
        • devcontainer.json
        • Dockerfile
      • Development Workflow
        • Building the Project
        • Running Tests
        • Building Documentation
        • Generating Coverage
      • Customization
        • Adding Extensions
        • Changing Shell
        • Persistent Storage
      • Troubleshooting
        • Container fails to start
        • ROS 2 commands not found
        • Slow file I/O on macOS/Windows
      • See Also
    • Integrating with Your ROS 2 System
      • Overview
      • Zero-Configuration Integration
      • Organizing with Namespaces
      • Reporting Custom Faults
      • Exposing Custom Data
      • Exposing Services and Actions
      • Exposing Parameters
      • Launch File Integration
      • Production Checklist
      • See Also
    • Customizing the Entity Hierarchy
      • Understanding the Entity Model
      • Default Entity Mapping (Runtime Mode)
      • Designing Your Namespace Structure
      • Implementing in Launch Files
      • Topic-Based Discovery
      • Filtered Topics
      • Best Practices
      • Example: Complete Robot Hierarchy
      • See Also
    • Web UI (ros2_medkit_web_ui)
      • Features
      • Quick Start
        • Using Docker
        • From Source
      • Connecting to ros2_medkit
      • Using the Interface
        • Data View
        • Operations
        • Configurations
      • Docker Compose Example
      • Docker Image Tags
      • Tech Stack
      • Repository
      • See Also
    • MCP Server for LLM Integration
      • Overview
      • Quick Start
        • Prerequisites
        • Installation
        • Running the Server
      • Configuration
      • Claude Desktop Integration
      • VS Code Integration
      • Docker Usage
      • MCP Tools Reference
        • Discovery Tools
        • Faults Tools
        • Data Tools
        • Operations Tools
        • Configurations Tools
      • Example Prompts
      • Repository
      • See Also
    • OpenAPI / Swagger
      • Accessing the Spec
      • Swagger UI
      • Using with External Tools
      • Configuration
      • See Also
    • Beacon Discovery Plugins
      • Overview
      • The MedkitDiscoveryHint Message
        • Hint Lifecycle
      • Topic Beacon
        • How It Works
        • Publisher Example (C++)
        • CMakeLists.txt Dependencies
        • Configuration
        • Querying Topic Beacon Data
      • Parameter Beacon
        • How It Works
        • Parameter Naming Convention
        • Node Example (C++)
        • Configuration
        • Querying Parameter Beacon Data
      • Running Both Plugins
      • Entity Metadata Injection
      • When to Use Which
      • See Also
    • Plugin System
      • Overview
      • Configuration
      • Writing a Plugin
      • Complete Minimal Plugin
      • Plugin Lifecycle
      • PluginContext
      • PluginContext API (v4)
      • Custom REST Endpoints
      • Cyclic Subscription Extensions
      • IntrospectionProvider Example
      • ScriptProvider Example
      • Multiple Plugins
      • Graph Provider Plugin (ros2_medkit_graph_provider)
      • Error Handling
      • API Versioning
      • Build Requirements
    • Linux Introspection Plugins
      • Requirements
      • Building
      • Configuration
      • API Reference
        • procfs Endpoints
        • systemd Endpoints
        • container Endpoints
      • Error Responses
      • Composable Nodes
      • Introspection Metadata
      • Troubleshooting
        • PID lookup failures
        • Composable nodes
        • Permission errors (procfs)
        • systemd bus access
        • Container detection
    • Triggers Use Cases
      • Prerequisites
      • Scenario 1: OTA Update Monitoring
        • Step 1: Create the update status trigger
        • Step 2: Create the failure alert trigger with log_settings
        • Step 3: Create the fault monitor trigger
        • Step 4: List all triggers
        • Step 5: Connect to SSE event streams
        • Step 6: Clean up
      • Scenario 2: Thermal Protection
        • Step 1: Create the range warning trigger
        • Step 2: Create the critical temperature alert
        • Step 3: Create the component fault trigger
        • Step 4: Verify all triggers
        • Step 5: Connect SSE streams and observe cascade
        • Step 6: Clean up
      • Scenario 3: Fleet Diagnostics
        • Step 1: Start gateway in manifest mode
        • Step 2: Create the area-level fault trigger
        • Step 3: Create the app-level data trigger
        • Step 4: Verify triggers on different entity types
        • Step 5: Connect SSE streams
        • Step 6: Clean up
      • Key Concepts
      • See Also
    • Demos
    • Discovery Tutorials
    • Manifest Discovery
    • Basic Tutorials
    • Companion Projects
    • Advanced Tutorials
  • Troubleshooting & FAQ
    • Installation Issues
    • Gateway Issues
    • Authentication Issues
    • TLS/HTTPS Issues
    • Docker Issues
    • Fault Manager Issues
    • Performance Issues
    • FAQ
    • Getting Help

Architecture

  • Architecture
    • ros2_medkit_beacon_common
      • Overview
      • Architecture
      • Main Components
      • Design Decisions
        • Shared Library, Not Plugin
        • Three-State Hint Lifecycle
        • Capacity Limits
        • Validation Strategy
    • ros2_medkit_cmake
      • Overview
      • Modules
      • Design Decisions
        • Separate Package
        • Multi-Distro Strategy
    • ros2_medkit_diagnostic_bridge
      • Overview
      • Architecture
      • Data Flow
      • Severity Mapping
      • Main Components
      • Configuration
        • Parameters
        • Example Launch Configuration
      • Design Decisions
        • Fault Code Auto-Generation
        • STALE as CRITICAL
    • ros2_medkit_fault_manager
      • Architecture
      • Main Components
      • Services
        • ~/report_fault
        • ~/list_faults
        • ~/clear_fault
      • Design Decisions
        • Thread Safety
        • Fault Aggregation
        • Severity Escalation
        • Status Lifecycle (Debounce Model)
    • ros2_medkit_fault_reporter
      • Overview
      • Architecture
      • Main Components
      • Usage
        • Basic Example
        • Configuration
      • Design Decisions
        • Local Filtering Rationale
        • Fire-and-Forget Service Calls
        • Thread Safety
        • Integration with FaultManager
    • ros2_medkit_gateway
      • Architecture
      • Main Components
      • Triggers
    • ros2_medkit_graph_provider
      • Overview
      • Architecture
      • Graph Document Schema
      • Pipeline Status Logic
      • Data Sources
        • Diagnostics Subscription
        • Fault Manager Integration
        • Entity Cache
        • Function Scoping
      • Design Decisions
        • Extracted Plugin
        • Static build_graph_document
        • Per-Function Config Overrides
        • Cyclic Subscription Sampler
    • ros2_medkit_integration_tests
      • Overview
      • Architecture
      • Test Categories
        • Feature Tests
        • Scenario Tests
      • Demo Nodes
      • Shared Test Library
      • Design Decisions
        • Test Split: Features vs Scenarios
        • Shared Launch Helpers
        • Self-Contained Scenario Steps
    • ros2_medkit_linux_introspection
      • Overview
      • Architecture
      • Plugins
      • PidCache
      • Vendor Extension Endpoints
      • Design Decisions
        • Three Separate Plugins
        • IntrospectionProvider Dual Interface
        • Configurable proc_root
    • ros2_medkit_msgs
      • Overview
      • Message Definitions
      • Service Definitions
      • Design Decisions
        • Separate Package
        • SOVD Alignment
    • ros2_medkit_param_beacon
      • Overview
      • How It Works
      • Key Design Points
        • Polling Model
        • Client Management
        • Backoff and Budget
        • Injectable Client Factory
        • Integration with Gateway
    • ros2_medkit_serialization
      • Overview
      • Architecture
      • Main Components
      • Data Flow
        • Publishing (JSON → CDR)
        • Subscribing (CDR → JSON)
        • Service Calls (JSON → CDR → JSON)
      • Design Decisions
        • YAML Bridge
        • Singleton TypeCache
        • Thread Safety
      • Usage in Gateway
        • Example: Publishing to a Topic
        • Example: Deserializing from Subscription
    • ros2_medkit_topic_beacon
      • Overview
      • How It Works
      • Key Design Points
        • Push Model
        • Rate Limiting
        • Timestamp Back-Projection
        • Integration with Gateway
  • Roadmap
    • Strategy
    • Milestones
      • MS1: Full Discovery & Data Access - Complete
      • MS2: App Observability - Complete
      • MS3: Configuration & Control - Complete
      • MS4: Automation & Subscriptions - In Progress
      • MS5: Fleet & Advanced Features - In Progress
      • MS6: Fault Management System - Complete
      • Beyond Milestones
    • Future Directions

Configuration

  • Configuration Reference
    • Server Configuration
      • Quick Start
      • Network Settings
      • TLS/HTTPS Configuration
      • CORS Configuration
      • Data Access Settings
      • Fault Manager Integration
      • Logging Configuration
      • Performance Tuning
      • Bulk Data Storage
      • SSE (Server-Sent Events)
      • Triggers
      • Rate Limiting
      • Authentication
      • Plugin Framework
      • Software Updates
      • Complete Example
      • API Documentation
      • Scripts
      • Locking
      • See Also
    • Discovery Options Reference
      • Discovery Modes
      • Runtime Discovery Options
        • Synthetic Components
        • Synthetic Areas
        • Topic-Only Namespaces
      • Merge Pipeline (Hybrid Mode)
        • Layer Enable/Disable
        • Field Groups
        • Merge Policies
        • Gap-Fill
        • Health Endpoint
      • Configuration Example
      • Command Line Override
      • Discovery Mechanism Selection
      • Beacon Discovery Plugin (TopicBeaconPlugin)
        • Configuration
        • Beacon Lifecycle
        • Beacon Metadata Keys
      • Parameter Beacon Plugin (ParameterBeaconPlugin)
        • Configuration
        • Parameter Naming
        • Running Both Plugins
      • See Also
    • Manifest Schema Reference
      • Top-Level Structure
        • manifest_version (Required)
        • metadata (Optional)
        • config (Optional)
      • Areas
        • Schema
        • Fields
        • Example
      • Components
        • Schema
        • Fields
        • Common Component Types
        • Example
      • Apps
        • Schema
        • Fields
        • ros_binding Fields
        • Example
      • Functions
        • Schema
        • Fields
        • Function Capabilities
        • Example
      • Scripts
        • Schema
        • Fields
        • Example
      • Flat Entity Tree
      • Complete Example
      • Validation
    • Fault Manager Configuration
      • Basic Configuration
        • Storage
        • Debounce Settings
        • Per-Entity Thresholds
      • Snapshot Configuration
        • Basic Snapshot Settings
        • Rosbag Recording
      • Correlation Configuration
      • Complete Example
      • See Also
    • Diagnostic Bridge Configuration
      • Overview
      • Parameters
      • Custom Fault Code Mappings
        • Auto-Generated Fault Codes
      • Launch File Configuration
      • Integration with FaultManager
      • Migration Strategy
      • See Also
    • Server Configuration
    • Discovery Options
    • Manifest Configuration
    • Fault Manager
    • Diagnostic Bridge

API Reference

  • API Reference
    • REST API Reference
      • Server Capabilities
      • Discovery Endpoints
        • Areas
        • Components
        • Apps
        • Functions
      • Data Endpoints
      • Operations Endpoints
        • List Operations
        • Execute Operations
      • Configurations Endpoints
      • Resource Locking
      • Faults Endpoints
      • Logs Endpoints
      • Bulk Data Endpoints
        • List Categories
        • List Bulk Data Items
        • Download Bulk Data
        • Upload Bulk Data
        • Delete Bulk Data
      • Software Updates
      • Cyclic Subscriptions
      • Scripts
        • Upload Script
        • List Scripts
        • Get Script
        • Delete Script
        • Start Execution
        • Get Execution Status
        • Terminate Execution
        • Delete Execution
      • Triggers
        • Create Trigger
        • List Triggers
        • Get Trigger
        • Update Trigger
        • Delete Trigger
        • Trigger Events (SSE Stream)
        • Trigger Conditions
        • Configuration
        • Persistence
      • Rate Limiting
        • Configuration
        • Response Headers
        • Rejection (429 Too Many Requests)
      • Authentication Endpoints
      • Vendor Extension Endpoints (Plugins)
        • Linux Process Introspection (x-medkit-procfs)
        • Systemd Unit Introspection (x-medkit-systemd)
        • Container Introspection (x-medkit-container)
        • x-medkit-topic-beacon
        • x-medkit-param-beacon
      • Error Responses
        • Common Error Codes
      • URL Encoding
      • SOVD Compliance
      • Capability Description (OpenAPI Docs)
        • See Also
    • Locking API
      • Overview
      • Configuration
      • Endpoints
        • Acquire Lock
        • List Locks
        • Get Lock Details
        • Extend Lock
        • Release Lock
      • Error Responses
    • Message Definitions
      • Messages
        • Fault.msg
        • FaultEvent.msg
        • MutedFaultInfo.msg
        • ClusterInfo.msg
      • Services
        • ReportFault.srv
        • ClearFault.srv
        • ListFaults.srv
        • GetSnapshots.srv
        • MedkitDiscoveryHint.msg
      • See Also
    • C++ API Reference
      • ros2_medkit_gateway
        • Classes
        • Data Models
      • ros2_medkit_fault_manager
        • ros2_medkit_fault_manager::FaultManagerNode
        • ros2_medkit_fault_manager::FaultStorage
        • ros2_medkit_fault_manager::InMemoryFaultStorage
      • ros2_medkit_fault_reporter
        • ros2_medkit_fault_reporter::FaultReporter
        • ros2_medkit_fault_reporter::LocalFilter
      • ros2_medkit_diagnostic_bridge
        • ros2_medkit_diagnostic_bridge::DiagnosticBridgeNode
      • ros2_medkit_serialization
        • ros2_medkit_serialization::JsonSerializer
        • ros2_medkit_serialization::TypeCache
        • ros2_medkit_serialization::SerializationError
        • ros2_medkit_serialization::TypeNotFoundError
        • ros2_medkit_serialization::JsonConversionError
    • REST API
    • Message Definitions
    • C++ API

Standard Compliance

  • Standard Compliance
    • Verification
    • Coverage Report
      • Overall Coverage
      • Coverage by Category
      • Missing Verification
      • Full Traceability Matrix
    • API Specification
      • Discovery
      • Faults
      • Data
      • DataSets
      • Subscriptions
      • Operations
        • Operations Overview
        • ExecutionStatus Values
        • Capability Mapping
      • Scripts
      • Configuration
      • Modes
      • ClearData
      • Logs
      • CommLogs
      • BulkData
      • Lifecycle
      • Updates
      • Auth
      • Locking
    • All Requirements

Reference

  • Glossary
  • Changelog
    • Changelog for package ros2_medkit_gateway
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_fault_manager
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_fault_reporter
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_diagnostic_bridge
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_serialization
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_msgs
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
      • 0.2.0 (2026-02-07)
    • Changelog for package ros2_medkit_integration_tests
      • 0.4.0 (2026-03-20)
      • 0.3.0 (2026-02-27)
    • Changelog for package ros2_medkit_cmake
      • 0.4.0 (2026-03-20)
    • Changelog for package ros2_medkit_linux_introspection
      • 0.4.0 (2026-03-20)
    • Changelog for package ros2_medkit_beacon_common
      • 0.4.0 (2026-03-20)
    • Changelog for package ros2_medkit_param_beacon
      • 0.4.0 (2026-03-20)
    • Changelog for package ros2_medkit_topic_beacon
      • 0.4.0 (2026-03-20)
    • Changelog for package ros2_medkit_graph_provider
      • 0.4.0 (2026-03-20)
ros2_medkit
  • Architecture
  • View page source

Architecture

This section contains design documentation for the ros2_medkit project packages.

  • ros2_medkit_beacon_common
  • ros2_medkit_cmake
  • ros2_medkit_diagnostic_bridge
  • ros2_medkit_fault_manager
  • ros2_medkit_fault_reporter
  • ros2_medkit_gateway
  • ros2_medkit_graph_provider
  • ros2_medkit_integration_tests
  • ros2_medkit_linux_introspection
  • ros2_medkit_msgs
  • ros2_medkit_param_beacon
  • ros2_medkit_serialization
  • ros2_medkit_topic_beacon
Previous Next

© Copyright 2026, selfpatch.

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