AC_FS32 智能机器人控制系统 - 完整子模块开发文档
本文档面向子模块开发者,提供核心架构、开发规范、管理机制和最佳实践。
- 快速开始
- 核心架构
- 子模块管理
- Provider/Engine 可插拔架构
- 共享工具模块
- 事件系统
- 状态管理
- 数据流通道
- 硬件抽象层 (HAL)
- 数据缓冲
- 模型管理
- 日志系统
- 配置管理
- 调试与测试
- 性能优化
- 开发规范
- 完整示例
- 多模块协作示例
- 常见问题
- 最佳实践
- API参考
- 与监控系统集成
- 附录
- LLM 语音指令扩展
- MQTT 客户端集成
- WebSocket 流数据传输
- SLAM 工作模式
- 后端 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/ # 文档
src/sub/your_module/
├── __init__.py # 主类实现
├── events.py # 模块私有事件(可选)
└── states.py # 模块私有状态键(可选)
# 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)编辑 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发布-订阅模式的异步通信机制。
# 订阅事件
self.event_bus.subscribe(SomeEvent, self._handler)
# 发布事件
self.event_bus.publish(SomeEvent(data="value"))线程安全的全局状态键值存储。
# 设置状态
self.state_store.set("your_module.status", "running")
# 获取状态
status = self.state_store.get("your_module.status", default="stopped")用于模块间共享大数据对象。
# 存储数据
self.data_buffer.put("your_module.result", result_data)
# 获取数据
result = self.data_buffer.get("your_module.result")用于实时数据流传输(视频帧、音频)。
# 订阅数据流
stream_channel["video_stream"].subscribe(self._process_frame)
# 发布数据流
stream_channel["audio_output"].publish(audio_bytes){
"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/ 加载) |
- 优先使用
class_name(如果指定) - 否则尝试以下命名规范:
{ModuleName}- 如VoiceRecognition{ModuleName}Controller- 如WakeupController{ModuleName}Module- 如LoggerModule
- 模块目录:小写+下划线
voice_recognition - 主类名:驼峰命名
VoiceRecognition - 配置文件:小写+下划线
voice_recognition.json
# 主程序
main = MainController()
main.initialize_submodules()内部流程:
- 加载
config/submodules.json - 按
enabled_modules顺序遍历 - 对每个模块:
- 动态导入:
from sub.{module_name} import {ClassName} - 实例化:
instance = ClassName(eventBus, stateStore, dataBuffer, streamChannel) - 加载配置:从
config_file或config字段 - 调用
initialize(**config) - 如果
auto_start=true且有start()方法,则调用
- 动态导入:
所有子模块应继承 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(输出方向)工厂模式。
-
定义基类(
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: ...
-
实现具体 Provider(如
providers/whisper_provider.py) -
工厂方法(在子模块
__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()
-
配置切换:通过 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_service 子模块支持插件式自定义 Provider 扩展。只需 3 步:
# 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将 .py 文件放入 config/llm_service.json 中 custom_providers_path 指定的目录(默认 src/sub/llm_service/custom_providers/)。
在 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 控制器位于 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.levelyour_module.processing.enabledyour_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 采用 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 (Hardware Abstraction Layer) 提供跨平台的硬件设备访问接口。支持 Windows 和 Linux (包括树莓派)。
| 设备类型 | HAL 名称 | Windows 实现 | Linux 实现 |
|---|---|---|---|
| 摄像头 | camera | OpenCV | picamera2 |
| 麦克风 | microphone | PyAudio | pyalsaaudio |
| 扬声器 | speaker | PyAudio | pyalsaaudio |
| 电机驱动 | motor | 不支持 | 串口通信 |
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 设备继承 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: ...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()mic = self.get_hal_device("microphone")
if mic:
mic.open()
data = mic.read() # 读取一次音频数据
# 或使用连续采集模式
mic.subscribe(self._on_audio)
mic.start_capture()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()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 可用
passDataBuffer 用于存储和管理大数据对象(图像、音频、点云等),提供显式的生命周期管理。
# 存储图像数据
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}")- 及时释放:数据使用完毕立即调用
release() - 存储元数据:包含 source、timestamp、format 等信息
- 异常处理:始终捕获
KeyError和RuntimeError - 检查存在性:使用前先
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)系统提供统一的模型管理接口,支持模型注册、查询、验证和路径管理。
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)如果需要添加新的模型:
- 在
src/model/下创建模型目录:
src/model/
├── model_whisper/ # 已有模型
│ ├── base.pt
│ └── small.pt
└── your_model/ # 新模型
├── v1.pt
└── v2.pt
- 创建模型加载器(在
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())- 在
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}")- 模块初始化/关闭
- 重要状态变更
- 识别结果
- 模型加载成功
self.logger.info("[Wakeup] 模块初始化完成")
self.logger.info(f"[Wakeup] 检测到唤醒词: '{word}'")
self.logger.info(f"[ASR] 识别完成: '{text}'")- 配置加载
- 事件订阅/发布
- 数据流状态
- 中间处理步骤
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")- 配置文件不存在(使用默认值)
- 可选功能不可用
- 数据已释放
self.logger.warning("[Wakeup] 检测未启用")
self.logger.warning(f"[Data] Image not available: {data_id}")- 操作失败但模块可继续运行
- 数据处理错误
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 # 你的模块配置
从 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)- kwargs 参数 (最高优先级)
- StateStore 运行时配置
- ConfigManager 加载的文件配置
- 直接读取 JSON 文件
- 硬编码默认值 (最低优先级)
{
"_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){
"modules": {
"your_module": {
"enabled": true,
"config": {
"param1": "value1",
"param2": 123
}
}
}
}{
"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所有测试通过!")临时修改 src/main.py:
main.set_log_level("DEBUG")或发布事件:
from sub.logger.events import LogLevelChangeEvent
event_bus.publish(LogLevelChangeEvent(level="DEBUG"))def process_data(self, data):
# 设置断点
import pdb; pdb.set_trace()
# 或使用 breakpoint() (Python 3.7+)
breakpoint()
result = self._complex_operation(data)
return resultdef dump_state(self):
"""打印模块状态(调试用)"""
state = {
"initialized": self._initialized,
"param1": self.param1,
"state_keys": self.stateStore.keys()
}
self.logger.debug(f"[Debug] Module state: {state}")# 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()❌ 错误示例:
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)def _process_frame(self, frame):
"""快速处理,避免阻塞流通道"""
try:
# ✓ 快速操作
self._fast_detection(frame)
# ✓ 或提交到队列
self.work_queue.put(frame)
except queue.Full:
# 丢弃帧而不是阻塞
passdef 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)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()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 异常类型: 异常说明
'''遵循 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"
))# 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)# 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)展示从唤醒到执行指令的完整事件流转:
每个模块只关心自己订阅的事件,通过 EventBus 自动串联,无需直接引用其他模块。
展示 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也不知道跟随的具体实现。新增或替换模块时,只要事件接口不变,其他模块无需修改。
A: 根据数据类型选择:
- 配置/状态数据:
StateStore - 大对象/临时数据:
DataBuffer - 实时流数据:
StreamChannel - 通知/事件:
EventBus
A: 核心组件都是线程安全的(使用锁保护)。自己的数据需要自己加锁。
A: 检查:
- 模块目录名是否正确(小写+下划线)
- 主类名是否符合命名规范或配置了
class_name initialize()方法是否正确实现- 查看日志文件中的错误信息
A: 检查:
config_file路径是否正确- JSON 格式是否有效
initialize(**kwargs)是否正确接收参数
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()- 配置优先:所有可调参数都应在配置文件中定义
- 日志分级:严格按照 INFO/DEBUG/WARNING/ERROR 使用
- 错误处理:使用
handle_error(e, fatal=True/False)发布错误事件 - 资源清理:在
shutdown()中释放所有资源 - 状态更新:关键状态变化要更新
StateStore - 事件驱动:模块间通信使用事件,避免直接调用
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: 是否为致命错误
"""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: 事件实例
"""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: 回调函数
"""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列表
"""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:
"""关闭通道"""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 就会:
- 将事件记录到历史缓冲区(最多 200 条)
- 通过 WebSocket (
/ws) 实时推送给所有已连接的前端客户端 - 在 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 接收实时事件流:
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+ |
生产动作目录由 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 | 系统是否已完成初始化 |
{
"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_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)
# 执行运动控制...| 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 | 配置更新推送 |
{
"broker": {
"host": "your-server.com",
"port": 1883,
"username": "",
"password": ""
},
"device_id": "robot_001",
"heartbeat_interval": 30,
"auto_reconnect": true
}ws_streamer 子模块负责将高带宽数据(LiDAR 扫描、视频帧)通过 WebSocket 实时传输到后端。
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 | WebSocket |
|---|---|---|
| 消息大小 | 小 (<1KB) | 大 (LiDAR ~50KB/帧) |
| 用途 | 控制指令、遥测、事件 | LiDAR 点云、视频流、实时地图 |
| QoS | 支持 (0/1/2) | 不支持 |
| 延迟 | 中 | 低 |
| 编码 | JSON | msgpack (二进制) |
{
"server_url": "ws://your-server.com:8000/ws/stream/{device_id}",
"stream_types": ["lidar"],
"max_fps": 10,
"auto_reconnect": true
}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 的交互主要通过 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/auth/ |
注册/登录/刷新令牌 |
| 设备 | /api/devices/ |
设备 CRUD + 状态查询 |
| 控制 | /api/control/ |
远程指令 → MQTT 下发 |
| 地图 | /api/maps/ |
地图列表/详情/图片/建图控制 |
| 分析 | /api/analytics/ |
遥测查询/统计/清理 |
| 对话 | /api/conversation/ |
LLM 对话/历史/WebSocket |
最后更新: 2025/07/15 文档版本: 4.0.0 作者: AC_FS32 开发团队