# 跑通 R1 示例 Demo (/zh-CN/ai/device-kit/build/run-r1-demo)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
为了让开发者快速上手，声网与 Wi-Fi 芯片原厂合作，推出了基于博通集成了 BK7258 的开源开发套件 R1。你可以前往体验或查看源码。
本文介绍如何跑通该示例 Demo。
## 项目简介 [#项目简介]
R1 套件由 App 端、BK7258 Device 端、配套 Server 端组成。使用时需要分别参考三个端侧对应的开源工程，分别部署 Server、安装 App 后，与 BK7258 Device 端进行联调。各端之间的关系如下图所示：
## 前提条件 [#前提条件]
- 套件的 Server 端依赖 Python 环境。请确保你的开发环境满足 Python 3.7 及以上版本。
- 套件的 Device 端基于声网与博通 BK 联合开发的 R1 开发板构建。你需要联系 sales@shengwang.cn 购买，并参考 [BK 官方文档](https://docs.bekencorp.com/arminodoc/bk_idk/bk7258/zh_CN/v2.0.1/get-started/index.html)完成开发环境搭建。
- 一台 Android 设备，用于安装并体验套件的 App 端。
- 对话式套件的语音对话功能依赖于第三方大语言模型 (LLM) 和文本转语音 (TTS) 服务实现。因此你还需要获取相关服务供应商的 API Key 和服务地址。
- 一个开启了对话式 AI 引擎的声网项目，并获取了项目的 App ID、App 证书、以及客户 ID 和客户密钥。详见[开通服务](/zh-CN/ai/device-kit/reference/enable-services)。
## 下载示例 Demo [#下载示例-demo]
1. 运行如下命令行，将 `Conversational-AI-IOT-Sample` 克隆到本地。
```shell
$ git clone https://github.com/Shengwang-Community/Conversational-AI-IOT-Sample.git
```
2. 切换到 `bk7258/v2.0.1` 分支。
```shell
$ git checkout bk7258/v2.0.1
```
## 配置 Server 端 [#配置-server-端]
:::warning[注意]
此 Server 端示例仅供开发者快速体验和演示，请勿在生产环境中使用。生产环境的 Server 端服务需要你自行开发。
:::
### 安装 Python 服务组件 [#安装-python-服务组件]
运行如下命令行，安装相关的服务组件：
```shell
$ pip install requests
$ pip install flask
$ pip install pyjwt
```
### 设置配置文件 [#设置配置文件]
`/server/aiot_server_demo_example/config.json` 是一个标准 `JSON` 格式的配置文件。你需要在该文件中设置定制的服务参数。更多详细参数配置可以参考[创建对话式智能体 RESTful API](/zh-CN/api-reference/api-ref/conversational-ai/join)。
```json
{
// 声网相关配置
// 声网项目的 App ID
"app_id": "YOUR_AGORA_APP_ID",
// 声网项目的 App 证书
"app_certificate": "YOUR_AGORA_APP_CERTIFICATE",
// 客户认证信息
// 客户 ID
"customer_key": "YOUR_CUSTOMER_KEY",
// 客户密钥
"customer_secret": "YOUR_CUSTOMER_SECRET",
// 语音识别 (ASR) 配置
"asr": {
// 识别语言，默认中文，（支持中英文混合）
"language": "zh-CN"
},
// 系统参数配置
"parameters": {
// RTC 发流音频编码格式，支持格式："PCMU"、"PCMA"、"G722"、"OPUS"、"OPUSFB"
"output_audio_codec": "PCMA"
},
// 语音合成 (TTS) 配置
"tts": {
// TTS 服务提供商
"vendor": "YOUR_TTS_VENDOR",
"params": {
}
},
// 会话超时配置
// 会话超时时间（秒）
"idle_timeout": 30,
// 大语言模型 (LLM) 配置
"llm": {
// LLM 服务地址
"url": "YOUR_LLM_API_URL",
"params": {
// 使用的模型
"model": "YOUR_LLM_MODEL"
},
// LLM 服务 API Key
"api_key": "YOUR_LLM_API_KEY",
// 系统预设消息
"system_messages": [
{
"role": "system",
"content": "You are a helpful chatbot."
}
],
// 最大历史记录数
"max_history": 10,
// 欢迎语
"greeting_message": "你好，我是小爱，有什么可以帮助你的吗？",
// 失败提示
"failure_message": "抱歉，我暂时无法回答您的问题..."
}
}
```
### 运行服务 [#运行服务]
在 `server/aiot_server_demo_example` 路径下，通过如下命令行运行服务：
```shell
$ python3 main.py
```
Server 端服务默认运行在你本地的 `5001` 端口，即 `http://localhost:5001`。你可以根据实际业务需求修改代码设置端口号。
:::info[信息]
Server 端共提供 3 个 RESTful API 为设备端运行提供业务支持，详见 [Server 端接口文档](#server-端接口文档)。
:::
## App 端配网 [#app-端配网]
R1 套件的 `app` 文件夹提供了一个 Android 端的蓝牙低功耗设备配网 App，可以通过蓝牙连接智能设备、配置 Wi-Fi 网络连接。
该 App 基于我们的蓝牙配网库开发，提供了一个简单直观的用户界面。完成安装后，App 界面如下图所示：
本节介绍如何在 App 端操作实现设备配网。
### 配网流程 [#配网流程]
完整的设备配网流程如下：
1. 申请并获取必要权限；
2. 获取当前 Wi-Fi 信息；
3. 输入 Wi-Fi 密码；
4. 扫描并找到目标蓝牙设备；
5. 点击**建立连接**按钮连接设备；
6. 连接成功后，点击**配置网络**按钮将 Wi-Fi 信息发送给设备；
7. 配网完成后，点击**断开连接**按钮断开与设备的连接。
### 操作步骤 [#操作步骤]
:::warning[注意]
开始配网操作前，请确保：
- 你的 Android 设备已开启蓝牙和位置服务。
- 目标智能设备处于可发现模式。
- 配网过程中保持手机与智能设备的距离不超过 5 米。
- 提前在手机设置界面中连接 2.4G 类型的 Wi-Fi，并保证该 Wi-Fi 可以正常访问互联网，否则会配网失败。
- 对于 Android 12 及以上的设备，需要特别注意授予 `BLUETOOTH_SCAN` 和 `BLUETOOTH_CONNECT` 的权限。
:::
1. 申请权限。首次使用 App 时，需要获取必要的权限：
1. 点击**申请权限**按钮，App 会请求蓝牙和位置权限。这些权限对于蓝牙设备的扫描和连接是必需的。
2. 在系统弹出的权限请求对话框中选择**允许**。
2. 检查 Wi-Fi 权限。点击**检查 Wi-Fi 权限**按钮，App 会检查是否已获取 Wi-Fi 相关权限：
- 如果已获取，会显示**已获取 Wi-Fi 权限**的提示
- 如果未获取，会显示**未获取 Wi-Fi 权限**的提示
3. 获取当前 Wi-Fi 信息。点击**获取当前 Wi-Fi 信息**按钮，App 会获取并显示当前连接的 Wi-Fi 网络名称 (SSID)。获取的 Wi-Fi 信息将显示在按钮下方的卡片中。
4. 输入 Wi-Fi 密码。在**Wi-Fi 密码**输入框中输入当前 Wi-Fi 网络的密码，这个密码用于将智能设备连接到你的 Wi-Fi 网络。
5. 扫描蓝牙设备
1. 点击**开始扫描**按钮，App 会开始扫描周围蓝牙设备。扫描过程中，按钮文字会变为**停止扫描**。
2. 扫描到的设备会显示在下方的列表中。
3. 再次点击**开始扫描**按钮可停止扫描。
6. 连接设备。在设备列表中，每个设备卡片包含以下信息和操作：
- 设备名称
- MAC 地址
- 信号强度 (RSSI)
- **建立连接**按钮：点击此按钮与选中的设备建立蓝牙连接
- **配置网络**按钮：点击此按钮将之前输入的 Wi-Fi 信息发送给设备，帮助设备连接到 Wi-Fi 网络
- **断开连接**按钮：点击此按钮断开与设备的蓝牙连接
如果配网失败，请尝试重新连接设备或重启 App。
### 配网常见问题故障排除 [#配网常见问题故障排除]
- 如果 App 无法扫描到设备，请检查蓝牙和位置服务是否已开启。
- 如果连接设备失败，请尝试重新扫描或重启智能设备。
- 如果配网失败，请确认 Wi-Fi 密码是否正确输入。
## 跑通 Device 端 [#跑通-device-端]
本节步骤以 Ubuntu 18.04 操作系统为例。
### 硬件要求 [#硬件要求]
R1 套件基于声网与博通 BK 联合开发的 R1 开发板构建。相关硬件功能模块如下图所示：
### 下载并配置工程 [#下载并配置工程]
:::info[信息]
本示例工程支持 bk_aidk branch ai_release/v[2.0.1] 及之后版本。示例工程默认使用 tag ai_release/v[2.0.1.2] (commit id: 3cb4544aa5cdc66ad0b4ccf3175beae152dee6c8)。
:::
1. 运行如下命令行，从 GitHub 获取 `bk_aidk` 工程：
```shell
$ git clone --recurse-submodules https://github.com/bekencorp/bk_aidk.git -b ai_release/v2.0.1
$ git checkout ai_release/v2.0.1.8
$ git submodule update --recursive
```
2. 将示例 Demo 的 `projects` 目录复制到 `bk_aidk` 工程并完全替换的 `projects` 目录（建议先删除 BK 官方 `projects` 目录后录制）：
```shell
$ rm -rf ${bk_aidk路径}/projects/
$ cp -r ./projects ${bk_aidk路径}/projects
```
3. 修改配置文件 `projects/common_components/network_transfer/agora_rtc/agora_config.h`，将 Server URL 设置为你自己部署的服务器地址，如：
```shell
define CONFIG_AGENT_SERVER_URL "http://192.168.1.100:5001"
```
### 编译固件 [#编译固件]
在 `bk_aidk` 目录下，运行如下命令行构建示例项目固件：
```shell
$ cd ${bk_aidk路径}
$ make bk7258 PROJECT=beken_genie
```
### 烧录固件 [#烧录固件]
固件构建完毕后，参考 [BK 官方说明](https://docs.bekencorp.com/arminodoc/bk_idk/bk7258/zh_CN/v2.0.1/developer-guide/config_tools/bk_tool_bkfil.html) 使用烧录程序下载固件。
### 运行示例 Demo [#运行示例-demo]
使用 Type-C 数据线接入开发板的 `USB TO UART` 接口，并与电脑连接。参考如下步骤运行示例：
1. 如果还未给开发板设置 Wi-Fi 账号及密码，长按 `S1` 按键 5 秒，进入配网模式，然后和配套的 App 完成配网。
2. 配网成功后，你可以短按 `S2` 唤醒设备，启动和 AI Agent 的通话。
3. 对话完毕后，你可以再次短按 `S2` 退出和 AI Agent 的通话。
4. 开发板在静默状态 3 分钟后自动进入深度休眠状态，你可以通过 `RST` 按键重启运行。
:::info[信息]
- 开发板的 `USB TO UART` 接口可同时用于电池充电。开发板插入电池或数据线后会自动启用。
- 当烧录工具无法自动重启开发板时，可以使用 `RST` 按键手动重启恢复烧录能力。
:::
## 参考信息 [#参考信息]
### Server 端接口文档 [#server-端接口文档]
Server 端共提供 3 个 RESTful API 为设备端运行提供业务支持。本节对这 3 个接口进行简要介绍。
- 基础 URL 路径：`https://your-domain.com/`
- 鉴权方式：本示例项目 Server 端未实现鉴权相关功能。你可以根据需要自行实现：
```shell
Authorization: None
```
#### 获取设备 RTC 相关参数 [#获取设备-rtc-相关参数]
- 方法类型：POST
- 接入点：`/device`
- 请求 Body 示例：
```json
{
"channel_name": "DEVICE_ID",
"uid": DEVICE_USER_ID
}
```
#### 启动对话式 AI 引擎服务 [#启动对话式-ai-引擎服务]
- 方法类型：POST
- 接入点：`/agent/start`
- 请求 Body 示例：
```json
{
"channel_name": "DEVICE_ID",
"uid": DEVICE_USER_ID,
"agent_uid": AGENT_USER_ID
}
```
#### 停止对话式 AI 引擎服务 [#停止对话式-ai-引擎服务]
- 方法类型：POST
- 接入点：`/agent/stop`
- 请求 Body 示例：
```json
{
"agent_id": "AGENT_ID"
}
```