mobile - 蜂窝网络

作者：拓毅恒

一、概述

mobile 核心库允许在 LuatOS 平台上管理蜂窝网络相关功能，包括 SIM 卡管理、网络状态查询、基站信息获取、APN 设置等。该模块提供了丰富的 API，用于实现设备的网络连接、状态监控和特殊功能配置。

LuatOS 提供的 mobile 核心库适用于蜂窝通信模块，可用于设备联网、信号质量监测、小区信息获取等场景，为物联网设备提供稳定可靠的通信能力。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/mobile

-- 简单演示

log.info("imei", mobile.imei())
log.info("imsi", mobile.imsi())
local sn = mobile.sn()
if sn then
    log.info("sn",   sn:toHex())
end
log.info("muid", mobile.muid())
log.info("iccid", mobile.iccid())
log.info("csq", mobile.csq())
log.info("rssi", mobile.rssi())
log.info("rsrq", mobile.rsrq())
log.info("rsrp", mobile.rsrp())
log.info("snr", mobile.snr())
log.info("simid", mobile.simid())

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

3.1 网络注册状态常量

这些常量用于表示设备的网络注册状态：

mobile.UNREGISTER

常量含义：未注册；
数据类型：number；
示例代码：
          if mobile.status() == mobile.UNREGISTER then
              log.info("未注册")
          end；

mobile.REGISTERED

常量含义：已注册；
数据类型：number；
示例代码：
          if mobile.status() == mobile.REGISTERED then
             log.info("已注册")
          end；

mobile.SEARCH

常量含义：正在搜索中；
数据类型：number；
示例代码：
          if mobile.status() == mobile.SEARCH then
              log.info("正在搜索网络")
          end；

mobile.DENIED

常量含义：注册被拒绝；
数据类型：number；
示例代码：
          if mobile.status() == mobile.DENIED then
              log.info("注册被拒绝")
          end；

mobile.UNKNOW

常量含义：未知状态；
数据类型：number；
示例代码：
          if mobile.status() == mobile.UNKNOW then
              log.info("未知状态")
          end；

mobile.REGISTERED_ROAMING

常量含义：已注册,漫游；
数据类型：number；
示例代码：
          if mobile.status() == mobile.REGISTERED_ROAMING then
              log.info("已注册,漫游")
          end；

mobile.SMS_ONLY_REGISTERED

常量含义：已注册,仅SMS；
数据类型：number；
示例代码：
          if mobile.status() == mobile.SMS_ONLY_REGISTERED then
              log.info("已注册,仅SMS")
          end；

mobile.SMS_ONLY_REGISTERED_ROAMING

常量含义：已注册,漫游,仅SMS；
数据类型：number；
示例代码：
          if mobile.status() == mobile.SMS_ONLY_REGISTERED_ROAMING then
              log.info("已注册,漫游,仅SMS")
          end；

mobile.EMERGENCY_REGISTERED

常量含义：已注册,紧急服务；
数据类型：number；
示例代码：
          if mobile.status() == mobile.EMERGENCY_REGISTERED then
              log.info("已注册,紧急服务")
          end；

mobile.CSFB_NOT_PREFERRED_REGISTERED

常量含义：已注册,非主要服务；
数据类型：number；
示例代码：
          if mobile.status() == mobile.CSFB_NOT_PREFERRED_REGISTERED then
              log.info("已注册,非主要服务")
          end；

mobile.CSFB_NOT_PREFERRED_REGISTERED_ROAMING

常量含义：已注册,非主要服务,漫游；
数据类型：number；
示例代码：
          if mobile.status() == mobile.CSFB_NOT_PREFERRED_REGISTERED_ROAMING then
              log.info("已注册,非主要服务,漫游")
          end；

3.2 PIN 码操作常量

这些常量用于 mobile.simPin() 函数中，控制 SIM 卡的 PIN 码操作：

mobile.PIN_VERIFY

常量含义：验证PIN码操作；
数据类型：number；
示例代码：
          local result = mobile.simPin(mobile.PIN_VERIFY, "1234")
          log.info("PIN验证结果", result)；

mobile.PIN_CHANGE

常量含义：更换PIN码操作；
数据类型：number；
示例代码：
          local result = mobile.simPin(mobile.PIN_CHANGE, "1234", "5678")
          log.info("PIN更换结果", result)；

mobile.PIN_ENABLE

常量含义：使能PIN码验证；
数据类型：number；
示例代码：
          local result = mobile.simPin(mobile.PIN_ENABLE, "1234")
          log.info("PIN使能结果", result)；

mobile.PIN_DISABLE

常量含义：关闭PIN码验证；
数据类型：number；
示例代码：
          local result = mobile.simPin(mobile.PIN_DISABLE, "1234")
          log.info("PIN关闭结果", result)；

mobile.PIN_UNBLOCK

常量含义：解锁PIN码；
数据类型：number；
示例代码：
          local result = mobile.simPin(mobile.PIN_UNBLOCK, "123456", "5678")
          log.info("PIN解锁结果", result)；

3.3 高级配置常量 (mobile.CONF_XXX)

这些常量用于 mobile.config() 函数中，用于配置蜂窝网络模块的高级功能；这些配置通常需要在飞行模式下设置才能生效，配置完成后再退出飞行模式；仅支持 Air780EXXX 系列和 Air8000 系列模块。

mobile.CONF_RESELTOWEAKNCELL

常量含义：小区重选信号差值门限；
数据类型：number；
取值范围：0-15（单位：dBm），不能大于15dBm；推荐值：根据实际环境调整，城市环境可设置为5-10，乡村环境可设置为10-15；
注意事项：当满足协议规定的小区切换条件时，额外看当前小区和目标小区的信号差值，如果当前小区的RSRP-目标小区的RSRP大于这个门限，就不切换；
         当相邻基站的信号强度比当前服务基站强过这个门限值时，设备会触发小区重选；这个参数的设置会影响设备的网络稳定性和功耗；
         当设备在信号边缘频繁切换小区导致网络不稳定时，可增大此值减少切换频率；当设备在强信号区域但仍连接弱信号基站时，可减小此值；必须在飞行模式下设置才能生效；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 进入飞行模式
         mobile.flymode(0, true)
         -- 设置小区重选信号差值门限为8dBm
         mobile.config(mobile.CONF_RESELTOWEAKNCELL, 8)
         -- 退出飞行模式
         mobile.flymode(0, false)

mobile.CONF_CE_MODE

常量含义：attach模式配置；
数据类型：number；
取值范围：0：EPS ONLY模式（仅支持4G网络）；
         2：混合模式（支持多种网络制式）；
注意事项：控制设备的网络附着模式，影响设备的网络连接行为；
         当遇到IMSI detach导致的脱网问题时，可以尝试设置为0；在4G网络覆盖良好的区域，设置为0可获得更稳定的连接；
         设置为EPS ONLY模式（0）时，会取消短信功能；实际效果可能因网络环境和运营商策略而异；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 进入飞行模式
         mobile.flymode(0, true)
         -- 设置为EPS ONLY模式（仅4G）
         mobile.config(mobile.CONF_CE_MODE, 0)
         -- 退出飞行模式
         mobile.flymode(0, false)

mobile.CONF_SIM_WC_MODE

常量含义：SIM写入次数的配置和读取；
数据类型：number；
取值范围：0：关闭统计；
         1：开启统计（默认状态）；
         2：读取统计值（异步操作，通过系统消息SIM_IND获取结果）；
         3：清空统计值；
注意事项：控制SIM卡写入次数的统计功能；可用于监控SIM卡的健康状态和使用寿命；监控频繁写入SIM卡的应用（如频繁更新联系人、短信等）；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 开启统计
         mobile.config(mobile.CONF_SIM_WC_MODE, 1)

         -- 读取统计值（异步）
         sys.subscribe("SIM_IND", function(stats, value)
             if stats == "SIM_WC" then
                 log.info("sim", "write counter", value)
             end
         end)
         mobile.config(mobile.CONF_SIM_WC_MODE, 2)

         -- 清空统计值
         mobile.config(mobile.CONF_SIM_WC_MODE, 3)

mobile.CONF_FAKE_CELL_BARTIME

常量含义：伪基站禁止接入的时间；
数据类型：number；
取值范围：0：取消伪基站禁止接入限制；
         其他值：禁止接入的时间（最大值：0xffff 永久禁止接入）；
注意事项：配置设备禁止接入被识别为伪基站的小区的时长；有助于提高设备的通信安全性，防止伪基站攻击；
         适用于对通信安全要求高的应用场景；在伪基站较多的区域提高设备安全性；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 进入飞行模式
         mobile.flymode(0, true)
         -- 设置为永久禁止接入被识别为伪基站的小区
         mobile.config(mobile.CONF_FAKE_CELL_BARTIME, 0xffff)
         -- 退出飞行模式
         mobile.flymode(0, false)

mobile.CONF_RESET_TO_FACTORY

常量含义：删除已保存的协议栈参数；
数据类型：number；
取值范围：1：清除设备保存的所有网络协议栈参数配置；
注意事项：重启设备后将使用默认配置；
         适用于网络配置出现异常且无法通过其他方式恢复和准备将设备恢复出厂设置的场景下；
         操作生效需要重启设备；会清除所有之前的自定义网络配置；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 进入飞行模式
         mobile.flymode(0, true)
         -- 触发恢复出厂设置
         mobile.config(mobile.CONF_RESET_TO_FACTORY, 1)
         -- 退出飞行模式
         mobile.flymode(0, false)
         -- 重启设备使设置生效
         rtos.reboot()

mobile.CONF_USB_ETHERNET

常量含义：蜂窝网络模块的USB以太网卡控制；
数据类型：number；
取值范围：0x01：开启RNDIS功能；
         0x03：开启RNDIS功能，使用NAT模式(基站分配ip)；
         0x05：开启ECM功能；
         0x07：开启ECM功能，使用NAT模式(基站分配ip)；
注意事项：控制设备的USB以太网卡功能，通过位操作来控制不同的功能；
         仅在开启前可以修改；bit2：协议选择（1ECM协议，0RNDIS协议）；
         必须在飞行模式下设置才能生效；
         仅支持Air780EXXX系列和Air8000系列模块；
示例代码：-- 进入飞行模式
         mobile.flymode(0, true)
         -- 设置开启RNDIS协议（bit0=1, bit1=1, bit2=0 → 0x03）
         mobile.config(mobile.CONF_USB_ETHERNET, 0x03)
         -- 退出飞行模式
         mobile.flymode(0, false)

3.3.1 典型应用示例

1. 增强网络稳定性配置

-- 进入飞行模式
mobile.flymode(0, true)
-- 设置小区重选信号差值门限为10dBm
mobile.config(mobile.CONF_RESELTOWEAKNCELL, 10)
-- 退出飞行模式
mobile.flymode(0, false)

2. SIM 卡写入次数监控

-- 开启 SIM 卡写入次数统计
mobile.config(mobile.CONF_SIM_WC_MODE, 1)

function sim_status(stats, value)
    if stats == "SIM_WC" then
        log.info("SIM卡写入统计", "当前写入次数:", value)
        -- 可以在这里添加写入次数过多时的告警逻辑
        if value > 10000 then
            log.warn("SIM卡", "写入次数过多，会影响SIM卡使用寿命")
        end
    end
end

-- 订阅 SIM_IND 事件以获取统计结果
sys.subscribe("SIM_IND", sim_status)

-- 定期查询 SIM 卡写入次数
sys.taskInit(function()
    while true do
        -- 触发读取统计值
        mobile.config(mobile.CONF_SIM_WC_MODE, 2)
        -- 每24小时查询一次
        sys.wait(24 * 3600 * 1000)
    end
end)

3.4 系统消息常量

"SIM_IND"

常量含义：SIM卡状态变化通知消息；
数据类型：string；
注意事项：当SIM卡状态发生变化时，系统会发送此消息；
示例代码：-- 订阅SIM卡状态变化通知
         function get_sim_status(status, value)
             -- status的取值有:
             -- "RDY": SIM卡就绪, value为nil
             -- "NORDY": 无SIM卡, value为nil
             -- "SIM_PIN": 需要输入PIN, value为nil
             -- "GET_NUMBER": 获取到电话号码(不一定有值), value为nil
             -- "SIM_WC": SIM卡的写入次数统计,掉电归0, value为统计值
             log.info("sim status", status, value)
         end

         sys.subscribe("SIM_IND", get_sim_status)

"CELL_INFO_UPDATE"

常量含义：基站数据已更新通知消息；
数据类型：string；
注意事项：当基站数据更新时，系统会发送此消息；
示例代码：-- 订阅基站数据更新通知
         function get_cellinfo()
             log.info("cell", json.encode(mobile.getCellInfo()))
         end

         sys.subscribe("CELL_INFO_UPDATE", get_cellinfo)

"SCELL_INFO"

常量含义：服务小区额外信息更新通知消息；
数据类型：string；
注意事项：当服务小区额外信息更新时，系统会发送此消息；
示例代码：-- 订阅服务小区额外信息更新通知
         function get_service_cellinfo()
             log.info("service cell", mobile.scell())
         end

         sys.subscribe("SCELL_INFO", get_service_cellinfo)

"NTP_UPDATE"

常量含义：时间已经同步通知消息；
数据类型：string；
注意事项：对于电信/移动的卡，联网后基站会下发时间，但联通卡不会，务必留意；
示例代码：-- 订阅时间同步通知
         function time_update()
             log.info("mobile", "time", os.date())
         end

         sys.subscribe("NTP_UPDATE", time_update)

"CSCON"

常量含义：RRC状态通知消息；
数据类型：string；
注意事项：当无线资源控制(RRC)状态发生变化时，系统会发送此消息；
示例代码：-- 订阅RRC状态通知
         function get_rrc_state(state)
             -- state 1 CONNECT 0 IDLE
             log.info("mobile", "CSCON", state)
         end

         sys.subscribe("CSCON", get_rrc_state)

四、函数详解

mobile.imei(index)

功能

获取 IMEI（国际移动设备识别码）

参数

index

参数含义：编号；
数据类型：number；
取值范围：0或1，不填默认0；
是否必选：可选传入此参数；
注意事项：在支持双卡的模块上才会出现0或1的情况；
参数示例：0 -- 表示获取第一张SIM卡的IMEI

返回值

local result = mobile.imei(index)

result

含义说明：当前的IMEI值；
数据类型：string；
取值范围：IMEI字符串，若失败返回nil；
返回示例："861234567890123" -- IMEI号

示例

log.info("imei", mobile.imei())

mobile.imsi(index)

功能

获取 IMSI（国际移动用户识别码）

参数

index

参数含义：编号；
数据类型：number；
取值范围：0或1，不填默认0；
是否必选：可选传入此参数；
注意事项：必须等待sim卡准备就绪后，才能获取成功；
         在支持双卡的模块上才会出现0或1的情况；
参数示例：0 -- 表示获取第一张SIM卡的IMSI

返回值

local result = mobile.imsi(index)

result

含义说明：当前的IMSI值；
数据类型：string；
取值范围：IMSI字符串，若失败返回nil；
返回示例："460111234567890" -- IMSI字符串

示例

if mobile.simPin() then
    log.info("SIM卡准备就绪，开始获取imsi")
    log.info("imsi", mobile.imsi())
else
    log.info("SIM卡未准备就绪，可能未插入SIM卡或SIM卡有问题")
end

mobile.muid()

功能

获取 MUID（设备唯一标识）

参数

无

返回值

local result = mobile.muid()

result

含义说明：当前的MUID值；
数据类型：string；
取值范围：MUID字符串，若失败返回nil；
返回示例："01234567xxxxxxx" -- 一个唯一的MUID字符串

示例

log.info("muid", mobile.muid())

mobile.iccid(id)

功能

获取或设置 ICCID（集成电路卡识别码）

参数

id

参数含义：SIM卡的编号；
数据类型：number；
取值范围：0或1,不填默认0；
是否必选：可选传入此参数；
注意事项：必须等待sim卡准备就绪后，才能获取成功；
参数示例：0 -- 表示获取第一张SIM卡的ICCID

返回值

local result = mobile.iccid(id)

result

含义说明：ICCID值；
数据类型：string；
取值范围：ICCID字符串，若失败返回nil；
返回示例："89860855102480513111" -- 一个20位的ICCID字符串

示例

if mobile.simPin() then
    log.info("SIM卡准备就绪，开始获取iccid")
    log.info("iccid", mobile.iccid())
else
    log.info("SIM卡未准备就绪，可能未插入SIM卡或SIM卡有问题")
end

mobile.number(id)

功能

获取手机卡号

注意！是否能成功读取手机号码取决于运营商提供 SIM 卡时是否有事先写入手机号；

从实际情况来看，有些 SIM 卡有事先写入手机号，大部分 SIM 卡未事先写入手机号，

如果运营商事先未写入手机号码，则 mobile.number(id)也将无法将手机号读出来；

可以确定的是：

实名认证的、可语音通话的手机可能会事先写入手机号码，

但物联网卡肯定没有事先写入手机号码，也就是物联网卡无法使用此函数读取手机号码；

参数

id

参数含义：SIM卡的编号；
数据类型：number；
取值范围：0或1，不填默认0；
是否必选：可选传入此参数；
注意事项：必须等待sim卡准备就绪后，才能获取成功；
         在支持双卡的模块上才会出现0或1的情况；
参数示例：0 -- 表示获取第一张SIM卡的手机号

返回值

local result = mobile.number(id)

result

含义说明：手机号码；
数据类型：string；
取值范围：手机号码字符串，若失败或未写入手机号则返回nil；
返回示例："13812345678" -- 一个11位的手机号码字符串

示例

if mobile.simPin() then
    log.info("SIM卡准备就绪，开始获取number")
    log.info("number", mobile.number())
else
    log.info("SIM卡未准备就绪，可能未插入SIM卡或SIM卡有问题")
end

mobile.simid(id, priority)

功能

获取当前 SIM 卡槽,或者切换卡槽

参数

id

参数含义：SIM卡的编号, 例如0, 1, 如果支持双卡，可以填2来自适应；
         如果不填就直接读取当前卡槽；
数据类型：number；
取值范围：0、1或2；
是否必选：可选传入此参数，不填为读取当前卡槽；
注意事项：Air780EXXX系列和Air8000系列模块，填写2时会占用4个IO口(gpio4/5/6/23)；
参数示例：0 -- 表示使用第一张SIM卡

priority

参数含义：是否优先用SIM0；
         如果不填就直接读取当前卡槽；
数据类型：boolean；
取值范围：true优先用SIM0，false则由具体平台决定；
是否必选：可选传入此参数；默认是false，必须在开机就配置，否则就无效了；
注意事项：只有SIM卡编号写2自适应才有用
参数示例：true -- 表示在自适应模式下优先使用SIM0

返回值

local result = mobile.simid(id, priority)

result

含义说明：当前sim卡槽编号；
数据类型：number；
取值范围：整数，若失败返回-1；
返回示例：0 -- 表示当前使用的是第一张SIM卡

示例

mobile.simid() -- 获取sim卡槽编号
mobile.simid(0) -- 固定使用SIM0
mobile.simid(1) -- 固件使用SIM1
mobile.simid(2) -- 自动识别SIM0, SIM1, 优先级看具体平台
mobile.simid(2, true) -- 自动识别SIM0, SIM1, 且SIM0优先
-- 提醒, 自动识别是会增加时间的

mobile.simPin(id, operation, pin1, pin2)

功能

检测当前 SIM 卡是否准备好，对 SIM 卡的 PIN 码做相关操作

参数

id

参数含义：SIM卡的编号, 例如0, 1, 支持双卡双待的才需要选择；
         如果不填就检测当前SIM卡是否准备好；
数据类型：number；
取值范围：0或1；
是否必选：可选传入此参数；
参数示例：0 -- 表示对第一张SIM卡进行操作

operation

参数含义：PIN码操作类型，只能是mobile.PIN_XXXX，不操作就留空；
         如果不填就检测当前SIM卡是否准备好；
数据类型：number；
取值范围：mobile.PIN_VERIFY、mobile.PIN_CHANGE、mobile.PIN_ENABLE、mobile.PIN_DISABLE、mobile.PIN_UNBLOCK；
是否必选：可选传入此参数；
参数示例：mobile.PIN_VERIFY -- 表示验证PIN码操作

pin1

参数含义：更换pin时操作的pin码，或者验证操作的pin码，或者解锁pin码时的PUK；
         如果不填就检测当前SIM卡是否准备好；
数据类型：string；
取值范围：4~8字节；
是否必选：根据操作类型决定；
参数示例："1234" -- 一个4位的PIN码

pin2

参数含义：更换pin码操作时的新的pin码，解锁pin码时的新PIN；
         如果不填就检测当前SIM卡是否准备好；
数据类型：string；
取值范围：4~8字节；
是否必选：根据操作类型决定；
参数示例："5678" -- 一个4位的新PIN码

返回值

local result = mobile.simPin(id, operation, pin1, pin2)

result

含义说明：当无PIN操作时，返回SIM卡是否准备好，有PIN操作时，返回是否成功；
数据类型：boolean；
取值范围：true表示成功或SIM卡准备好，false表示失败或SIM卡未准备好；
返回示例：true -- 表示操作成功或SIM卡已准备好

示例

local cpin_is_ready = mobile.simPin() -- 当前sim卡是否准备好，一般返回false就是没卡
local succ = mobile.simPin(0, mobile.PIN_VERIFY, "1234") -- 输入pin码验证

mobile.setAuto(check_sim_period, get_cell_period, search_cell_time, auto_reset_stack, network_check_period)

功能

设置一些辅助周期性或者自动功能，目前支持 SIM 卡暂时脱离后恢复，周期性获取小区信息，网络遇到严重故障时尝试自动恢复；适用于同一卡槽更换 sim 卡。

注意：此函数仅需要配置一次，不要放在循环中执行！！！

参数

check_sim_period

参数含义：SIM卡自动恢复时间，单位毫秒；
         当SIM卡暂时脱离后，系统会根据设定的时间周期自动检查SIM卡状态并尝试恢复连接；
数据类型：number；
取值范围：5000~10000，写0或者不写则是关闭功能；
是否必选：可选传入此参数；
注意事项：和飞行模式：mobile.flymode() 冲突，不能再同一时间使用，必须错开执行；
         和SIM卡切换：mobile.simid() 冲突，不能再同一时间使用，必须错开执行；
参数示例：10000 -- 表示每10秒检查一次SIM卡状态

get_cell_period

参数含义：周期性获取小区信息的时间间隔，单位毫秒；
数据类型：number；
取值范围：写0或者不写则是关闭功能；
是否必选：可选传入此参数；
注意事项：获取小区信息会增加部分功耗；
参数示例：30000 -- 表示每30秒获取一次小区信息

search_cell_time

参数含义：每次搜索小区时最大搜索时间，单位秒；
数据类型：number；
取值范围：不要超过8秒；
是否必选：可选传入此参数；
参数示例：5 -- 表示每次搜索小区的最大时间为5秒

auto_reset_stack

参数含义：网络遇到严重故障时尝试自动恢复；
数据类型：boolean；
取值范围：固定写nil；
是否必选：可选传入此参数；
注意事项：此参数无需设置，固定写nil；
参数示例：nil -- 固定值

network_check_period

参数含义：设置无网恢复时长，单位ms；
数据类型：number；
取值范围：建议60000以上，为搜索网络保留足够的时间；
是否必选：可选传入此参数；留空则不做更改；
注意事项：此参数会在检测到长时间无网时通过重启协议栈来恢复，并且设置后会按照设定时长检测网络是否正常；
参数示例：60000 -- 表示60秒检测一次网络状态

返回值

无返回值

示例

-- 开启SIM卡自动恢复功能，并且30秒搜索一次周围小区信息
mobile.setAuto(10000, 30000, 5)

-- 开启SIM卡自动恢复功能和网络检测功能
mobile.setAuto(5000, 0, 5, false, 60000)

mobile.apn(index, cid, new_apn_name, user_name, password, ip_type, protocol, is_del)

功能

获取或设置 APN（接入点名称），设置 APN 必须在入网前就设置好，比如在 SIM 卡识别完成前就设置好

专网卡访问白名单

用定向 IP 的物联网卡，需要把域名或 IP 加入白名单才能使用，下面列出模块会访问的域名或 IP 服务器。

功能	地址	端口	协议
远程升级	iot.openluat.com	80	http
基站WIFI定位	bs.openluat.com	12411	udp
基站WIFI定位(收费)	airlbs.openluat.com	12413	udp
AGPS星历下载	download.openluat.com	80	http
NTP时间同步	ntp.aliyun.com	123	udp
errdump	dev_msg1.openluat.com	12425	udp

参数

index

参数含义：编号,默认0. 在支持双卡的模块上才会出现0或1的情况；
数据类型：number；
是否必选：可选传入此参数；
参数示例：0 -- 表示对第一张SIM卡进行操作

cid

参数含义：APN的连接ID；
数据类型：number；
取值范围：默认0，如果要用非默认APN来激活，必须>0；
是否必选：可选传入此参数；
参数示例：1 -- 表示使用连接ID为1的APN配置

new_apn_name

参数含义：新的APN名称；
数据类型：string；
是否必选：不填就是获取APN, 填了就是设置APN；
注意事项：是否支持设置取决于底层实现；
参数示例："cmiot" -- 设置APN名称为cmiot

user_name

参数含义：新的APN的用户名；
数据类型：string；
是否必选：如果APN不是空,那必须填写,如果没有留个空字符串""。如果APN是空的，那可以nil；
参数示例："" -- 表示不需要用户名认证

password

参数含义：新的APN的密码；
数据类型：string；
是否必选：如果APN不是空,那必须填写,如果没有留个空字符串""。如果APN是空的，那可以nil；
参数示例："" -- 表示不需要密码认证

ip_type

参数含义：激活APN时的IP TYPE；
数据类型：number；
取值范围：1=IPV4 2=IPV6 3=IPV4V6,默认是1；
是否必选：可选传入此参数；
参数示例：1 -- 表示支持IPv4

protocol

参数含义：激活APN时,如果需要username和password,就要写鉴权协议类型；
数据类型：number；
取值范围：默认3，不需要鉴权的写0；
是否必选：可选传入此参数；
参数示例：0 -- 表示不需要鉴权

is_del

参数含义：是否删除APN；
数据类型：boolean；
取值范围：true是,其他都否；
是否必选：可选传入此参数；只有参数3新的APN不是string的时候才有效果；
参数示例：true -- 表示删除指定的APN

返回值

local result = mobile.apn(index, cid, new_apn_name, user_name, password, ip_type, protocol, is_del)

result

含义说明：如果网络注册成功，返回注册用的APN值，反之是nil；
数据类型：string；
注意事项：设置好不会立刻有返回值，需要等网络注册成功；
返回示例："cmiot" -- 当前注册使用的APN名称

示例

-- 获取当前APN
mobile.apn()

-- 注意, 在国内, 公网卡基本上都不需要设置APN, 专网卡才需要设置
mobile.apn(0,1,"cmiot","","",nil,0)

-- 专网卡设置的demo，name，user，password联系卡商获取
-- 设置后, 再次立即获取, 并不会返回设置的值, 要等联网成功 - 设置好不会立刻有返回值，需要等网络注册成功
mobile.apn(0,1,"name","user","password",nil,3)

mobile.ipv6(onff)

功能

是否默认开启 IPV6 功能，必须在 LTE 网络连接前就设置好

参数

onff

参数含义：开关；
数据类型：boolean；
取值范围：true开启，false 关闭(默认)；
是否必选：可选传入此参数，nil：获取当前设备的 IPv6 功能开启状态；
注意事项：必须在main.lua中的初始化时就设置好；
         开启ipv6后, 开机联网会慢2~3秒。
参数示例：true -- 表示开启IPv6功能

返回值

local result = mobile.ipv6(onff)

result

含义说明：当前ipv6功能的状态；
数据类型：boolean；
取值范围：true 当前是开启的，false 当前是关闭的；

示例

-- 注意, 开启ipv6后, 开机联网会慢2~3秒
mobile.ipv6()     -- 获取当前设备的 IPv6 功能开启状态
mobile.ipv6(true) -- 默认开启IPV6功能

mobile.csq()

功能

获取 CSQ（信号质量指示）

参数

无

返回值

local result = mobile.csq()

result

含义说明：当前CSQ值；
数据类型：number；
取值范围：0 - 31, 越大越好，若失败返回0；
         CSQ值小于10，网络较差。
         CSQ值在10和25之间，网络中等。
         CSQ值大于25，网络较好。
返回示例：23 -- 表示当前信号质量中等

示例

-- 注意, 4G模块的CSQ值仅供参考, rsrp/rsrq才是真正的信号强度指标
log.info("csq", mobile.csq())

mobile.rssi()

功能

获取 RSSI（接收信号强度指示）

参数

无

返回值

local result = mobile.rssi()

result

含义说明：当前rssi值；
数据类型：number；
取值范围：0 到 -114, 越大越好，若失败返回0；
         RSSI ≤ -90 dBm，网络较差。
         -90 dBm < RSSI ≤ -75 dBm，网络中等。
         RSSI > -75 dBm，网络较好。
返回示例：-75 -- 表示当前信号强度良好

示例

log.info("rssi", mobile.rssi())

mobile.rsrp()

功能

获取 RSRP（参考信号接收功率）

参数

无

返回值

local result = mobile.rsrp()

result

含义说明：当前rsrp值；
数据类型：number；
取值范围：-44 ~ -140，值越大越好，若失败返回0；
         RSRP < -95 dBm，网络较差。
         -85 dBm > RSRP ≥ -95 dBm，网络中等。
         RSRP ≥ -85 dBm，网络较好。
返回示例：-75 -- 表示当前信号强度良好

示例

log.info("rsrp", mobile.rsrp())

mobile.rsrq()

功能

获取 RSRQ（参考信号接收质量）

参数

无

返回值

local result = mobile.rsrq()

result

含义说明：当前rsrq值；
数据类型：number；
取值范围：-3 ~ -19.5，值越大越好，若失败返回0；
         RSRQ < -15 dB，网络较差。
         -10 dB > RSRQ ≥ -15 dB，网络中等。
         RSRQ ≥ -10 dB，网络较好。
返回示例：-9 -- 表示当前信号质量较好

示例

log.info("rsrq", mobile.rsrq())

mobile.snr()

功能

获取 SNR（信噪比）

参数

无

返回值

local result = mobile.snr()

result

含义说明：当前snr值；
数据类型：number；
取值范围：0 - 30, 越大越好，若失败返回0；
         RSRQ < 5 dB，网络较差。
         5 dB ≥ RSRQ ≥ 15 dB，网络中等。
         RSRQ > 15 dB，网络较好。
返回示例：15 -- 表示当前信噪比良好

示例

log.info("snr", mobile.snr())

mobile.eci()

功能

获取当前服务小区的 ECI(E-UTRAN Cell Identifier)

参数

无

返回值

local result = mobile.eci()

result

含义说明：当前eci值；
数据类型：number；
取值范围：整数，若失败返回-1；
返回示例：124045360 -- 表示当前服务小区的ECI值

示例

log.info("eci", mobile.eci())

mobile.tac()

功能

获取当前服务小区的 TAC 或者 LAC（跟踪区码或位置区码）

参数

无

返回值

local result = mobile.tac()

result

含义说明：当前tac值；
数据类型：number；
取值范围：整数，若失败返回-1。如果尚未注册到网络,会返回0；

示例

log.info("tac", mobile.tac())

mobile.enbid()

功能

获取当前服务小区的 eNBID(eNodeB Identifier)

参数

无

返回值

local result = mobile.enbid()

result

含义说明：当前enbid值；
数据类型：number；
取值范围：整数，若失败返回-1；
返回示例：124045360 -- 表示当前服务小区的eNBID值

示例

log.info("enbid", mobile.enbid())

mobile.scell()

功能

获取当前服务小区更详细的信息

参数

无

返回值

local result = mobile.scell()

result

含义说明：服务小区的详细信息；
数据类型：table；
取值范围：包含小区各项参数的table；
返回示例：{"mnc": 11, "mcc": 460, "rssi": -78, "pci": 115, "rsrp": -107, "tac": 30005, "eci": 124045360, "cid": 124045360, "rsrq": -9, "snr": 15, "earfcn": 1850}
-- table返回值参数说明：
-- "mnc": 移动网络代码(Mobile Network Code)(number)
-- "mcc": 移动国家代码(Mobile Country Code)(number)，460表示中国
-- "rssi": 接收信号强度指示器(Received Signal Strength Indicator)(number)，单位dBm
-- "pci": 物理小区标识(Physical Cell Identifier)(number)
-- "rsrp": 参考信号接收功率(Reference Signal Received Power)(number)，单位dBm
-- "tac": 跟踪区域码(Tracking Area Code)(number)
-- "eci": 小区标识(E-UTRAN Cell Identifier)(number)
-- "cid": 小区标识(Cell Identifier)(number)
-- "rsrq": 参考信号接收质量(Reference Signal Received Quality)(number)，单位dB
-- "snr": 信噪比(Signal-to-Noise Ratio)(number)
-- "earfcn": 频点(E-UTRA Absolute Radio Frequency Channel Number)(number)

**示例**

```lua
log.info("cell", json.encode(mobile.scell()))
-- 返回值示例
-- {
--     "mnc": 11,
--     "mcc": 460,
--     "rssi": -78,
--     "pci": 115,
--     "rsrp": -107,
--     "tac": 30005,
--     "eci": 124045360,
--     "cid": 124045360,
--     "rsrq": -9,
--     "snr": 15,
--     "earfcn": 1850
-- }

mobile.flymode(index, enable)

功能

进出飞行模式

参数

index

参数含义：编号,默认0. 在支持双卡的模块上才会出现0或1的情况；
数据类型：number；
是否必选：可选传入此参数；

enable

参数含义：是否设置为飞行模式；
数据类型：boolean；
取值范围：true为设置, false为退出；
是否必选：可选传入此参数；

返回值

local result = mobile.flymode(index, enable)

result

含义说明：原飞行模式的状态；
数据类型：boolean；
取值范围：true表示原状态为飞行模式，false表示原状态非飞行模式；
返回示例：false -- 表示原状态非飞行模式

示例

-- sim0 进入飞行模式
mobile.flymode(0,true)

-- sim0 退出飞行模式
mobile.flymode(0, false)

mobile.syncTime(enable)

功能

配置基站同步时间开关，默认开启

参数

enable

参数含义：开关；
数据类型：boolean；
取值范围：为空查询当前状态, true开启, false关闭；
是否必选：可选传入此参数；nil为查询功能；
返回示例：true -- 表示基站同步时间功能当前处于开启状态

返回值

local result = mobile.syncTime(enable)

result

含义说明：当前开关状态；
数据类型：boolean；
取值范围：true表示开启，false表示关闭；

示例

local result = mobile.syncTime() --获取当前开关状态

mobile.syncTime(false) --关闭基站同步时间

mobile.status()

功能

获取网络状态

参数

无

返回值

local result = mobile.status()

result

含义说明：当前网络状态；
数据类型：number；
取值范围：
        "mobile.UNREGISTER(数值为0)":网络未注册
        "mobile.REGISTERED(数值为1)":网络已注册
        "mobile.SEARCH(数值为0)":正在搜网中
        "mobile.DENIED(数值为3)":网络注册被拒绝
        "mobile.UNKNOW(数值为4)":网络状态未知
        "mobile.REGISTERED_ROAMING(数值为5)":漫游,且已注册
        "mobile.SMS_ONLY_REGISTERED(数值为6)":仅SMS可用
        "mobile.SMS_ONLY_REGISTERED_ROAMING(数值为7)":仅SMS可用,且漫游状态
        "mobile.EMERGENCY_REGISTERED(数值为8)":仅紧急呼叫. 注意, 国内不支持此状态,模块也不支持紧急呼叫；

示例

-- 状态描述
-- "mobile.UNREGISTER(数值为0)":网络未注册
-- "mobile.REGISTERED(数值为1)":网络已注册
-- "mobile.SEARCH(数值为0)":正在搜网中
-- "mobile.DENIED(数值为3)":网络注册被拒绝
-- "mobile.UNKNOW(数值为4)":网络状态未知
-- "mobile.REGISTERED_ROAMING(数值为5)":漫游,且已注册
-- "mobile.SMS_ONLY_REGISTERED(数值为6)":仅SMS可用
-- "mobile.SMS_ONLY_REGISTERED_ROAMING(数值为7)":仅SMS可用,且漫游状态
-- "mobile.EMERGENCY_REGISTERED(数值为8)":仅紧急呼叫. 注意, 国内不支持此状态,模块也不支持紧急呼叫；

log.info("network status", mobile.status())

mobile.getCellInfo()

功能

获取基站信息

参数

无

返回值

local result = mobile.getCellInfo()

result

含义说明：包含基站数据的数组；
数据类型：table；
取值范围：包含多个基站信息的table数组；
注意事项：需要主动请求一次reqCellInfo才会有基站数据；

示例

-- 注意: 需要主动请求一次reqCellInfo才会有基站数据.

--示例输出(原始数据是table, 下面是json格式化后的内容)
--[[
[
    {"rsrq":-10,"rssi":-55,"cid":124045360,"mnc":17,"pci":115,"earfcn":1850,"snr":15,"rsrp":-85,"mcc":1120,"tdd":0},
    {"pci":388,"rsrq":-11,"mnc":17,"earfcn":2452,"snr":5,"rsrp":-67,"mcc":1120,"cid":124045331},
    {"pci":100,"rsrq":-9,"mnc":17,"earfcn":75,"snr":17,"rsrp":-109,"mcc":1120,"cid":227096712}
]
]]

mobile.reqCellInfo(60)

function cell_info()
    log.info("cell", json.encode(mobile.getCellInfo()))
end

function cellinfo_handle_task()
    sys.wait(3000)
    while 1 do
        mobile.reqCellInfo(15)
        sys.waitUntil("CELL_INFO_UPDATE", 15000)
        log.info("cell", json.encode(mobile.getCellInfo()))
    end
end

-- 订阅
sys.subscribe("CELL_INFO_UPDATE", cell_info)

-- 定期轮训式
sys.taskInit(cellinfo_handle_task)

mobile.reqCellInfo(timeout)

功能

发起基站信息查询,含临近小区

参数

timeout

参数含义：超时时长,单位秒；
数据类型：number；
取值范围：默认15. 最少5, 最高60；
是否必选：可选传入此参数；

返回值

无返回值

示例

mobile.reqCellInfo(30) -- 设置30秒超时

mobile.lockCell(mode, earfcn, pci)

功能

锁定/解锁小区，仅用于外场测试，量产环境中请勿使用。

参数

mode

参数含义：操作码；
数据类型：number；
取值范围：0 删除优先的频点，1 设置优先频点，2 锁定小区，3 解锁小区；
是否必选：必须传入此参数；

earfcn

参数含义：下行频点；
数据类型：number；
是否必选：根据mode决定；

pci

参数含义：物理小区ID；
数据类型：number；
是否必选：根据mode决定；

返回值

local result = mobile.lockCell(mode, earfcn, pci)

result

含义说明：操作是否成功；
数据类型：boolean；
取值范围：成功true 失败false；

示例

log.info("cell", json.encode(mobile.scell())) --获取earfcn和pci参数
-- 返回值示例
-- {
--     "mnc": 11,
--     "mcc": 460,
--     "rssi": -78,
--     "pci": 115,
--     "rsrp": -107,
--     "tac": 30005,
--     "eci": 124045360,
--     "cid": 124045360,
--     "rsrq": -9,
--     "snr": 15,
--     "earfcn": 1850
-- }

-- 当 mode=0 （删除优先频点）时，需要传入earfcn参数
mobile.lockCell(0, 1850)
-- 当 mode=1 （设置优先频点）时，需要传入earfcn参数
mobile.lockCell(1, 1850)
-- 当 mode=2（锁定小区）时，需要同时传入earfcn和pci参数
mobile.lockCell(2, 1850, 115)
-- 当 mode=3（解锁小区）时，不需要传入earfcn和pci参数
mobile.lockCell(3)

mobile.reset()

功能

重启协议栈；注意：并不会重启软件系统。

参数

无

返回值

无返回值

示例

-- 重启LTE协议栈
mobile.reset()

mobile.dataTraffic(clearUplink, clearDownlink)

功能

数据量流量处理

参数

clearUplink

参数含义：是否清空上行流量累计值；
数据类型：boolean；
取值范围：true清空，不填则为获取上下行流量累计值；
是否必选：可选传入此参数；

clearDownlink

参数含义：是否清空下行流量累计值；
数据类型：boolean；
取值范围：true清空，不填则为获取上下行流量累计值；
是否必选：可选传入此参数；

返回值

local uplinkGB, uplinkB, downlinkGB, downlinkB = mobile.dataTraffic()

uplinkGB

含义说明：上行流量GB部分；
数据类型：number；

uplinkB

含义说明：上行流量B部分；
数据类型：number；

downlinkGB

含义说明：下行流量GB部分；
数据类型：number；

downlinkB

含义说明：下行流量B部分；
数据类型：number；

示例

-- 获取上下行流量累计值
-- 注：仅记录开机后的流量，复位/重启会归零
-- 上行流量值Byte = uplinkGB * 1024 * 1024 * 1024 + uplinkB
-- 下行流量值Byte = downlinkGB * 1024 * 1024 * 1024 + downlinkB
local uplinkGB, uplinkB, downlinkGB, downlinkB = mobile.dataTraffic()

-- 清空上下行流量累计值
mobile.dataTraffic(true, true)

mobile.config(item, value)

功能

网络特殊配置（目前仅支持 Air780EXXX 系列和 Air8000 系列模块）

参数

item

参数含义：配置项目，看mobile.CONF_XXX，常量详细解释可以查看第三章；
数据类型：number；
取值范围：mobile.CONF_XXX系列常量；
是否必选：必须传入此参数；

value

参数含义：配置值,根据具体配置的item决定；
数据类型：number；
取值范围：根据具体配置项而定；
是否必选：必须传入此参数；

返回值

local result = mobile.config(item, value)

result

含义说明：配置是否成功；
数据类型：boolean；
取值范围：成功true 失败false；

示例

--针对不同平台有不同的配置，谨慎使用，目前仅Air780EXXX系列和Air8000系列模块支持。

-- 配置小区重选信号差值门限，不能大于15dbm，必须在飞行模式下才能用
mobile.flymode(0,true)
mobile.config(mobile.CONF_RESELTOWEAKNCELL, 15)
mobile.flymode(0,false)

-- 设置SIM写入次数的统计
-- 关闭统计
mobile.config(mobile.CONF_SIM_WC_MODE, 0)
-- 开启统计, 默认也是开启的.
mobile.config(mobile.CONF_SIM_WC_MODE, 1)
-- 读取统计值,异步, 需要通过系统消息SIM_IND获取
function sim_status(stats, value)
    log.info("SIM_IND", stats)
    if stats == "SIM_WC" then
        log.info("sim", "write counter", value)
    end
end
sys.subscribe("SIM_IND", sim_status)
mobile.config(mobile.CONF_SIM_WC_MODE, 2)
-- 清空统计值
mobile.config(mobile.CONF_SIM_WC_MODE, 3)

mobile.getBand(band, is_default)

功能

获取当前使用/支持的 band；

需要注意：

1、此函数仅用于获取硬件支持的频段能力，不是当前驻留的频段；

2、数组中的内容是频段索引（如 1,3,5,8 等），不是频率值。

参数

band

参数含义：输出band的缓冲区；
数据类型：zbuff；
是否必选：必须传入此参数；

is_default

参数含义：是否获取默认支持的band；
数据类型：boolean；
取值范围：true默认支持，false当前支持的，默认是false；
是否必选：可选传入此参数；当前是预留功能，不要写true；

返回值

local result = mobile.getBand(band, is_default)

result

含义说明：操作是否成功；
数据类型：boolean；
取值范围：成功返回true，失败放回false；

示例

local buff = zbuff.create(40)
mobile.getBand(buff) --输出当前使用的band，band号放在buff内，buff[0]，buff[1]，buff[2] .. buff[buff:used() - 1]
log.info("当前使用的band:")
--轮训方式打印所用band
for i=0,buff:used()-1 do
    log.info("band", buff[i])
end

mobile.setBand(band, num)

功能

设置使用的 band；需要注意：此函数仅用于获取硬件支持的频段能力，不是当前驻留的频段；数组中的内容是频段索引（如 1,3,5,8 等），不是频率值。

参数

band

参数含义：输入使用的band的缓冲区；
数据类型：zbuff；
是否必选：必须传入此参数；

num

参数含义：band数量；
数据类型：number；
是否必选：必须传入此参数；

返回值

local result = mobile.setBand(band, num)

result

含义说明：操作是否成功；
数据类型：boolean；
取值范围：成功返回true，失败放回false；

示例

local buff = zbuff.create(40)
buff[0] = 3
buff[1] = 5
buff[2] = 8
buff[3] = 40
mobile.setBand(buff, 4) --设置使用的band一共4个，为3,5,8,40

mobile.vsimOnOff(enable)

功能

切换内置虚拟卡和外置实体卡，虚拟卡需要固件支持，否则切换后无网络，需要在飞行模式下切换，或者切换后重启协议栈；

由于历史原因，保留了这个接口的介绍；

当前合宙的产品都不支持虚拟卡，客户新项目可以忽略这个功能接口；

参数

enable

参数含义：是否开启虚拟卡；
数据类型：boolean；
取值范围：true开启, false关闭；
是否必选：必须传入此参数；

返回值

无返回值

示例

mobile.vsimOnOff(true) --使用内置虚拟卡
mobile.vsimOnOff(false) --使用外置实体卡

mobile.apnTableInit()

功能

初始化自定义 APN 列表，主要用于海外 SIM 卡

参数

无

返回值

无返回值

示例

mobile.apnTableInit()

mobile.apnTableAdd(mcc, mnc, ip_type, protocol, apn_name, user_name, password)

功能

往自定义 APN 列表添加一条 APN 信息，主要用于海外 SIM 卡

参数

mcc

参数含义：MCC码,16进制BCD码；
数据类型：number；
是否必选：必须传入此参数；

mnc

参数含义：MNC码,16进制BCD码；
数据类型：number；
是否必选：必须传入此参数；

ip_type

参数含义：激活APN时的IP TYPE；
数据类型：number；
取值范围：1=IPV4 2=IPV6 3=IPV4V6,默认是1；
是否必选：可选传入此参数；

protocol

参数含义：激活APN时,如果需要username和password,就要写鉴权协议类型；
数据类型：number；
取值范围：0：不需要鉴权；
         3：需要鉴权；
是否必选：可选传入此参数；

apn_name

参数含义：APN name；
数据类型：string；
是否必选：必须传入此参数；不能为空；

user_name

参数含义：APN的username；
数据类型：string；
是否必选：可选传入此参数；

password

参数含义：APN的password；
数据类型：string；
是否必选：可选传入此参数；

返回值

无返回值

示例

mobile.apnTableInit() -- 先初始化，必须放在SIM卡识别完成前加入，最好就是写在开头
mobile.apnTableAdd(0x460,0x00,3,0,"cmiot","","") -- 单独添加一条APN信息，必须放在SIM卡识别完成前加入，最好就是写在开头，移动公网卡设置APN为cmiot（一般不用设置，这里只是举例）

mobile.apnTablePrint(mcc, mnc)

功能

打印自定义 APN 列表里的一条信息，在没有拿到卡的情况下，测试一下对应的 APN 信息是否和运营商提供的匹配

参数

mcc

参数含义：MCC码,16进制BCD码；
数据类型：number；
是否必选：必须传入此参数；

mnc

参数含义：MNC码,16进制BCD码；
数据类型：number；
是否必选：必须传入此参数；

返回值

无返回值

示例

mobile.apnTableInit()
mobile.apnTablePrint(0x202, 0x01)

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 mobile 核心库。