概述¶

sentino IoT 是面向 AI 语音交互设备的物联网平台，让嵌入式设备（玩偶、故事机、机器人、音箱）能与云端 AI 进行实时语音对话。

商务关系：Sentino 是 Agora 合作伙伴——RTSA / ConvoAI / RTC 等基础设施层的官方推荐解决方案商。

核心能力：AI 实时语音对话、多角色智能体、NFC 角色切换、BLE 一键配网、工作流编排（Function Calling）、AI 设备控制、OTA 远程升级。

硬件接入路径（基于 Agora R1 / BK7258 自定义固件）

Sentino 提供完整的端到端固件示例项目（sentino-jp/sentino-iot-sample，目前 GitHub private）——客户用 BK7258 硬件 → 烧录 Sentino 自定义固件 → 连接 Sentino IoT 平台 → Agora SD-RTN 实时语音对话。

完整链路：

BLE 配网 Web App ──BLE V1──▶ BK7258 设备 ──MQTT──▶ Sentino IoT 云端
                                  │                        │
                                  │◀── Agora RTC 参数 ─────┘
                                  │
                                  ▼
                          Agora SD-RTN（音频通道）
                                  │
                                  ▼
                            AI Agent (ConversationalAI)

仓库结构： - device/ — BK7258 固件工程（集成声网 RTSA Lite SDK，CPU0 跑信令/网络，CPU1 跑 OPUS 编码） - web-app/ — BLE 配网工具：基于 Web Bluetooth API 的浏览器端工具（Chrome），通过 ble-provisioning BLE V1 协议完成 WiFi 配网和设备绑定

用户操作流： 1. 编译并烧录 BK7258 固件（Sentino IoT 模式） 2. 启动配网工具：cd web-app && node server.js，Chrome 打开 http://localhost:3000 完成 BLE 配网 3. 配网成功后，短按开发板 S2 键启动与 AI Agent 的语音对话

关键产品事实（合作伙伴关系的具体落地）：

使用 Sentino IoT 平台接入时，Agora ConvoAI 服务由 Sentino 统一提供，开发者无需单独向声网申请开通。 — 引自 Sentino IoT Sample README

这是 Sentino 是 Agora 合作伙伴的具体商业落地——Sentino 把 Agora ConvoAI 能力封装并代理给客户，客户不需要自己向声网申请 ConvoAI 服务开通，由 Sentino 统一提供。这是 IoT 客户场景下"Sentino 是客户唯一对接方"的重要表述。

Fork 关系（致谢声网/Agora 官方）：本固件示例项目 fork 自 Shengwang-Community/Conversational-AI-IOT-Sample（声网官方 IoT 示例工程）并定制。声网与 Agora 是同一家公司（海外品牌 Agora、国内品牌声网），同一份代码在 GitHub 有两个 mirror：AgoraIO-Community/Conversational-AI-IOT-Sample（海外）与 Shengwang-Community/...（国内）——Sentino 致谢的是中国版仓库，但代码是同源。这意味着 Sentino 不是从零写硬件接入，而是基于声网/Agora 官方推荐路径做产品化包装，印证 sentino-agent 经验教训段"Sentino-Agora 合作 + 竞合"关系——基础设施层走官方代码，应用层叠加 Sentino 自家能力。

当前仓库 private——对外销售/客户对话引用时需先确认是否到了 NDA / 公开阶段。

架构分层： - 设备层：MQTT Client + Agora RTSA Lite C SDK（agora-rtsa-sdk）+ BLE + NFC（可选） - Sentino IoT 平台：MQTT Broker、设备生命周期管理、AI 智能体管理、REST API 网关 - Sentino Agent 平台：LLM 推理调度、TTS 语音合成调度、工作流编排 - Agora 声网：SD-RTN 全球实时音频网络、Conversational AI Engine（ASR + Agent 运行时） - 外部 AI 服务：LLM（GPT/DeepSeek/通义）、TTS（MiniMax/ElevenLabs）

设备有两条通信链路： 1. MQTT（信令通道）：设备 ↔ Sentino，用于认证、状态上报、获取 RTC 参数 2. Agora RTC（音频通道）：设备 ↔ Agora，用于实时语音对话

两条产品路径：IoT 设备路径（MQTT 信令 + 嵌入式 RTC SDK）和 Web 路径（HTTPS + 浏览器 RTC SDK），共享同一套 Agent 平台工作流引擎。

架构定位：面向终端，而非面向开发者¶

Sentino IoT 的 API 是面向终端直接调用的（App/设备 → Sentino 云），而非传统的"给开发者在服务端调用"的模式（开发者后端 → 平台 API）。这是 Tuya 模式，不是 AWS IoT 模式。

证据：REST API 公共请求头（client_id、app_id、package_name、channel_identifier）全部是移动端 App 标识符，不是 server-side API Key。认证方式是 UID（终端用户身份），不是开发者凭证。

核心含义： - Sentino 就是客户的后端——品牌方不需要自建服务端，App 直接调 Sentino 云 - Standalone Agent 是唯一的可编程扩展点——客户没有自己的后端，无法用自定义服务端代码扩展，Agent 替代了本来该由后端完成的自定义逻辑（见 sentino-agent） - Enterprise 模式是架构切换，不只是功能增强——普通用户：终端直调（Sentino 就是后端）；Enterprise：服务端集成（Sentino 是后端的一个组件，通过 Webhook 对接客户系统） - 安全约束——每个 API 请求来自不可信环境（用户手机），API 暴露面需要克制，返回值要假设会被逆向 - 与 Agent 平台的概念割裂（2026-04-29 决策已落地）——IoT 侧的"智能体"是配置绑定单元，Agent 侧的"Agent"是运行时实体。已决策：Agent SaaS 是 agent 核心概念的 source of truth，IoT 平台仅做配置展示（拉 Agent SaaS 数据展示给终端用户 / 设备绑定，不持有 agent 定义、不做 CRUD）。详见 sentino "决策状态" #1。含义：IoT 平台的产品定位收紧——不是与 Agent SaaS 平级的"另一种 agent 平台"，而是 Agent SaaS 的设备接入层 + 终端面向 UI 层

待解决：谁在写调用这些 API 的 App？白标 App / App SDK / 品牌方自己开发？这决定了 DX 投入方向。

关键决策¶

• MQTT 只做信令，不承载音频流——音频走 Agora RTC（UDP），延迟更低
• 设备端极简：只需发一条 MQTT 消息 + 用返回参数加入 RTC 频道
• AI Agent 先于设备就绪：云端先创建 Agent，Agent 在频道内等待，设备进来即可对话
• 自动清理：设备只需离开频道，云端自动检测并清理
• 支持两种联网模式：WiFi（需 BLE 传 WiFi 凭证）和 4G（上电即联网，BLE 仅传绑定信息）
• MQTT 接入点不在固件硬编码——由 APP 蓝牙配网时把 mq (host) + iport (port) 与 WiFi SSID/密码一起下发到设备 Flash。当前实际接入点是 mqtt-iot.sentino.jp:8883（Sentino 自建 MQTT 集群）。这个设计的好处是 APP 端可以根据用户区域、账号路由到不同的 MQTT 集群（国内/海外、生产/测试），固件出厂后不用换。详见 iot-device-bootstrap
• 底层 SDK 已为 4G 形态留好基础设施：rino_iot_sdk/factory_test/factory_dynamic_register.c 是动态注册客户端，当前 WiFi 流程不走它，但纯 4G 形态产品可以直接接入引导服务器路径（方案 B），业务代码零改动。详见 iot-device-bootstrap + embedded-firmware-layering

经验教训¶

• 登录接口也需要携带公共请求头（client_id、channel_identifier 等），否则签发的 Token 无法通过后续验证
• 设备消息 id 必须唯一，重复 ID 会被云端忽略
• 未对接 info 协议的设备无法收到因断电/断网导致的遗留消息
• BLE 单包有效数据最大 118 字节，大 JSON 需分包传输
• 排查"MQTT 连不上"时不要先改固件常量——rino_iot_common.h:10 QCLOUD_IOT_MQTT_DIRECT_DOMAIN 是腾讯云原厂 SDK 留下的常量，当前业务流程不读它；实际接入地址是配网时蓝牙下发到 Flash 的，要清 Flash 重配网才能换 broker
• 后台背景的工程师入门：先读 iot-platform-fundamentals 建立"后台 vs IoT 概念对照"直觉（用户↔设备、JWT↔HMAC、HTTP↔MQTT、数据库 schema↔物模型、OAuth↔配网、Spring DI↔import callback）+ 7 条嵌入式与后台关键差异（重启就解决问题是合法手段、Flash 是唯一持久化、消息队列≈chan 等），再读固件分层 embedded-firmware-layering，最后读具体协议页

对照样本：claude-desktop-buddy（协议优先派）¶

Anthropic 2026-04-20 开源的 claude-desktop-buddy（M5StickC Plus 桌宠 + 225 行 BLE 协议规范）是 sentino-iot-sample 的最强对照样本——同样是"BLE + 设备"参考代码，但完全相反的设计哲学：

→ 两种哲学没有谁对谁错——商业模式决定的（Anthropic 卖模型，开放协议拉硬件生态；Sentino 卖云服务，整链路必须一体）。但 sentino-iot-sample 的 web-app 配网工具可以学 buddy 的 "REFERENCE.md 是契约" 姿态，把 BLE V1 帧 + 状态码 + bind 双信号确认明确写成对外协议文档（已部分做到 raw/snippets/iot-docs/ref-ble.md），让客户能自己 fork 配网工具。详见 claude-desktop-buddy。

关于 sentino-iot-sample 命名¶

正式名 sentino-iot-sample（仓库 sentino-jp/sentino-iot-sample，GitHub private）。本地目录 ~/local/Conversational-AI-IOT-Sample/ 保留旧名，是因为 fork 自 Shengwang-Community/Conversational-AI-IOT-Sample。wiki 与对外材料统一用 sentino-iot-sample。

相关概念¶

• iot-platform-fundamentals — 后台 vs IoT 概念对照 + 7 条嵌入式关键差异（后台背景工程师的入门页）
• embedded-firmware-layering — 业务/适配/SDK/BSP 四层架构 + import/export = Hexagonal
• iot-device-bootstrap — "开机第一个连谁" 5 种方案 + Sentino 4G 形态扩展路径
• mqtt-device-protocol
• ble-provisioning
• agora-rtc-voice
• ai-intelligent-agent
• device-lifecycle
• rest-api-iot
• bk7258-firmware
• agora-convoai-server
• agora-rtsa-sdk — 设备端实际跑的轻量 C SDK；BK7258 + RTSA Lite + ConvoAI 是 Agora 官方推荐组合
• claude-desktop-buddy — Anthropic"协议优先"BLE 参考实现，与 sentino-iot-sample 平台优先派形成对照样本
• sentino-agent