# cal **Repository Path**: rippleos/cal ## Basic Information - **Project Name**: cal - **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-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # mcal - 在线标定模块 ## 概述 mcal 是 MOSS 中间件的在线标定模块，提供运行时参数标定能力，支持感知/控制算法的参数调整、版本管理和约束验证。 ## 架构设计 ``` ┌─────────────────────────────────────────────────────────────┐ │ Application Layer │ │ (Perception, Control Algorithms) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ mcal (NEW) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ CalParam │ │ CalRegistry │ │ CalStorage │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ CalServer │ │ CalClient │ │ CalValidator │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ mcom (RPC Transport) │ └─────────────────────────────────────────────────────────────┘ ``` ### 目录结构 ``` moss/cal/ ├── CMakeLists.txt ├── include/cal/ │ ├── mcal.h # 模块入口 │ ├── types.h # 类型定义 │ ├── cal_param.h # 参数定义 │ ├── cal_registry.h # 参数注册表 │ ├── cal_server.h # 标定服务端 │ ├── cal_client.h # 标定客户端 │ ├── cal_storage.h # 持久化存储 │ └── cal_validator.h # 约束验证器 ├── src/ │ ├── cal_param.cpp │ ├── cal_registry.cpp │ ├── cal_server.cpp │ ├── cal_client.cpp │ ├── cal_storage.cpp │ └── cal_validator.cpp ├── test/ │ └── test_*.cpp └── proto/ └── cal.proto # RPC 协议定义 ``` ## 核心组件 ### 1. CalParam - 标定参数 定义标定参数的数据结构和约束。 ```cpp namespace moss { namespace mcal { enum class CalParamType : uint8_t { INT, // int64_t DOUBLE, // double BOOL, // bool STRING, // std::string INT_ARRAY, // std::vector DOUBLE_ARRAY, // std::vector MATRIX // std::vector> }; struct CalParam { std::string key; // 参数标识 std::string group; // 分组 (如 "perception", "control") std::string description; // 描述 CalParamType type; // 类型 CalValue value; // 当前值 CalValue default_value; // 默认值 CalConstraint constraint; // 约束条件 int64_t version; // 版本号 int64_t timestamp_us; // 最后修改时间 CalStatus status; // 状态 uint32_t flags; // 标志位 double confidence; // 置信度 std::string calibration_note; // 标定备注 bool validate() const; bool is_locked() const; void set_locked(bool locked); }; } // namespace mcal } // namespace moss ``` ### 2. CalRegistry - 参数注册表 管理所有标定参数的注册、查询和修改。 ```cpp class CalRegistry { public: // 注册/注销 bool register_param(const CalParam& param); bool unregister_param(const std::string& key); // 查询 bool has(const std::string& key) const; std::optional get(const std::string& key) const; std::vector get_all() const; std::vector get_by_group(const std::string& group) const; // 修改 CalError set(const std::string& key, const CalValue& value, const std::string& changed_by = "", const std::string& reason = ""); CalError reset(const std::string& key); void reset_all(); // 锁定 bool lock(const std::string& key); bool unlock(const std::string& key); // 变更监听 using ChangeCallback = std::function; size_t add_watcher(const std::string& key, ChangeCallback cb); size_t add_global_watcher(ChangeCallback cb); void remove_watcher(size_t id); }; ``` ### 3. CalStorage - 持久化存储 提供参数的 JSON 持久化和版本管理。 ```cpp class CalStorage { public: // 基本保存/加载 bool save(const std::string& path, const CalRegistry& registry); bool load(const std::string& path, CalRegistry& registry); // 版本管理 bool save_version(const std::string& path, const CalRegistry& registry, const std::string& version_name); std::vector list_versions(const std::string& path); bool load_version(const std::string& path, const std::string& version_name, CalRegistry& registry); bool delete_version(const std::string& path, const std::string& version_name); // 回滚 bool rollback(const std::string& path, int steps, CalRegistry& registry); bool rollback_to_version(const std::string& path, const std::string& version_name, CalRegistry& registry); // 历史记录 bool append_history(const std::string& path, const CalChange& change); std::vector get_history(const std::string& path, const std::string& key = "", int max_entries = 100); }; ``` ### 4. CalValidator - 约束验证器 验证参数值是否满足约束条件。 ```cpp class CalValidator { public: static bool validate(const CalParam& param, const CalValue& value); static bool check_range(const CalConstraint& constraint, double value); static bool check_shape(const CalConstraint& constraint, const std::vector>& matrix); }; ``` ## 使用示例 ### 注册参数 ```cpp #include using namespace moss::mcal; CalRegistry registry; // 注册感知参数 CalParam param; param.key = "perception.camera.exposure"; param.group = "perception"; param.description = "Camera exposure time (ms)"; param.type = CalParamType::INT; param.value = int64_t(30); param.default_value = int64_t(30); param.constraint.has_min = true; param.constraint.min_value = 1; param.constraint.has_max = true; param.constraint.max_value = 100; registry.register_param(param); ``` ### 修改参数 ```cpp // 设置参数值 CalError err = registry.set("perception.camera.exposure", int64_t(50), "calibrator", "Optimize for low light"); if (err == CalError::OK) { std::cout << "Parameter updated successfully" << std::endl; } // 锁定关键参数 registry.lock("control.steering.gain"); ``` ### 监听变更 ```cpp // 监听特定参数变更 size_t watcher_id = registry.add_watcher("perception.camera.exposure", [](const CalChange& change) { std::cout << "Parameter " << change.key << " changed" << std::endl; std::cout << " Old: " << std::get(change.old_value) << std::endl; std::cout << " New: " << std::get(change.new_value) << std::endl; }); // 全局监听 registry.add_global_watcher([](const CalChange& change) { // 记录所有变更到日志 }); ``` ### 持久化 ```cpp CalStorage storage; // 保存到 JSON 文件 storage.save("/var/moss/calibration/current.json", registry); // 创建版本快照 storage.save_version("/var/moss/calibration", registry, "v1.2.0"); // 列出所有版本 auto versions = storage.list_versions("/var/moss/calibration"); // 回滚到指定版本 storage.rollback_to_version("/var/moss/calibration", "v1.1.0", registry); ``` ## JSON 格式 参数文件使用 JSON 格式存储： ```json { "version": "1.0.0", "timestamp_us": 1714540800000000, "params": { "perception.camera.exposure": { "key": "perception.camera.exposure", "group": "perception", "description": "Camera exposure time (ms)", "type": "int", "value": 50, "default_value": 30, "constraint": { "min": 1, "max": 100 }, "version": 5, "flags": 0 }, "control.steering.gain": { "key": "control.steering.gain", "group": "control", "type": "double", "value": 1.5, "default_value": 1.0, "constraint": { "min": 0.1, "max": 5.0 }, "version": 2, "flags": 1 } } } ``` ## 约束类型 | 约束 | 适用类型 | 说明 | |------|----------|------| | min/max | INT, DOUBLE | 数值范围限制 | | matrix_shape | MATRIX | 矩阵维度限制 | | locked | ALL | 禁止修改 | | readonly | ALL | 禁止手动修改（仅程序内部） | ## 依赖关系 ```yaml mcal: depends_on: - mruntime # Clock, 工具类 - mlog # 日志 optional: - mcom # RPC 通信 ``` ## 测试覆盖 | 测试文件 | 覆盖范围 | |----------|----------| | test_cal_param.cpp | 参数定义、验证 | | test_cal_registry.cpp | 注册表操作、监听器 | | test_cal_storage.cpp | JSON 读写、版本管理 | | test_cal_validator.cpp | 约束验证 | ## 里程碑 | 里程碑 | 内容 | 状态 | |--------|------|------| | mcal-ms1 | 核心实现 | ✅ 完成 | | mcal-ms2 | RPC 服务 | 规划中 | ## 参考 - ISO 26262 功能安全 - 标定数据管理 - AUTOSAR Calibration Data Management