【新人分享】智能语音助手（二）：嵌入式端开发，从按一下按键到说出第一句话

TL_PENGCHENG · 发表于昨天 19:58

## 0. 先说说我是谁

嵌入式新人，C 语言能写但不算熟。这一篇讲**板子这一端**我做了什么：按键、录音、Opus 编码、收数据、播放。

设备端工程基于 **tl_arduino_wifi_sdk**，就是标准 Arduino 的 `setup()` + `loop()` 写法，核心代码直接贴在下面，新手向，写得比较直白，请多包涵。

## 1. 这一端要做的事

用一句话说：**我按住按键说话，松手，板子把音频发给服务器；服务器回音频，板子播出来。**

拆成四件事：

1. 连 WiFi、连服务器的 WebSocket。
2. 按键按下开始录音，编码后一帧帧发出去。
3. 收到服务器的数据，解析 → Opus 解码 → 送喇叭。
4. 两个按键调音量。

## 2. 技术选型

- **SDK**：tl_arduino_wifi_sdk（Arduino IDE 直接安装），`setup()` + `loop()` 组织逻辑。
- **音频编码**：Opus（SDK 自带 `opus_encode` / `opus_decode` 接口）。
- **传输**：WebSocket，连接时带自定义 header 做鉴权。
- **缓冲**：环形缓冲区（ring buffer），一边收一边播必须靠它。

**放弃的方案**：一开始想用裸 TCP，但自己从零实现 WebSocket 握手太麻烦，SDK 里现成的 `websocket_begin` 直接用了。

## 3. 动手过程

### 3.1 环境准备

1. 安装 Arduino IDE；
2. 按官方 Getting Started 安装 tl_arduino_wifi_sdk：[https://doc.telink-semi.cn/doc/en/software/res/sdk/arduino/tl_arduino_wifi_sdk/getting_started/tl_arduino_wifi_sdk_getting_started_en/](https://doc.telink-semi.cn/doc/en/software/res/sdk/arduino/tl_arduino_wifi_sdk/getting_started/tl_arduino_wifi_sdk_getting_started_en/)；
3. 开发板选 **AIOT-DK2**（芯片 TLSR9118）；
4. 新建工程，先把 WiFi 和服务器信息改成自己的（示例里都是占位值，**别把真实密钥提交到仓库**）：

```c
#define AP_SSID                  "your_ssid"
#define AP_PASSWD                "your_password"
#define ASSISTANT_SERVER_IP      "xxx.xxx.xxx.xxx"
#define ASSISTANT_SERVER_PORT    4567
#define ASSITANT_PATH            "/ino"
#define ASSISTANT_USER_NAME      "your_user_name"
#define ASSISTANT_API_KEY        "your_api_key"
```

然后是 `setup()`，按顺序把底层都拉起来：

```c
void setup(void)
{
    log_i("hello assistant demo!");
    async_init();                                       // 异步任务框架
    coprocessor_begin();                                // 协处理器（WiFi）就绪
    wifi_sta_begin(AP_SSID, AP_PASSWD, 10000);          // 连 WiFi，超时 10s
    audio_begin();                                      // 音频子系统

// 三个按键：录音 / 音量+ / 音量-
    btn_ctx.pin = 4;        btn_ctx.on_down = btn_on_down;      btn_ctx.on_up = btn_on_up;   btn_init(&btn_ctx);
    btn_add_ctx.pin = 5;    btn_add_ctx.on_down = btn_add_on_down;                              btn_init(&btn_add_ctx);
    btn_reduce_ctx.pin = 6; btn_reduce_ctx.on_down = btn_reduce_on_down;                         btn_init(&btn_reduce_ctx);

// 播放用的 Opus 缓存
    opus_buffer = ring_buffer_create(4096);

// 流控解析器：缓存 1024 字节，最多注册 8 个标签
    sc_handle = sc_create(1024, TAG_NUM_DEFAULT);

sc_register(sc_handle, TAG_OPS, NULL,         on_OPS_recv, NULL);
    sc_register(sc_handle, TAG_TXT, on_TXT_begin, on_TXT_recv, on_TXT_end);
    sc_register(sc_handle, TAG_PLY, on_PLY_begin, NULL, NULL);
    sc_register(sc_handle, TAG_STP, on_STP_begin, NULL, NULL);
    sc_register(sc_handle, TAG_END, NULL, NULL, NULL);

async_register(stream_handle_loop, NULL, true, 4096);   // 起一个 4K 栈的异步任务收数据

websocket_context.server_ip   = ASSISTANT_SERVER_IP;
    websocket_context.server_port = ASSISTANT_SERVER_PORT;
    websocket_context.headers     = "user: " ASSISTANT_USER_NAME "\r\napiKey: " ASSISTANT_API_KEY "\r\n";
    websocket_context.path        = ASSITANT_PATH;
    websocket_context.buffer_size = 1024;
    websocket_begin(&websocket_context);
}
```

> `SAMPLE_RATE` / `SAMPLES_PER_FRAME` / `OPUS_BITRATE` / `AUDIO_MAX_LEN` 这些宏在 SDK 的其他头文件里，和服务器端约定的采样率是 16kHz / 单声道 / 每帧 20ms，具体取值见【待确认】。

### 3.2 录音：按键控制 + 边录边编码边发

按键回调只改状态，真正的活儿放在主循环里干：

```c
void btn_on_down(void) {
    audio_start_record(AUDIO_MAX_LEN);
    audio_stop_play();                  // 边播边录会互相干扰，先停播放
    record_context.state = RECORD_START;
    record_context.frameCnt = 0;
}

void btn_on_up(void) {
    audio_stop_record();
    record_context.state = RECORD_END;  // 注意：不是直接结束，还要把剩余数据发完
}
```

主循环里的 `record_handle_loop()` 是一个小状态机：

```c
void record_handle_loop(void) {
    if (record_context.state == RECORD_SND_DATA || record_context.state == RECORD_END) {
        do {
            record_len = audio_read_record_async(pcm_buffer, sizeof(pcm_buffer));
            record_len = dualTomono(pcm_buffer, record_len);     // 双声道 → 单声道
            opus_encode(pcm_buffer, record_len, opus_enc_buffer, sizeof(opus_enc_buffer), &out_len);

uint8_t packet_len = out_len;                        // 帧长用 1 字节表示
            websocket_write(&websocket_context, &packet_len, 1, -1);
            websocket_write(&websocket_context, opus_enc_buffer, out_len, -1);
        } while(0);

if (record_context.state == RECORD_END) {                // 剩余数据发完了才发结束标签
            websocket_write(&websocket_context, (uint8_t *)TAG_END, TAG_LENGTH, -1);
            record_context.state = RECORD_IDLE;
        }
    } else if (record_context.state == RECORD_START) {
        websocket_write(&websocket_context, (uint8_t *)TAG_RST, TAG_LENGTH, -1);  // 先重置对端
        websocket_write(&websocket_context, (uint8_t *)TAG_OPS, TAG_LENGTH, -1);  // 声明：下面是 Opus 流
        record_context.state = RECORD_SND_DATA;
        opus_encode_init(SAMPLE_RATE, SAMPLES_PER_FRAME, OPUS_BITRATE);
    }
}
```

几个我后来才想明白的点：

- **`RECORD_END` 不等于立刻结束**。松手时缓存里可能还有没编码的音频，必须发干净再发 `<END`，否则最后半句话会被吃掉。
- **`<RST` 要发在整个流的最前面**，用来告诉服务器「上一次的残留全清掉，重新开始」。
- 这里用 `do { } while(0)` 包着，其实就是**每轮只处理一帧**，靠 `loop()` 高频轮询。我一开始写成 `while` 想一次发完，结果把主循环堵死了。

### 3.3 接收与播放

收数据的任务很小，就是把 WebSocket 的字节丢进流控解析器（`stream_controller`，第三篇专门讲它）：

```c
void stream_handle_loop(void *para) {
    uint8_t buffer[512];
    while (websocket_available(&websocket_context) > 0) {
        uint32_t rwLen = sc_free_size(sc_handle);            // 先问问解析器还能吃多少
        if (rwLen == 0) break;                               // 满了就别读了，别把数据丢了
        rwLen = websocket_read(&websocket_context, buffer, min(rwLen, sizeof(buffer)), 0);
        if (rwLen == 0) break;
        sc_input(sc_handle, buffer, rwLen);
    }
    sc_handle_loop(sc_handle);                                // 解析 + 触发回调
}
```

这里有个**反压（back pressure）** 的小设计：`sc_free_size()` 返回缓存剩余空间，满了就停止读取，等解析器消费掉再读。

播放则是由回调触发状态、在主循环里取数据：

```c
static void on_PLY_begin(void) {          // 服务器说：要开始播了
    ring_buffer_clear(opus_buffer);
    opus_decode_init(SAMPLE_RATE, SAMPLES_PER_FRAME);
    audio_start_play(AUDIO_MAX_LEN);
}

static size_t on_OPS_recv(void *data, size_t len) {
    if (record_context.state == RECORD_IDLE) {   // 只在没录音时接收，避免播到自己录的音
        return ring_buffer_push(opus_buffer, data, len);
    }
    return len;
}
```

真正的解码播放：

```c
size_t opus_packet_len = buffer[0];                     // 第 1 个字节 = 帧长度，和上行格式一致
if ((ring_buffer_available(opus_buffer) >= opus_packet_len + 1) &&
    (audio_play_free_size() >= sizeof(pcm_buffer))) {
    ring_buffer_pop(opus_buffer, 1);                    // 先弹出长度字节
    ring_buffer_copy(opus_buffer, buffer + 1, opus_packet_len);   // 注意：copy 不弹出
    size_t outLen = 0;
    if (opus_decode(buffer + 1, opus_packet_len, pcm_buffer, sizeof(pcm_buffer), &outLen)) {
        audio_pcm_volume(pcm_buffer, outLen, volume);            // 软件调音量
        size_t rwLen = monoTodual(pcm_buffer, outLen, sizeof(pcm_buffer));  // 单声道 → 双声道
        audio_play_async(pcm_buffer, rwLen);
    } else {
        log_e("Opus.decode failed");
    }
    ring_buffer_pop(opus_buffer, opus_packet_len);
}
```

下行的数据包和上行完全一样，就是最朴素的「长度 + 数据」：

```
┌────────┬─────────────┐
│  长度   │  Opus 数据   │
└────────┴─────────────┘
 （1 字节） （最多 255 字节）
```

## 4. 踩过的坑

| 坑                              | 现象                                               | 原因                                              | 怎么解决的                                                          |
| ------------------------------- | -------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| 麦克风是双声道，Opus 是单声道   | 编码出来声音变调、时长不对                         | 直接拿双声道 PCM 去编码，数据量翻倍还错位         | 录之前`dualTomono` 降声道，播之前 `monoTodual` 升回双声道           |
| 播放死活不出声                  | 日志显示解码成功，但没声音                         | 解码了却没等播放缓冲区有空间，数据被丢掉          | 加`audio_play_free_size() >= sizeof(pcm_buffer)` 判断，不够就不解码 |
| `ring_buffer_copy` 之后数据还在 | 同一帧被反复播放                                   | 以为`copy` 会弹出数据，其实只是拷贝               | 校验通过后手动`ring_buffer_pop`                                     |
| 一旦串流就全乱                  | 错读一个长度字节，后面每帧的边界都跟着错，越错越远 | 「长度 + 数据」没有帧头和校验，错位后无法重新对齐 | 目前靠`<RST` 整段重来恢复；要不要加帧头/校验见「求指点」            |
| 播放时又按了录音键              | 喇叭里的声音被录进去                               | 录音和播放同时在跑                                | 录音开始时`audio_stop_play()`，且录音期间下行数据直接丢弃           |
| 松手后最后一句被吞              | 说的最后一个字听不到                               | 松手就立刻发`<END`，缓存里的音频没发完            | `RECORD_END` 状态下继续发，发空后再发 `<END`                        |

## 5. 还没做好 / 下一步

- **已知问题**：
  - 帧长用 1 字节，Opus 帧超过 255 字节就得拆，目前没做保护。
  - 音量是软件乘法（`audio_pcm_volume`），只影响播放，跟系统音量无关。
  - 只支持一个 WebSocket 连接，断了不会自动重连。
  - 采样率、帧长等宏散落在 SDK 头文件里，跟服务器端需要人工对齐。
- **想做的方向**：
  - [ ]  加断线重连
  - [ ]  加录音过程中的本地 VAD（静音自动停止）
  - [ ]  试试硬件音量控制

## 6. 求指点

1. 「按键回调只改状态、实际处理放主循环」这种做法对不对？在这种带任务调度器的环境里是不是应该直接用任务和队列？
2. `stream_handle_loop` 每次只调用一次 `sc_handle_loop`，是不是应该循环处理到缓存空为止？我担心那样会饿死别的任务。
3. Opus 帧长度超过 255 字节时应该怎么处理比较好？有没有推荐的封装方式？
4. 上下行统一「1 字节长度 + 数据」后没有任何帧头和校验，错位后很难自愈。这种简化在 WebSocket（底层 TCP 已可靠）的场景下可以接受吗？还是应该加 0xAA/0x55 + 校验和？

先谢过各位前辈！