随着物联网技术的蓬勃发展，将蜂窝通信功能集成到嵌入式设备中已成为实现远程连接与数据交互的关键。蜂窝通信模块作为设备接入移动网络的核心组件，其集成过程涉及硬件接口设计、驱动开发及网络协议栈的配置。本文将深入探讨蜂窝通信模块在嵌入式系统中的集成方法，解析从硬件连接到软件调试的全流程，帮助开发者实现设备的稳定联网与数据传输。

一、概述

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

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

二、核心示例

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

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

三、常量详解

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

3.1 网络注册状态常量

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

mobile.UNREGISTER

mobile.REGISTERED

mobile.SEARCH

mobile.DENIED

mobile.UNKNOW

mobile.REGISTERED_ROAMING

mobile.SMS_ONLY_REGISTERED

mobile.SMS_ONLY_REGISTERED_ROAMING

mobile.EMERGENCY_REGISTERED

mobile.CSFB_NOT_PREFERRED_REGISTERED

mobile.CSFB_NOT_PREFERRED_REGISTERED_ROAMING

3.2 PIN 码操作常量

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

mobile.PIN_VERIFY

mobile.PIN_CHANGE

mobile.PIN_ENABLE

mobile.PIN_DISABLE

mobile.PIN_UNBLOCK

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

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

mobile.CONF_RESELTOWEAKNCELL

mobile.CONF_CE_MODE

mobile.CONF_SIM_WC_MODE

mobile.CONF_FAKE_CELL_BARTIME

mobile.CONF_RESET_TO_FACTORY

mobile.CONF_USB_ETHERNET

3.3.1 典型应用示例

1. 增强网络稳定性配置

2. SIM 卡写入次数监控

3.4 系统消息常量

"SIM_IND"

"CELL_INFO_UPDATE"

"SCELL_INFO"

"NTP_UPDATE"

"CSCON"

四、函数详解

mobile.imei(index)

功能

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

参数

index

返回值

local result = mobile.imei(index)

result

示例

mobile.imsi(index)

功能

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

参数

index

返回值

local result = mobile.imsi(index)

result

示例

mobile.muid()

功能

获取 MUID（设备唯一标识）

参数

无

返回值

local result = mobile.muid()

result

示例

mobile.iccid(id)

功能

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

参数

id

返回值

local result = mobile.iccid(id)

result

示例

mobile.number(id)

功能

获取手机卡号

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

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

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

可以确定的是：

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

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

参数

id

返回值

local result = mobile.number(id)

result

示例

mobile.simid(id, priority)

功能

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

注意：

如果要固定使用卡槽2，需在代码开头设置mobile.simid(1)，如果没有设置，固件会默认使用卡槽1(sim0)

此函数可以在程序运行中使用，设置后会自动进出飞行模式尝试切换SIM卡槽

在双卡设备上设置 mobile.simid(2) 自适应模式，固件版本需≥V2022，否则会在sim0有卡时一直读取sim0卡槽，无法进行自适应切换!!!

mobile.simid()运行流程图如下

参数

id

priority

返回值

-- 获取当前卡槽 local result = mobile.simid()

--先设置，后获取（不建议这样使用，可能会因为还未设置完毕而获取到错误的卡槽） local result = mobile.simid(id, priority)

result

示例

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

功能

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

参数

id

operation

pin1

pin2

返回值

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

result

示例

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

功能

设置一些辅助周期性或者自动功能，周期性获取小区信息，网络遇到严重故障时尝试自动恢复

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

参数

check_sim_period

get_cell_period

search_cell_time

auto_reset_stack

network_check_period

返回值

无返回值

示例

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

功能

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

专网卡访问白名单

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

支持的API列表请查看下方“第五章”详情介绍

参数

index

cid

new_apn_name

user_name

password

ip_type

protocol

is_del

返回值

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

result

示例

mobile.ipv6(onff)

功能

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

参数

onff

返回值

local result = mobile.ipv6(onff)

result

示例

mobile.csq()

功能

获取 CSQ（信号质量指示）

参数

无

返回值

local result = mobile.csq()

result

示例

mobile.rssi()

功能

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

参数

无

返回值

local result = mobile.rssi()

result

示例

mobile.rsrp()

功能

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

参数

无

返回值

local result = mobile.rsrp()

result

示例

mobile.rsrq()

功能

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

参数

无

返回值

local result = mobile.rsrq()

result

示例

mobile.snr()

功能

获取 SNR（信噪比）

参数

无

返回值

local result = mobile.snr()

result

示例

mobile.eci()

功能

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

参数

无

返回值

local result = mobile.eci()

result

示例

mobile.tac()

功能

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

参数

无

返回值

local result = mobile.tac()

result

示例

mobile.enbid()

功能

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

参数

无

返回值

local result = mobile.enbid()

result

示例

mobile.scell()

功能

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

参数

无

返回值

local result = mobile.scell()

result

示例

mobile.flymode(index, enable)

功能

进出飞行模式

注意事项：

1、进入飞行模式不会断开WIFI或以太网；

2、V2024及以下固件返回值为：false 表示原状态为飞行模式，true 表示原状态非飞行模式；

3、V2026以上固件返回值为：true 表示原状态为飞行模式，false 表示原状态非飞行模式；

4、飞行模式PSM+休眠模式保持，掉电不保持：

进入飞行模式后，重启会自动退出飞行模式：

参数

index

enable

返回值

local result = mobile.flymode(index, enable)

result

示例

mobile.syncTime(enable)

功能

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

参数

enable

返回值

local result = mobile.syncTime(enable)

result

示例

mobile.status()

功能

获取网络状态

参数

无

返回值

local result = mobile.status()

result

示例

mobile.getCellInfo()

功能

获取基站信息

参数

无

返回值

local result = mobile.getCellInfo()

result

示例

mobile.reqCellInfo(timeout)

功能

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

参数

timeout

返回值

无返回值

示例

mobile.lockCell(mode, earfcn, pci)

功能

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

参数

mode

earfcn

pci

返回值

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

result

示例

mobile.reset()

功能

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

参数

无

返回值

无返回值

示例

mobile.dataTraffic(clearUplink, clearDownlink)

功能

数据量流量处理

参数

clearUplink

clearDownlink

返回值

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

uplinkGB

uplinkB

downlinkGB

downlinkB

示例

mobile.config(item, value)

功能

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

参数

item

value

返回值

local result = mobile.config(item, value)

result

示例

mobile.getBand(band, is_default)

功能

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

需要注意：

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

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

参数

band

is_default

返回值

local result = mobile.getBand(band, is_default)

result

示例

mobile.setBand(band, num)

功能

设置使用的 band；

注意事项：

此函数仅用于设置硬件支持的频段能力，不是当前驻留的频段；

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

此函数设置的band掉电会保存！！！；

参数

band

num

返回值

local result = mobile.setBand(band, num)

result

示例

mobile.vsimOnOff(enable)

功能

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

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

当前我们的模组都不支持虚拟卡，用户新项目可以忽略这个功能接口；

参数

enable

返回值

无返回值

示例

mobile.apnTableInit()

功能

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

参数

无

返回值

无返回值

示例

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

功能

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

参数

mcc

mnc

ip_type

protocol

apn_name

user_name

password

返回值

无返回值

示例

mobile.apnTablePrint(mcc, mnc)

功能

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

参数

mcc

mnc

返回值

无返回值

示例

五、模组API支持说明

AT固件支持的APN列表

注意：仅海外模组 780EEN/EEU/EEJ/EEA 开启了海外apn

LuatOS固件支持的APN列表

注意：2025年之后的固件均支持海外APN

六、模组支持说明

支持 LuatOS 开发的所有模组都支持 mobile 核心库。

今天的内容就分享到这里了~