SIM 开发指导_Rev1.3

English

修订记录

版本

日期

作者

修订内容

Rev1.0

23-09-14

YPP

创建文档

Rev1.1

24-03-25

sxx

更改文档名称

Rev1.2

24-10-25

LJZ

修改文档格式

Rev1.3

25-04-18

ZH

增加系列常见问题

1 简介

本文档主要介绍 LTE-EC71X OpenCPU SIM API 函数详解，API 位于 components/kernel/lierda_api/liot_sim/liot_sim.h 文件。

2 API 函数概览

函数

说明

liot_sim_get_imsi()

获取 SIM 卡的 IMSI

liot_sim_get_iccid()

获取 SIM 卡的 ICCID

liot_sim_get_phonenumber()

获取 SIM 卡本机号码

liot_sim_get_card_status()

获取 SIM 卡缓存状态信息

3 API 函数详解

3.1 liot_sim_get_imsi

该函数用于获取 SIM 卡的 IMSI。

  • 函数

liot_sim_errcode_e liot_sim_get_imsi(uint8_t nSim, char *imsi, size_t imsiLen)

  • 参数

nSim：

[In] 所用的 SIM 卡，范围：0~1。

imsi：

[Out] SIM 卡的 IMSI，字符串。

imsiLen：

[In] IMSI 数组的长度。

  • 返回值

详见第 3.1.1 章。

3.1.1 liot_sim_errcode_e

SIM API 执行结果错误码。

typedef enum
{
    LIOT_SIM_SUCCESS     = 0,
    LIOT_SIM_EXECUTE_ERR = 1 | LIOT_SIM_ERRCODE_BASE,
    LIOT_SIM_MEM_ADDR_NULL_ERR,
    LIOT_SIM_INVALID_PARAM_ERR,
    LIOT_SIM_NO_MEMORY_ERR,
    LIOT_SIM_SEMAPHORE_CREATE_ERR = 5 | LIOT_SIM_ERRCODE_BASE,
    LIOT_SIM_SEMAPHORE_TIMEOUT_ERR,
    LIOT_SIM_NOT_INSERTED_ERR,
    LIOT_SIM_CFW_IMSI_GET_REQUEST_ERR,
    LIOT_SIM_CFW_IMSI_GET_RSP_ERR,
    LIOT_SIM_CFW_ICCID_GET_REQUEST_ERR = 10 | LIOT_SIM_ERRCODE_BASE,
    LIOT_SIM_CFW_PHONE_NUM_GET_REQUEST_ERR,
    LIOT_SIM_CFW_PHONE_NUM_GET_RSP_NULL_ERR,
    LIOT_SIM_CFW_STATUS_GET_REQUEST_ERR,
    LIOT_SIM_CFW_PIN_ENABLE_REQUEST_ERR,
    LIOT_SIM_CFW_PIN_DISABLE_REQUEST_ERR = 15 | LIOT_SIM_ERRCODE_BASE,
    LIOT_SIM_CFW_PIN_RevERIFY_REQUEST_ERR,
    LIOT_SIM_CFW_PIN_CHANGE_REQUEST_ERR,
    LIOT_SIM_CFW_PIN_UNBLOCK_REQUEST_ERR,
    LIOT_SIM_OPERATION_NOT_ALLOWED_ERR,
    LIOT_PBK_NOT_EXIT_ERR = 100 | LIOT_SIM_ERRCODE_BASE,
    LIOT_PBK_NOT_INIT_ERR,
    LIOT_PBK_ITEM_NOT_FOUND_ERR,
} liot_sim_errcode_e;

  • 参数

参数

描述

LIOT_SIM_SUCCESS

执行成功

LIOT_SIM_EXECUTE_ERR

执行失败

LIOT_SIM_MEM_ADDR_NULL_ERR

参数地址为空

LIOT_SIM_INVALID_PARAM_ERR

参数无效

LIOT_SIM_NO_MEMORY_ERR

申请内存失败

LIOT_SIM_SEMAPHORE_CREATE_ERR

创建信号量失败

LIOT_SIM_SEMAPHORE_TIMEOUT_ERR

等待信号量超时

LIOT_SIM_NOT_INSERTED_ERR

未插卡

LIOT_SIM_CFW_IMSI_GET_REQUEST_ERR

请求获取 IMSI 号失败

LIOT_SIM_CFW_IMSI_GET_RSP_ERR

响应获取 IMSI 号失败

LIOT_SIM_CFW_ICCID_GET_REQUEST_ERR

请求获取 ICCID 号失败

LIOT_SIM_CFW_PHONE_NUM_GET_REQUEST_ERR

请求获取本机号码失败

LIOT_SIM_CFW_PHONE_NUM_GET_RSP_NULL_ERR

本机号码为空

LIOT_SIM_CFW_STATUS_GET_REQUEST_ERR

请求获取卡状态失败

LIOT_SIM_CFW_PIN_ENABLE_REQUEST_ERR

请求卡 PIN 码使能失败

LIOT_SIM_CFW_PIN_DISABLE_REQUEST_ERR

请求卡 PIN 码去使能失败

LIOT_SIM_CFW_PIN_VERIFY_REQUEST_ERR

请求 PIN 码验证失败

LIOT_SIM_CFW_PIN_CHANGE_REQUEST_ERR

请求卡 PIN 码更改失败

LIOT_SIM_CFW_PIN_UNBLOCK_REQUEST_ERR

请求卡 PIN 码解锁失败

LIOT_SIM_OPERATION_NOT_ALLOWED_ERR

操作不被允许

LIOT_PBK_NOT_EXIT_ERR

卡 PBK 未退出

LIOT_PBK_NOT_INIT_ERR

卡 PBK 未初始化

LIOT_PBK_ITEM_NOT_FOUND_ERR

卡 PBK item 未找到

3.2 liot_sim_get_iccid

该函数用于获取 SIM 卡的 ICCID。

  • 函数

liot_sim_errcode_e liot_sim_get_iccid(uint8_t nSim, char *iccid, size_t iccidLen)

  • 参数

nSim：

[In] 所用的 SIM 卡，范围：0~1。

iccid：

[Out] SIM 卡的 ICCID，字符串。

imsiLen：

[In] iccid 数组的长度。

  • 返回值

详见第 3.1.1 章。

3.3 liot_sim_get_phonenumber

该函数用于获取 SIM 卡本机号码。

  • 函数

liot_sim_errcode_e liot_sim_get_phonenumber(uint8_t nSim, char *phonenumber, size_t phonenumberLen)

  • 参数

nSim：

[In] 所用的 SIM 卡，范围：0~1。

phonenumber：

[Out] SIM 卡本机号码，字符串。

phonenumberLen：

[In] phonenumber 数组的长度。

  • 返回值

详见第 4.1.1 章。

3.4 liot_sim_get_card_status

该函数用于获取 SIM 卡缓存状态信息。

  • 函数

liot_sim_errcode_e liot_sim_get_card_status(uint8_t nSim, liot_sim_status_e *cardStatus)

  • 参数

nSim：

[In] 所用的 SIM 卡，范围：0~1。

cardStatus：

[Out] 详见第 3.4.1 章。

  • 返回值

详见第 4.1.1 章。

3.4.1 liot_sim_status_e

SIM 卡状态。

typedef enum
{
    LIOT_SIM_STATUS_READY = 0,
    LIOT_SIM_STATUS_PIN1_READY,
    LIOT_SIM_STATUS_SIMPIN,
    LIOT_SIM_STATUS_SIMPUK,
    LIOT_SIM_STATUS_PHONE_TO_SIMPIN,
    LIOT_SIM_STATUS_PHONE_TO_FIRST_SIMPIN = 5,
    LIOT_SIM_STATUS_PHONE_TO_FIRST_SIMPUK,
    LIOT_SIM_STATUS_SIMPIN2,
    LIOT_SIM_STATUS_SIMPUK2,
    LIOT_SIM_STATUS_NETWORKPIN,
    LIOT_SIM_STATUS_NETWORKPUK = 10,
    LIOT_SIM_STATUS_NETWORK_SUBSETPIN,
    LIOT_SIM_STATUS_NETWORK_SUBSETPUK,
    LIOT_SIM_STATUS_PROVIDERPIN,
    LIOT_SIM_STATUS_PROVIDERPUK,
    LIOT_SIM_STATUS_CORPORATEPIN = 15,
    LIOT_SIM_STATUS_CORPORATEPUK,
    LIOT_SIM_STATUS_NOSIM,
    LIOT_SIM_STATUS_PIN1BLOCK,
    LIOT_SIM_STATUS_PIN2BLOCK,
    LIOT_SIM_STATUS_PIN1_DISABLE = 20,
    LIOT_SIM_STATUS_SIM_PRESENT,
    LIOT_SIM_STATUS_UNKNOW,
} liot_sim_status_e;

  • 参数

常见参数

描述

LIOT_SIM_STATUS_READY

状态已就绪

LIOT_SIM_STATUS_SIMPIN

等待验证 PIN 码

LIOT_SIM_STATUS_SIMPUK

等待验证 PUK 码

LIOT_SIM_STATUS_SIMPIN2

等待验证 PIN2 码

LIOT_SIM_STATUS_SIMPUK2

等待验证 PUK2 码

LIOT_SIM_STATUS_NOSIM

未插卡

LIOT_SIM_STATUS_UNKNOW

未知状态

4 代码示例

示例代码参考 examples/demo/src/demo_sim.c 文件。如下运行结果则说明获取所有信息正常：

_images/sim-guide/image_1.png

5 常见问题

5.1 是否支持 SIM 卡热插拔

支持，软件上需要用户自己用 WAKEUP 脚检测拔插卡动作，然后调用appSetSIMHotSwapNotify 函数去通知协议栈走插拔卡流程。

5.2 EC718 是否支持双 SIM 卡？

支持。双卡单待，SIM2 只支持 1.8V 卡。

5.3 EC718 是否支持海外运营商的 APN LIST？

可以。   说明如下：

1 、随卡匹配特性为用户可定制特性，若用户需要使用，则需要在 psdial_plmn_param.h 文 件 中 ， 打 开

FEATURE_PER_PLMN_ENABLE 宏（默认是未定义的，目的是节省 flash 和 RAM）；

2、随卡配置功能受 NV 控制，默认不使能。在第一次开机后，需要使用 AT+ECCFG=“AutoApn”,1 命令使能该特性，若不需要使用该功能，使用 AT+ECCFG=“AutoApn”,0 命令去使能该特性。

3、由于全球 plmn 非常多，目前我们只提供部分常用 PLMN 的配置信息，后续客户需要使用的 PLMN 信息如果不在当前表中，

可以自行补充（客户可以定制 psdial_plmn_param.c 文件中的参数）；

4、当前的 plmn 配置信息占用 AP 空间较大，客户也可以对 PLMN 表适当进行剪裁；

5、打开后增加 20K+ flash，<1K RAM 空间