Skip to content

Latest commit

 

History

History
2847 lines (2165 loc) · 74.7 KB

SubmoduleDevelopment.md

File metadata and controls

2847 lines (2165 loc) · 74.7 KB

AC_FS32 子模块开发指南

AC_FS32 智能机器人控制系统 - 完整子模块开发文档

本文档面向子模块开发者,提供核心架构、开发规范、管理机制和最佳实践。


📑 目录

  1. 快速开始
  2. 核心架构
  3. 子模块管理
  4. Provider/Engine 可插拔架构
  5. 共享工具模块
  6. 事件系统
  7. 状态管理
  8. 数据流通道
  9. 硬件抽象层 (HAL)
  10. 数据缓冲
  11. 模型管理
  12. 日志系统
  13. 配置管理
  14. 调试与测试
  15. 性能优化
  16. 开发规范
  17. 完整示例
  18. 多模块协作示例
  19. 常见问题
  20. 最佳实践
  21. API参考
  22. 与监控系统集成
  23. 附录
  24. LLM 语音指令扩展
  25. MQTT 客户端集成
  26. WebSocket 流数据传输
  27. SLAM 工作模式
  28. 后端 API 集成模式

快速开始

项目结构

AC_FS32/
├── src/
│   ├── main.py                 # 程序入口
│   ├── config.py               # 路径常量定义
│   ├── core/                   # 核心模块
│   │   ├── EventBus.py        # 事件总线
│   │   ├── StateStore.py      # 状态存储
│   │   ├── DataBuffer.py      # 数据缓冲
│   │   ├── StreamChannel.py   # 流通道
│   │   ├── MainController.py  # 主控制器
│   │   ├── ConfigManager.py   # 统一配置管理
│   │   ├── ModelManager.py    # 模型管理器
│   │   ├── MonitorAPI.py      # FastAPI 监控服务
│   │   ├── pub/               # 公共模块(子模块可用)
│   │   │   ├── event/        # 公共事件
│   │   │   └── states/       # 公共状态键
│   │   ├── private/           # 主控私有定义
│   │   ├── hal/               # 硬件抽象层
│   │   └── init/             # 初始化系统
│   ├── sub/                   # 子模块目录
│   │   ├── logger/           # 日志模块
│   │   ├── controller/       # 底盘控制
│   │   ├── voice_recognition/# 语音识别
│   │   ├── wakeup_word/      # 唤醒词检测
│   │   ├── text_to_speech/   # 语音合成
│   │   ├── perception_fusion/# 感知融合
│   │   └── test/             # 测试脚本
│   ├── model/                # AI 模型
│   └── web/                  # 监控前端(静态 HTML/JS/CSS)
├── config/                    # 配置文件
│   ├── submodules.json       # 子模块管理配置
│   └── *.json                # 各模块配置
└── doc/                       # 文档

创建子模块三步走

1. 创建模块目录

src/sub/your_module/
├── __init__.py       # 主类实现
├── events.py         # 模块私有事件(可选)
└── states.py         # 模块私有状态键(可选)

2. 实现主类

# src/sub/your_module/__init__.py
from core.init.submod import SubModule
from sub.logger import Logger

class YourModule(SubModule):
    """你的子模块"""
  
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
        self.module_name = "YourModule"
        self.logger = Logger.get_logger("YourModule")
  
    def initialize(self, param1="default", **kwargs):
        """初始化模块,接收配置参数"""
        self.param1 = param1
        # 你的初始化逻辑
        self._initialized = True
        self.logger.info("YourModule initialized")
  
    def shutdown(self):
        """清理资源"""
        # 你的清理逻辑
        self._initialized = False
        self.logger.info("YourModule shutdown")
  
    def restart(self, **kwargs):
        """重启模块"""
        self.shutdown()
        self.initialize(**kwargs)

3. 注册到配置文件

编辑 config/submodules.json:

{
  "enabled_modules": [
    "logger",
    "your_module"
  ],
  "modules": {
    "your_module": {
      "enabled": true,
      "auto_start": false,
      "config": {
        "param1": "custom_value"
      }
    }
  }
}

单文件子模块

对于功能简单的子模块,可以使用单文件形式(不需要目录):

src/sub/
├── line_following.py      ← 单文件子模块
├── yolo_detector.py       ← 单文件子模块  
├── teleop.py              ← 单文件子模块
├── controller/            ← 多文件子模块(目录形式)
│   ├── __init__.py
│   ├── events.py
│   └── states.py

单文件子模块将事件、状态键、主类定义在同一个 .py 文件中。 在 config/submodules.json 中注册时,module 字段使用 sub.模块名(无 __init__):

{
    "name": "line_following",
    "module": "sub.line_following",
    "class": "LineFollower",
    "enabled": true
}

核心架构

四大核心组件

所有子模块通过构造函数接收四个核心组件:

from core import EventBus, StateStore, DataBuffer, StreamChannel

1. EventBus - 事件总线

发布-订阅模式的异步通信机制。

# 订阅事件
self.event_bus.subscribe(SomeEvent, self._handler)

# 发布事件
self.event_bus.publish(SomeEvent(data="value"))

2. StateStore - 状态存储

线程安全的全局状态键值存储。

# 设置状态
self.state_store.set("your_module.status", "running")

# 获取状态
status = self.state_store.get("your_module.status", default="stopped")

3. DataBuffer - 数据缓冲

用于模块间共享大数据对象。

# 存储数据
self.data_buffer.put("your_module.result", result_data)

# 获取数据
result = self.data_buffer.get("your_module.result")

4. StreamChannel - 流通道

用于实时数据流传输(视频帧、音频)。

# 订阅数据流
stream_channel["video_stream"].subscribe(self._process_frame)

# 发布数据流
stream_channel["audio_output"].publish(audio_bytes)

子模块管理

配置文件结构

config/submodules.json

{
  "enabled_modules": ["logger", "voice_recognition", "wakeup_word"],
  "modules": {
    "voice_recognition": {
      "enabled": true,
      "auto_start": false,
      "class_name": "VoiceRecognition",
      "config_file": "voice_recognition.json"
    }
  }
}

配置字段说明

字段 类型 说明
enabled bool 是否启用该模块
auto_start bool 初始化后是否自动调用 start()
class_name string 显式指定主类名(可选)
config object 直接嵌入的配置参数
config_file string 独立配置文件名(从 config/ 加载)

类名查找规则

  1. 优先使用 class_name(如果指定)
  2. 否则尝试以下命名规范:
    • {ModuleName} - 如 VoiceRecognition
    • {ModuleName}Controller - 如 WakeupController
    • {ModuleName}Module - 如 LoggerModule

命名规范

  • 模块目录:小写+下划线 voice_recognition
  • 主类名:驼峰命名 VoiceRecognition
  • 配置文件:小写+下划线 voice_recognition.json

初始化流程

# 主程序
main = MainController()
main.initialize_submodules()

内部流程:

  1. 加载 config/submodules.json
  2. 按 enabled_modules 顺序遍历
  3. 对每个模块:
    • 动态导入:from sub.{module_name} import {ClassName}
    • 实例化:instance = ClassName(eventBus, stateStore, dataBuffer, streamChannel)
    • 加载配置:从 config_file 或 config 字段
    • 调用 initialize(**config)
    • 如果 auto_start=true 且有 start() 方法,则调用

SubModule 基类

所有子模块应继承 SubModule 基类:

from core.init.submod import SubModule

class YourModule(SubModule):
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
        self.module_name = "YourModule"
        self._initialized = False
  
    def initialize(self, **kwargs):
        """必须实现:初始化模块"""
        # 你的初始化逻辑
        self._initialized = True
  
    def shutdown(self):
        """必须实现:清理资源"""
        # 你的清理逻辑
        self._initialized = False
  
    def restart(self, **kwargs):
        """必须实现:重启模块"""
        self.shutdown()
        self.initialize(**kwargs)
  
    def handle_error(self, error: Exception, fatal: bool = False):
        """可选:错误处理"""
        if fatal:
            # 发布致命错误事件
            pass

Provider/Engine 可插拔架构

对于需要支持多种后端的子模块,使用 Provider(输入方向)或 Engine(输出方向)工厂模式。

设计模式

  1. 定义基类(providers/base.py 或 engines/base.py):

    from abc import ABC, abstractmethod
    
    class ASRProvider(ABC):
        @abstractmethod
        def initialize(self, config: dict) -> None: ...
        
        @abstractmethod
        def recognize(self, audio_data) -> str: ...
        
        @abstractmethod
        def shutdown(self) -> None: ...
  2. 实现具体 Provider(如 providers/whisper_provider.py)

  3. 工厂方法(在子模块 __init__.py 中):

    def _create_provider(self) -> ASRProvider:
        provider_type = self._config.get("provider", "whisper")
        if provider_type == "whisper":
            from .providers.whisper_provider import WhisperASRProvider
            return WhisperASRProvider()
        elif provider_type == "aliyun":
            from .providers.aliyun_provider import AliyunASRProvider
            return AliyunASRProvider()
  4. 配置切换:通过 JSON 配置文件中的字段选择后端

现有实现

  • voice_recognition:ASRProvider(whisper / aliyun)
  • text_to_speech:TTSEngine(piper / aliyun)
  • wakeup_word:WakeupMethod(software / wonderecho)
  • controller/kinematics:Kinematics(ackermann;历史 quadruped 已归档)
  • llm_service:LLMProvider(aliyun / openai / 自定义)

自定义 LLM Provider 开发

llm_service 子模块支持插件式自定义 Provider 扩展。只需 3 步:

1. 实现 LLMProvider 基类

# my_custom_provider.py
from sub.llm_service.providers.base import LLMProvider

class MyCustomProvider(LLMProvider):
    '''
    :brief 自定义 LLM Provider
    '''

    def initialize(self, config: dict) -> None:
        '''初始化连接、加载模型等'''
        self._api_key = config.get("api_key", "")
        self._model = config.get("models", {}).get("default", "my-model")
        self._base_url = config.get("base_url", "https://api.example.com")

    def chat(self, messages: list, **kwargs) -> str:
        '''
        :brief 发送对话请求并返回文本
        :param messages: [{"role": "system"|"user"|"assistant", "content": "..."}]
        :return 模型回复文本
        '''
        # 实现 API 调用逻辑
        import urllib.request, json
        req = urllib.request.Request(
            f"{self._base_url}/v1/chat/completions",
            data=json.dumps({
                "model": self._model,
                "messages": messages
            }).encode(),
            headers={"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"}
        )
        with urllib.request.urlopen(req) as resp:
            result = json.loads(resp.read())
        return result["choices"][0]["message"]["content"]

    def shutdown(self) -> None:
        '''释放资源'''
        pass

    # 可选重写
    def supports_vision(self) -> bool:
        return False

    def supports_streaming(self) -> bool:
        return False

2. 放入自定义目录

将 .py 文件放入 config/llm_service.json 中 custom_providers_path 指定的目录(默认 src/sub/llm_service/custom_providers/)。

3. 添加配置

在 config/llm_service.json 的 providers 中添加条目:

{
    "providers": {
        "my_custom": {
            "class": "MyCustomProvider",
            "enabled": true,
            "api_key": "your-api-key",
            "base_url": "https://api.example.com",
            "models": {
                "default": "my-model-v1",
                "vision": ""
            }
        }
    },
    "default_provider": "my_custom"
}

要点:

  • class 字段必须与 Python 类名一致
  • ProviderRegistry 在启动时自动扫描自定义目录加载
  • 运行时可通过 LLMProviderSwitchEvent 切换 Provider

共享工具模块

PID 控制器

多个子模块共享的 PID 控制器位于 src/sub/common/pid_controller.py:

from sub.common.pid_controller import PIDController

pid = PIDController(kp=0.5, ki=0.01, kd=0.1, output_min=-1.0, output_max=1.0)
output = pid.compute(error)  # dt 自动计算
pid.reset()                  # 重置状态

使用该模块的子模块:object_tracking、line_following、lidar_controller

注意:新模块如需 PID 控制,请直接引用此共享实现,不要重复实现。


事件系统

公共事件

位于 core.pub.event,所有子模块可订阅/发布。

系统生命周期事件

from core.pub.event import (
    SystemStartingEvent,      # 系统启动中
    SystemStartedEvent,       # 系统已启动
    SystemStoppingEvent,      # 系统停止中
    SystemStoppedEvent,       # 系统已停止
    SystemRestartingEvent,    # 系统重启中
    SystemRestartedEvent,     # 系统已重启
    SystemShutdownRequestEvent # 关闭请求
)

SystemStoppingEvent 停止原因:

reason 说明 建议操作
"normal" 正常关闭 保存所有数据
"restart" 系统重启 保留临时数据
"fatal_error" 致命错误 紧急保存关键数据
"user_request" 用户请求 完成当前任务后退出
def _on_stopping(self, event: SystemStoppingEvent):
    if event.reason == "normal":
        self._save_all_data()
    elif event.reason == "restart":
        self._save_critical_data()

硬件控制事件

from core.pub.event import (
    VideoStreamControlEvent,
    AudioInputStreamControlEvent,
    AudioOutputStreamControlEvent
)

错误事件

from core.pub.event import (
    SubsystemErrorEvent,      # 子模块错误
    FatalSubsystemErrorEvent, # 子模块致命错误
    ControllerErrorEvent,     # 主控错误
    ExternalErrorEvent        # 外部依赖错误
)

# 发布错误
self.event_bus.publish(SubsystemErrorEvent(
    module="your_module",
    level="ERROR",
    message="Processing failed"
))

# 发布致命错误(触发重启)
self.event_bus.publish(FatalSubsystemErrorEvent(
    module="your_module",
    message="Critical failure"
))

自定义事件

# your_module/events.py
from dataclasses import dataclass
from core.EventBus import Event

@dataclass
class YourModuleEvent(Event):
    """你的模块事件"""
    module_name: str = "your_module"
    data: dict = None

状态管理

公共状态键

位于 core.pub.states,所有子模块可读。

from core.pub.states import (
    KEY_SYSTEM_INITIALIZED,
    KEY_SYSTEM_RUNNING,
    KEY_SYSTEM_PLATFORM,
    KEY_SYSTEM_VIDEO_ENABLED,
    KEY_SYSTEM_AUDIO_IN_ENABLED,
    KEY_HAL_CAMERA_AVAILABLE,
    KEY_HAL_MICROPHONE_AVAILABLE,
    PLATFORM_TEST,    # 0 - 测试平台 (Windows)
    PLATFORM_CAR,     # 1 - 小车 (Ackermann)
    PLATFORM_NAMES,   # {0: "测试平台", 1: "小车"}
)

# 检查系统状态
if self.state_store.get(KEY_SYSTEM_RUNNING):
    # 系统正在运行
    pass

# 获取平台类型
platform = self.get_platform()  # 0=测试平台, 1=小车
if platform == PLATFORM_CAR:
    # 小车平台专用逻辑
    pass

平台类型

系统通过 config/system.json 中的 platform.type 字段区分运行平台:

值 常量 说明
0 PLATFORM_TEST 测试平台 (Windows 开发环境)
1 PLATFORM_CAR 小车 (Ackermann 底盘)
# 在子模块中获取平台类型
platform = self.get_platform()

# 或从 StateStore 读取
platform = self.stateStore.get(KEY_SYSTEM_PLATFORM, PLATFORM_TEST)

# 获取平台名称
from core.pub.states import PLATFORM_NAMES
name = PLATFORM_NAMES.get(platform)  # "小车"

定义私有状态键

# your_module/states.py

'''模块是否已初始化
:type bool
'''
KEY_YOUR_MODULE_INITIALIZED = "your_module.initialized"

'''模块当前状态
:type str
:values running, stopped, error, paused
'''
KEY_YOUR_MODULE_STATUS = "your_module.status"

状态键命名规范:

<模块>.<功能>.<属性>

示例:

  • logger.level
  • your_module.processing.enabled
  • your_module.worker.count

数据流通道

标准通道

MainController 提供三个标准流通道:

通道名 用途 数据类型 队列大小
video_stream 视频帧 numpy.ndarray 2
audio_input 音频输入 bytes 10
audio_output 音频输出 bytes 10

注意: StreamChannel 主要用于模块间数据通信。对于硬件数据流,推荐使用 HAL 设备订阅机制。

订阅数据流

class YourModule(SubModule):
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
      
        # 订阅视频流
        if "video_stream" in streamChannel:
            streamChannel["video_stream"].subscribe(self._process_video)
  
    def _process_video(self, frame):
        """处理视频帧"""
        height, width = frame.shape[:2]
        # 你的处理逻辑

发布数据流

def play_audio(self, audio_bytes):
    """播放音频"""
    if "audio_output" in self.streamChannel:
        self.streamChannel["audio_output"].publish(audio_bytes)

StreamChannel 使用指南

StreamChannel 采用 Per-Subscriber Queue 架构,每个订阅者拥有独立的缓冲队列和工作线程,慢订阅者不会阻塞快订阅者。

订阅视频流

def initialize(self, **kwargs):
    self._video_channel = self._main_controller.get_channel("video_stream")

def _start_processing(self):
    # 订阅时可指定独立的队列深度
    self._video_channel.subscribe(self._on_frame, maxsize=2)
    # 订阅后摄像头自动开启(订阅者驱动)

def _stop_processing(self):
    self._video_channel.unsubscribe(self._on_frame)
    # 无其他订阅者时摄像头自动关闭

def _on_frame(self, frame):
    """在独立线程中被调用,不阻塞其他订阅者"""
    # 如需修改帧数据,先 copy
    frame = frame.copy()
    result = self.process(frame)
    self.eventBus.publish(MyResultEvent(result=result))

订阅音频输入

def _start_listening(self):
    audio_channel = self._main_controller.get_channel("audio_input")
    audio_channel.subscribe(self._on_audio_chunk, maxsize=10)
    # 麦克风自动开启

def _on_audio_chunk(self, data):
    """接收 PCM int16 音频数据"""
    audio_np = np.frombuffer(data, dtype=np.int16)
    # 处理音频...

关键原则

  • 订阅者驱动:第一个订阅者触发硬件自动开启,最后一个取消订阅时自动关闭
  • 独立队列:每个订阅者有自己的缓冲队列,可通过 maxsize 参数自定义深度
  • 帧共享:所有订阅者收到的是同一个对象引用,如需修改请先 copy()
  • 异常隔离:单个订阅者的异常不影响其他订阅者

硬件抽象层 (HAL)

概述

HAL (Hardware Abstraction Layer) 提供跨平台的硬件设备访问接口。支持 Windows 和 Linux (包括树莓派)。

可用设备

设备类型 HAL 名称 Windows 实现 Linux 实现
摄像头 camera OpenCV picamera2
麦克风 microphone PyAudio pyalsaaudio
扬声器 speaker PyAudio pyalsaaudio
电机驱动 motor 不支持 串口通信

访问 HAL 设备

class YourModule(SubModule):
    def initialize(self, **kwargs):
        # 获取 HAL 设备(推荐方式)
        self.mic = self.get_hal_device("microphone")
        self.camera = self.get_hal_device("camera")
        self.motor = self.get_hal_device("motor")
        
        if self.mic:
            # 订阅音频数据
            self.mic.subscribe(self._on_audio_data)
            self.mic.open()
            
    def _on_audio_data(self, audio_bytes):
        """处理音频数据"""
        # 你的处理逻辑
        pass
    
    def shutdown(self):
        if self.mic:
            self.mic.unsubscribe(self._on_audio_data)

HAL 设备接口

所有 HAL 设备继承 HALDevice 基类:

class HALDevice:
    @property
    def is_open(self) -> bool: ...
    
    def open(self) -> bool: ...
    def close(self) -> None: ...
    def subscribe(self, callback: Callable) -> None: ...
    def unsubscribe(self, callback: Callable) -> None: ...

视频设备 (VideoDevice)

camera = self.get_hal_device("camera")
if camera:
    camera.width = 640
    camera.height = 480
    camera.fps = 30
    
    camera.open()
    ret, frame = camera.read()  # 单帧读取
    
    # 或使用连续采集模式
    camera.subscribe(self._on_frame)
    camera.start_capture()

音频输入设备 (AudioInputDevice)

mic = self.get_hal_device("microphone")
if mic:
    mic.open()
    data = mic.read()  # 读取一次音频数据
    
    # 或使用连续采集模式
    mic.subscribe(self._on_audio)
    mic.start_capture()

电机驱动 (MotorDriver)

motor = self.get_hal_device("motor")
if motor and motor.is_connected():
    # 设置电机速度
    motor.set_motor_speed([[1, 500], [2, 500]])  # 电机1和2以500速度运行
    
    # 设置舵机位置
    motor.pwm_servo_set_position(duration=100, positions=[[1, 1500]])
    
    # 读取 IMU 数据
    imu_data = motor.get_imu()

舵机复位 (v1.12.0)

motor = self.get_hal_device("motor")
if motor and motor.is_connected():
    # 从 hal.json 读取 home_positions 配置并复位
    config_mgr = self.get_config_manager()
    hal_config = config_mgr.load("hal")
    home_pos = hal_config.get("motor", {}).get("home_positions")
    motor.servo_reset_to_home(duration=1000, home_positions=home_pos)

home_positions 配置在 config/hal.json 的 motor 段,预设 PWM 1-4 中位 1500、总线 1-8 中位 500。

平台检测

from core.hal import get_platform_info, is_hal_available

info = get_platform_info()
# {'platform': 'win32', 'machine': 'amd64', 'is_arm': False, 'is_linux': False, 'is_windows': True}

if is_hal_available():
    # HAL 可用
    pass

数据缓冲

DataBuffer 用法

DataBuffer 用于存储和管理大数据对象(图像、音频、点云等),提供显式的生命周期管理。

存储数据

# 存储图像数据
data_id = self.dataBuffer.put(
    payload=image_array,
    metadata={
        "source": "camera_front",
        "width": 1920,
        "height": 1080,
        "timestamp": time.time()
    }
)
self.logger.debug(f"[Data] Stored image with ID: {data_id}")

获取数据

try:
    # 获取数据
    image = self.dataBuffer.get(data_id)
    
    # 获取元数据
    metadata = self.dataBuffer.get_metadata(data_id)
    self.logger.debug(f"[Data] Retrieved image: {metadata['width']}x{metadata['height']}")
    
except KeyError:
    self.logger.error(f"[Data] Data not found: {data_id}")
except RuntimeError:
    self.logger.error(f"[Data] Data already released: {data_id}")

检查数据存在

if self.dataBuffer.exists(data_id):
    # 数据可用
    image = self.dataBuffer.get(data_id)

释放数据

# 数据使用完毕后释放内存
self.dataBuffer.release(data_id)
self.logger.debug(f"[Data] Released: {data_id}")

最佳实践

  1. 及时释放:数据使用完毕立即调用 release()
  2. 存储元数据:包含 source、timestamp、format 等信息
  3. 异常处理:始终捕获 KeyError 和 RuntimeError
  4. 检查存在性:使用前先 exists() 检查

完整示例

class ImageProcessor(SubModule):
    def process_image(self, image_array):
        """处理图像并存储结果"""
        try:
            # 处理图像
            result = self._do_processing(image_array)
            
            # 存储结果
            data_id = self.dataBuffer.put(
                payload=result,
                metadata={
                    "source": self.module_name,
                    "timestamp": time.time(),
                    "format": "processed_image"
                }
            )
            
            # 发布事件通知其他模块
            self.eventBus.publish(ImageProcessedEvent(
                data_id=data_id,
                width=result.shape[1],
                height=result.shape[0]
            ))
            
            return data_id
            
        except Exception as e:
            self.handle_error(e, fatal=False)
            return None
    
    def _on_image_processed(self, event: ImageProcessedEvent):
        """处理其他模块的图像结果"""
        if not self.dataBuffer.exists(event.data_id):
            self.logger.warning(f"[Data] Image not available: {event.data_id}")
            return
        
        try:
            # 获取并使用数据
            image = self.dataBuffer.get(event.data_id)
            self._use_image(image)
            
        except RuntimeError:
            self.logger.error(f"[Data] Image already released: {event.data_id}")
        finally:
            # 使用完毕释放
            if self.dataBuffer.exists(event.data_id):
                self.dataBuffer.release(event.data_id)

模型管理

ModelManager 使用

系统提供统一的模型管理接口,支持模型注册、查询、验证和路径管理。

获取模型管理器

from core.ModelManager import get_model_manager

class YourModule(SubModule):
    def initialize(self, model_name="model_whisper", model_size="base", **kwargs):
        # 获取模型管理器
        model_manager = get_model_manager()
        
        # 检查模型是否已注册
        if not model_manager.is_registered(model_name):
            self.logger.error(f"[Model] Model not registered: {model_name}")
            return
        
        # 获取模型路径
        model_path = model_manager.get_model_path(model_name, size=model_size)
        if not model_path or not model_path.exists():
            self.logger.error(f"[Model] Model file not found: {model_path}")
            return
        
        # 加载模型
        self.model = self._load_model(model_path)
        self.logger.info(f"[Model] Loaded: {model_name}/{model_size}")

查询模型信息

model_manager = get_model_manager()

# 获取所有已注册的模型
models = model_manager.get_model_list()
self.logger.debug(f"[Model] Registered models: {models}")

# 获取模型详细信息
info = model_manager.get_model_info("model_whisper")
# {
#     'name': 'model_whisper',
#     'dir': Path('src/model/model_whisper'),
#     'default_size': 'base',
#     'supported_sizes': ['tiny', 'base', 'small', 'medium', 'large'],
#     'default_path': Path('src/model/model_whisper/base.pt')
# }

# 获取支持的模型尺寸
sizes = model_manager.get_supported_sizes("model_whisper")
# ['tiny', 'base', 'small', 'medium', 'large']

# 获取默认尺寸
default_size = model_manager.get_default_size("model_whisper")
# 'base'

验证模型

# 快速验证(检查文件是否存在)
is_valid = model_manager.verify_model("model_whisper", size="base", load=False)

# 完整验证(实际加载模型)
is_valid = model_manager.verify_model("model_whisper", size="base", load=True)

注册自定义模型

如果需要添加新的模型:

  1. 在 src/model/ 下创建模型目录:
src/model/
├── model_whisper/      # 已有模型
│   ├── base.pt
│   └── small.pt
└── your_model/         # 新模型
    ├── v1.pt
    └── v2.pt
  1. 创建模型加载器(在 src/model/your_model/ 下):
# src/model/your_model/__init__.py
from core.init.model import ModelLoader, register_model_loader

class YourModelLoader(ModelLoader):
    def __init__(self):
        super().__init__(
            model_name="your_model",
            model_dir=Path(__file__).parent,
            default_size="v1"
        )
    
    def get_allSizes(self) -> List[str]:
        return ["v1", "v2"]
    
    def load(self, size: str = None):
        size = size or self.default_size
        model_path = self.model_dir / f"{size}.pt"
        # 加载模型逻辑
        return load_your_model(model_path)
    
    def verify(self, size: str = None, load: bool = False):
        # 验证逻辑
        return super().verify(size, load)

# 注册模型
register_model_loader(YourModelLoader())
  1. 在 config/models.json 中配置:
{
    "models": {
        "your_model": {
            "default_size": "v1"
        }
    }
}

日志系统

使用日志

from sub.logger import Logger

class YourModule(SubModule):
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
        self.logger = Logger.get_logger("YourModule")
      
        self.logger.debug("Debug message")
        self.logger.info("Info message")
        self.logger.warning("Warning message")
        self.logger.error("Error message")
      
        # 异常日志
        try:
            risky_operation()
        except Exception:
            self.logger.exception("Operation failed")

日志格式规范

使用 [Category] 前缀分类:

# 事件相关
self.logger.debug(f"[Event] ✓ Subscribed: WakeupDetectedEvent")
self.logger.debug(f"[Event] → SystemStartedEvent")
self.logger.debug(f"[Event] ← WakeupDetectedEvent received")

# 配置加载
self.logger.debug(f"[Config] model_size=base, device=cuda")
self.logger.info(f"[Config] Loaded from {config_file}")

# 音频/视频处理
self.logger.debug(f"[Audio] Buffer: {duration:.2f}s")
self.logger.debug(f"[Video] Frame: {width}x{height}")

# 处理流程
self.logger.debug(f"[Process] 处理音频增强")
self.logger.info(f"[Process] 处理完成")

# ASR/识别
self.logger.debug(f"[ASR] 转录开始")
self.logger.info(f"[ASR] 识别结果: '{text}'")

# 数据操作
self.logger.debug(f"[Data] 存储结果: data_id={data_id}")
self.logger.debug(f"[Data] 释放: {data_id}")

# 状态更新
self.logger.debug(f"[State] VR_RUNNING=True")

# 会话管理
self.logger.debug(f"[Session] 录音线程启动, data_id={data_id}")

日志级别规范

INFO - 关键操作

  • 模块初始化/关闭
  • 重要状态变更
  • 识别结果
  • 模型加载成功
self.logger.info("[Wakeup] 模块初始化完成")
self.logger.info(f"[Wakeup] 检测到唤醒词: '{word}'")
self.logger.info(f"[ASR] 识别完成: '{text}'")

DEBUG - 详细信息

  • 配置加载
  • 事件订阅/发布
  • 数据流状态
  • 中间处理步骤
self.logger.debug(f"[Config] recognize_timeout=5.0")
self.logger.debug(f"[Event] ✓ Subscribed: WakeupDetectedEvent")
self.logger.debug(f"[Audio] Buffer: 3.2s, has_speech=True")

WARNING - 可恢复问题

  • 配置文件不存在(使用默认值)
  • 可选功能不可用
  • 数据已释放
self.logger.warning("[Wakeup] 检测未启用")
self.logger.warning(f"[Data] Image not available: {data_id}")

ERROR - 错误但不致命

  • 操作失败但模块可继续运行
  • 数据处理错误
self.logger.error(f"[ASR] 转录失败: {e}")
self.logger.error(f"[Data] Data not found: {data_id}")

动态调整日志级别

from sub.logger.events import LogLevelChangeEvent

# 发布日志级别变更事件
self.eventBus.publish(LogLevelChangeEvent(level="DEBUG"))

配置管理

配置文件位置

config/
├── submodules.json           # 子模块管理配置
├── models.json              # 模型管理配置
├── system.json              # 系统配置
├── chassis.json             # 底盘配置
├── hal.json                 # HAL 硬件配置
├── voice_recognition.json   # 语音识别配置
├── wakeup_word.json         # 唤醒词配置
└── your_module.json         # 你的模块配置

ConfigManager (推荐)

从 v0.3.0 开始,强烈推荐使用 ConfigManager 统一管理配置。

基本用法

class YourModule(SubModule):
    def initialize(self, **kwargs):
        # 方式1: 使用内置辅助方法(推荐)
        config = self._load_config(
            config_name="your_module",
            overrides=kwargs,
            defaults={"param1": "default", "param2": 100}
        )
        
        self.param1 = config.get("param1")
        self.param2 = config.get("param2")
        
        # 方式2: 直接使用 ConfigManager
        config_mgr = self.get_config_manager()
        if config_mgr:
            full_config = config_mgr.load("your_module")

带回退的配置加载(最佳实践)

对于需要在模块级别加载配置的场景(如 states.py),使用以下模式:

def _load_module_config() -> dict:
    '''
    :brief 加载模块配置
    :return: 配置字典
    '''
    # 内部默认值(硬编码作为最后回退)
    fallback = {
        "param1": "default_value",
        "param2": 100,
    }
    
    # 尝试使用 ConfigManager(推荐)
    try:
        from core.ConfigManager import get_config_manager
        config_mgr = get_config_manager()
        if config_mgr._config_path:
            config = config_mgr.load_with_defaults("your_module", fallback)
            return config
    except Exception:
        pass  # ConfigManager 不可用
    
    # 回退:直接读取配置文件
    from pathlib import Path
    config_path = Path(__file__).parent.parent.parent.parent / "config" / "your_module.json"
    
    if config_path.exists():
        try:
            import json
            with open(config_path, 'r', encoding='utf-8') as f:
                config = json.load(f)
            fallback.update(config)
        except Exception:
            pass  # 文件读取失败,使用默认值
    
    return fallback


# 模块级别加载配置
config_data = _load_module_config()

# 导出常量
DEFAULT_PARAM1 = config_data.get("param1", "default_value")
DEFAULT_PARAM2 = config_data.get("param2", 100)

配置加载优先级

  1. kwargs 参数 (最高优先级)
  2. StateStore 运行时配置
  3. ConfigManager 加载的文件配置
  4. 直接读取 JSON 文件
  5. 硬编码默认值 (最低优先级)

配置文件格式

{
  "_meta": {
    "version": "1.0.0",
    "module": "your_module",
    "description": "模块说明"
  },
  "param1": "value1",
  "param2": 123
}

热重载配置保留

子模块重启时自动保留配置:

def restart(self, **kwargs):
    # 保存当前配置到 StateStore
    self._save_config_to_store()
    
    self.shutdown()
    
    # 加载保存的配置并合并新参数
    saved_config = self._load_config_from_store()
    saved_config.update(kwargs)
    
    self.initialize(**saved_config)

旧版配置加载方式

方式1:使用 config 字段

{
  "modules": {
    "your_module": {
      "enabled": true,
      "config": {
        "param1": "value1",
        "param2": 123
      }
    }
  }
}

方式2:使用 config_file

{
  "modules": {
    "your_module": {
      "enabled": true,
      "config_file": "your_module.json"
    }
  }
}

然后创建 config/your_module.json:

{
    "_comment": "你的模块配置",
    "param1": "value1",
    "param2": 123,
    "_comment_param1": "参数1说明"
}

在模块中读取配置

class YourModule(SubModule):
    def initialize(self, param1="default", param2=100, **kwargs):
        """初始化时接收配置参数"""
        self.param1 = param1
        self.param2 = param2
        
        self.logger.debug(f"[Config] param1={param1}, param2={param2}")
        self.logger.info(f"[Config] 配置加载完成")

配置注释规范

JSON 使用 "_comment" 字段添加注释:

{
    "_comment": "模块总体说明",
    
    "param1": "value1",
    "_comment_param1": "参数1的简短说明",
    
    "timeout": 5.0,
    "_comment_timeout": "超时时间(秒), 推荐3-10"
} 

调试与测试

单元测试

创建测试文件 src/sub/test/test_your_module.py:

import sys
from pathlib import Path

# 添加项目路径
sys.path.insert(0, str(Path(__file__).parent.parent.parent))

from core import EventBus, StateStore, DataBuffer
from sub.your_module import YourModule

def test_module_init():
    """测试模块初始化"""
    event_bus = EventBus()
    state_store = StateStore()
    data_buffer = DataBuffer()
    stream_channel = {}
    
    module = YourModule(event_bus, state_store, data_buffer, stream_channel)
    module.initialize(param1="test_value")
    
    assert module._initialized
    assert module.param1 == "test_value"
    
    module.shutdown()
    assert not module._initialized
    
    print("✓ 测试通过: 模块初始化")

def test_event_handling():
    """测试事件处理"""
    event_bus = EventBus()
    state_store = StateStore()
    data_buffer = DataBuffer()
    stream_channel = {}
    
    module = YourModule(event_bus, state_store, data_buffer, stream_channel)
    module.initialize()
    
    # 发布测试事件
    from sub.your_module.events import YourEvent
    event_bus.publish(YourEvent(data="test"))
    
    # 验证处理结果
    # ...
    
    module.shutdown()
    print("✓ 测试通过: 事件处理")

if __name__ == "__main__":
    test_module_init()
    test_event_handling()
    print("\n所有测试通过!")

调试技巧

1. 启用 DEBUG 日志

临时修改 src/main.py:

main.set_log_level("DEBUG")

或发布事件:

from sub.logger.events import LogLevelChangeEvent
event_bus.publish(LogLevelChangeEvent(level="DEBUG"))

2. 使用 Python Debugger

def process_data(self, data):
    # 设置断点
    import pdb; pdb.set_trace()
    
    # 或使用 breakpoint() (Python 3.7+)
    breakpoint()
    
    result = self._complex_operation(data)
    return result

3. 状态检查工具

def dump_state(self):
    """打印模块状态(调试用)"""
    state = {
        "initialized": self._initialized,
        "param1": self.param1,
        "state_keys": self.stateStore.keys()
    }
    self.logger.debug(f"[Debug] Module state: {state}")

4. 模拟主控环境

# src/sub/test/mock_controller.py
from core import EventBus, StateStore, DataBuffer, StreamChannel

class MockController:
    """模拟主控环境用于测试"""
    
    def __init__(self):
        self.event_bus = EventBus()
        self.state_store = StateStore()
        self.data_buffer = DataBuffer()
        self.channels = {
            "video_stream": StreamChannel("video", maxsize=2),
            "audio_input": StreamChannel("audio_in", maxsize=10),
        }
    
    def test_module(self, ModuleClass, config=None):
        """测试模块"""
        config = config or {}
        
        module = ModuleClass(
            self.event_bus,
            self.state_store,
            self.data_buffer,
            self.channels
        )
        
        module.initialize(**config)
        return module

使用:

from sub.test.mock_controller import MockController
from sub.your_module import YourModule

mock = MockController()
module = mock.test_module(YourModule, {"param1": "test"})

# 测试功能
# ...

module.shutdown()

性能优化

1. 避免阻塞主线程

❌ 错误示例:

def _on_event(self, event):
    # 长时间操作阻塞事件处理
    result = self._heavy_computation()  # 5秒
    self.stateStore.set("result", result)

✅ 正确做法:

def _on_event(self, event):
    # 提交到后台线程处理
    threading.Thread(
        target=self._process_in_background,
        args=(event,),
        daemon=True
    ).start()

def _process_in_background(self, event):
    result = self._heavy_computation()
    self.stateStore.set("result", result)

2. StreamChannel 消费者优化

def _process_frame(self, frame):
    """快速处理,避免阻塞流通道"""
    try:
        # ✓ 快速操作
        self._fast_detection(frame)
        
        # ✓ 或提交到队列
        self.work_queue.put(frame)
        
    except queue.Full:
        # 丢弃帧而不是阻塞
        pass

3. DataBuffer 及时释放

def process_data(self, data_id):
    """处理完立即释放"""
    try:
        data = self.dataBuffer.get(data_id)
        result = self._process(data)
        return result
    finally:
        # 确保释放
        if self.dataBuffer.exists(data_id):
            self.dataBuffer.release(data_id)

4. 批处理优化

class BatchProcessor(SubModule):
    def __init__(self, *args):
        super().__init__(*args)
        self.batch = []
        self.batch_size = 10
    
    def add_item(self, item):
        self.batch.append(item)
        
        if len(self.batch) >= self.batch_size:
            self._process_batch()
    
    def _process_batch(self):
        """批量处理提高效率"""
        results = self._batch_operation(self.batch)
        self.batch.clear()

5. 缓存优化

from functools import lru_cache

class YourModule(SubModule):
    @lru_cache(maxsize=128)
    def _compute_feature(self, data_hash):
        """缓存计算结果"""
        return expensive_computation(data_hash)

开发规范

代码注释

采用项目统一注释风格:

'''
:brief 函数功能简述
:desc 详细说明(可选)
:param 参数名: 参数说明
:return 返回值说明
:raises 异常类型: 异常说明
'''

Git 提交规范

遵循 Conventional Commits:

<type>(<scope>): <subject>

Type 类型:

Type 说明 示例
feat 新功能 feat(speech): 添加语音识别
fix Bug修复 fix(logger): 修复路径错误
docs 文档 docs(readme): 更新安装说明
refactor 重构 refactor(event): 优化事件总线
perf 性能优化 perf(stream): 优化音频流

异常处理

# ✅ 正确的异常处理
try:
    result = risky_operation()
except SpecificError as e:
    self.logger.error(f"Operation failed: {e}")
    self.event_bus.publish(SubsystemErrorEvent(
        module="your_module",
        message=str(e)
    ))
except Exception as e:
    self.logger.exception("Unexpected error")
    self.event_bus.publish(FatalSubsystemErrorEvent(
        module="your_module",
        message="Critical failure"
    ))

完整示例

示例1:简单数据处理模块

# src/sub/data_processor/__init__.py
from core.init.submod import SubModule
from sub.logger import Logger

class DataProcessor(SubModule):
    """数据处理模块"""
  
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
        self.module_name = "DataProcessor"
        self.logger = Logger.get_logger("DataProcessor")
  
    def initialize(self, **kwargs):
        """初始化模块"""
        # 订阅视频流
        if "video_stream" in self.streamChannel:
            self.streamChannel["video_stream"].subscribe(self._process_frame)
            self.logger.info("Subscribed to video stream")
      
        # 初始化状态
        self.state_store.set("data_processor.frames_processed", 0)
        self._initialized = True
        self.logger.info("DataProcessor initialized")
  
    def _process_frame(self, frame):
        """处理视频帧"""
        try:
            # 处理逻辑
            processed = self._do_processing(frame)
          
            # 更新计数
            count = self.state_store.get("data_processor.frames_processed", 0)
            self.state_store.set("data_processor.frames_processed", count + 1)
          
            # 存储结果
            self.data_buffer.put("data_processor.result", processed)
          
        except Exception as e:
            self.logger.error(f"Frame processing failed: {e}")
  
    def _do_processing(self, frame):
        """实际处理逻辑"""
        return frame
  
    def shutdown(self):
        """清理资源"""
        if "video_stream" in self.streamChannel:
            self.streamChannel["video_stream"].unsubscribe(self._process_frame)
        self._initialized = False
        self.logger.info("DataProcessor shutdown")
  
    def restart(self, **kwargs):
        """重启模块"""
        self.shutdown()
        self.initialize(**kwargs)

示例2:带工作线程的模块

# src/sub/background_worker/__init__.py
import threading
import time
from core.init.submod import SubModule
from sub.logger import Logger

class BackgroundWorker(SubModule):
    """后台工作模块"""
  
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        super().__init__(eventBus, stateStore, dataBuffer, streamChannel)
        self.module_name = "BackgroundWorker"
        self.logger = Logger.get_logger("BackgroundWorker")
        self.running = False
        self.worker_thread = None
  
    def initialize(self, interval=1.0, **kwargs):
        """初始化模块"""
        self.interval = interval
        self._initialized = True
        self.logger.info("BackgroundWorker initialized")
  
    def start(self):
        """启动后台线程"""
        if self.running:
            return
      
        self.running = True
        self.worker_thread = threading.Thread(
            target=self._worker_loop,
            name="BackgroundWorker",
            daemon=True
        )
        self.worker_thread.start()
        self.logger.info("Worker thread started")
  
    def stop(self):
        """停止后台线程"""
        if not self.running:
            return
      
        self.running = False
        if self.worker_thread:
            self.worker_thread.join(timeout=2.0)
        self.logger.info("Worker thread stopped")
  
    def _worker_loop(self):
        """工作线程主循环"""
        while self.running:
            try:
                self._do_work()
                time.sleep(self.interval)
            except Exception as e:
                self.logger.error(f"Worker error: {e}")
  
    def _do_work(self):
        """执行实际工作"""
        pass
  
    def shutdown(self):
        """清理资源"""
        self.stop()
        self._initialized = False
        self.logger.info("BackgroundWorker shutdown")
  
    def restart(self, **kwargs):
        """重启模块"""
        self.shutdown()
        self.initialize(**kwargs)

多模块协作示例

示例1:语音交互流水线

展示从唤醒到执行指令的完整事件流转:

事件驱动流水线

📐 在 draw.io 中编辑 · 详见 ARCHITECTURE.md §5

每个模块只关心自己订阅的事件,通过 EventBus 自动串联,无需直接引用其他模块。

示例2:人员跟随事件链

展示 person_follower 如何通过事件与其他模块协作:

# 外部模块(如 ActionDispatcher)启动跟随
eventBus.publish(FollowStartEvent(target_type="person"))

# PersonFollower 内部订阅多个事件源:
# 1. DetectionResultEvent → 筛选 person 类别 → 计算目标角度/距离
# 2. LidarScanEvent → 前方障碍物检测 → 决定是否减速
# 3. 融合后发布底盘控制:
#    eventBus.publish(ChassisMoveEvent(linear_speed=0.3, angular_speed=-0.1))

# 停止跟随(用户语音指令或超时)
eventBus.publish(FollowStopEvent(reason="user_command"))

要点:模块间通过事件松耦合——PersonFollower 不知道检测结果来自哪个视觉模块,ActionDispatcher 也不知道跟随的具体实现。新增或替换模块时,只要事件接口不变,其他模块无需修改。


常见问题

Q: 如何在模块间传递数据?

A: 根据数据类型选择:

  • 配置/状态数据: StateStore
  • 大对象/临时数据: DataBuffer
  • 实时流数据: StreamChannel
  • 通知/事件: EventBus

Q: 如何确保线程安全?

A: 核心组件都是线程安全的(使用锁保护)。自己的数据需要自己加锁。

Q: 模块加载失败怎么办?

A: 检查:

  1. 模块目录名是否正确(小写+下划线)
  2. 主类名是否符合命名规范或配置了 class_name
  3. initialize() 方法是否正确实现
  4. 查看日志文件中的错误信息

Q: 配置未生效?

A: 检查:

  1. config_file 路径是否正确
  2. JSON 格式是否有效
  3. initialize(**kwargs) 是否正确接收参数

Q: 如何测试子模块?

A:

from core import EventBus, StateStore, DataBuffer, StreamChannel
from sub.your_module import YourModule

def test_module():
    event_bus = EventBus()
    state_store = StateStore()
    data_buffer = DataBuffer()
    stream_channel = {}
  
    module = YourModule(event_bus, state_store, data_buffer, stream_channel)
    module.initialize(param1="test")
  
    assert module._initialized
    module.shutdown()

最佳实践

  1. 配置优先:所有可调参数都应在配置文件中定义
  2. 日志分级:严格按照 INFO/DEBUG/WARNING/ERROR 使用
  3. 错误处理:使用 handle_error(e, fatal=True/False) 发布错误事件
  4. 资源清理:在 shutdown() 中释放所有资源
  5. 状态更新:关键状态变化要更新 StateStore
  6. 事件驱动:模块间通信使用事件,避免直接调用

API参考

SubModule 基类

class SubModule(ABC):
    """所有子模块必须继承的基类"""
    
    def __init__(self, eventBus, stateStore, dataBuffer, streamChannel):
        """构造函数
        
        Args:
            eventBus: 事件总线实例
            stateStore: 状态存储实例
            dataBuffer: 数据缓冲实例
            streamChannel: 流通道字典
        """
    
    @abstractmethod
    def initialize(self, **kwargs) -> None:
        """初始化模块(必须实现)
        
        Args:
            **kwargs: 配置参数
        
        Raises:
            Exception: 初始化失败时抛出
        """
    
    @abstractmethod
    def shutdown(self) -> None:
        """关闭模块(必须实现)"""
    
    @abstractmethod
    def restart(self, **kwargs) -> None:
        """重启模块(必须实现)
        
        Args:
            **kwargs: 重启时的配置参数
        """
    
    def is_initialized(self) -> bool:
        """检查模块是否已初始化"""
    
    def get_platform(self) -> int:
        """获取当前平台类型
        
        Returns:
            平台常量 (PLATFORM_TEST=0, PLATFORM_CAR=1)
        """
    
    def handle_error(self, error: Exception, fatal: bool = False) -> None:
        """处理错误
        
        Args:
            error: 异常对象
            fatal: 是否为致命错误
        """

EventBus API

class EventBus:
    """事件总线"""
    
    def subscribe(self, event_type: Type[Event], handler: Callable) -> None:
        """订阅事件
        
        Args:
            event_type: 事件类型
            handler: 回调函数
        """
    
    def unsubscribe(self, event_type: Type[Event], handler: Callable) -> None:
        """取消订阅
        
        Args:
            event_type: 事件类型
            handler: 回调函数
        """
    
    def publish(self, event: Event) -> None:
        """发布事件
        
        Args:
            event: 事件实例
        """

StateStore API

class StateStore:
    """状态存储"""
    
    def set(self, key: str, value: Any) -> None:
        """设置状态值
        
        Args:
            key: 状态键
            value: 状态值
        """
    
    def get(self, key: str, default: Any = None) -> Any:
        """获取状态值
        
        Args:
            key: 状态键
            default: 默认值
        
        Returns:
            状态值或默认值
        """
    
    def exists(self, key: str) -> bool:
        """检查状态键是否存在
        
        Args:
            key: 状态键
        
        Returns:
            是否存在
        """
    
    def delete(self, key: str) -> None:
        """删除状态
        
        Args:
            key: 状态键
        """
    
    def keys(self) -> List[str]:
        """获取所有状态键
        
        Returns:
            键列表
        """
    
    def add_observer(self, key: str, callback: Callable) -> None:
        """添加状态观察者
        
        Args:
            key: 状态键
            callback: 回调函数 (key, value) -> None
        """
    
    def remove_observer(self, key: str, callback: Callable) -> None:
        """移除状态观察者
        
        Args:
            key: 状态键
            callback: 回调函数
        """

DataBuffer API

class DataBuffer:
    """数据缓冲"""
    
    def put(self, payload: Any, metadata: Optional[dict] = None) -> str:
        """存储数据
        
        Args:
            payload: 数据对象
            metadata: 元数据字典
        
        Returns:
            数据ID (UUID)
        """
    
    def get(self, data_id: str) -> Any:
        """获取数据
        
        Args:
            data_id: 数据ID
        
        Returns:
            数据对象
        
        Raises:
            KeyError: ID不存在
            RuntimeError: 数据已释放
        """
    
    def get_metadata(self, data_id: str) -> dict:
        """获取元数据
        
        Args:
            data_id: 数据ID
        
        Returns:
            元数据字典
        
        Raises:
            KeyError: ID不存在
        """
    
    def exists(self, data_id: str) -> bool:
        """检查数据是否存在且未释放
        
        Args:
            data_id: 数据ID
        
        Returns:
            是否存在
        """
    
    def release(self, data_id: str) -> None:
        """释放数据
        
        Args:
            data_id: 数据ID
        
        Raises:
            KeyError: ID不存在
        """
    
    def list_ids(self) -> List[str]:
        """列出所有数据ID
        
        Returns:
            ID列表
        """

StreamChannel API

class StreamChannel:
    """实时数据流通道"""
    
    def __init__(self, name: str, maxsize: int = 10, drop_oldest: bool = True):
        """初始化流通道
        
        Args:
            name: 通道名称
            maxsize: 缓冲区大小
            drop_oldest: 满时是否丢弃最旧数据
        """
    
    def publish(self, data: Any) -> None:
        """发布数据(非阻塞)
        
        Args:
            data: 数据对象
        """
    
    def subscribe(self, callback: Callable) -> None:
        """订阅数据流
        
        Args:
            callback: 回调函数 (data) -> None
        """
    
    def unsubscribe(self, callback: Callable) -> None:
        """取消订阅
        
        Args:
            callback: 回调函数
        """
    
    def close(self) -> None:
        """关闭通道"""

ModelManager API

class ModelManager:
    """模型管理器(单例)"""
    
    @classmethod
    def get_instance(cls) -> 'ModelManager':
        """获取单例实例"""
    
    def is_registered(self, model_name: str) -> bool:
        """检查模型是否已注册"""
    
    def get_model_list(self) -> List[str]:
        """获取所有已注册模型名称"""
    
    def get_model_dir(self, model_name: str) -> Optional[Path]:
        """获取模型目录"""
    
    def get_model_path(self, model_name: str, size: Optional[str] = None,
                      extension: str = ".pt") -> Optional[Path]:
        """获取模型文件路径"""
    
    def verify_model(self, model_name: str, size: Optional[str] = None,
                    load: bool = False) -> bool:
        """验证模型是否有效"""
    
    def get_supported_sizes(self, model_name: str) -> List[str]:
        """获取支持的模型尺寸"""
    
    def get_default_size(self, model_name: str) -> Optional[str]:
        """获取默认模型尺寸"""
    
    def get_model_info(self, model_name: str) -> Optional[Dict[str, Any]]:
        """获取模型完整信息"""

辅助函数

# 获取模型管理器
from core.ModelManager import get_model_manager
model_manager = get_model_manager()

# 获取Logger
from sub.logger import Logger
logger = Logger.get_logger("ModuleName")

与监控系统集成

子模块与监控系统 (MonitorAPI) 的集成是完全自动的——开发者不需要编写任何监控相关代码。本节说明这一机制的原理及高级用法。

零代码自动监控

MonitorAPI 采用观察者模式,通过 EventBus 的基类订阅机制自动捕获系统中发布的所有事件。当 config/system.json 中 monitor.enabled=true 时,以下数据会被自动采集并推送到 Web 监控面板:

数据类型 采集方式 子模块需要做什么
EventBus 事件 自动捕获(基类订阅 Event) 正常使用 event_bus.publish() 即可
StateStore 状态 周期性轮询 正常使用 state_store.set() 即可
DataBuffer 条目 周期性轮询 正常使用 data_buffer.put() 即可
StreamChannel 统计 周期性轮询 正常使用流通道即可

关键点:子模块代码中无需导入任何 MonitorAPI 相关模块,也无需发布特殊的监控事件。

事件自动捕获原理

MonitorAPI 利用 EventBus 的事件继承特性——订阅 Event 基类即可接收所有子类事件:

# 这是 MonitorAPI 内部的实现,子模块开发者无需关心
event_bus.subscribe(Event, self._on_any_event)

因此,只要你的子模块通过 EventBus 发布事件,MonitorAPI 就会:

  1. 将事件记录到历史缓冲区(最多 200 条)
  2. 通过 WebSocket (/ws) 实时推送给所有已连接的前端客户端
  3. 在 REST API (/api/events) 中提供查询
# 你的子模块代码 — 正常发布事件即可
@dataclass
class MyModuleProcessedEvent(Event):
    """处理完成事件"""
    result_count: int = 0
    duration_ms: float = 0.0

# 发布事件 → MonitorAPI 自动捕获 → 前端实时显示
self.event_bus.publish(MyModuleProcessedEvent(
    result_count=42,
    duration_ms=150.3
))

状态变更的可视化

通过 StateStore 设置的状态会自动出现在监控面板的 States 页面中:

# 设置状态 → 监控面板自动可见
self.state_store.set("my_module.processing.active", True)
self.state_store.set("my_module.processing.count", 42)
self.state_store.set("my_module.last_error", "")

建议使用有意义的状态键命名(module.feature.property 格式),以便在监控面板中快速定位。

自定义监控数据

如果需要向监控面板发送额外的调试或诊断信息,最佳方式是定义并发布自定义事件:

# your_module/events.py
@dataclass
class MyModuleDiagnosticsEvent(Event):
    """诊断信息事件,用于监控面板展示"""
    queue_depth: int = 0
    avg_latency_ms: float = 0.0
    error_rate: float = 0.0

# 周期性发布诊断事件
def _report_diagnostics(self):
    self.event_bus.publish(MyModuleDiagnosticsEvent(
        queue_depth=len(self._queue),
        avg_latency_ms=self._calc_avg_latency(),
        error_rate=self._error_count / max(self._total_count, 1)
    ))

这些自定义事件会:

  • 出现在监控面板的 Events 页实时事件流中
  • 通过 WebSocket 实时推送
  • 在 Event Topology 页展示订阅关系
  • 在 Control 页的事件发布表单中自动生成(可用于调试触发)

监控配置

监控服务通过 config/system.json 的 monitor 段配置,子模块无需关心:

{
  "monitor": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 9090,
    "update_interval": 0.5
  }
}
  • enabled:设为 false 时 MonitorAPI 不启动,对系统行为零影响
  • update_interval:WebSocket 周期性推送间隔(秒),影响 States/DataBuffer 等轮询数据的刷新频率
  • 事件推送是即时的,不受 update_interval 控制

WebSocket 实时事件流

前端或外部工具可通过 WebSocket 接收实时事件流:

ws://<host>:9090/ws

连接后会收到:

  • welcome 消息(连接确认)
  • system_data 消息(周期性系统状态快照)
  • event 消息(每当 EventBus 上有事件发布时即时推送)

提示:子模块开发者通常不需要直接与 WebSocket 交互。监控面板已提供完整的可视化界面。如需程序化访问监控数据,可使用 REST API (/api/status, /api/events, /api/states 等)。


附录

事件列表

系统生命周期

  • SystemStartingEvent - 系统启动中
  • SystemStartedEvent - 系统已启动
  • SystemStoppingEvent - 系统停止中
  • SystemStoppedEvent - 系统已停止
  • SystemRestartingEvent - 系统重启中
  • SystemRestartedEvent - 系统已重启
  • SystemShutdownRequestEvent - 关闭请求

硬件控制

  • VideoStreamControlEvent - 视频流控制
  • AudioInputStreamControlEvent - 音频输入控制
  • AudioOutputStreamControlEvent - 音频输出控制

错误事件

  • SubsystemErrorEvent - 子模块错误
  • FatalSubsystemErrorEvent - 子模块致命错误
  • ControllerErrorEvent - 主控错误
  • ExternalErrorEvent - 外部依赖错误

状态键列表

系统状态

  • KEY_SYSTEM_PLATFORM - 平台类型 (0=测试, 1=小车)
  • KEY_SYSTEM_INITIALIZED - 系统是否初始化
  • KEY_SYSTEM_RUNNING - 系统是否运行中
  • KEY_SYSTEM_VIDEO_ENABLED - 视频是否启用
  • KEY_SYSTEM_AUDIO_IN_ENABLED - 音频输入是否启用
  • KEY_SYSTEM_AUDIO_OUT_ENABLED - 音频输出是否启用

硬件可用性

  • KEY_HAL_CAMERA_AVAILABLE - 摄像头是否可用
  • KEY_HAL_MICROPHONE_AVAILABLE - 麦克风是否可用
  • KEY_HAL_SPEAKER_AVAILABLE - 扬声器是否可用

模型管理

  • KEY_MODEL_MANAGER_INITIALIZED - 模型管理器是否初始化
  • KEY_MODEL_MANAGER_AVAILABLE - 模型管理器是否可用
  • KEY_MODEL_MANAGER_MODELS_COUNT - 已注册模型数量

目录结构规范

src/sub/your_module/
├── __init__.py           # 主类实现(必须)
├── events.py            # 模块私有事件(可选)
├── states.py            # 模块私有状态键(可选)
├── README.md            # 模块说明(推荐)
└── utils.py             # 辅助工具(可选)

config/
└── your_module.json     # 模块配置(推荐)

doc/
└── YourModule.md        # 详细文档(可选)

版本兼容性

组件版本 说明
Python >= 3.9
EventBus v0.1.0+
StateStore v0.1.0+
DataBuffer v0.1.0+
StreamChannel v0.1.0+
MainController v0.2.0+ (带run方法)
SubModule基类 v1.0.0+
ModelManager v0.1.0+
ConfigManager v1.0.0+
MonitorAPI v1.0.0+

LLM 语音指令扩展

注册新的语义动作

生产动作目录由 config/action_registry.json 统一管理。新增可执行动作时,需要同时具备真实事件/工作流适配、能力清单依据、风险等级、参数 schema、观察结果和测试;不能只在 config/llm_agent.json 里增加一个语音字符串。

{
    "op": "your_module.do_something",
    "name_zh": "执行某动作",
    "description": "动作说明",
    "params_schema": {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数说明"}
        },
        "required": ["param1"]
    },
    "risk_level": "low",
    "capability_required": "your_module.do_something",
    "adapter_type": "event",
    "adapter_target": {
        "event_class": "sub.your_module.events.YourEvent",
        "field_mapping": {
            "param1": "param1"
        }
    },
    "preconditions": {
        "description": "前置条件说明",
        "checks": [
            {
                "state_key": "system.initialized",
                "expected": true,
                "message": "系统未完成初始化"
            }
        ]
    },
    "observation": {
        "event_class": "sub.your_module.events.YourResultEvent",
        "success_field": "success",
        "timeout_ms": 3000
    }
}

配置字段说明

字段 必填 说明
op 是 产品级动作 ID,使用点分 snake_case 命名
params_schema 是 参数 JSON Schema,供 planner/backend/frontend 校验
risk_level 是 风险等级,用于确认、权限和 Monitor 展示
capability_required 是 所需能力,必须能在能力清单中解释可用/不可用原因
adapter_type 是 当前主要使用 event,后续可接 workflow adapter
adapter_target 是 真实机器人事件/工作流目标,不能指向 mock
preconditions 否 执行前 StateStore 条件检查
observation 是 判断动作结果的真实观察事件/超时

添加前置条件

前置条件用于在动作执行前检查系统状态,避免在条件不满足时执行操作:

# 前置条件检查流程(PlanExecutor 自动执行):
# 1. 从 config/action_registry.json 获取动作配置
# 2. 结合 capability_manifest 评估能力状态
# 3. 读取 preconditions.checks 列表
# 4. 对每个 check,从 StateStore 读取 state_key 的值
# 5. 任一检查失败 -> 发布 rejected/failed 结果,说明原因
# 6. 全部通过 -> 发布真实事件并等待 observation

常用的 state_key:

state_key 类型 说明
hal.camera.is_open bool 摄像头是否已打开
hal.microphone.is_open bool 麦克风是否已打开
hal.motor.is_connected bool 电机驱动是否已连接
system.initialized bool 系统是否已完成初始化

完整示例:注册 LiDAR 避障指令

{
    "op": "lidar.avoidance.enable",
    "name_zh": "开启激光雷达避障",
    "description": "开启 LiDAR 避障模式",
    "params_schema": {
        "type": "object",
        "properties": {}
    },
    "risk_level": "medium",
    "capability_required": "lidar.behavior_mode",
    "adapter_type": "event",
    "adapter_target": {
        "event_class": "core.pub.event.navigation.LidarModeChangeEvent",
        "field_mapping": {
            "mode": {
                "const": 1
            },
            "source": "semantic_planner"
        }
    },
    "observation": {
        "event_class": "core.pub.event.navigation.LidarModeChangedEvent",
        "success_field": "success",
        "timeout_ms": 3000
    }
}

注册后,用户说"开启避障",语义入口应提交 SemanticRequestEvent,semantic_planner 生成候选计划,确认后由 plan_executor 发布真实事件并等待 observation。直接 ActionDispatcher.dispatch() 只允许作为明确标记的兼容/调试路径。


MQTT 客户端集成

子模块可通过 mqtt_client 子模块向后端服务器发布 MQTT 消息。mqtt_client 已作为独立子模块运行,其他模块通过 EventBus 事件机制与其交互。

发布遥测数据

from sub.mqtt_client.events import MqttPublishEvent

class YourModule(SubModule):
    def _send_telemetry(self, data: dict):
        """通过 MQTT 发布遥测数据到后端"""
        self.eventBus.publish(MqttPublishEvent(
            topic=f"ac_fs32/{{device_id}}/telemetry",
            payload=data,
            qos=0
        ))

接收远程控制指令

from sub.mqtt_client.events import RemoteCommandEvent

class YourModule(SubModule):
    def initialize(self, **kwargs):
        self.eventBus.subscribe(RemoteCommandEvent, self._on_remote_command)
    
    def _on_remote_command(self, event: RemoteCommandEvent):
        """处理后端下发的远程控制指令"""
        if event.action == "move":
            linear = event.params.get("linear_speed", 0)
            angular = event.params.get("angular_speed", 0)
            # 执行运动控制...

MQTT Topic 规范

Topic 方向 QoS 说明
ac_fs32/{device_id}/telemetry 上行 0 传感器遥测 (电池/IMU/CPU)
ac_fs32/{device_id}/status 上行 1 设备在线状态 (retain)
ac_fs32/{device_id}/events 上行 1 系统事件 (错误/唤醒/重启)
ac_fs32/{device_id}/control 下行 1 远程控制指令
ac_fs32/{device_id}/config 下行 1 配置更新推送

配置 (config/mqtt_client.json)

{
    "broker": {
        "host": "your-server.com",
        "port": 1883,
        "username": "",
        "password": ""
    },
    "device_id": "robot_001",
    "heartbeat_interval": 30,
    "auto_reconnect": true
}

WebSocket 流数据传输

ws_streamer 子模块负责将高带宽数据(LiDAR 扫描、视频帧)通过 WebSocket 实时传输到后端。

发布 LiDAR 数据到后端

from sub.ws_streamer.events import StreamSendEvent

class YourModule(SubModule):
    def _on_lidar_scan(self, event):
        """将 LiDAR 扫描数据通过 WS 发送到后端"""
        self.eventBus.publish(StreamSendEvent(
            stream_type="lidar",
            data={
                "scan": {
                    "ranges": event.ranges,
                    "angle_min": event.angle_min,
                    "angle_max": event.angle_max
                },
                "pose": {
                    "x": event.pose_x,
                    "y": event.pose_y,
                    "theta": event.pose_theta
                }
            }
        ))

MQTT vs WebSocket 选择

维度 MQTT WebSocket
消息大小 小 (<1KB) 大 (LiDAR ~50KB/帧)
用途 控制指令、遥测、事件 LiDAR 点云、视频流、实时地图
QoS 支持 (0/1/2) 不支持
延迟 中 低
编码 JSON msgpack (二进制)

配置 (config/ws_streamer.json)

{
    "server_url": "ws://your-server.com:8000/ws/stream/{device_id}",
    "stream_types": ["lidar"],
    "max_fps": 10,
    "auto_reconnect": true
}

SLAM 工作模式

SLAM 子模块支持三种工作模式,通过 config/slam.json 的 mode 字段切换:

模式对比

模式 处理位置 适用场景 说明
local 机器人端 离线环境 完全本地处理,分辨率受限于 RPi 算力
remote 后端服务器 有网络连接 机器人只采集原始数据,后端做完整 SLAM
hybrid 两端协作 推荐默认 本地做低分辨率预览,后端做精细建模

配置示例

{
    "mode": "remote",
    "local": {
        "resolution": 0.05,
        "max_range": 12.0
    },
    "remote": {
        "send_raw_scans": true,
        "receive_processed_map": true,
        "local_preview_resolution": 0.2
    }
}

数据流

[LiDAR 传感器] → [slam 子模块]
                      │
          ┌───────────┼───────────┐
          │           │           │
       local       remote      hybrid
          │           │           │
     本地栅格    ws_streamer   本地预览
     更新地图    → 后端 SLAM    + 后端精细
          │        ↓  ↑          │
          │     处理后地图       合并
          │     → DataBuffer     │
          └───────────┼───────────┘
                      │
               [navigation 子模块]

后端 API 集成模式

子模块与后端 API 的交互主要通过 MQTT 和 WebSocket 间接进行,不直接调用 REST API。

架构分层

子模块 (src/sub/)
    ↓ EventBus 事件
mqtt_client / ws_streamer 子模块
    ↓ MQTT / WebSocket
后端 (backend/)
    ↓ REST API
前端 (frontend/)

常见集成模式

1. 遥测上报:子模块 → StateStore → mqtt_client 定时采集 → MQTT → 后端 analytics

2. 远程控制:前端 REST → 后端 control → MQTT → mqtt_client → EventBus → 目标子模块

3. 地图数据:slam → ws_streamer → WebSocket → 后端 map_builder → WebSocket → 前端地图

4. 对话执行:前端对话 → 后端 LLM → 意图解析 → MQTT 指令 → mqtt_client → EventBus → 执行

后端 API 端点速查

详细 API 文档参见 后端 API 文档。

模块 端点前缀 说明
认证 /api/auth/ 注册/登录/刷新令牌
设备 /api/devices/ 设备 CRUD + 状态查询
控制 /api/control/ 远程指令 → MQTT 下发
地图 /api/maps/ 地图列表/详情/图片/建图控制
分析 /api/analytics/ 遥测查询/统计/清理
对话 /api/conversation/ LLM 对话/历史/WebSocket

最后更新: 2025/07/15 文档版本: 4.0.0 作者: AC_FS32 开发团队