生成的智能灯首次配网场景,非实机测试证据

涂鸦 App 首次配网验收:把失败定位到具体阶段

涂鸦设备被发现、联网和首次控制是不同的验收结果。沿Android App配网链路核对权限、家庭、token、回调与结果回查,设计可恢复的首次使用流程。

“添加成功”之后,客户点亮的仍然只是手机上的开关。这时继续延长配网倒计时,通常找错了修复位置:设备可能已经建立绑定,缺的是面板初始化、状态同步,或者第一次控制的结果确认。

涂鸦 App 的首次配网验收应沿着“可发现、可建立关系、可联网、可完成约定操作”逐步取证。在哪一步丢失证据,就从哪一步恢复;没有得到结果时,保留未知状态,而不是立刻删除设备重来。这是一套验收设计,不是声称 SDK 已提供同名状态机。

以下限定 Android SmartLife App SDK 的 Wi-Fi 与蓝牙双模设备路径,依据截至 2026 年 11 月 18 日可读的官方资料。版本核对锚点为 Android Changelog 的 v7.11.0 条目,不把条目存在当作已安装或已验证兼容;没有做 SDK 编译、BizBundle 集成或真实设备测试。Matter、纯蓝牙产品和网关子设备需要各自的流程,不能直接套用本文的云端验收终点。

失败发生在哪一条边上

把“设备没添加上”拆开,首先是为了决定下一步该由谁处理。搜索列表为空,应该看手机权限、设备是否广播以及发现路径;已有设备对象但打不开面板,继续改 Wi-Fi 密码就缺少依据。负责 App、固件和交付的人需要能指向同一个阶段,才能避免各自拿一张成功截图互相证明。

对一款承诺远程控制的双模灯,发现广播只证明手机看到了候选设备;向设备交付联网信息不证明它已经接入云端;拿到设备对象也不证明约定的数据点能够工作。验收终点来自产品承诺。如果交付要求包括离开现场后仍能操作,就要单独核查远程路径,不能用手机近场蓝牙控制替代。

这条链并非所有产品都严格线性执行。有的步骤由 SDK 内部完成,有的产品支持本地激活。App 没有收到某个中间事件时,应记录“未观察到”,而不是推断它必然没有发生。可以建立业务阶段,但不能为了画一条漂亮的进度条而虚构设备已经取得地址、通过认证或完成绑定。

一个有用的失败页应该保留已知信息。例如“已发现设备,尚未取得云激活结果”能够指引下一次检查;“请确认设备正常后重试”只把诊断责任交还给客户。向客户展示的状态可以简洁,内部仍要保留事件来源、时间和当次尝试标识,以便区分没有回调与明确拒绝。

留下一份能复现的首次使用基线

手机、路由器与灯组成的首次配网测试台示意

生成场景示意,不是涂鸦界面截图,也不代表这组设备已经完成配网或控制验收。

在开始测试前,把 App 构建号、SDK 依赖解析结果、Android 系统版本、targetSdk、设备型号、产品标识、固件版本以及所用配网入口绑定成一个基线。只写“最新版 SDK”不够:更换一个 BizBundle 或手机系统后,即使页面长得一样,也可能已经不是同一条交付路径。

版本号应来自实际工程依赖和设备信息,不能从文档更新时间反推。官方更新日志可以用于找升级线索,却不能证明你手里的安装包采用了该版本。若尚未接入项目,记录“待项目填入”比抄一个看起来新的版本号更有用;本文也是公开接口核对,不提供经过编译的版本组合。

初次验收用什么账户和家庭,也应与生产使用一致。拿研发人员已经建好家庭、授予全部权限的手机演示,很容易漏掉新用户登录后没有可用家庭、权限第一次被拒绝、设备已经被别的账户占用等入口条件。这里验收的是首次使用,不是已调通手机的第二十次演示。

测试设备必须明确允许恢复网络或重新绑定。已经承载客户自动化的灯、锁或网关,不应因为一个失败提示就被当作可反复重置的样机。重置会改变后续复现条件,还可能抹掉原本能帮助定位问题的关系和状态;先保留现场,再决定是否需要破坏性恢复。

这份基线也能约束缺陷修复范围。如果只改了 Android 权限请求,回归重点应包括拒绝后再授权、返回页面和重新扫描;若同时升级固件并更换路由器,就不能把好转归因于权限修复。一次改变一个有依据的变量,比不断收集“这次好了”的结果更容易决定修复是否可以交付。

搜不到设备时,别急着让客户重启路由器

系统允许,不等于当前扫描路径可用

先核对蓝牙开关、运行时授权和目标 Android 版本对应的权限行为。Android 12 及以上目标版本涉及 BLUETOOTH_SCAN、BLUETOOTH_CONNECT 等运行时权限;Manifest 中写了声明不代表用户已经允许。Google 还说明,声明 neverForLocation 会过滤部分 BLE 信标,不能把这个标记当作没有影响的默认优化。具体条件见 Android 蓝牙权限文档。

平台允许的最小权限与某一 SDK 扫描实现的前置条件应一起核对,不能只复制其中一份示例。Tuya 蓝牙设备文档要求扫描前检查权限与开关,并指出相关预检查需要由应用处理。不要据此让所有 Android 版本统一弹同一套权限,也不要因为新系统出现“附近设备”授权就直接删掉 SDK 仍要求的检查。

空列表需要一个可解释的退出方向

用户拒绝授权时,失败页应说明缺少哪项能力,并给出继续授权或取消的选择。取消不是设备故障,不应启动重试计数;返回系统设置后,也要重新检查实际状态,再开始一个新的发现动作。重复展示一个已经失效的权限弹窗,不会增加任何诊断证据。

设备端则应确认所选产品是否真的处于对应配网模式。灯在闪并不是足够精确的协议描述;产品说明、固件状态和 App 选择的入口要对应。不要把其他模组的复位次数照搬到当前产品,更不要在没有产品依据时指导客户不断断电。发现阶段就能排除的问题,没有必要升级成路由器兼容性故障。

联网失败要保留原始返回,也要知道它来自哪里

获取配网 token 前,先确认当前会话与目标家庭。Tuya 的 Wi-Fi EZ 配网文档说明 token 有效期为十分钟,设备完成配网后立即失效,再次配网需要新 token。这个时间不能拿来当作整个产品的统一超时,更不意味着每一次重试都可以复用上次缓存。

同一页面停留很久后才点击开始,或切换账户、家庭后继续使用旧参数,都会让“当前用户想做什么”和“任务实际使用什么”脱节。建议在启动尝试时重新核对主体与家庭,按接口要求获取有效输入。token 本身不要写进客服截图或普通日志;保留签发时间与脱敏关联标识即可判断是否复用了过期上下文。

收到错误时,记录 SDK 入口、回调类型、原始错误码、脱敏消息和发生阶段,再把它映射成面向客户的说明。不能只保存一个经过翻译的“连接失败”,也不应把同一个数字在不同 SDK、协议或固件中的含义强行统一。错误码表是具体入口的合同,不是所有产品通用的故障字典。

在所引用的蓝牙双模文档中,207211 指向路由器密码错误,207213 指向 DHCP 地址获取失败,207206 表示设备状态未知。前两者给出了不同检查方向,第三个则没有提供足以直接删除设备的结论。此处只是对应文档的示例,不保证目标固件一定返回这些细分信息。

检查 Wi-Fi 时应以目标模组支持能力为准,不把所有 Tuya 产品都写成只能使用某个频段。路由器找不到、认证失败和获取地址失败也不应合并处理:在密码没有变化时反复要求输入,只会增加操作负担;已有明确地址分配失败线索时,更应保留网络配置和时间窗口供网络侧核查。

一次尝试结束后,谁还在写页面

页面生命周期与设备结果要分开

建议为每次配网分配应用自己的 attempt_id,并记录设备候选标识、家庭、入口和启动时间。它用于关联本次 UI 与本次任务,不是 Tuya 已存在的请求字段。客户退出页面、切换设备或重新开始后,旧回调仍可能到达;如果不核对尝试归属,上一台设备的迟到结果就可能把当前页面改成成功。

取消时调用对应入口的停止、释放方法,并关闭本次页面对结果的写入通道。EZ 文档给出的生命周期包含 start()、stop()、onDestroy();蓝牙双模有各自接口,不能照搬方法名。业务取消也不等于云端绑定已回滚,退出页面后仍需保留足以回查的最小任务记录。

避免把“有回调”与“可更新当前页面”绑定在一起。回调先进入任务记录,确认属于当前尝试后再驱动 UI;旧任务的结果可以作为恢复线索,却不能覆盖新任务。若 App 重建页面或被系统回收,恢复页应先重新核对设备与关系,而不是从上一次缓存的进度百分比接着往下走。

重试不是再次调用同一个按钮

能够明确修正的输入错误可以引导客户修正后重新发起;没有支持依据的设备状态,应先回查。支持何种续配需要按固件和所选接口确认。官方蓝牙文档对部分恢复能力列有固件条件,不能只凭安装了较新 App 就假定所有旧模组都能原地续配。

重试还要避免制造并发尝试。一次尚未确认停止的任务,不应同时开启另一个扫描器或另一种配网模式去“碰碰运气”。这样做会使返回结果难以归属,并把可复现的单次失败变成随机的混合现场。先明确本次任务是否结束,必要时结束旧任务,再以新标识启动下一次。

超时以后,设备可能已经走得比页面更远

涂鸦 App 首次配网验收:把失败定位到具体阶段:技术流程图 1

图为应用侧建议的恢复分流;中间过程必须以实际可观察事件记录,不能据此声称 SDK 暴露了全部阶段。

App 等不到结果,只能证明本次等待没有得到可接受的完成证据,不能直接证明云端没有形成关系。恢复时先刷新目标家庭的设备列表和相关设备信息,核对候选与已出现设备是否能建立可靠对应。不要只按客户可随时修改的设备名称判断,更不要靠“列表多了一项”猜测就是刚才那台。

如果确实找到对应设备,进入状态与控制验收;如果没有找到,保留未完成结果,再按产品支持的恢复方式重新配网。列表查询失败本身也属于未知,不等于设备不存在。把网络请求错误当成空列表,会让原本应该稍后核验的设备被错误地要求重置。

这里最重要的是给未知结果留位置。UI 可以显示“正在确认添加结果”,并允许用户离开后返回核查,而不是只能在“成功”和“失败”两格中选一格。恢复记录需要有保留期限与受控访问,避免为了排障长期存储设备标识和家庭关系;到期未确认也应以未完成关闭,而不是自动补成成功。

首次控制是另一次验收

设备被添加后,先检查面板使用的产品与数据点定义是否匹配,再执行一个经过授权、可观察且低风险的动作。看 App 中按钮变色只能证明界面响应,不能证明目标设备已动作。应把发起操作、状态反馈和物理现象放在同一次验收记录中,避免拿前一次缓存状态为这次控制背书。

Tuya 设备管理文档区分 DP 更新、设备状态和网络状态监听。应用可据此组织证据,但单个状态回调不能替代全部产品承诺。若要验收远程操作,需在受控条件下核对对应链路;即使 DP 值更新,锁、电机或温控执行器仍需按实际风险验证物理结果。

首次使用记录应能够回答:哪一个账户、哪一个家庭、哪台设备、哪个 App 与固件组合,在什么授权和网络条件下完成了什么动作。失败记录还应保留已通过的阶段、首个未通过阶段和下一步责任方。不要把 Wi-Fi 密码、token、密钥或完整账户资料附进工单,诊断信息可以脱敏,不必靠泄露凭证换可读性。

这套分阶段验收值得用在要面向真实用户交付的品牌 App,而不值得被包装成几段通用配网代码便可替代的工作。它增加了状态记录、恢复入口与回归测试成本,却能让“失败后怎么办”成为产品能力。量产前仍要在选定手机、固件和网络组合上验证;公开文档和一张流程图无法给出你产品的配网成功率。

客户在首次使用后由谁管理设备,是下一道不同的交付任务,可继续看安装人员退出控制与客户接管。需要把这些恢复与验收路径纳入品牌应用,可从涂鸦 App 定制开发梳理范围,而不是只验收一个正常路径演示。

星野云联微信二维码