简介：《百度IOT平台——平台使用手册》是一份面向物联网开发者、设备端工程师及嵌入式入门者的实操型文档，围绕设备接入云端的完整链路展开，帮助读者解决产品创建、固件烧录、数据点定义与批量生产等环节中的操作疑问。压缩包内共1个doc文件，体积约1.35MB，内容以分步图文说明为主，按「研发与管理—数据分析—服务与应用」三大模块组织，便于边看边照着平台界面操作。手册细化了创建产品时类别、型号与联网方式的配置，Profile与CA文件的下载烧录，心跳检测失败后的排查思路，数据点类型选择与Demo APP扫码测试，以及最多10000个Profile的批量生产、10MB以内zip固件的OTA静默或分级提醒升级；数据统计部分还解释了新增设备、存活、活跃、在网时长与固件版本分布的口径差异，应用侧则覆盖AK/SK复制与Android包名签名、iOS Bundle ID配置。目前已有384人学习，适合需要快速上手百度IoT基础平台、对照排查接入问题的读者查阅。

1. 从一份 Word 手册说起：物联网 IoT 基础平台的接入链路到底长什么样

上周一个做硬件的同学抱着刚打样的模组过来：Wi-Fi 连上了，串口日志里也有数据在跑，平台侧就是不显示在线。查了半天，问题出在产品创建时“联网方式”那栏随手选了默认值，后面下载的 Profile 和 CA 跟模组实际链路对不上。设备接入真正卡人的地方常常不是代码，而是配置链路上那些不起眼的选项。

这份《平台使用手册》讲的是物联网 IoT 基础平台从产品创建到数据统计的整条操作链路：建产品、下 Profile 和 CA、测心跳、配数据点、批量生产、OTA、接应用。它像一张接线图，不是 API 文档。适合刚接手设备接入的嵌入式同学、管设备台账的后端，以及要做 App 控制的移动端；熟手可以拿来对照平台侧的口径和上限。

2. 产品建模与设备接入：Profile、CA 和一次心跳的三段验证

设备接入这条链路上，最容易被跳过的是第一步。很多人拿到账号就直奔烧录，结果卡在心跳检测上反复怀疑模组。手册把这一段拆成创建产品、下载 Profile 与 CA、检测心跳三个动作，顺序不能换，因为后一步的输入全部来自前一步的输出。

2.1 产品是一类设备的模板，型号才是具体款

平台里的“产品”不是指某一台设备，而是一类设备的模板：同一种用途、同一套数据点定义、共享一份固件升级策略的设备，归到同一个产品下。设备是产品下的实例，一台设备对应一份独立的 Profile。这个层级关系搞混，后面批量生产和 OTA 会连带出错。

创建入口在开发者中心的设备接入页面，点【新建产品】后要填的东西不多，但每一项都影响后续：

我一般按这个判断：品类变了（从温控终端变成门磁）→ 新建产品；硬件改版了（换蜂窝模组、加一路传感器）→ 同一产品下新建型号；只是同一款硬件的不同生产批次 → 什么都不用建，直接在产品下加设备。自定义配置信息那栏经常被当成备忘录用，塞进去一堆和启动无关的说明文字，结果每次下发都多背一段 payload，设备侧解析还得容错，实在没必要。

填完点【新建】，创建成功的产品会出现在新研发区域的右侧列表里。这时候别急着下载文件，先确认产品的联网方式和型号没选错，因为 Profile 一旦批量生成再想改，只能整批作废重来。

2.2 Profile 和 CA：两个文件决定设备能不能被认出来

产品建好后，点进产品详情能看到【下载 Profile】和【下载 CA】两个按钮。这两个文件的分工不一样，很多人把它们混成一个“证书包”一起烧，出问题就查不出层次。

Profile 是这台设备的身份凭据，常见做法是里面带产品标识、设备名、设备密钥这类三元信息，有的平台还会把接入域名一起打进去。CA 是平台侧的根证书，设备拿它去校验云端出示的证书，属于 TLS 双向认证里设备这一侧要握着的信任锚。设备端开发者手册里通常会写明烧录地址，我见过的大多数模组方案是把 Profile 放在 flash 的一个独立分区（比如 4KB 对齐的保留区），CA 放在另一个只读分区，两者都不参与 OTA 覆盖。

拿到文件先落盘归档再做校验，不要下一个烧一个：

# 下发的 Profile 与 CA 先归档，再生成清单供产线比对 mkdir -p profiles/batch_20240612 cp Profile_*.bin CA_*.pem profiles/batch_20240612/ # manifest 是产线防串号的依据，烧一台勾一台 sha256sum profiles/batch_20240612/* | tee profiles/batch_20240612/manifest.sha256

sha256sum那一步看着多余，实际上是产线最容易出事的地方：Profile 文件名相近，工位同时开三个烧录器时极容易拿错，一个 Profile 烧到两台设备上，两台都会间歇性互踢下线。有了 manifest，烧录前扫一遍比对哈希，串号当场就能拦住。

CA 文件本身也值得看一眼，尤其是设备端 TLS 握手一直失败的时候：

# 只输出主题、签发者和有效期，确认 CA 没拿错版本 openssl x509 -in CA_*.pem -noout -subject -issuer -dates

-noout表示不回显完整 PEM 内容，-dates打印 notBefore 和 notAfter。设备端如果 RTC 时间没有校准，开机时间戳落在证书有效期之外，握手会直接失败，而串口日志里往往只留一句含糊的握手错误，这就是典型的黑匣子场景。所以我习惯在设备启动流程里加一条：联网成功后先对时，再发起业务连接。

2.3 心跳检测：平台侧只认收到过

设备联网后，会按配置的周期向云端上报心跳。平台在设备接入页面提供的【心跳检测】，本质是查这台设备最近有没有心跳落库，检测过程有个短暂的等待，成功后弹窗提示互通正常，失败则提示回去检查烧录过程。

失败提示只给了方向，具体定位还得自己分层。我按发送侧、网络侧、身份侧、时间侧四层往下走：

第三行那种情况最难查，因为设备侧一切正常，日志漂亮得很，问题在平台侧的设备台账和烧进去的身份对不上。我一般的做法是让产线在烧录完成后立刻回读设备名，跟批次索引文件对一遍，当场发现当场重烧，别等到装机之后返工。

心跳周期这个参数值得单独说：平台统计在线时长是按心跳次数折算的，一次心跳代表设备在网一段时间，这个折算关系决定了心跳间隔能开多大。间隔开太长，设备明明活着，统计口径上却是断的；开太短，蜂窝模组的功耗和流量都受不了。具体换算放到后面统计那章细说，这里先记住一条：改了心跳周期，等于改了所有在网相关指标的读数。

3. 数据点建模：把设备语义翻译成云端能读懂的字段

产品建好、心跳通了，接下来才是真正决定这套接入能不能长期维护的一步。数据点定义的是设备和云端之间到底交换哪些字段、字段是什么类型、能不能被 App 写。它同时被三方消费：设备端固件、云端解析、App 面板。任何一方对不上，表现都是“设备在线但功能不好使”。

3.1 三种数据点类型与数据类型的选型

手册里数据点设置的操作路径很短：进入产品数据点页面、选定产品、点新建数据点、选类型、选数据类型、确认。短路径背后是模型设计，选错了后期改起来代价很大。

常见做法是把数据点分成三类：

数据类型上，平台一般提供布尔、整型、浮点、字符串、枚举、时间这几类。选型有三个我踩过坑的原则：

能用整型就不用浮点。浮点在设备端序列化和云端入库时都有精度处理的差异，25.3 在两边可能变成 25.299999，做阈值判断时特别难受。温度这类量改成以 0.1 度为单位的整型，端侧乘 10、云端除 10，控温逻辑立刻干净。

能用枚举就不用字符串。枚举把合法值前置到定义里，App 侧直接渲染成下拉，设备端上报一个越界值平台能当场拦下；字符串则什么都能塞，脏数据要等到业务层才发现。

按上报节奏合并，不按传感器数量拆。一台设备装了六路传感器，如果六路采样周期一致、变化频率接近，合成一个结构化的属性比建六个独立数据点更好维护，描述文件不会膨胀，OTA 时固件里的字段映射表也短。反过来，一路每秒上报的电流和一路每小时上报的电池电压，硬塞进一个数据点会互相拖累。

3.2 设备描述文件导出与 Demo APP 扫码自测

数据点建完，要把定义导出成设备描述文件，再跟 CA 一起集成进固件烧到设备，设备才知道该按什么格式打包上报。手册给的自测路径是：数据点设置页面点【数据点测试】，用 Demo APP 扫描二维码，进入测试面板直接看字段收发。

导出的描述文件大概长这样，结构示意，具体字段名以实际导出为准：

{ "productKey": "<产品标识>", "version": "1.0.3", "datapoints": [ {"id": 1, "name": "power_state", "type": "property", "dataType": "bool", "rw": "rw"}, {"id": 2, "name": "target_temp", "type": "property", "dataType": "int", "unit": "0.1C", "range": [50, 350]}, {"id": 3, "name": "fault_code", "type": "event", "dataType": "enum", "values": [0, 1, 2, 3]} ] }

id是设备端解析时的主键，一旦分配就不要复用，删掉的数据点 id 永久作废；name用全小写下划线，别混大小写，有些端侧解析器区分得很死；range和values是给端侧和 App 侧做双重校验用的，范围写宽松一点没关系，写死了后期调整量程要重新走一遍数据点发布。version每次改动都递增，产线上固件版本和描述文件版本是要对得上号的，对不上就会出现设备上报了但平台解析不出来的情况。

Demo APP 扫码测试时，重点看两件事：一是属性写入能不能真正下发到设备（很多问题出在只测了上报，没测下发），二是事件类数据点连续触发两次，平台侧是不是两条独立记录而不是被覆盖成一条。这两点过了，数据链路基本就通了。

3.3 命名、单位与版本：上线后别动的那几个字段

数据点这类东西，上线之后再改就是给自己找麻烦。我给自己定了几条硬规矩：

名称里带单位后缀。temp_c、power_kwh、battery_pct，一眼能看出量纲，避免 App 端把摄氏度当华氏度显示。单位不要放在备注里，备注没人看。

枚举值只增不改。故障码 1 原本是“传感器开路”，后来想改成“通信超时”，一改历史数据全废，运维拿着三个月前的告警记录根本对不上。要改就新增一个码值，老码值标记为废弃。

删除数据点之前先确认没有历史数据依赖。平台侧的统计和报表通常按数据点维度聚合，删掉之后历史曲线直接断档，而且不可恢复。宁可留着不用，也别删。

预留两三个通用字段。reserved_1、reserved_2这种看着不优雅，但硬件小改版时能救急，不用为了加一个字段重新走一遍描述文件发布和固件升级。

4. 批量生产、OTA 与应用接入：三件上线前必须过的关

研发阶段一台设备跑通，和量产、可维护之间隔着三件事。手册把这三件事放在不同章节，实际项目里它们是连着做的：数据点测试没问题，先批量生成 Profile 交给产线；固件要能远程升级，才敢把设备发出去；App 要能控制设备，得先把应用建起来拿到凭据。

4.1 批次化 Profile：10000 个上限怎么分批

批量生产的入口在数据点页面之后，操作是选产品型号、点【新建批次】、设置批次信息、创建完成后点进批次下载 Profile。手册明确写了单批次 Profile 数量最多 10000 个，这个数字决定了分批策略。

按生产工单分批，不按总量分批。工单 3000 台就建 3000 的批次，不要图省事一次建 10000 然后慢慢用。原因是批次号会成为产线、仓库、售后三方对账的共同索引，一次建满之后第二批货混进来，追溯就断了。

留 2% 到 5% 的余量给返修和跌落损坏。批次数量按计划产量乘 1.03 向上取整，多余的那部分单独存放，不要和正常料混在一起。

批次下载下来是一个压缩包，解压后不要直接丢给工位，先生成一份索引：

# 解压批次包并生成工位可用的顺序索引 unzip -q profile_batch_A_20240612.zip -d batch_A find batch_A -name 'Profile_*' | sort -V > batch_A/index.txt wc -l batch_A/index.txt # 行数应与批次申请数量一致

-q静默解压，-d指定目录，sort -V按自然序排，避免Profile_10排到Profile_2前面导致工位取号顺序错乱。wc -l那行是对账，行数和申请数量对不上说明压缩包下漏了或者平台侧生成有缺失，这时候就该停下来找平台侧确认，而不是先把能烧的烧了。

产线工位的规矩只有一条：一个 Profile 只烧一台设备，烧完立刻在索引里打勾并回读设备名。这条不做，返修阶段就是灾难，因为你无法判断手上这块板子的身份是不是和别人重复了。

4.2 OTA 固件包：10MB、zip 与四种通知方式

OTA 页面的操作是选产品、上传固件、填版本号、配通知方式。两个硬约束写在手册里：固件最大 10MB，格式必须是 zip。这两条经常一起把人卡住，因为调试符号一打进去就超限。

打包我固定用这条命令：

# 只打运行时文件，剔除调试符号与版本库目录 zip -r -9 firmware_v1.2.3.zip ./bin ./conf \ -x "*.map" -x "*.debug" -x "*.git/*" -x "*/.DS_Store" ls -lh firmware_v1.2.3.zip # 必须小于 10MB

-9是最高压缩比，-x逐个排除。.map和.debug这两个后缀在带 RTOS 的工程里动辄几十兆，不排除必然超限；.git目录和 macOS 的.DS_Store属于无意义的体积噪声。压完之后建议再unzip -l看一眼目录层级，有些产线脚本期望压缩包根目录直接就是bin/，多套一层目录会导致解压路径错位，设备升完起不来。

版本号用主.次.修三段式，只增不减。同一个版本号重复上传，平台侧通常按覆盖处理，已经升过的设备不会再拉一次，指望用同号覆盖来修 bug 是行不通的，必须发新号。

四种通知方式的差别在这里：

静默升级听起来最省事，但设备正在执行任务时被强制重启是实打实的事故。我的做法是在固件里留一个空闲窗口判断：收到升级指令后先看当前有没有在执行的控制任务，有就挂起等待，超时才强制。另外强提醒、弱提醒、被动这三种最终行为要 App 侧配合实现，平台只负责把消息推出去，App 不做处理，用户那边什么都看不到。

回滚策略也要在发版前想清楚：至少保留上一个可回退的固件版本，新固件里带一个自检失败自动回退的标记位。

4.3 应用接入：AK/SK 与 Android/iOS 两个平台参数

设备要靠 App 控制，就得先建应用。操作是点【创建应用】、输入应用名称、创建成功后进入配置，可以复制 API Key 和 Secret Key，然后按平台填参数：Android 需要包名和应用签名，iOS 需要 Bundle ID（手册里印成了 Bunld ID，是笔误，照着填会校验不过）。

这几个参数的作用是绑定来源，防止别人拿同一套凭据做一个仿冒 App 去控你的设备。Android 的应用签名要和正式签名的指纹一致，用 debug 签名调试时记得单独建一个应用，别把正式应用填成调试签名，上线才发现对不上。

Secret Key 的处理是这一节唯一需要强调的事：不要编进客户端。APK 和 IPA 都是可反编译的，密钥放进去等于公开。常见做法是客户端只带 API Key，由自己的服务端持有 Secret Key，客户端登录后向服务端换一个短期令牌再调接口。手册里写“可复制 API Key、Secret Key”是描述界面能力，不是建议你把两个都塞进 App。

5. 常见问题排查：五条从烧录失败到统计对不上的记录

下面这五条都是我在实际项目里撞过的，按发生频率从高到低排。每条都按现象、原因、解决三步写，遇到同类问题可以直接对号。

5.1 五条翻车记录

第一条：心跳检测一直失败，串口却能看到数据在发。现象是设备端日志显示已经连上，平台侧点检测始终弹失败。原因多半是 Profile 烧到了错误的 flash 分区，或者烧录工具校验选项没开，写进去的是旧内容。解决方式是回读该分区跟原始 Profile 文件做哈希比对，对不上就重烧；重烧后仍失败，再用 openssl 查 CA 有效期和设备 RTC 时间。

第二条：批量生产之后，现场出现设备互相踢下线。现象是同一批设备里零星几台反复上线掉线，换一台好的上去就正常。原因是 Profile 串号，两台设备烧了同一份身份。解决方式是把疑似设备回读设备名，跟批次 manifest 逐一比对，找到重复的那一对，其中一台重新烧一份未使用的 Profile。预防手段是产线烧一台勾一台并回读确认。

第三条：OTA 上传被平台拒绝。现象是固件上传按钮点了没反应或者直接报错。原因有三种：包超过 10MB、不是 zip 格式、压缩包根目录多套了一层。解决方式是先ls -lh看体积，超了就按前面那条命令剔除调试符号重打；再看扩展名是不是严格的.zip，有些工具默认产出.tar.gz；最后unzip -l确认目录结构。这三步走完基本都能过。

第四条：改了数据点名称之后，App 面板整片空白。现象是设备在线、数据也在上报，App 上什么值都没有。原因是数据点重命名后，App 侧还在按老名字取字段，或者描述文件版本没有跟着递增，端侧用的还是旧定义。解决方式是先把名称改回去恢复服务，然后按新增字段的方式灰度：新老字段并存一段时间，App 升级完成后再下掉老字段。这条教训很贵，改名的成本远高于新增。

第五条：统计里的新增设备数远小于实际出货量。现象是仓库出了一万台，后台新增设备只有七千多。原因是“新增设备”按首次上报心跳才算激活，没联网、没上电、装在信号死角里的设备不计入。解决方式不是改统计，而是先排查未激活设备的分布：按批次看激活率，某一批次明显偏低就重点查那批的烧录和包装。这条后面还会展开。

5.2 一条固定的排查顺序：从电源到 App

设备接不上，不要东一榔头西一棒子，按这条线走，每一步都有明确的判定输出：

第一步，看供电和网络。模组有没有正常起来，能不能拿到 IP，串口有没有打印 DNS 解析结果。这一步没有输出，后面全白搭。

第二步，看时间和证书。设备 RTC 时间是否在 CA 有效期内，TLS 握手有没有走完。这一步用 openssl 看证书，用串口看时间戳。

第三步，看身份匹配。烧进去的 Profile 和平台台账里的设备是不是同一台，哈希和设备名对一遍。

第四步，看心跳周期。间隔配置是否超出平台判定窗口，改了周期之后统计口径有没有跟着变。

第五步，看数据点定义。描述文件版本和固件版本是否配套，字段名、类型、范围是否一致。

第六步，看应用侧。AK/SK 是否正确，Android 签名和 iOS Bundle ID 是否和平台登记的一致。

顺序别跳，跳步的代价是把一个电源问题当成协议问题查两天。

6. 进阶：六个统计口径的对齐方法与一份接入验收清单

平台数据统计页面给的六个指标，名字都很直白，但读法有讲究，尤其是拿去和出货量、DAU 对账的时候。

新增设备指的是首次向云端上报心跳的设备数量，也就是“激活量”，不是出货量，也不是注册量。设备存活指有数据上报的设备，心跳算，App 连上去控制产生的数据也算。设备活跃的口径更窄，只算有非心跳数据上报的设备，所以活跃数永远小于等于存活数，如果你的报表里活跃大于存活，那一定是统计窗口没对齐。设备在网时间按心跳折算，一次心跳代表设备在网 30 分钟，这个折算关系是硬编码的口径，心跳间隔一旦超过 30 分钟，在网时长就会出现系统性缺口。在网时长分布是按区间统计的设备数量占比，固件版本分布则只统计已激活设备，未激活的不进分母。

按这个口径粗算单台设备的在网时长，逻辑大概是这样：

# 一次心跳按 30 分钟折算，落在统计窗口外的心跳要截断 WINDOW_MIN = 30 def online_minutes(beats, day_start, day_end): total = 0 for ts in beats: if ts < day_start or ts >= day_end: continue # 窗口外的心跳不计入当天 total += min(WINDOW_MIN, (day_end - ts) // 60) # 末尾心跳按剩余时间截断 return total

beats是当天的心跳时间戳列表，day_start和day_end是统计窗口边界。末尾那次心跳如果离窗口结束不足 30 分钟，只能按实际剩余时间算，否则跨天统计会重复计数。这段逻辑跟平台侧不一定完全一致，但用来做趋势对比足够，能快速判断某批设备的在线表现是不是异常。

有了口径，验收就有依据。我每接一款新设备都会过一遍这八项：产品与型号是否按硬件版本拆分、联网方式是否与模组一致、Profile 与 CA 是否分区分开烧录、心跳间隔是否小于 30 分钟、数据点命名是否带单位、描述文件版本是否随固件递增、批次 Profile 是否留了返修余量、OTA 包是否在 10MB 以内且保留上一版可回退。八项里任何一项打问号，我都不会让设备出研发阶段。

从那以后，我每次接新设备都强制把这份清单走一遍，哪怕硬件和上一款只差一个传感器，也不省这一步。省下来的那点时间，最后都会以返修工单的形式还回去。希望帮到你。

本文还有配套的精品资源，点击获取