QuecPython蜂窝网卡特有机制

本文主要说明QuecPython蜂窝无线网卡特有的一些处理机制，并说明这些机制的基本流程与原理。帮助用户更好的使用QuecPython的蜂窝无线网卡功能。

概述

QuecPython蜂窝无线网卡的处理机制主要包括如下3个部分：

• 开机自动激活蜂窝无线网卡（下文中简称自动激活）。

• 蜂窝无线网卡自动恢复机制（下文中简称自动重连）。

• 蜂窝无线网卡配置参数保存。

下图是QuecPython蜂窝无线网卡开机自动激活的流程。总体而言，可以分为三个阶段：

• 阶段1：根据datacall_config.json文件是否存在，决定开机时使能哪一路或者多路蜂窝无线网卡的自动激活和自动重连功能。

• 阶段2：根据用户是否配置了APN等网卡参数，决定使用什么参数来进行蜂窝移动网卡的激活。

• 阶段3：前面两个阶段主要是参数配置，这个阶段是实际的网卡激活操作。

下面将结合上述流程图来详细介绍QuecPython蜂窝无线网卡的各种处理机制。

开机自动激活网卡

开机自动激活蜂窝无线网卡，是指模组在开机后，系统在判断模组网络注册已经成功时，会自动进行蜂窝无线网卡激活的操作。

结合上面的流程图，可以看到，系统会先根据datacall_config.json文件是否存在，决定激活哪一路或者多路蜂窝无线网卡。有如下两种处理机制：

• datacall_config.json文件不存在：系统会选择激活第一路蜂窝无线网卡。

• datacall_config.json文件存在：系统会根据该文件中的配置，来决定开机时激活哪一路或者多路蜂窝无线网卡。

系统决定了激活哪些蜂窝无线网卡后，在执行网卡激活操作之前，系统还会进一步确认用户是否为对应的蜂窝无线网卡配置了APN等参数。有如下两种处理机制：

• 用户没有配置APN等参数：如果没有配置，则使用默认参数进行蜂窝无线网卡的激活。默认的参数配置如下：

使用默认的参数配置进行蜂窝无线网卡的激活，可能会导致激活失败。建议用户按照实际情况，配置正确的APN参数。

• 用户配置了APN等参数：如果用户配置了，则使用用户配置的APN参数进行蜂窝无线网卡的激活。

网卡自动恢复机制

蜂窝无线网卡自动恢复机制，是指模组在激活蜂窝无线网卡后，因为一些异常原因（如网络异常、环境干扰、信号差等）导致模组与网络的连接断开，当异常因素消失，模组在重新注册到网络后，自动重新激活蜂窝无线网卡的行为过程。我们也将这个机制称为蜂窝无线网卡自动重连机制。

结合上面的流程图，可以看到，系统会先根据datacall_config.json文件是否存在，决定使能哪一路或者多路蜂窝无线网卡的自动重连功能。有如下两种处理机制：

• datacall_config.json文件不存在：系统会选择使能第一路蜂窝无线网卡的自动重连功能。

• datacall_config.json文件存在：系统会根据该文件中的配置，来决定使能哪一路或者多路蜂窝无线网卡的自动重连功能。

蜂窝无线网卡自动重连机制的基本工作原理如下：

系统会监控设备与无线网络的连接状态，当网络连接断开了，引起网络异常的因素消失后，设备会自动发起附着流程（Attach procedure）重新注册到网络上。一旦注册成功，系统会按照之前的网卡配置参数重新激活网卡。

下面是一些会导致设备网络连接断开的常见情况：

• 设备在一些信号很差的环境中，容易导致设备网络连接断开。比如在隧道中。

• 设备所处的环境，存在同频干扰或者其他干扰，影响设备与基站的正常通信，也会导致设备与网络连接断开。

• 设备接入的小区因为负载过重，即接入该小区的设备过多时，也可能会导致设备与网络连接断开。

• 无线网络发生异常，会导致设备与网络连接断开。

网卡信息保存

在QuecPython中，系统会保存蜂窝无线网卡相关的参数，具体可以分为两个部分：

自动激活和自动重连配置信息保存

通过【概述】部分的流程图可以看出，系统会根据datacall_config.json文件是否存在，决定开机时使能哪一路或者多路蜂窝无线网卡的自动激活和自动重连功能。这是因为datacall_config.json文件保存了每一路蜂窝无线网卡是否自动激活和自动重连的配置信息。其内容和格式如下：

{
    "1": {"autoActivate": 0, "autoConnect": 0},
    "2": {"autoActivate": 0, "autoConnect": 0},
    "3": {"autoActivate": 0, "autoConnect": 0}
}

配置文件中有3组配置信息，分别用于控制3路蜂窝无线网卡的自动激活和自动重连功能。其中autoActivate用于控制是否自动激活，autoConnect则用于控制是否自动重连。autoActivate和autoConnect的值为0表示关闭对应功能，为1表示开启对应功能。

用户可以通过下面两个方法来修改datacall_config.json文件：

配置自动激活

dataCall.setAutoActivate(profileID, enable)

配置自动重连

dataCall.setAutoConnect(profileID, enable)

默认是不存在datacall_config.json文件的，只有用户使用dataCall.setAutoActivate或者dataCall.setAutoConnect方法配置过对应的功能，系统才会在模组的usr目录下创建datacall_config.json文件并保存用户配置信息，该文件不会因为设备断电而丢失。

用户配置的APN等参数保存

用户为每一路蜂窝无线网卡配置的APN等参数，都会被保存到系统的NVM当中，不会因为设备断电而丢失。即使用下面的方法配置的信息会被保存：

dataCall.setPDPContext(profileID, ipType, apn, username, password, authType)

checkNet机制

checkNet是QuecPython提供的一个功能模块。该模块主要用于检查网络是否已经就绪。关于该checkNet模块API的使用说明，请参考QuecPython官网API参考手册内checkNet部分。

checkNet使用场景

UE开机后入网流程是一个很复杂的过程，需要终端设备与基站以及核心网进行一系列交互，进行信息确认。这个过程会受很多因素影响，比如终端设备的射频性能（硬件设计、天线等）、周边环境、小区信号覆盖情况、基站负载情况等。因此在设备开机后，用户应用程序开始运行时，蜂窝无线网卡尚未激活成功是很常见也很正常的现象。

如果用户在其应用程序中，一开始就进行网络相关的业务操作，很可能因为蜂窝无线网卡尚未激活的原因而导致用户网络业务失败。因此我们建议用户在进行socket、http/https以及mqtt等网络相关的业务操作之前，先判断网络是否就绪。这里我们推荐用户使用checkNet模块的如下方法来检测网络是否就绪：

checkNet.waitNetworkReady(timeout)

推荐用户使用这个方法主要有以下原因：

• 该方法会完整的检测SIM卡状态、设备网络注册状态以及蜂窝无线网卡激活状态。并且还可以设置超时时间，即在该超时时间内，如果检测到蜂窝无线网卡以及激活成功，则会立即返回，否则该方法会一直阻塞到超时才会退出。

• 该方法在超时退出时，会返回详细的错误码，告知用户当前蜂窝无线网卡没有激活，是在哪一个阶段失败。比如是SIM卡状态异常、设备网络注册失败或者在蜂窝无线网卡激活阶段失败。这样缩小了问题范围，可以帮助更快的确认问题。

checkNet机制说明

checkNet检查网络是否就绪的流程如下图所示。分为3个阶段：

• 阶段1：首先检查SIM卡的状态，确认SIM卡是否已经就绪。如果SIM卡已经就绪，则进入下一个阶段；否则等待SIM卡就绪，直到超时时间到了才返回。

• 阶段2：则开始检查设备的网络注册状态。如果设备已经注网成功，则进入下一个阶段；否则等待设备注网成功，直到超时时间到了才返回。

• 阶段3：开始检查蜂窝无线网卡的激活状态。如果蜂窝无线网卡已经激活成功，则直接返回检查结果；否则等待蜂窝无线网卡激活成功，直到超时时间到了才返回。

网络事件监听

网络事件监听是QuecPython蜂窝无线网卡特有的机制之一，旨在以高效及时的方式通知用户的应用程序，设备网络连接状态发生了变化。用户应用程序可以根据网络状态变化来及时的做出合适的处理。

之所以说这种机制高效及时，是因为QuecPython提供方法让用户应用程序去注册回调函数。当设备与无线网络的连接状态发生变化时，系统就会将对应的事件推送给用户的应用程序。相比于让用户应用程序经常主动的去查询设备网络连接状态，QuecPython这种网络监听机制则更加高效并且及时了。

用户可以通过下面的方法来注册监听回调函数：

dataCall.setCallback(fun)

关于该方法的详细说明，请参考QuecPython官网API参考手册内dataCall模块的回调注册功能部分，这里主要说明如何使用。

回调函数的示例如下：

def network_event_callback(args):
    profileID = args[0]
    netState = args[1]
    if netState == 0:
        print('### network {} disconnected.'.format(profileID))
    elif netState == 1:
        print('### network {} connected.'.format(profileID))

该回调函数的参数是一个元组，包含3个元素，目前用户只需要关注前两个元素即可。前两个参数说明如下：

下面是一个简单的示例，在该示例代码中，我们注册了网络事件监听的回调函数，然后在回调函数中打印网络状态。并且通过将模组先切换到飞行模式，来模拟网络网络异常导致的连接断开；再切回正常模式，来模拟网络网络异常因素消失后，网络连接重新恢复的过程。

import net
import utime
import dataCall


def network_event_callback(args):
    profile_id = args[0]
    conn_state = args[1]
    ret = dataCall.getInfo(1, 0)
    if conn_state == 0:
        print('### NIC{} network disconnected.'.format(profile_id))
    elif conn_state == 1:
        print('### NIC{} network connected.'.format(profile_id))
    else:
        print('Unknown event.')
    print('Current NIC information:{}'.format(ret))


def main():
    # 注册网络事件监控回调函数
    dataCall.setCallback(network_event_callback)
    ret = dataCall.getInfo(1, 0)
    print('Current NIC information:{}'.format(ret))
    # 切换到飞行模式，会导致模组网络连接断开
    net.setModemFun(4)
    utime.sleep(5)
    # 切换到正常模式，此时模组会重新进行网络注册并激活无线网卡
    net.setModemFun(1)


if __name__ == '__main__':
    main()

上面的示例仅仅是为了让用户直观的感受一下QuecPython的网络事件监控功能。如果用户需要在实际项目中使用，请参考后续《网络异常处理》章节中网络异常事件处理示例部分。

多路蜂窝无线网卡

多路蜂窝无线网卡指的是模组为了满足用户设备同时接入多个网络的需求，从软件上虚拟出来多张蜂窝无线网卡。

场景

前面我们提到，APN是终端入网时必须配置的一个参数，它决定了终端通过哪种接入方式来访问网络。而不同的接入点所能访问的范围以及接入的方式是不同的，即APN决定了终端设备通过哪种接入方式来访问什么样的网络。那么对于终端设备来说，能否配置多个不同的APN，让终端设备可以同时连接到不同的网络服务呢？答案是肯定可以的。

因此，当用户需要他们的产品能在连接公共网络（Internet）的同时，还需要能接入一些专用网络时，就需要使用到多路蜂窝无线网卡。此时需要给不同的网卡配置不同的APN，并激活这些网卡，即可实现用户需求。

说明

QuecPython各个平台的模组都可以虚拟出多路蜂窝无线网卡，为了平台的统一性，开放给用户使用的网卡有3路，即用户可以同时激活和使用3路网卡，这3路网卡没有其他特殊用途。同时，各个平台的VoLTE功能也会占用一路网卡，具体占用哪一路，各个平台不一样，但是不会占用开放给用户使用的3路网卡。

BG95系列的模组，在NB网络制式下，实际只支持激活最多2路网卡。