LuatOS扩展库API——【libfota2】远程升级

LuatOS 是面向物联网设备的轻量级嵌入式 Lua 脚本运行框架 / 实时系统基于 Lua 5.3 深度优化用于 4G‑Cat.1、MCU 等物联网终端。LuatOS 开发特点是基于 Lua 脚本、协程多任务设计当前LuatOS共有70多个核心库20多个扩展库1000多个应用demo示例覆盖所有基础应用开发方便。一、概述FOTA远程升级功能是物联网设备的核心功能之一它允许设备通过无线网络更新固件而无需物理接触。在LuatOS开发模式下固件分为两部分core(底层核心固件)和script(用户脚本)。远程升级时core采用差分升级方式而 script 则采用全量覆盖升级方式。您可以选择仅升级script、仅升级core或同时升级corescript。LuatOS主要提供了两套FOTA接口传统的libfota和更新的libfota2两者都支持通过合宙官方IoT平台和自建第三方HTTP服务器进行升级需要注意的是第三方http服务器需要满足如下两点-- 若需要升级, 响应http 200, body为升级文件的内容-- 若不需要升级, 响应300或以上的代码,务必注意为了更清晰地了解这两个库的特点下表对比了它们的主要特性。libfota2 是LuatOS提供的升级版FOTA接口它通过opts表传递参数相比传统的libfota库在接口清晰度和易用性上有显著提升。对于新开发的LuatOS项目建议优先选择libfota2来实现远程升级功能。二、核心示例1、核心示例是指使用本库文件提供的核心API开发的基础业务逻辑的演示代码2、核心示例的作用是帮助开发者快速理解如何使用本库所以核心示例的逻辑都比较简单3、更加完整和详细的demo请参考 LuatOS仓库 中各个产品目录下的demo/fota/fota2--用法实例locallibfota2require(libfota2)-- 升级结果的回调函数-- 功能:获取fota的回调函数-- 参数:-- result:number类型-- 0表示成功-- 1表示连接失败-- 2表示url错误-- 3表示服务器断开-- 4表示接收报文错误-- 5表示使用iot平台VERSION需要使用 xxx.yyy.zzz形式localfunctionfota_cb(ret)log.info(fota,ret)ifret0thenlog.info(升级包下载成功,重启模块)rtos.reboot()elseifret1thenlog.info(连接失败,请检查url拼写或服务器配置(是否为内网))elseifret2thenlog.info(url错误,检查url拼写)elseifret3thenlog.info(服务器断开,检查服务器白名单配置)elseifret4thenlog.error(FOTA 失败,原因可能有\n..1) 服务器返回 200/206 但报文体为空(0 字节—— 通常是升级包文件缺失或 URL 指向空文件\n..2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效\n..3) 已经是最新版本无需升级)elseifret5thenlog.info(版本号书写错误,iot平台版本号需要使用xxx.yyy.zzz形式)elselog.info(不是上面几种情况 ret为,ret)endendlibfota2.request(fota_cb)-- 若需要定时升级sys.timerLoopStart(libfota2.request,4*3600*1000,fota_cb)三、常量详解libfota2核心库没有常量。四、函数详解libfota2.request(cbFnc, opts)功能发起远程升级libfota2.request 是LuatOS为物联网设备提供的一个强大、灵活且安全的远程固件升级接口它能极大简化通过合宙平台或私有服务器实现设备FOTA功能的开发流程。参数cbFnc参数含义升级包下载结果回调函数用于返回升级包下载结果。回调函数的调用形式为cbFnc(result) result:number类型0表示成功1表示连接失败2表示url错误3表示服务器断开4表示接收报文错误5表示使用iot平台VERSION需要使用 xxx.yyy.zzz形式 数据类型function类型 取值范围任意有效的函数名都行 是否必选必须传入此参数 注意事项暂无 参数示例如下方所示定义了一个函数fota_cb就可以做为此参数传入localfunctionfota_cb(result)log.info(fota,result)ifresult0thenlog.info(升级包下载成功,重启模块)rtos.reboot()elseifresult1thenlog.info(连接失败,请检查url拼写或服务器配置(是否为内网))elseifresult2thenlog.info(url错误,检查url拼写)elseifresult3thenlog.info(服务器断开,检查服务器白名单配置)elseifresult4thenlog.error(FOTA 失败,原因可能有\n..1) 服务器返回 200/206 但报文体为空(0 字节—— 通常是升级包文件缺失或 URL 指向空文件\n..2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效\n..3) 已经是最新版本无需升级)elseifresult5thenlog.info(版本号书写错误,iot平台版本号需要使用xxx.yyy.zzz形式)elselog.info(不是上面几种情况 result为,result)endendopts参数含义fota升级参数配置参数为table类型table内容格式说明如下{-- 参数含义指定固件升级服务器的URL。默认值是合宙iot平台的升级地址。所以若使用合宙iot平台,则不 需要填-- 数据类型string类型-- 取值范围支持HTTP、HTTPS支持域名、IP地址支持自定义端口标准的HTTP URL格式都支持-- 是否必选可选传入此参数-- 注意事项-- 如果是使用合宙IOT平台不需要填写URL, 因为默认值是合宙iot平台的升级地址-- 如果是自建的OTA服务器, 则需要填写正确的URL, 例如 http://192.168.1.5:8000/update-- 如果自建OTA服务器,且url包含全部参数,不需要额外添加参数, 请在url前面添加 ###-- 如果不加###则默认会上传如下参数--1. opts.version string 版本号, 默认是 固件版本号.xxx.zzz格式。注固件版本号是 rtos.version()返回的版本号xxx.zzzz是_G.VERSION参数中x和z--2. opts.timeout int 请求超时时间, 默认300000毫秒,单位毫秒--3. opts.project_key string 合宙IOT平台的项目key, 默认取全局变量PRODUCT_KEY,自建服务器不用填--4. opts.imei string 设备识别码, Cat.1模块默认取IMEIwifi模块默认取WLAN的STA MAC地 址mcu默认取 mcu.unique_id() 返回的唯一ID--5. opts.firmware_name string 底层版本号默认是 _G.PROJECT.. _LuatOS-SoC_ .. rtos.bsp()其中rtos.bsp()返回的是模组型号-- 参数示例-- 合宙iot服务器local opts {}-- 自建服务器库会自动附加默认参数(imei, version等):local opts { url http://192.168.1.5:8000/update%simeixxxxxxxproject_keyxxxxxxxxfirmware_namexxxxxxxxxversionxxxxxxxx }-- 自建服务器,且url包含全部参数,不需要额外添加参数, 请在url前面添加###local opts { url ###http://192.168.1.5:8000/update?device_id12345fw_ver1.2.3}url,-- 参数含义请求的版本号-- 数据类型string类型-- 取值范围合宙IOT有一套版本号体系,不传就是合宙规则默认是 BSP版本号.xxxx.zzz格式, 自建服务器的话当然是自行约定版本号了注BSP版本号是通过rtos.version()返回的版本号xxx.zzz是_G.VERSION参数中x和z-- 是否必选可选传入此参数-- 注意事项暂无-- 参数示例默认BSP版本号.xxx.zzz是2012.001.000或者自定义1.0.0version,-- 参数含义上网使用的网卡ID-- 数据类型number或者nil-- 取值范围number类型时取值范围参考socket api中的常量详解-- 是否必选可选传入此参数-- 注意事项如果没有传入此参数内核固件会自动选择当前时间点其他功能模块设置的默认网卡-- 除非你HTTP请求时一定要使用某一种网卡才设置此参数-- 如果没什么特别要求不要设置此参数使用系统中设置的默认网卡即可 -- 一般来说LuatOS的网络应用demo中都会有netdrv_device功能模块设置默认网卡-- 所以建议使用http.request接口时不要设置此参数直接使用netdrv_device设置的默认网卡就行-- 参数示例socket.LWIP_GP表示使用4G网卡adapter,-- 参数含义设置整个 FOTA HTTP 请求过程的超时时间-- 数据类型int类型,-- 取值范围number类型时取值范围为大于等于0的整数0表示永久等待-- 是否必选可选传入此参数-- 注意事项暂无-- 参数示例300000表示300stimeout,-- 参数含义合宙IOT平台的项目key, 默认取全局变量PRODUCT_KEY. 自建服务器不用填-- 数据类型string类型-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项仅用于合宙 IoT 平台。自建服务器不需要此参数。--如果未设置库会尝试从全局变量 PRODUCT_KEY 中获取。-- 参数示例user123 或者 nilproject_key,-- 参数含义设备识别码,用于服务器识别具体设备-- 数据类型string类型-- 取值范围默认取IMEI(Cat.1模块)或WLAN的STA MAC地址 (wifi模块)或 mcu.unique_id()获取MCU唯一ID-- 是否必选可选传入此参数-- 注意事项暂无-- 参数示例imei mobile.imei(),imei,-- 参数含义固件名称-- 数据类型string类型-- 取值范围默认是 _G.PROJECT.. _LuatOS-SoC_ .. rtos.bsp()-- 是否必选可选传入此参数-- 注意事项暂无-- 参数示例FOTA2_DEMO_LuatOS-SoC_Air780EPMfirmware_name,-- 参数含义服务器ca证书数据-- 数据类型string或者nil-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项当客户端需要验证服务器证书时需要此参数如果证书数据在一个文件中要把文件内容读出来赋值给server_ca_cert-- 参数示例例如通过Luatools烧录了server_ca.crt文件就可以通过io.readFile(/luadb/server_ca.crt)读出文件内容赋值给赋值给server_ca_certserver_cert,-- 参数含义客户端证书数据-- 数据类型string或者nil-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项当服务器需要验证客户端证书时需要此参数如果证书数据在一个文件中要把文件内容读出来赋值给client_cert-- 参数示例例如通过Luatools烧录了clinet.crt文件就可以通过io.readFile(/luadb/clinet.crt)读出文件内容赋值给赋值给client_certclient_cert,-- 参数含义加密后的客户端私钥数据-- 数据类型string或者nil-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项当服务器需要验证客户端证书时需要此参数如果加密后的私钥数据在一个文件中要把文件内容读出来赋值给client_key-- 参数示例例如通过Luatools烧录了clinet.key文件就可以通过io.readFile(/luadb/clinet.key)读出文件内容赋值给client.keyclient_key,-- 参数含义客户端私钥口令数据-- 数据类型string或者nil-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项当服务器需要验证客户端证书时需要此参数如果加密后的私钥数据在一个文件中要把文件内容读出来赋值给client_password-- 参数示例例如通过Luatools烧录了clinet.password文件就可以通过io.readFile(/luadb/clinet.password)读出文件内容赋值给client_passwordclient_password,-- 参数含义HTTP请求方法-- 数据类型string-- 取值范围支持GET、POST、HEAD等所有HTTP请求方法请求方法用大写字母表示-- 是否必选可选传入此参数如果没有传入此参数或者传入了nil类型则使用默认值默认值分为以下两种情况-- 如果没有设置filesformsbodybodyfile参数则默认为GET-- 如果至少设置了filesformsbodybodyfile中的一种参数则默认为POST-- 注意事项暂无-- 参数示例GET请求时填GETPOST请求时填POSTmethod,-- 参数含义HTTP请求头列表键值对的形式-- 数据类型table或者nil-- 取值范围当为table数据类型时请求头列表中支持一个或者多个请求头-- 是否必选可选传入此参数-- 注意事项暂无-- 参数示例{-- [Content-Type] application/x-www-form-urlencoded,-- [self_defined_key] self_defined_value-- }headers,-- 参数含义HTTP请求体-- 数据类型string或者zbuff或者nil-- 取值范围无特别限制-- 是否必选可选传入此参数-- 注意事项如果请求体是一个文件中的内容需要把文件内容读出来赋值给body使用-- 参数示例123456 或者 一个zbuff对象 或者 nilbody,}数据类型table或者nil 取值范围参考参数含义内各字段说明 是否必选可选传入此参数 注意事项暂无 参数示例如下方所示,如果url是http://192.168.1.5:8000/updateversion是1.0.0--local opts {-- url http://192.168.1.5:8000/update,-- version 1.0.0--}返回值无示例本示例章节仅列举一些常用功能的核心代码片段更加完整和详细的demo请参考 https://gitee.com/openLuat/LuatOS/tree/master/module 各个产品目录下的demo/fota2文件夹下内容--用法实例locallibfota2require(libfota2)-- 升级结果的回调函数-- 功能:获取fota的回调函数-- 参数:-- result:number类型-- 0表示成功-- 1表示连接失败-- 2表示url错误-- 3表示服务器断开-- 4表示接收报文错误-- 5表示使用iot平台VERSION需要使用 xxx.yyy.zzz形式localfunctionfota_cb(ret)log.info(fota,ret)ifret0thenlog.info(升级包下载成功,重启模块)rtos.reboot()elseifret1thenlog.info(连接失败,请检查url拼写或服务器配置(是否为内网))elseifret2thenlog.info(url错误,检查url拼写)elseifret3thenlog.info(服务器断开,检查服务器白名单配置)elseifret4thenlog.error(FOTA 失败,原因可能有\n..1) 服务器返回 200/206 但报文体为空(0 字节—— 通常是升级包文件缺失或 URL 指向空文件\n..2) 服务器返回 4xx/5xx 等异常状态码 —— 请确认升级包已上传、URL 正确、鉴权信息有效\n..3) 已经是最新版本无需升级)elseifret5thenlog.info(版本号书写错误,iot平台版本号需要使用xxx.yyy.zzz形式)elselog.info(不是上面几种情况 ret为,ret)endendlibfota2.request(fota_cb)五、模组支持说明支持LuatOS开发的所有产品都支持libfota2扩展库。