init: Air780EPM 官方 LuatOS 项目代码基线

- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00
commit 173dd6874f
813 changed files with 125484 additions and 0 deletions
@@ -0,0 +1,48 @@
+--[[
+@module  lbsloc2_app.lua
+@summary lbsloc2单基站定位应用
+@version 1.0
+@date    2025.08.13
+@author  王城钧
+@usage
+本文件为lbsloc2“单基站”定位功能演示，核心业务逻辑为：
+1. 等待网络就绪  
+2. 循环获取基站信息
+3. 请求定位 
+
+本文件没有对外接口，直接在main.lua中require "lbsloc2_app"就可以加载运行；
+]]
+
+-- 加载lbsloc2库
+local lbsLoc2 = require("lbsLoc2")
+
+-- lbsloc2循环定位函数
+local function lbsloc2_task_func()
+    while not socket.adapter(socket.dft()) do
+            log.warn("lbsloc2_task_func", "wait IP_READY", socket.dft())
+            -- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
+            -- 或者等待1秒超时退出阻塞等待状态;
+            -- 注意：此处的1000毫秒超时不要修改的更长；
+            -- 因为当使用exnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
+            -- 当exnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
+            -- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
+            sys.waitUntil("IP_READY", 1000)
+    end
+
+    -- 检测到了IP_READY消息
+    log.info("lbsloc2_task_func", "recv IP_READY", socket.dft())
+
+    while true do 
+        mobile.reqCellInfo(15)--进行基站扫描，超时时间为15s
+        sys.waitUntil("CELL_INFO_UPDATE", 3000)--等到扫描成功，超时时间3S
+        local lat, lng, t = lbsLoc2.request(5000)--仅需要基站定位给出的经纬度
+        --local lat, lng, t = lbsLoc2.request(5000,nil,nil,true)--需要经纬度和当前时间
+        --(时间格式{"year":2024,"min":56,"month":11,"day":12,"sec":44,"hour":14})
+        log.info("lbsLoc2", lat, lng, (json.encode(t or {})))--打印经纬度和时间
+        sys.wait(60000) -- 1分钟定位一次
+    end
+end
+
+sys.taskInit(lbsloc2_task_func)
+
+
@@ -0,0 +1,56 @@
+--[[
+@module  main.lua
+@summary LuatOS用户应用脚本文件入口，总体调度应用逻辑
+@version 1.0
+@date    2025.08.13
+@author  王城钧
+@usage
+本功能模块演示的内容为：
+使用Air780EPM开发板来演示lbsloc2“单基站”定位功能
+
+更多说明参考本目录下的readme.md文件
+]]
+
+--[[
+必须定义PROJECT和VERSION变量，Luatools工具会用到这两个变量，远程升级功能也会用到这两个变量
+PROJECT：项目名，ascii string类型
+        可以随便定义，只要不使用,就行
+VERSION：项目版本号，ascii string类型
+        如果使用合宙iot.openluat.com进行远程升级，必须按照"XXX.YYY.ZZZ"三段格式定义：
+            X、Y、Z各表示1位数字，三个X表示的数字可以相同，也可以不同，同理三个Y和三个Z表示的数字也是可以相同，可以不同
+            因为历史原因，YYY这三位数字必须存在，但是没有任何用处，可以一直写为999
+        如果不使用合宙iot.openluat.com进行远程升级，根据自己项目的需求，自定义格式即可
+]]
+
+PROJECT = "LBSLOC2_DEMO"
+VERSION = "001.999.000"
+
+-- 在日志中打印项目名和项目版本号
+log.info("main", "project name is ", PROJECT, "version is ", VERSION)
+
+
+-- 如果内核固件支持errDump功能，此处进行配置，【强烈建议打开此处的注释】
+-- 因为此功能模块可以记录并且上传脚本在运行过程中出现的语法错误或者其他自定义的错误信息，可以初步分析一些设备运行异常的问题
+-- 以下代码是最基本的用法，更复杂的用法可以详细阅读API说明文档
+-- 启动errDump日志存储并且上传功能，600秒上传一次
+-- if errDump then
+--     errDump.config(true, 600)
+-- end
+
+
+-- 使用LuatOS开发的任何一个项目，都强烈建议使用远程升级FOTA功能
+-- 可以使用合宙的iot.openluat.com平台进行远程升级
+-- 也可以使用客户自己搭建的平台进行远程升级
+-- 远程升级的详细用法，可以参考fota的demo进行使用
+
+-- 加载网络驱动设备功能模块
+require "netdrv_device"
+
+-- 加载lbsloc2单基站定位功能模块
+require "lbsloc2_app"
+
+
+-- 用户代码已结束---------------------------------------------
+-- 结尾总是这一句
+sys.run()
+-- sys.run()之后后面不要加任何语句!!!!!
@@ -0,0 +1,43 @@
+--[[
+@module  netdrv_4g
+@summary “4G网卡”驱动模块
+@version 1.0
+@date    2025.07.01
+@author  马梦阳
+@usage
+本文件为4G网卡驱动模块，核心业务逻辑为：
+1、监听"IP_READY"和"IP_LOSE"，在日志中进行打印；
+
+本文件没有对外接口，直接在其他功能模块中require "netdrv_4g"就可以加载运行；
+]]
+
+local function ip_ready_func(ip, adapter)
+    if adapter == socket.LWIP_GP then
+        -- 在位置1和2设置自定义的DNS服务器ip地址：
+        -- "223.5.5.5"，这个DNS服务器IP地址是阿里云提供的DNS服务器IP地址；
+        -- "114.114.114.114"，这个DNS服务器IP地址是国内通用的DNS服务器IP地址；
+        -- 可以加上以下两行代码，在自动获取的DNS服务器工作不稳定的情况下，这两个新增的DNS服务器会使DNS服务更加稳定可靠；
+        -- 如果使用专网卡，不要使用这两行代码；
+        -- 如果使用国外的网络，不要使用这两行代码；
+        socket.setDNS(adapter, 1, "223.5.5.5")
+        socket.setDNS(adapter, 2, "114.114.114.114")
+        
+        log.info("netdrv_4g.ip_ready_func", "IP_READY", socket.localIP(socket.LWIP_GP))
+    end
+end
+
+local function ip_lose_func(adapter)
+    if adapter == socket.LWIP_GP then
+        log.warn("netdrv_4g.ip_lose_func", "IP_LOSE")
+    end
+end
+
+
+-- 此处订阅"IP_READY"和"IP_LOSE"两种消息
+-- 在消息的处理函数中，仅仅打印了一些信息，便于实时观察4G网络的连接状态
+-- 也可以根据自己的项目需求，在消息处理函数中增加自己的业务逻辑控制，例如可以在连网状态发生改变时更新网络图标
+sys.subscribe("IP_READY", ip_ready_func)
+sys.subscribe("IP_LOSE", ip_lose_func)
+
+-- 在Air780EPM上，内核固件运行起来之后，默认网卡就是socket.LWIP_GP
+
@@ -0,0 +1,77 @@
+--[[
+@module  netdrv_eth_spi
+@summary “通过SPI外挂CH390H芯片的以太网卡”驱动模块
+@version 1.0
+@date    2025.07.24
+@author  马梦阳
+@usage
+本文件为“通过SPI外挂CH390H芯片的以太网卡”驱动模块，核心业务逻辑为：
+1、打开CH390H芯片供电开关；
+2、初始化spi0，初始化以太网卡，并且在以太网卡上开启DHCP(动态主机配置协议)；
+3、以太网卡的连接状态发生变化时，在日志中进行打印；
+
+直接使用Air780EPM V1.3版本开发板硬件测试即可；
+
+本文件没有对外接口，直接在其他功能模块中require "netdrv_eth_spi"就可以加载运行；
+]]
+
+local exnetif = require "exnetif"
+
+local function ip_ready_func(ip, adapter)
+    if adapter == socket.LWIP_ETH then
+        -- 在位置1和2设置自定义的DNS服务器ip地址：
+        -- "223.5.5.5"，这个DNS服务器IP地址是阿里云提供的DNS服务器IP地址；
+        -- "114.114.114.114"，这个DNS服务器IP地址是国内通用的DNS服务器IP地址；
+        -- 可以加上以下两行代码，在自动获取的DNS服务器工作不稳定的情况下，这两个新增的DNS服务器会使DNS服务更加稳定可靠；
+        -- 如果使用专网卡，不要使用这两行代码；
+        -- 如果使用国外的网络，不要使用这两行代码；
+        socket.setDNS(adapter, 1, "223.5.5.5")
+        socket.setDNS(adapter, 2, "114.114.114.114")
+
+        log.info("netdrv_eth_spi.ip_ready_func", "IP_READY", socket.localIP(socket.LWIP_ETH))
+    end
+end
+
+local function ip_lose_func(adapter)
+    if adapter == socket.LWIP_ETH then
+        log.warn("netdrv_eth_spi.ip_lose_func", "IP_LOSE")
+    end
+end
+
+
+-- 以太网联网成功（成功连接路由器，并且获取到了IP地址）后，内核固件会产生一个"IP_READY"消息
+-- 各个功能模块可以订阅"IP_READY"消息实时处理以太网联网成功的事件
+-- 也可以在任何时刻调用socket.adapter(socket.LWIP_ETH)来获取以太网是否连接成功
+
+-- 以太网断网后，内核固件会产生一个"IP_LOSE"消息
+-- 各个功能模块可以订阅"IP_LOSE"消息实时处理以太网断网的事件
+-- 也可以在任何时刻调用socket.adapter(socket.LWIP_ETH)来获取以太网是否连接成功
+
+--此处订阅"IP_READY"和"IP_LOSE"两种消息
+--在消息的处理函数中，仅仅打印了一些信息，便于实时观察“通过SPI外挂CH390H芯片的以太网卡”的连接状态
+--也可以根据自己的项目需求，在消息处理函数中增加自己的业务逻辑控制，例如可以在连网状态发生改变时更新网络图标
+sys.subscribe("IP_READY", ip_ready_func)
+sys.subscribe("IP_LOSE", ip_lose_func)
+
+
+local function netdrv_eth_spi_task_func()
+-- 配置SPI外接以太网芯片CH390H的单网卡，exnetif.set_priority_order使用的网卡编号为socket.LWIP_ETH
+-- 本demo使用Air780EPM V1.3版本开发板测试，开发板上的硬件配置为：
+-- GPIO20为CH390H以太网芯片的供电使能控制引脚
+-- 使用spi0，片选引脚使用GPIO8，中断引脚使用GPIO22
+-- 如果使用的硬件和以上描述的环境不同，根据自己的硬件配置修改以下参数
+    exnetif.set_priority_order({
+        {
+            ETHERNET = {
+                pwrpin = 20, 
+                tp = netdrv.CH390,
+                opts = {spi = 0, cs = 8, irq = 22}
+            }
+        }
+    })
+end
+
+-- 启动一个task，task的处理函数为netdrv_eth_spi_task_func
+-- 在处理函数中调用exnetif.set_priority_order设置网卡优先级
+-- 因为exnetif.set_priority_order要求必须在task中被调用，所以此处启动一个task
+sys.taskInit(netdrv_eth_spi_task_func)
@@ -0,0 +1,88 @@
+--[[
+@module  netdrv_multiple
+@summary 多网卡（4G网卡、通过SPI外挂CH390H芯片的以太网卡）驱动模块
+@version 1.0
+@date    2025.07.24
+@author  马梦阳
+@usage
+本文件为多网卡驱动模块，核心业务逻辑为：
+1、调用exnetif.set_priority_order配置多网卡的控制参数以及优先级；
+
+直接使用Air780EPM V1.3版本开发板硬件测试即可；
+
+本文件没有对外接口，直接在其他功能模块中require "netdrv_multiple"就可以加载运行；
+]]
+
+local exnetif = require "exnetif"
+
+-- 网卡状态变化通知回调函数
+-- 当exnetif中检测到网卡切换或者所有网卡都断网时，会触发调用此回调函数
+-- 当网卡切换切换时：
+--     net_type：string类型，表示当前使用的网卡字符串
+--     adapter：number类型，表示当前使用的网卡id
+-- 当所有网卡断网时：
+--     net_type：为nil
+--     adapter：number类型，为-1
+local function netdrv_multiple_notify_cbfunc(net_type,adapter)
+    -- 在位置1和2设置自定义的DNS服务器ip地址：
+    -- "223.5.5.5"，这个DNS服务器IP地址是阿里云提供的DNS服务器IP地址；
+    -- "114.114.114.114"，这个DNS服务器IP地址是国内通用的DNS服务器IP地址；
+    -- 可以加上以下两行代码，在自动获取的DNS服务器工作不稳定的情况下，这两个新增的DNS服务器会使DNS服务更加稳定可靠；
+    -- 如果使用专网卡，不要使用这两行代码；
+    -- 如果使用国外的网络，不要使用这两行代码；
+    socket.setDNS(adapter, 1, "223.5.5.5")
+    socket.setDNS(adapter, 2, "114.114.114.114")
+    
+    if type(net_type)=="string" then
+        log.info("netdrv_multiple_notify_cbfunc", "use new adapter", net_type, adapter)
+    elseif type(net_type)=="nil" then
+        log.warn("netdrv_multiple_notify_cbfunc", "no available adapter", net_type, adapter)
+    else
+        log.warn("netdrv_multiple_notify_cbfunc", "unknown status", net_type, adapter)
+    end
+end
+
+local function netdrv_multiple_task_func()
+    --设置网卡优先级
+    exnetif.set_priority_order(
+        {
+            -- “通过SPI外挂CH390H芯片”的以太网卡，使用Air780EPM V1.3版本开发板验证
+            {
+                ETHERNET = {
+                    -- 供电使能GPIO
+                    pwrpin = 20,
+                    -- 设置的多个“已经IP READY，但是还没有ping通”网卡，循环执行ping动作的间隔（单位毫秒，可选）
+                    -- 如果没有传入此参数，exnetif会使用默认值10秒
+                    ping_time = 3000,
+
+                    -- 连通性检测ip(选填参数)；
+                    -- 如果没有传入ip地址，exnetif中会默认使用httpdns能否成功获取baidu.com的ip作为是否连通的判断条件；
+                    -- 如果传入，一定要传入可靠的并且可以ping通的ip地址；
+                    -- ping_ip = "填入可靠的并且可以ping通的ip地址",
+
+                    -- 网卡芯片型号(选填参数)，仅spi方式外挂以太网时需要填写。
+                    tp = netdrv.CH390,
+                    opts = {spi=0, cs=8, irq=22}
+                }
+            },
+
+            -- 4G网卡
+            {
+                LWIP_GP = true
+            }
+        }
+    )
+end
+
+-- 设置网卡状态变化通知回调函数netdrv_multiple_notify_cbfunc
+exnetif.notify_status(netdrv_multiple_notify_cbfunc)
+
+-- 如果存在udp网络应用，并且udp网络应用中，根据应用层的心跳能够判断出来udp数据通信出现了异常；
+-- 可以在判断出现异常的位置，调用一次exnetif.check_network_status()接口，强制对当前正式使用的网卡进行一次连通性检测；
+-- 如果存在tcp网络应用，不需要用户调用exnetif.check_network_status()接口去控制，exnetif会在tcp网络应用通信异常时自动对当前使用的网卡进行连通性检测。
+
+
+-- 启动一个task，task的处理函数为netdrv_multiple_task_func
+-- 在处理函数中调用exnetif.set_priority_order设置网卡优先级
+-- 因为exnetif.set_priority_order要求必须在task中被调用，所以此处启动一个task
+sys.taskInit(netdrv_multiple_task_func)
@@ -0,0 +1,45 @@
+--[[
+@module  netdrv_pc
+@summary “pc模拟器网卡”驱动模块 
+@version 1.0
+@date    2025.07.01
+@author  朱天华
+@usage
+本文件为pc模拟器网卡驱动模块，核心业务逻辑为：
+1、监听"IP_READY"和"IP_LOSE"，在日志中进行打印；
+
+本文件没有对外接口，直接在其他功能模块中require "netdrv_pc"就可以加载运行；
+]]
+
+local function ip_ready_func(ip, adapter)    
+    if adapter == socket.ETH0 then
+        -- 在位置1和2设置自定义的DNS服务器ip地址：
+        -- "223.5.5.5"，这个DNS服务器IP地址是阿里云提供的DNS服务器IP地址；
+        -- "114.114.114.114"，这个DNS服务器IP地址是国内通用的DNS服务器IP地址；
+        -- 可以加上以下两行代码，在自动获取的DNS服务器工作不稳定的情况下，这两个新增的DNS服务器会使DNS服务更加稳定可靠；
+        -- 如果使用专网卡，不要使用这两行代码；
+        -- 如果使用国外的网络，不要使用这两行代码；
+        socket.setDNS(adapter, 1, "223.5.5.5")
+        socket.setDNS(adapter, 2, "114.114.114.114")
+
+        log.info("netdrv_pc.ip_ready_func", "IP_READY", socket.localIP(socket.ETH0))
+    end
+end
+
+local function ip_lose_func(adapter)    
+    if adapter == socket.ETH0 then
+        log.warn("netdrv_pc.ip_lose_func", "IP_LOSE")
+    end
+end
+
+
+
+--此处订阅"IP_READY"和"IP_LOSE"两种消息
+--在消息的处理函数中，仅仅打印了一些信息，便于实时观察pc模拟器网络的连接状态
+--也可以根据自己的项目需求，在消息处理函数中增加自己的业务逻辑控制，例如可以在连网状态发生改变时更新网络图标
+sys.subscribe("IP_READY", ip_ready_func)
+sys.subscribe("IP_LOSE", ip_lose_func)
+
+-- 设置默认网卡为socket.ETH0
+-- pc模拟器上的默认网卡仍然需要使用接口(socket.ETH0)来设置，因为exnetif扩展库当前还不支持模拟器
+socket.dft(socket.ETH0)
@@ -0,0 +1,29 @@
+--[[
+@module  netdrv_device
+@summary 网络驱动设备功能模块
+@version 1.0
+@date    2025.07.24
+@author  朱天华
+@usage
+本文件为网络驱动设备功能模块，核心业务逻辑为：根据项目需求，选择并且配置合适的网卡(网络适配器)
+1、netdrv_4g：socket.LWIP_GP，4G网卡；
+2、netdrv_eth_spi：socket.LWIP_ETH，通过SPI外挂CH390H芯片的以太网卡；
+3、netdrv_multiple：可以配置多种网卡的优先级，按照优先级配置，使用其中一种网卡连接外网；
+
+根据自己的项目需求，只需要require以上三种中的一种即可；
+
+
+本文件没有对外接口，直接在main.lua中require "netdrv_device"就可以加载运行；
+]]
+
+
+-- 根据自己的项目需求，只需要require以下三种中的一种即可；
+
+-- 加载“4G网卡”驱动模块
+require "netdrv_4g"
+
+-- 加载“通过SPI外挂CH390H芯片的以太网卡”驱动模块
+-- require "netdrv_eth_spi"
+
+-- 加载“可以配置优先级的多种网卡”驱动模块
+-- require "netdrv_multiple"
@@ -0,0 +1,82 @@
+## 功能模块介绍
+
+1、main.lua：主程序入口；
+
+2、netdrv_device.lua：网卡驱动设备，可以配置使用netdrv文件夹内的四种网卡(单4g网卡，单wifi网卡，单spi以太网卡，多网卡)中的任何一种网卡；
+
+3、lbsloc2_app.lua：合宙lbsloc2“单基站”定位功能模块； 
+
+## 演示功能概述
+
+使用Air780EPM开发板测试lbsloc2功能：
+
+1、lbsloc2“单基站”定位演示。
+
+2、netdrv_device：配置连接外网使用的网卡，目前支持以下三种选择（三选一）
+
+(1) netdrv_4g：4G网卡
+
+(2) netdrv_eth_spi：通过SPI外挂CH390H芯片的以太网卡
+
+(3) netdrv_multiple：支持以上两种网卡，可以配置两种网卡的优先级
+
+本功能为免费服务，由于单基站定位技术本身的原因，无法提供相对精准的定位服务。
+
+如对定位精度要求较高，可以参考airlbs的demo，选择收费的airlbs定位服务，缴费地址[合宙云平台](https://iot.openluat.com/finance/order)。
+
+## 演示硬件环境
+
+* ![img](https://docs.openluat.com/air780epm/luatos/app/driver/eth/image/RFSvb75NRoEWqYxfCRVcVrOKnsf.jpg)
+  1、Air780EPM V1.3版本开发板一块+可上网的sim卡一张+4g天线一根+网线一根：
+  
+  - sim卡插入开发板的sim卡槽
+  - 天线装到开发板上
+  - 网线一端插入开发板网口，另外一端连接可以上外网的路由器网口
+  
+  2、TYPE-C USB数据线一根 + USB转串口数据线一根，Air780EPM V1.3版本开发板和数据线的硬件接线方式为：
+  
+  - Air780EPM V1.3版本开发板通过TYPE-C USB口供电；（外部供电/USB供电 拨动开关 拨到 USB供电一端）
+  - TYPE-C USB数据线直接插到核心板的TYPE-C USB座子，另外一端连接电脑USB口；
+
+## 演示软件环境
+
+1、Luatools下载调试工具
+
+2、[Air780EPM V2012版本固件]([固件版本 - luatos@air780epm - 合宙模组资料中心](https://docs.openluat.com/air780epm/luatos/firmware/version/))（理论上，2025年8月10日之后发布的固件都可以）
+
+## 演示核心步骤
+
+1、搭建好硬件环境
+
+2、demo脚本代码netdrv_device.lua中，按照自己的网卡需求启用对应的Lua文件
+
+- 如果需要单4G网卡，打开require "netdrv_4g"，其余注释掉
+- 如果需要以太网卡，打开require "netdrv_eth_spi"，其余注释掉
+- 如果需要多网卡，打开require "netdrv_multiple"，其余注释掉；同时netdrv_multiple.lua中的ssid = "茶室-降功耗,找合宙!", password = "Air123456", 修改为自己测试时wifi热点的名称和密码；注意：仅支持2.4G的wifi，不支持5G的wifi
+
+3、烧录内核固件和lbsloc2相关demo成功后，自动开机运行运行
+
+4、可以看到代码运行结果如下，不管是在选择什么网卡场景下，基本都是如下情况：
+
+以下是默认使用4G网卡下使用lbsloc2“单基站”应用场景的定位演示的日志
+
+日志中如果出现以下类似打印则说明定位成功：
+
+lbsLoc2 031.1346219 121.5382010 {}
+
+```
+[2025-08-18 15:50:04.995][000000006.372] D/user.lbsLoc2 free.bs.luatos.com 12411
+
+[2025-08-18 15:50:05.001][000000006.372] D/socket connect to free.bs.luatos.com,12411
+
+[2025-08-18 15:50:05.005][000000006.373] dns_run 674:free.bs.luatos.com state 0 id 1 ipv6 0 use dns server2, try 0
+
+[2025-08-18 15:50:05.011][000000006.413] D/mobile TIME_SYNC 0
+
+[2025-08-18 15:50:05.016][000000006.417] dns_run 691:dns all done ,now stop
+
+[2025-08-18 15:50:05.154][000000006.582] D/user.lbsLoc2 rx 0030114326912151830201
+
+[2025-08-18 15:50:05.166][000000006.585] I/user.lbsLoc2 031.1346219 121.5382010 {}
+
+```