简介面向物联网开发者、设备接入初学者及需要将硬件快速上云的工程人员这份百度IOT平台操作手册围绕设备接入、云端管理与数据交互展开帮助读者理解从产品创建到应用配置的完整流程。压缩包内为1个doc文档大小约1.35MB内容以平台操作说明和功能入口指引为主适合按章节对照界面查阅。已有384人学习对入门与实操具有一定参考价值。文档具体覆盖产品类别、型号与联网方式设置CA及Profile下载烧录、心跳检测数据点定义测试、批量生产和OTA固件升级并整理新增设备、设备存活、活跃、在网时长及固件版本分布等统计口径服务列表、服务管理以及应用创建、API Key、Secret Key和Android/iOS配置也有说明。读者可据此梳理设备上云的关键环节定位烧录、心跳与数据互通中的常见问题建立对物联网基础平台研发、数据分析和服务应用管理的整体认识。1. 接入前先看一眼这堆文件一个把 CA 烧错目录的下午去年帮一个做温控面板的团队接物联网 IOT 基础平台固件前后烧了三遍平台侧的心跳检测一直是灰的。代码没动过问题出在文件上他们把上一个产品的 CA 和这次的 Profile 扔在同一个目录模组按文件名顺序加载读进去的是旧证书看着都烧成功了实际连的是另一套凭据。平台使用手册里这件事只有一句话但真正卡人的地方全在那些没有被写进流程图的细节里。后面几章按我实际走的顺序展开先把产品和应用创建对再把 CA、Profile 拿到手并核对然后烧录、测心跳、建数据点、走测试和批量生产最后处理 OTA 和排查。照着走一遍一套最小可用的接入环境大概半个工作日能跑通。2. 创建产品与联网方式产品类别、型号、联网方式三项怎么填创建产品这一步看着只是填三个下拉框实际上它决定了后面 Profile 的格式、数据点的命名空间以及批量生产时批次能不能对上。我见过最常见的返工是产品型号随手填了个test01等一百台设备出厂要贴标签的时候才发现型号是印在包装和二维码上的改不了只能重建产品、重建数据点、重新烧一遍。2.1 开发者中心里的入口和前置状态注册完成之后进开发者中心左侧是「设备接入」入口页面右上角才是【新建产品】按钮。听着简单但有两个状态会让人以为按钮没了一是账号还没完成开发者认证页面上只显示引导文案二是当前处在某个产品详情页里需要先返回列表层。我一般先把这几件事确认掉再动手顺序别乱账号已完成开发者流程能进到设备接入页面页面上能看到已有产品列表哪怕是空的说明权限正常想清楚这次接入的设备台数量级几百台和几万台在产品结构上的取舍不一样想清楚是否需要通过 APP 控制需要的话应用要提前建AK/SK 后面配数据点测试会用到。第 4 条容易被跳过。等设备端都调通了才发现没有应用、拿不到 API KeyDemo APP 扫码那一步就卡住得回头补。2.2 联网方式的取舍Wi-Fi、蓝牙、4G 各管一段新建产品时要设置产品类别、产品型号、联网方式。产品类别按实际品类选智能家居、智能硬件这类分法主要影响平台侧的展示和部分默认能力不影响协议真正影响设备端的是联网方式。联网方式选错最直接的表现是设备端 SDK 编出来的接入参数和平台分配的 Profile 对不上模组发出的心跳包被平台判为非法连接。常见的三选一是这样取舍的Wi-Fi适合固定位置、有稳定供电的设备配网过程要走一遍 SSID 下发首次联调耗时主要在配网而不是云端蓝牙通常作为近场配置通道设备本身还是要通过网关或手机把数据转出去不要把蓝牙当成设备直连云端的链路4G/蜂窝适合分散部署、无固定网络的场景成本和功耗都要重新算心跳策略也要跟着调。我的习惯是先按样机实际使用的那条链路选选完立刻用一台样机验证不要等量产前再回头改联网方式——联网方式一改Profile 基本要重新下载之前烧好的设备全部作废。有一点提醒自定义配置信息那一栏不要留空着不填也不要想太多。留空不影响创建但填了的产品在后续批量生产时能按配置区分批次多型号共用一个产品的团队会省事。提示产品创建完成后新产品研发右侧区域会列出刚建的产品点进去才是产品详情。后面所有操作下载 Profile、心跳检测、数据点都在这个详情页里不在列表页。2.3 创建应用拿 AK/SKAndroid 包名签名与 iOS Bundle ID设备如果要通过 APP 控制必须先创建应用。这一步在产品之后做入口在应用管理里点【创建应用】输入应用名称即可创建成功不需要别的材料。创建完进入配置页能看到 API Key 和 Secret Key这两个值要复制走。Secret Key 只在配置页展示复制漏了就得重置重置之后已经发出去的 APP 全都要换配置这是很典型的后悔药场景。平台对客户端身份是有校验的不同平台要填的字段不一样Android需要填包名和应用签名iOS需要填 Bundle ID手册里拼成了 Bunld ID照字段位置填就行。签名这一项最常被填错。平台要的是签名证书的 SHA1 指纹不是 MD5也不是调试证书的指纹。发布版应用要拿 release keystore 去取# 取 release 签名证书的 SHA1平台填这一项不要填 MD5 keytool -list -v -keystore release.jks -alias releasekey | grep -i SHA1 # 顺手确认包名别用手写的应用显示名去填 aapt dump badging app-release.apk | grep package命令的含义很直白第一条从 keystore 里把证书指纹打出来-alias要换成你自己的别名第二条从已经打好的 APK 里读包名比在工程里翻 Gradle 配置可靠。iOS 侧同样建议从产物里读而不是凭记忆写# 从 Info.plist 读真实的 Bundle Identifier /usr/libexec/PlistBuddy -c Print :CFBundleIdentifier Info.plist包名和签名一旦填错APP 连得上网络但平台侧会拒绝鉴权日志里看不出是配置问题只会看到连接被断开非常像网络问题。血泪经验是先把这两个值确认下来再去调业务代码。顺带说一句服务列表。服务列表展示平台提供的能力和基本信息服务详情里有【查看文档】入口。接数据点之前花十分钟翻一遍对应服务的文档比自己猜字段含义快得多。3. CA 与 Profile 下载烧录文件放错位置等于没接产品建好之后详情页里有两个按钮【下载 Profile】和【下载 CA】。这两个文件是设备身份的载体烧录环节所有翻车八成出在它们身上——要么下错了产品的要么同名覆盖要么烧进去之后模组根本没读到。3.1 Profile 和 CA 各管哪一段Profile 是这台设备或这个产品批次的平台侧描述包含设备接入身份、数据点定义指向等信息CA 是证书链用来让设备校验云端身份。两者作用不同都不能省只有 Profile 没有 CA设备能发出连接请求但握手段校验不过表现为连接建立后立刻断开只有 CA 没有 Profile设备不知道以什么身份接入心跳包发不出去平台侧完全看不到设备两个都有但来自不同产品心跳可能偶尔成功但数据点对不上表现为能连上、下发指令无响应。第三种最坑因为它不是稳定失败而是时好时坏很容易被当成信号不好这种玄学问题排查好几天。3.2 烧录前的文件自检和目录约定我现在的固定动作是下载完不急着烧先在本地建一个按产品型号命名的目录把文件和一份校验值放进去。# 按产品型号日期建目录避免多产品文件混在一起 mkdir -p iot/profile-产品型号-$(date %Y%m%d) cd iot/profile-产品型号-$(date %Y%m%d) # 下载的文件放进来的同时算一遍校验值留档 sha256sum profile.json ca.crt | tee profile.sha256 ls -l第一条只做目录隔离重点是路径里带型号和日期后面再下载第二版的时候不会覆盖第二条把两个文件的哈希记下来烧录失败时可以确认文件本身有没有被截断或者拿错第三条看文件大小Profile 和 CA 都是小文件如果某个文件大小异常比如 0 字节或者几百 KB说明下载过程出了问题重新下不要硬烧。设备端工程按下面的结构放模组侧加载路径就固定了不用每次改代码# 设备端固件工程的资源目录约定 firmware/ ├── resources/ │ ├── ca/ │ │ └── ca.crt # 平台下载的 CA │ └── profile/ │ └── profile.json # 平台下载的 Profile └── src/ └── iot_entry.c # 加载上面两个路径的入口路径写死在配置里如果模组 SDK 支持配置文件把路径抽出来比写死在代码里好维护联调时换一组文件不用重新编译{ product_key: 产品创建后平台分配的产品标识, profile_path: ./resources/profile/profile.json, ca_path: ./resources/ca/ca.crt, heartbeat_interval_s: 1800 }product_key填平台侧给的标识不要手写产品名profile_path、ca_path用相对路径方便整包搬到别的编译机heartbeat_interval_s是心跳间隔平台以一次心跳代表设备在网 30 分钟来统计在线时长这里设 1800 秒刚好对齐设得太长会让在网时长统计偏低设得太短只是多耗一点功耗不影响正确性。3.3 心跳检测与设备在网时长口径文件烧进去、设备上电联网之后回到设备接入页面点【心跳检测】。平台会自动检测设备是否已向云端上报心跳检测成功会弹窗提示失败则提示检查烧录过程。这个按钮的判定逻辑要理解清楚不然会误判它检测的是有没有收到心跳不是设备在不在线。所以设备断电前最后一次心跳之后的 30 分钟内点检测仍然可能显示成功。反过来设备刚上电就点检测可能因为还没到第一个心跳周期而失败等一会儿再点就好。数据统计里的几个口径也建议在联调阶段就记住后面验收会用到统计项判定口径联调时的用法新增设备设备首次上报心跳即视为激活确认新烧的样机被正确识别设备存活有数据上报含心跳和 APP 连接控制判断设备是否还在工作设备活跃指定时间内有非心跳数据上报判断业务链路是否真的通了设备在网时间按心跳统计一次心跳代表在网 30 分钟核对心跳周期有没有配错在网时长分布一定时间内在网时长的分布看批量设备的稳定性固件版本分布各固件版本数量占比不含未激活设备验证 OTA 是否铺开存活和活跃这两个词在联调时特别容易混。设备只发心跳、业务数据一条没上来它在统计里是存活但不活跃这种情况八成是数据点没配好或者设备描述文件没烧进去而不是网络问题。4. 数据点设置与测试设备描述文件导出后被漏掉的一步设备与云端的具体数据交互靠数据点定义。这一步在平台上点几下就能建完真正容易漏的是后面那句需导出为设备描述文件之后将其与 CA 集成烧入设备。很多人建完数据点、看到列表里有条目就以为完事了结果设备端完全不知道有哪些字段读写出错。4.1 数据点类型与数据类型的对应关系数据点设置在产品数据点页面先选中要编辑的产品再点【新建数据点】。要填的核心是两项数据点类型和数据类型。前者决定这条数据在平台侧被当作什么用后者决定设备端序列化时的字节宽度和取值范围。常见的对应关系是属性类的点用于状态上报和下发的最终值数据类型按物理量选温度用浮点、开关用布尔、计数用整型事件类的点用于一次性上报服务类的点用于调用型交互。这里的取舍原则是——能被查询到当前值的用属性只在某个时刻发生一次的用事件。建数据点时有一个字段命名约束值得提前定规矩数据点标识一旦被设备端固件引用改名就等于要重新烧固件。所以命名别用d1、d2这种用temperature、switch_status这类语义化的名字后面加字段也不会乱。{ dataPoint: { identifier: temperature, type: 属性, dataType: float, unit: 摄氏度, access: 只读 } }这段是设备描述文件里单条数据点的大致结构字段名以平台导出的实际文件为准。identifier是设备端代码里要引用的键type决定它在平台页面上出现在哪个分组dataType要和固件里的变量类型对齐浮点填成整型会表现为数值被截断很难查access只读的点不要在下发指令里写平台会拒绝。建完之后可以对已创建的数据点做编辑和删除。删除要谨慎删掉再建同名点设备端描述文件不重新导出一遍是对不上的。4.2 导出设备描述文件并与 CA 一起烧录数据点建完回到数据点设置页面导出设备描述文件然后把它和 CA 一起集成进固件烧进设备。这一步的正确顺序是先导描述文件再确认 CA 是同一个产品的最后一起打包进固件。# 烧录前把三个文件放在一起核对缺一个都别往下走 ls -l resources/ca/ca.crt \ resources/profile/profile.json \ resources/profile/datapoints.json # 描述文件里的标识要和固件里引用的键一致 grep -o identifier[^,]* resources/profile/datapoints.json第一条是硬性检查三个文件必须同时存在第二条把描述文件里的标识列出来和固件里用到的那几个键名逐个对对不上就改描述文件或者改代码不要指望运行时容错。这里有个很容易被忽略的点数据点改过之后描述文件必须重新导出重新烧。平台上改一个类型、加一个点页面立刻生效设备端不会自动同步。我一般会在数据点页面临时改一个值做测试改完立刻导出一版放回工程形成习惯。4.3 Demo APP 扫码测试的边界数据点设置页面上有【数据点测试】按钮点开之后用 Demo APP 扫描二维码开始测试。这一步能验证的是应用侧的鉴权是否正常、数据点标识是否被正确识别、上报和下发的基本链路是否通。它验证不了的是真实业务的数据内容对不对、大批量设备并发时的稳定性、断网重连后的状态恢复。所以扫码测试通过只代表环境搭起来了不代表业务逻辑正确别把它当验收。扫码这一步最常见的失败原因是应用没配置好AK/SK 没复制、Android 的包名或签名填错、iOS 的 Bundle ID 填错。表现是扫码后 APP 报鉴权失败或者直接白屏。遇到这种情况先回应用配置页核对那三个字段比在设备端抓包快十倍。4.4 批量生产与 OTA10000 个 Profile 和 10MB 固件数据点建好并且检测无问题之后就可以申请批量生产。入口在产品数据点创建之后的页面里流程是选择要批量生产的产品型号点【新建批次】设置批次信息创建完成后点进批次下载 Profile。一个批次最多 10000 个 Profile这个数字是硬上限。超过就拆批次别想着一次全出来。批次信息里建议把生产日期或者客户代号写进去后面出货对不上批次的时候能靠这个名字找回来。# 批次文件下载后按批次号归档别散在下载目录里 mkdir -p batches/batch-20240612-a mv profile_batch_*.zip batches/batch-20240612-a/ cd batches/batch-20240612-a unzip -q profile_batch_*.zip ls | wc -l第一条建批次目录命名带日期和批次尾号第二条把下载的包移进去第三条解压后数文件数量和申请时的数量对一遍少一个都要重新下。批量产线上最怕的不是文件错是少给了几台等到烧录工位才发现。OTA 升级在产品页面里操作选择要升级的产品点上传固件固件最大 10MB格式必须是 zip然后填固件版本号和通知方式。# 打包 OTA 固件必须是 zip上传前先看大小 cd build/ zip -r ota_v1.0.3.zip firmware.bin ls -lh ota_v1.0.3.zipzip -r的-r是递归打包如果你的固件只有一个 bin 文件可以不加打包后一定要看大小超过 10MB 就别传了压缩包里塞了日志或者调试符号是常见原因先把这些剔掉。通知方式有四种静默、强提醒、弱提醒、被动提醒。静默是直接对设备升级无提醒、无需用户干预另外三种都是推送给 APP 端的信息具体表现由 APP 里的规则决定。选择原则很实际——安全类、修复类固件用静默体验类、功能类用提醒别为了省事全用静默用户端会突然发现设备行为变了。5. 常见问题排查从烧录到 OTA 的五条翻车记录这个平台的功能链路不复杂但每一步都有几个看着成功了其实没成功的状态。下面五条是我和几个团队在实际接入里反复撞到的按现象、原因、解决记下来。5.1 心跳检测一直失败重烧也没用现象设备上电、串口打印显示已连上网络但平台侧点【心跳检测】始终失败换了模组、换了电源都一样。原因八成是 Profile 和 CA 不是同一个产品的。多产品并行开发时两个产品的下载按钮长得一样下载目录里文件名也一样后下载的直接覆盖了前面的烧进去的是混合凭据。解决把设备端目录里的 CA 和 Profile 全部删掉重新从当前产品详情页下载下完立刻算哈希记到批次目录里再用这份文件重烧。以后固定按产品型号日期建目录不要在下载目录里直接烧。5.2 烧录显示成功设备却不在新增设备里现象烧录工具提示成功串口也有输出但数据统计里的新增设备数量一直是 0心跳检测偶尔能过。原因设备确实发起了连接但心跳没有真正上报到平台。常见于描述文件没烧进去或者固件加载路径写的是绝对路径换到另一台编译机打包后路径失效模组静默降级成了不带身份的连接。解决在固件里把三个资源文件的加载结果打日志加载失败直接进入错误状态而不是继续跑。同时把路径改成相对路径加配置项别写死绝对路径。5.3 数据点能下发读不到值现象APP 下发指令设备有反应但页面上读不到设备上报的值数据统计里设备是存活不是活跃。原因数据点标识在描述文件和固件里不一致或者数据类型不匹配。比如平台侧建的是浮点固件里按整型塞进去序列化出来的字节长度不对云端解析失败。解决先对描述文件里的 identifier 和固件里的键名做一次逐条比对再对数据类型。这一步不要靠肉眼用 grep 把标识列出来对比翻代码快。注意改完数据点一定要重新导出描述文件并重新烧录平台页面上改了不等于设备端改了。5.4 OTA 上传报格式错误现象点上传固件选了文件之后提示格式不对或者直接失败文件确实是自己打包的 zip。原因一是包里套了包先 zip 了一次又把 zip 打成 zip二是压缩包里带了系统生成的隐藏文件部分校验会拒三是文件大小超过 10MB 的上限。解决解压看一层结构确认 bin 文件在包内第一层打包时排除隐藏文件打完立刻看大小。版本号也要单独填对填成和上一个版本一样平台会当成重复版本。5.5 批量生产的 Profile 混批现象产线烧录到一半发现部分设备连上平台后归属的产品不对或者数据点缺失。原因批次目录里混进了上一次申请的文件或者中途重新申请了批次但没清空下载目录解压时同名覆盖。解决每个批次单独一个目录解压前先清空目标目录烧录工位按批次号领料一个批次烧完再领下一个。这条听起来像流程问题但它的代价最高——混批的设备要么返工重烧要么报废。5.6 排查顺序从平台侧往设备侧倒推上面几条的共性是可以按固定顺序排掉大半先看平台侧数据统计里有没有新增设备记录没有就是凭据或网络有记录但不活跃就是数据点或描述文件活跃但数值不对才是业务代码。这个顺序能省掉大量在设备端抓包的时间。6. 装完怎么验证跑通用数据统计反向确认设备真的在网接入环境的验收不要只看心跳检测那个弹窗。弹窗成功只说明某一刻收到过心跳不能说明设备持续在工作。我的做法是用平台自带的数据统计做三层反向验证一层过不了就停在那层查。第一层看新增设备。设备首次上报心跳即被视为激活新烧的样机上电后等一个心跳周期刷新数据统计新增设备数量应该加一。这一步不过说明烧录或凭据有问题直接回第 3 章查文件。第二层看设备活跃。给设备制造一次真实的业务上报不是心跳比如触发一次温度上报或者一次开关状态变更然后看活跃设备数。存活但不活跃是最常见的中间态说明连接通了、鉴权过了但数据点链路没通回第 4 章查描述文件。第三层看固件版本分布。这个指标在 OTA 之后特别有用升完级等一段时间看版本分布里新版本占比是否在涨未激活的设备不计入统计所以占比不动要么是 OTA 没推下去要么是设备根本没激活。两种情况的排查方向完全不同。# 本地留一份验收记录每次改动后跑一遍比记在脑子里可靠 cat acceptance.md EOF | 检查项 | 期望 | 实际 | 结论 | | 心跳检测 | 成功 | | | | 新增设备 | 1 | | | | 设备活跃 | 1 | | | | 数据点上报值 | 与设备一致 | | | | 固件版本分布 | 新版本占比上升 | | | EOF这个文件不用多正式关键是每次改配置、换固件、换批次之后都重新填一遍。我吃过一次亏数据点改完之后只测了上报没测下发等出厂前才发现下发指令被拒返工了两天。还有一个小技巧把心跳间隔和在网时长口径对一遍。平台以一次心跳代表在网 30 分钟统计在线时长如果你的固件里心跳设成了 5 分钟在网时长会明显偏高看统计的时候会误以为设备一直在线。反过来设成 2 小时在线时长会被低估排查掉线问题时会得出错误结论。联调阶段就把这个值定下来别等看报表的时候才发现口径不对。从那以后我每次接入新平台都会在烧第一台样机之前把三个文件放进一个按型号命名的目录、算一遍哈希、跑一次心跳、再跑一次真实业务上报四步全过才允许产线开始烧。这套动作多花二十分钟省下的是整批返工。需要照着按钮位置逐步操作的话把这份平台使用手册放在手边对着点比凭印象试要稳。希望帮到你。本文还有配套的精品资源点击获取
