# doc

**Repository Path**: rippleos/doc

## Basic Information

- **Project Name**: doc
- **Description**: MOSS 项目文档
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:2E86AB,100:A23B72&height=200&section=header&text=RippleOS&fontSize=70&fontColor=ffffff&animation=fadeIn&fontAlignY=35&desc=Robotics%20Middleware%20Platform&descAlignY=55&descSize=18" alt="RippleOS Banner">
</p>

<p align="center">
  <a href="#-overview">Overview</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#-modules">Modules</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-examples">Examples</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/C%2B%2B-17-blue?style=flat-square" alt="C++17">
  <img src="https://img.shields.io/badge/Linux-Compatible-brightgreen?style=flat-square" alt="Linux">
  <img src="https://img.shields.io/badge/RTOS-Ready-orange?style=flat-square" alt="RTOS">
</p>

---

## 🎯 Overview

**RippleOS** 是一套为自动驾驶和机器人系统设计的**模块化中间件框架**。

<table>
<tr>
<td width="50%">

### 🚗 为什么选择 RippleOS？

- **模块化设计** - 每个组件独立仓库，按需集成
- **行业标准** - AUTOSAR、DDS、OpenTelemetry
- **高性能** - 零拷贝通信，实时调度优化
- **生产就绪** - 完整的测试覆盖和文档

</td>
<td width="50%">

### 📊 项目统计

```
📦 23 Modules
💻 50k+ Lines of Code
🧪 80%+ Test Coverage
📖 Full Documentation
```

</td>
</tr>
</table>

---

## 🏗️ Architecture

<p align="center">
  <img src="architecture.svg" alt="RippleOS Architecture" width="90%">
</p>

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                          🚗 Application Layer                                │
│    Perception │ Planning │ Control │ Localization │ Prediction │ Decision   │
├─────────────────────────────────────────────────────────────────────────────┤
│                           📊 Observability                                   │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │  trace  │  │   log   │  │  perf   │  │ visual  │  │ record  │           │
│  │ Tracing │  │ Logging │  │ Metrics │  │ FoxGlove│  │  MCAP   │           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
├─────────────────────────────────────────────────────────────────────────────┤
│                         🔧 Configuration & Management                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │  param  │  │config_svr│  │ launch  │  │  exem   │  │ upgrade │           │
│  │ Params  │  │ Config  │  │ Launch  │  │ Executor│  │   OTA   │           │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘           │
├─────────────────────────────────────────────────────────────────────────────┤
│                          🔌 Communication Hub                                │
│                        ┌───────────────────┐                                │
│                        │       com        │                                │
│                        │  (Unified API)    │                                │
│                        └─────────┬─────────┘                                │
│            ┌─────────────────────┼─────────────────────┐                    │
│            │                     │                     │                    │
│     ┌──────▼──────┐      ┌──────▼──────┐      ┌──────▼──────┐              │
│     │     shm     │      │     dds     │      │   someip   │              │
│     │ Shared Mem  │      │     DDS     │      │   SOME/IP   │              │
│     │ Zero-Copy   │      │  Pub/Sub    │      │  Ethernet   │              │
│     └─────────────┘      └─────────────┘      └─────────────┘              │
│                                     │                                        │
│                              ┌──────▼──────┐                                │
│                              │   routing   │                                │
│                              │   Router    │                                │
│                              └─────────────┘                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                          ⚙️ Runtime & Safety                                 │
│     ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│     │ runtime │  │ safety  │  │  diag   │  │   tls   │                     │
│     │  Core   │  │ Monitor │  │   UDS   │  │  TLS    │                     │
│     └─────────┘  └─────────┘  └─────────┘  └─────────┘                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                              🛠️ Tools                                        │
│        ┌──────────┐           ┌──────────┐          ┌──────────┐           │
│        │  build   │           │  bridge  │          │   cal   │           │
│        │  Build   │           │   ROS2   │          │  Calib   │           │
│        └──────────┘           └──────────┘          └──────────┘           │
├─────────────────────────────────────────────────────────────────────────────┤
│                           💾 Data Layer                                      │
│                        ┌───────────────────┐                                │
│                        │      proto        │                                │
│                        │   (Protobuf IDL)  │                                │
│                        └───────────────────┘                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                          🖥️ Operating System                                 │
│                     Linux │ QNX │ VxWorks │ RTOS                            │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 📦 Modules

### 🔌 Communication Middleware

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [shm](https://gitee.com/rippleos/shm) | 共享内存通信 | ✅ Ready | 零拷贝、跨进程、高吞吐 |
| [dds](https://gitee.com/rippleos/dds) | DDS 数据分发 | ✅ Ready | 发布/订阅、QoS、发现 |
| [someip](https://gitee.com/rippleos/someip) | SOME/IP 协议 | ✅ Ready | 车载以太网、服务发现 |
| [com](https://gitee.com/rippleos/com) | 统一通信层 | ✅ Ready | Topic/Service/Action |
| [routing](https://gitee.com/rippleos/routing) | 路由管理 | ✅ Ready | 消息路由、负载均衡 |

### 🏃 Runtime Framework

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [runtime](https://gitee.com/rippleos/runtime) | 运行时核心 | ✅ Ready | 线程池、定时器、信号 |
| [launch](https://gitee.com/rippleos/launch) | 进程启动 | ✅ Ready | 依赖管理、生命周期 |
| [exem](https://gitee.com/rippleos/exem) | 执行编排 | ✅ Ready | 节点调度、资源管理 |
| [safety](https://gitee.com/rippleos/safety) | 安全监控 | ✅ Ready | 心跳、健康检查、故障恢复 |

### 📊 Observability

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [log](https://gitee.com/rippleos/log) | 日志系统 | ✅ Ready | 异步、多Sink、结构化 |
| [trace](https://gitee.com/rippleos/trace) | 分布式追踪 | ✅ Ready | OpenTelemetry、Span |
| [perf](https://gitee.com/rippleos/perf) | 性能监控 | ✅ Ready | Prometheus、指标采集 |
| [visual](https://gitee.com/rippleos/visual) | 可视化 | ✅ Ready | FoxGlove、WebSocket |
| [record](https://gitee.com/rippleos/record) | 录制回放 | ✅ Ready | MCAP格式、时间同步 |

### ⚙️ Configuration & Diagnostics

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [param](https://gitee.com/rippleos/param) | 参数管理 | ✅ Ready | 动态配置、热更新 |
| [config_server](https://gitee.com/rippleos/config_server) | 配置服务 | ✅ Ready | 集中管理、版本控制 |
| [diag](https://gitee.com/rippleos/diag) | UDS诊断 | ✅ Ready | ISO 14229、DTC、DID |

### 🔐 Security & Upgrade

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [tls](https://gitee.com/rippleos/tls) | 安全传输 | ✅ Ready | TLS/DTLS、证书管理 |
| [upgrade](https://gitee.com/rippleos/upgrade) | 远程升级 | ✅ Ready | OTA、差分更新 |

### 🛠️ Tools & Bridges

| Module | Description | Status | Key Features |
|--------|-------------|--------|--------------|
| [build](https://gitee.com/rippleos/build) | 构建工具 | ✅ Ready | CLI、依赖管理 |
| [bridge](https://gitee.com/rippleos/bridge) | 桥接适配 | ✅ Ready | ROS2、AUTOSAR |
| [cal](https://gitee.com/rippleos/cal) | 在线标定 | ✅ Ready | 参数标定、验证 |
| [proto](https://gitee.com/rippleos/proto) | 消息定义 | ✅ Ready | Protobuf IDL |

---

## 🚀 Quick Start

### Prerequisites

```bash
# 环境要求
C++17 Compiler (GCC 9+, Clang 10+)
CMake 3.14+
Python 3.8+ (for build tool)
```

### Build from Source

```bash
# 克隆主仓库
git clone https://gitee.com/rippleos/rippleos.git
cd rippleos

# 使用 Python 构建工具
python -m rippleos.build.mbuild build moss.yaml

# 或使用 CMake
mkdir build && cd build
cmake .. && make -j$(nproc)
```

---

## 💡 Examples

### 📡 DDS Publisher/Subscriber

```cpp
#include <dds/dds.h>

// Publisher
auto writer = dds.create_writer<PointCloud>("sensor/points");
PointCloud cloud;
cloud.points = {{1.0, 2.0, 3.0}, {4.0, 5.0, 6.0}};
writer->write(cloud);

// Subscriber
auto reader = dds.create_reader<PointCloud>("sensor/points");
reader->set_callback([](const PointCloud& msg) {
    std::cout << "Received " << msg.points.size() << " points" << std::endl;
});
```

### 🔍 Distributed Tracing (OpenTelemetry)

```cpp
#include <trace/trace.h>

using namespace rippleos::trace;

// 初始化 Tracer
TracerConfig config;
config.service_name = "perception_node";
auto provider = std::make_unique<TracerProvider>(config);
TracerProvider::set_global_instance(std::move(provider));

// 创建追踪链
auto tracer = get_tracer("perception");

// 父 Span
auto parent = tracer->start_span("perception_cycle", SpanKind::PRODUCER);
parent->set_attribute("cycle_id", 42);

// 子 Span (自动关联)
auto child = tracer->start_span("object_detection", 
    SpanKind::INTERNAL, TraceContext(parent->context()));
child->set_attribute("model", "yolov8n");
child->set_attribute("objects", 3);
child->end();

parent->end();
```

### 📊 Prometheus Metrics

```cpp
#include <perf/perf.h>

// 创建指标
auto& registry = perf::MetricsRegistry::instance();

auto counter = registry.create_counter("messages_received");
auto gauge = registry.create_gauge("queue_size");
auto histogram = registry.create_histogram("processing_time_ms", {1, 5, 10, 50, 100});

// 记录指标
counter->increment();
gauge->set(queue.size());
histogram->observe(elapsed_ms);

// 暴露 Prometheus 端点
// curl http://localhost:9090/metrics
```

### 🦊 FoxGlove Visualization

```bash
# 启动 FoxGlove 桥接服务
visual_bridge --port 8765

# 打开 FoxGlove Studio
# https://app.foxglove.dev
# 连接 ws://your-ip:8765
```

支持的数据类型：

| Type | Topic Example | Description |
|------|---------------|-------------|
| 🖼️ Image | `/camera/front` | 摄像头图像 |
| 📍 PointCloud | `/lidar/points` | 激光雷达点云 |
| 📊 Diagnostic | `/system/status` | 诊断状态 |
| 🔍 Traces | `/traces` | 分布式追踪 |
| 📈 Plot | `/vehicle/speed` | 时序数据 |

---

## 🧪 Testing

```bash
# 运行单个模块测试
cd dds/build && ctest --output-on-failure

# 运行所有模块测试
cd build && ctest --output-on-failure
```

---

## 📖 Documentation

| Resource | Link |
|----------|------|
| 📚 Architecture Guide | [architecture.svg](architecture.svg) |
| 🚀 Roadmap | [ROADMAP.md](ROADMAP.md) |
| 📖 Module Design Docs | [M*_Design.md](.) |

---

## 🤝 Contributing

我们欢迎各种形式的贡献！

### Development Workflow

```bash
# 1. Fork & Clone
git clone https://gitee.com/YOUR_USERNAME/dds.git

# 2. Create Branch
git checkout -b feature/amazing-feature

# 3. Make Changes & Test
make test

# 4. Commit
git commit -m "feat: add amazing feature"

# 5. Push & Create PR
git push origin feature/amazing-feature
```

---

## 🗓️ Roadmap

| Phase | Focus | Status |
|-------|-------|--------|
| **Phase 1** | 核心通信模块 (shm, dds, someip) | ✅ Done |
| **Phase 2** | 运行时与可观测性 | ✅ Done |
| **Phase 3** | 诊断与安全 | ✅ Done |
| **Phase 4** | 工具与桥接 | 🔄 In Progress |
| **Phase 5** | 性能优化与生产验证 | 📅 Planned |

---

## 📄 License

```
MIT License

Copyright (c) 2024-2026 RippleOS Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
```

---

## 🙏 Acknowledgments

感谢以下开源项目：

- [OpenTelemetry](https://opentelemetry.io/) - 分布式追踪标准
- [FoxGlove](https://foxglove.dev/) - 可视化平台
- [Fast DDS](https://www.eprosima.com/index.php/products-all/eprosima-fast-dds) - DDS 实现
- [vsomeip](https://github.com/COVESA/vsomeip) - SOME/IP 参考

---

<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:2E86AB,100:A23B72&height=100&section=footer" alt="Footer">
</p>

<p align="center">
  <b>RippleOS</b> - 构建可靠的自动驾驶软件基础设施 🚗💨
</p>

<p align="center">
  <a href="https://gitee.com/rippleos">Gitee</a> •
  <a href="https://gitee.com/rippleos/doc">Documentation</a>
</p>