固件升级

本文介绍固件升级和差分升级的操作方式，用于需要进行固件升级的平台用户。

背景信息

如果产品采用 MCU SDK 或 TuyaOS 进行对接，当需要对已出货的设备进行固件升级时，可以通过涂鸦 IoT 开发平台进行远程在线升级，无需烧录。

名词解释

名词	解释
自定义固件	开发者在涂鸦 IoT 开发平台自定义上传的固件，由开发者自行维护更新。
涂鸦固件	由涂鸦开发并提供平台开发者开发时选择的固件，由涂鸦官方维护更新。
厂商固件	其它涂鸦平台开发者通过 OEM 或复制方式创建产品而获得的固件，由固件厂商维护。
固件类型	分为生产固件、用户区固件和升级固件。 生产固件和用户区固件：主要用于涂鸦工厂生产烧录。仅使用涂鸦生产的产品需上传生产固件和用户区固件。 升级固件：主要用于设备远程更新，即固件 OTA 升级，对所有产品生效。
固件所属者	指具备管理该固件的账号，分为以下两种情况。 情况 1：在产品开发中进行固件创建，固件归属于当前 PID 所属的账号空间。 在 我的产品 中创建的固件，归属于当前登录账号的空间。 在 客户的产品 中创建的固件，归属于当前产品 PID 和固件创建人所属账号空间，其中客户的产品一般来源于 OEM、复制以及企业间授权而获得的客户产品。 情况 2：在固件管理中进行固件创建，固件归属于当前登录账号空间。
涂鸦标准芯片	是芯片的标签。涂鸦已经使用过的芯片，可以复用涂鸦的上位机程序，用涂鸦的上位机进行烧录。
通道号	仅用于固件升级。当一个产品存在多个固件需要升级时，云端和设备会通过升级通道号，区分不同的升级固件，然后进行不同的升级操作。
固件灰度发布	让设备固件版本逐步过渡到新版固件的一种发布方式。一般是新固件开发完成即将发布升级时，可进行 A/B 测试，即让一部分用户继续使用老版本 A，一部分用户开始用新版本 B。如果用户对版本 B 无反对意见，且版本 B 没有漏洞，则可逐步扩大范围，将所有固件都迁移到版本 B。

前提条件

您已经创建了至少一个产品。详情请参考 创建产品。

基础功能：普通固件升级

根据当前产品固件的来源，共分为三种固件类型进行固件升级。

• 类型一：已发布的涂鸦固件或厂商固件。
• 类型二：自定义上传的固件。
• 类型三：生态设备接入（TuyaLink）的设备固件。

基本流程

类型一：已发布的涂鸦固件或厂商固件

1. 登录涂鸦 IoT 开发平台。

2. 在左侧导航栏中，选择 产品 > 设备 > 固件 OTA。

   涂鸦固件或厂商固件，一般为当前产品开发时直接使用涂鸦提供的固件或者 OEM 获得的厂商固件。此时若需要固件升级，需要接收到平台或厂商有新版本上架、即有新版本可更新提醒，才能进行固件升级。

3. 切换选择要升级的产品，选择对应的固件。

   

4. 单击 新建固件升级，进行相关升级规则的设置。

   

   参数分类	参数	说明
   基本信息设置	待升级的产品	当前固件对应的产品。
   	固件名称	当前选择的固件的名称。
   	固件版本	需要升级的目标固件版本。这里只能选择未做过升级的版本。
   	关键版本	主要定义是否是关键版本。 是：表示必须升级的版本。 否：表示可以跳过的版本。
   升级信息设置	升级方式	App 提醒升级：用户在 App 端收到升级提醒，可选择升级或不升级。 App 强制升级：App 用户必须升级后才能继续使用。 App 检测升级：App 用户选择对应设备的面板，然后点按右上角，主动更新。
   	自动升级	在 IoT 平台上选择是否自动升级，自动升级由 IoT 平台自动升级开关和 App 自动升级开关共同决定。 注意：一个产品可能存在多个固件，选择您需要升级的固件和对应的版本。 关闭：关闭自动升级，会执行在上一步选择的升级方式进行升级。 开启：开启自动升级，会选择 App 提醒升级、App 强制升级、App 检测升级中任意一种方式进行自动升级。
   	升级文案	添加中、英文升级文案，该内容将展示在 App 端。
   	升级备注	可用做本次升级的备注信息。
   发布范围设置	待升级版本号	用于选择本次需要升级的低版本，支持指定 1 个或多个低于指定升级版本的版本。默认全选低于 基本信息设置 中所选固件版本的所有版本。
   	待升级地区	用于选择本次版本升级需要覆盖的地区，支持指定 1 个或多个低于待升级地区。其中，中国支持省市区，其它国家仅支持选择国家维度。默认全选所有待升级地区。

5. 完成固件升级规则配置后，单击 确认。平台将会生成一条升级记录。

   

6. 单击 常用验证设备，添加反复使用的测试验证设备。常用验证设备，用于管理经常使用的日常验证测试的设备，在下一步做测试验证时，可以快速选择。

   

   • 支持根据您的 App 账号批量选择设备 ID，请先设置测试白名单。

   • 支持选择设备所在区域，即中国区、美国区、欧洲区、微软区、印度区和西欧区。

   • 支持通过用户的 App 账号，新增白名单。输入 App 账号并且验证通过后，此账号下该 PID（产品 ID）的所有设备会添加至白名单。

     

     为了安全起见，需要对 App 用户账号进行验证。

7. 推送固件并验证。

   1. 单击 固件升级 栏的 验证 进入如下页面。支持在六个区进行设备验证，包括中国区、美国区、欧洲区、微软区、印度区和西欧区。

      

   2. 添加测试设备时，支持 从常用验证设备中选择添加 或者 通过设备号直接添加。选择 通过设备号直接添加 后，即推送固件到指定的设备中。

      

   3. 单击 验证是否完成升级 进行设备 OTA 验证。

      

8. 发布固件 OTA。

   当测试设备验证成功后，表示当前固件版本 OTA 升级功能正常，可以进行批量升级，单击 发布 可进入批量发布的设备。由于平台升级迭代，目前存在新旧两个版本的发布页面流程。

   默认展示新版流程，您也可以单击 切换到旧版，使用旧版固件发布功能，后期旧版固件发布功能将停用，停用前会提前进行通知。

   新版固件 OTA 发布流程

   1. 单击 发布 按钮，进入 版本发布 页面。

   2. 在 升级发布规则 区域中，选择 灰度发布 功能，可以按照不同数据区（非设备所在的地理位置）和不同的比例进行发布。

      • 不同数据区的设备相互隔离，可通过切换不同的数据区选择对应的设备，分别发布。

      • 灰度升级比例设置：通过调整灰度比例后提交，可以发布不同比例的设备数，建议前几次发布，设置较小的比例，如 5%。可以通过观察发布过程中的数据情况，决定每次发布的比例，直至发布到 100%。

      • 暂停发布：在发布过程中，如有用户反馈固件存在问题，可以直接暂停发布，以便降低影响。排查完问题后，可恢复发布。

      • 升级发布核心数据：主要展示以下数据。

        • 可升级设备总数

        • 指定升级设备数

        • 升级触发设备数

        • 升级成功设备数

          

      • 数据分析：提供升级状态分布和升级次数分布图。

      • 数据趋势：查看升级触发设备数和升级成功设备数随时间变化趋势图。

        

      • 升级设备明细：提供根据设备 ID 维度的设备升级明细，供用户查询。

   旧版固件升级发布流程

   1. 单击 发布 按钮，进入 版本发布 页面。

   2. 选择 切换到旧版。

      

   3. 单击 全量发布 或 灰度发布 后，系统将自动提交一个发布申请。涂鸦会审核固件的安全性，审核通过后，会向您选择的发布范围进行消费者推送。

      

      • 测试设备验证通过后，可进行 OTA 固件发布。
      • 支持多区发布。
      • 支持灰度发布和全量发布，可设置发布时间。灰度发布时，可选择地域（多选）、数量和版本号（多选）。
      • 确认发布后，对于未审核过的固件，需要预留 24 小时进行审核。对应已审核过的固件，无需预留审核时间。

类型二：自定义上传的固件

自定义固件，一般为产品开发中自定义上传的固件。同时，固件具备所属权限，只有具备该固件所属权的平台账号，才能进行新建固件版本操作.

1. 登录 涂鸦 IoT 开发平台。

2. 在左侧导航栏中，选择 产品 > 设备 > 固件 OTA。

3. 在 固件包来源 栏中，选择属性为 自定义上传 的需要更新的固件。

   

4. 单击 新建固件升级，进入新建页面后进行以下操作。

   • 选择一个固件版本：选择一个已经存在的固件版本。
   • 单击 新建固件版本：当没有固件版本可用，或者 关键版本 已有升级记录、不支持二次升级发布时，可以新建一个固件版本。
   更多信息，请参考上文 类型一 的配置。

   参数	说明
   基本信息	根据需求选择上传对应的固件，默认上传用于升级的 升级固件。若此新版本计划用于生产，则可以同时上传生产固件和用户区固件。
   版本生产配置	该配置主要用于生产授权。 运行模式：根据 SPI Flash 运行模式选择，涂鸦模组默认选择 QIO 即可，只有需要涂鸦生产的固件版本有此选项。 是否支持国家码：默认为支持。 是否支持 FFS 能力：默认为支持。

   

5. 保存固件，或保存并上架固件。

   完成基本信息和固件文件上传后，默认为未上架状态。若需要进行固件 OTA，则需要执行 保存并上架 操作。

   根据 设置允许使用范围，可以指定哪些产品可使用当前版本进行固件 OTA。

   

6. 升级新建固件。

   1. 在当前页面中单击 固件升级 或在左侧导航栏中进入 产品 > 设备 > 固件 OTA，选择对应产品固件，进行新建固件升级。

      

   2. 指定待升级的产品并填写相关参数后，单击 确定。

      

7. 参考上文 类型一 中的步骤 6、步骤 7 和步骤 8，进行自定义固件的 OTA 操作，完成固件升级。

类型三：生态设备接入 TuyaLink 的固件

此章节描述适用于智能化方式为 生态设备接入 （TuyaLink）的产品，您在创建产品时选择的设备开发方式为 开放协议接入。

1. 登录 涂鸦 IoT 开发平台。

2. 在左侧导航栏中，选择 产品 > 极速智能化 > 产品开发。

3. 找到并单击设备，进入产品开发流程。

4. 在 设备开发阶段，单击 新建固件，并进行相关版本管理，完成固件文件上传。

   

5. 保存并上架固件版本。

   

6. 其余操作，重复 类型一 和 类型二 的操作内容。

   采用生态设备接入的产品固件暂不支持固件差分升级。

附加功能：固件差分升级

固件升级，是实现设备远程更新的一项空中升级技术。在通用的固件升级场景中，针对设备固件往往采用整包升级的方式进行推送更新，即设备需要下载完整的升级包达到远程升级的目的。

此方式可能导致的问题是对于升级包过大的固件，会带来较大的流量消耗，以及对于硬件存储空间有一定的门槛要求。因此，部分设备无法按传统的固件升级方式完成远程更新，常见的如 NB-IoT、Cat.1 设备。此类设备需要用更小的文件包，实现固件升级。基于此固件进行 差分升级，便是用于解决此类场景的解决方案。

适用范围

仅适用于采用涂鸦差分升级 SDK 的设备固件，主要用于 NB-IoT 和 Cat.1 产品设备，同时支持 Matter 产品设备。

名词解释

名词	解释
目标版本	将要推送升级的目标固件版本。
待升级版本	准备要接收升级的固件版本。
用于差分的文件	该文件可以被差分算法识别，用于和另一个版本对应的差分文件。
版本差分包	通过目标版本和待升级版本的用于差分的文件计算生成的文件，用于实际推送的升级包。待升级版本设备可以根据差分包，还原目标版本固件功能内容，实现升级。

前提条件

差分升级前，请确认：

• 对应产品固件支持差分升级。
• 待升级的低版本固件存在 用于差分的文件。

第一步：新建固件版本

1. 登录 涂鸦 IoT 开发平台。

2. 在左侧导航栏中，选择 产品 > 设备 > 固件管理。

3. 选择一个固件，并单击 新增固件版本。

   

4. 根据页面提示，填写各项信息，并上传 用于差分的文件。

   

第二步：生成差分包

1. 在 固件版本管理 区域，单击 操作 栏的 差分管理，进入差分管理页面。

   

2. 单击 系统生成差分包。

   

3. 系统生成差分包。若低版本没有上传用于差分的文件，则不支持差分。

   

第三步：上架固件版本

1. 在 固件版本管理 区域，单击 上架状态 栏的 固件上架。

   

2. 固件上架后，上架状态 栏显示 已上架。

第四步：新增固件升级

1. 选择 产品 > 设备 > 固件 OTA，单击 新建固件升级。

2. 在 新建固件升级 窗口，找到 是否支持差分，开启差分升级，代表设备可拉取差分升级包。

   

3. 查看可用的、支持差分升级的差分包。

   

4. 单击 确认，即可生成固件升级记录，此时设备可拉取差分升级包。具体由设备端升级方式决定，不影响整包拉取。

第五步：验证升级

与普通固件升级 类型一 和 类型二 步骤相同。

第六步：发布升级

与普通固件升级 类型一 和 类型二 步骤相同。

常见问题

1：自定义的固件为什么无法新增版本？

当出现自定义固件无法上传新的固件文件（新增固件版本）时，主要原因为当前账号不是此固件的创建者或不具备此固件的权限。可以联系固件拥有人进行空间授权后，再新增版本。

2：固件管理里面为什么无法找到对应固件 key？

首先需确认此固件 key 是否为当前账号所创建。若此固件 key 不是当前账号创建的，则无法进行查看。

3：针对无地区信息的设备，能接收升级推送吗？

关于没有地区信息的设备，可分以下两种情况：

• 该设备为国内设备：当 App 上没有打开位置权限时，这类设备进行 OTA 升级，可能无法接收到推送。

• 该设备为国外设备：国外设备以国家码（即 App 注册时填写的账号地址）作为推送地址。若发布地区不是该地址，则可能无法接收到推送。

参考文档

更多固件管理指导说明，请参考 固件管理。