# Largemodel ROS2 Package

## 概述

`largemodel` 是一个基于 ROS2 Humble 的机器人 AI 服务节点包，集成了语音识别（ASR）、大模型任务规划、双层 AI 决策、动作执行和语音合成（TTS）等功能。该包使机器人能够理解用户的自然语言指令，通过大模型进行任务规划，并自主执行导航、机械臂控制、物体抓取等多种动作。

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     largemodel_control.launch.py                  │
├─────────────┬─────────────────┬─────────────────┬───────────────┤
│ camera_arm  │   model_service │  action_service │      asr      │
│   _kin      │       节点       │       节点       │      节点     │
├─────────────┴─────────────────┴─────────────────┴───────────────┤
│                    large_model_interface (共用工具)               │
└─────────────────────────────────────────────────────────────────┘
```

## 核心节点

### 1. ASR 节点 (asr)

**功能**：语音唤醒 → 录音 → 语音识别

- 支持 KWS 语音唤醒（串口通信）
- WebRTC VAD 语音活动检测
- 多 ASR 引擎：SenseVoiceSmall（本地）/ 讯飞 / 阿里云（在线）

**发布话题**：
| 话题 | 类型 | 说明 |
|------|------|------|
| `/asr` | String | ASR 识别结果 |
| `/wakeup` | Bool | 唤醒信号 |
| `/beep` | UInt16 | 蜂鸣器控制 |
| `/record_status` | Bool | 录音状态 |

### 2. Model Service 节点 (model_service)

**功能**：AI 大脑，调用大模型进行任务规划和执行

**双层 AI 架构**：
- **决策层**：解析用户意图，生成任务步骤
- **执行层**：生成具体动作列表和回复

**订阅话题**：
| 话题 | 说明 |
|------|------|
| `/asr` | ASR 识别结果 |
| `/actionstatus` | 动作执行反馈 |
| `/seewhat_handle` | 视觉触发信号 |

### 3. Action Service 节点 (action_service)

**功能**：解析并执行机器人动作

**支持的动作函数（18种）**：

| 类别 | 动作 | 函数签名 |
|------|------|---------|
| 基础移动 | 左转/右转 | `move_left(x, speed)`, `move_right(x, speed)` |
| 基础移动 | 漂移/跳舞 | `drift()`, `dance()` |
| 基础移动 | 速度控制 | `set_cmdvel(x, y, z, duration)` |
| 导航 | 导航到点 | `navigation(point_name)` |
| 导航 | 获取位置 | `get_current_pose()` |
| 机械臂 | 上下/摇头点头鼓掌 | `arm_up()`, `arm_down()`, `arm_shake()`, `arm_nod()`, `arm_applaud()` |
| 机械臂 | 抓取/放置 | `grasp_obj(x1,y1,x2,y2)`, `putdown()` |
| 机械臂 | Apriltag 分拣 | `apriltag_sort(id)`, `apriltag_remove_higher(h)` |
| 机械臂 | 颜色追踪移除 | `color_remove_higher(color, h)` |
| 视觉 | 追踪/巡线 | `track(x1,y1,x2,y2)`, `follw_line_clear()` |
| 系统 | 等待/结束 | `wait(seconds)`, `finish_dialogue()`, `finishtask()` |

## 目录结构

```
largemodel/
├── config/
│   ├── yahboom.yaml              # 主配置文件
│   ├── large_model_interface.yaml # 大模型 API 配置
│   └── map_mapping.yaml          # 地图导航点配置
├── launch/
│   └── largemodel_control.launch.py  # 启动文件
├── largemodel/
│   ├── __init__.py
│   ├── asr.py                   # 语音识别节点
│   ├── model_service.py         # 模型服务节点
│   └── action_service.py        # 动作执行节点
├── utils/
│   ├── large_model_interface.py # 大模型接口封装
│   ├── mic_serial.py            # 串口通信工具
│   ├── promot.py                # Prompt 模板
│   └── dify_client2.py          # Dify API 客户端
├── resources_file/
│   └── system_vioce/            # 系统提示音
│       ├── zh/                   # 中文提示音
│       └── en/                   # 英文提示音
├── test/                         # 测试文件
├── package.xml
└── setup.py
```

## 配置说明

### 主配置 (yahboom.yaml)

支持国内版和国际版两种模式：

```yaml
# 国内版本参数
asr:
  ros__parameters:
    VAD_MODE: 2
    sample_rate: 16000
    use_oline_asr: True
    language: 'zh'
    regional_setting: "China"

action_service:
  ros__parameters:
    text_chat_mode: True      # True: 文字模式, False: 语音模式
    useolinetts: True         # True: 在线 TTS, False: 本地 TTS

model_service:
  ros__parameters:
    language: 'zh'
    regional_setting: "China"
```

### 大模型配置 (large_model_interface.yaml)

```yaml
# 阿里百炼配置
tongyi_api_key: "your-api-key"
tongyi_base_url: "https://dashscope.aliyuncs.com"
tongyi_app_id: "your-app-id"
multimodel: "qwen-vl-max"

# TTS 配置
tts_supplier: "aliyun"  # 或 "baidu"
oline_tts_model: "cosyvoice-v1"
voice_tone: "zh_CN-female-shaohan"

# ASR 配置
oline_asr_model: "paraformer-realtime-v2"
oline_asr_sample_rate: 16000
local_asr_model: "iic/SenseVoiceSmall"
```

### 地图配置 (map_mapping.yaml)

```yaml
A:
  name: '水果店'
  position:
    x: 1.633
    y: 3.490
    z: 0.0
  orientation:
    x: 0.0
    y: 0.0
    z: 0.618
    w: 0.786
```

## 编译命令

### 1. 进入工作空间

```bash
cd ~/M3Pro_ws
```

### 2. 编译 largemodel 包

```bash
colcon build --packages-select largemodel
```

或编译整个工作空间：

```bash
colcon build
```

### 3. Source 环境

```bash
source install/setup.bash
```

## 启动命令

### 1. 启动完整功能（国内版 + 文字交互模式）

```bash
ros2 launch largemodel largemodel_control.launch.py text_chat_mode:=True
```

### 2. 启动完整功能（国内版 + 语音交互模式）

```bash
ros2 launch largemodel largemodel_control.launch.py text_chat_mode:=False
```

### 3. 仅启动特定节点

```bash
# 启动 ASR 节点
ros2 run largemodel asr

# 启动模型服务节点
ros2 run largemodel model_service

# 启动动作服务节点
ros2 run largemodel action_service
```

### 4. 带参数启动

```bash
ros2 launch largemodel largemodel_control.launch.py \
    text_chat_mode:=True \
    language:=zh \
    regional_setting:=China
```

## 依赖项

### 系统依赖

- ROS2 Humble
- Python 3.8+
- pip

### Python 依赖

```bash
pip install rclpy std_msgs geometry_msgs sensor_msgs nav2_msgs
pip install pyaudio webrtcvad playsound pygame
pip install dashscope openai piper funasr
pip install pyserial cv-bridge pyyaml
```

### ROS2 依赖

- `interfaces` (自定义 action 包)
- `arm_msgs` (机械臂消息)
- `arm_interface` (机械臂接口)
- `M3Pro_demo` (相机和运动学节点)

## 工作流程

```
用户语音 ──▶ ASR 节点 ──▶ Model Service ──▶ Action Service ──▶ 机器人执行
              │              │                 │
              │              │                 ▼
              │              │            动作反馈
              │              │                 │
              ▼              ▼                 ▼
           唤醒成功      双层AI规划      执行完成
           提示音        任务分解        语音播报
```

## 注意事项

1. **串口权限**：确保 `/dev/mic` 串口设备有正确的读写权限
2. **API 密钥**：在 `large_model_interface.yaml` 中配置正确的大模型 API 密钥
3. **地图配置**：根据实际场景修改 `map_mapping.yaml` 中的导航点坐标
4. **资源文件**：确保 `resources_file` 目录下的音频文件存在
5. **多线程执行**：Action Service 使用 6 线程执行器，确保节点稳定运行

## 故障排除

### ASR 节点无法启动

```bash
# 检查串口设备
ls -l /dev/mic

# 添加串口权限
sudo usermod -a -G dialout $USER
```

### 大模型调用失败

```bash
# 检查 API 密钥配置
cat config/large_model_interface.yaml

# 检查网络连接
ping dashscope.aliyuncs.com
```

### 动作执行异常

```bash
# 检查导航点配置
cat config/map_mapping.yaml

# 检查 action 服务是否正常
ros2 node list | grep action_service
```