硬件接入

把实体硬件接进 NovaMeow,有三条路,按你的技术程度选:

你是…怎么接看哪节
有技术看 API 文档,自己写固件接入一、API 自接
没技术,买了我们的成品插上电脑,网页串口配置一下就好配置我买的设备
想要自己的硬件组合网页选硬件 → 生成固件 → 烧录定制我的固件

下面是给固件开发者的接入规范(第一条路 + 让自研固件兼容我们的配置器)。

一、API 自接(技术向)

设备只要能联网,就能用三组 HTTP 接口跑起来:激活拿 key → 对话 / 语音 → 心跳。

1. 设备激活(拿到设备专属 key)

设备不自注册。流程是:你(或用户)先在控制台 / 用租户 key 注册一台设备,拿到一次性激活码;设备开机后凭码换它自己的 key。

text
① 注册(控制台「设备」或 Bearer 租户通用 key):
   POST /v1/devices  { "name": "客厅的喵伴", "app_id": "可选" }
   → 201 { "id", "activation_code": "16位", "code_expires_at": "15分钟后" }

② 设备凭码换 key(无需鉴权,码即凭证):
   POST /v1/devices/activate  { "code": "16位激活码" }
   → 200 { "device_id", "key": "sk-meow-…", "app_id" }
       ↑ 明文 key 只回这一次,设备务必立刻存进 NVS / 安全存储

   失败:401(码不存在/过期)· 410(码已用过)· 429(同 IP 太频繁)

激活码 80 位熵 + 15 分钟有效 + 只存哈希 + 一次性(用过即作废)。丢了 key 就在控制台「重发码」重新配对(旧 key 立即失效)。

2. 对话 / 语音(用设备 key)

text
对话(SSE 流式):  POST /v1/agent   Authorization: Bearer sk-meow-…   { "text": "你好" }
语音闭环(音频进→音频出):POST /v1/voice  Authorization: Bearer …   (音频体)

设备绑了应用(app_id)的话,说话即该应用的人设 / 模型 / 知识库配置;否则走租户默认。详见 Agent API 与 语音。

3. 心跳(可选,报在线 + 固件版本)

text
POST /v1/devices/heartbeat   Authorization: Bearer sk-meow-…
   { "firmware": "1.0.0", "hw_model": "atoms3r" }

每次 /v1/agent 调用也会自动刷新「最后在线」,控制台据此显示绿点(5 分钟内有动静 = 在线)。

设备需要持有什么

项哪来存哪
cloud host固定 api.cloud.novameow.ai固件 / NVS
WiFi 账号密码用户配NVS(别硬编码)
设备 key激活换来NVS / 安全存储(明文只回显一次)
人设 / 模型云端按设备绑定的应用下发不用存

参考固件骨架(伪码)

c
// 开机
load_nvs(&wifi, &key, &host, &profile);
if (!key) enter_provisioning_mode();   // 没 key → 进「待配置」,监听串口(见下)
wifi_connect(wifi.ssid, wifi.pass);

// 激活(仅当还没 key 时,凭用户给的 code)
if (have_code && !key) {
    key = http_post(host "/v1/devices/activate", {"code": code}).key;
    nvs_save("device_key", key);
}

// 对话循环
on_button_or_wakeword() {
    audio = record();
    // 走语音闭环:音频进 → asr→agent→tts → 音频出
    reply_audio = http_post(host "/v1/voice", audio, "Bearer " key);
    play(reply_audio);
}

二、串口配置协议(让自研固件兼容我们的网页配置器)

我们的网页配置器通过 Web Serial 直连设备,帮没技术的用户填 WiFi + 自动激活。你的固件只要实现这个简单协议,就能被它配置。

载体:USB CDC 串口,行式 JSON(每条命令 / 回应一行,\n 结尾),115200 波特。

方向消息说明
网页 → 设备{"cmd":"hello"}握手。设备回 {"model","firmware","configured"}
网页 → 设备{"cmd":"wifiscan"}(可选)设备扫周边 WiFi,回 {"networks":["…"]}
网页 → 设备{"cmd":"provision","ssid","pass","host","code"}配网 + 激活
设备 → 网页{"status":"ok","device_id":"…"}联网 + 激活成功
设备 → 网页{"status":"err","error":"…"}失败(WiFi / 激活)
网页 → 设备{"cmd":"reset"}清 NVS 配置,回「待配置」态

provision 后设备要做的:① 用收到的 ssid/pass 连 WiFi → ② POST https://{host}/v1/devices/activate {code} 换 key → ③ key 存 NVS → ④ 串口回 {"status":"ok","device_id"}。任一步失败回 {"status":"err","error":"原因"}。

三、hw_profile(硬件描述,运行时配置)

固件定制器生成的「硬件配置」就是一份 hw_profile JSON,写进设备 NVS;通用固件开机按它初始化对应外设(无需为每种硬件组合单独编译)。schema:

json
{
  "variant": "atoms3r",            // 主控变体
  "mcu": "esp32-s3",
  "display":  { "driver": "m5-builtin", "res": "128x128" },
  "mic":      { "driver": "es8311", "pins": { "i2c_sda": 38, "i2c_scl": 39 } },
  "speaker":  { "driver": "es8311" },
  "buttons":  [ { "gpio": 41, "label": "main" } ],
  "extra_gpio": [],
  "ui":       { "vol": 200, "bri": 160, "voice": 0 }
}

可选的主控 / 屏 / 麦 / 扬 / 引脚清单(单一真源)由 GET /console/firmware/catalog 给出 —— 定制器即据此渲染选项。

现状:云侧(激活接口、配置器、定制器、catalog、串口协议规范)已就绪;通用固件二进制与固件侧串口协议实现在端侧固件仓推进中。自研固件按上面三节即可完整接入。