SIM Development Guide_Rev1.3

中文

Revision History

Version	Date	Author	Revision Content
Rev1.0	23-09-14	YPP	Initial document creation
Rev1.1	24-03-25	sxx	Changed document name
Rev1.2	24-10-25	LJZ	Modified document format
Rev1.3	25-04-18	ZH	Added common issues section

1 Introduction

This document mainly introduces the detailed explanation of LTE-EC71X OpenCPU SIM API functions. The APIs are located in the file components/kernel/lierda_api/liot_sim/liot_sim.h.

2 API Function Overview

Function	Description
liot_sim_get_imsi()	Get SIM card IMSI
liot_sim_get_iccid()	Get SIM card ICCID
liot_sim_get_phonenumber()	Get SIM card phone number
liot_sim_get_card_status()	Get SIM card cached status information

3 API Function Details

3.1 liot_sim_get_imsi

This function is used to get the SIM card’s IMSI.

• Function

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

• Parameters

nSim:

[In] SIM card used, range: 0~1.

imsi:

[Out] SIM card’s IMSI, string.

imsiLen:

[In] Length of IMSI array.

• Return Value

See Chapter 3.1.1 for details.

3.1.1 liot_sim_errcode_e

SIM API execution result error codes.

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_VERIFY_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;

• Parameters

Parameter	Description
LIOT_SIM_SUCCESS	Execution successful
LIOT_SIM_EXECUTE_ERR	Execution failed
LIOT_SIM_MEM_ADDR_NULL_ERR	Parameter address is null
LIOT_SIM_INVALID_PARAM_ERR	Invalid parameter
LIOT_SIM_NO_MEMORY_ERR	Failed to allocate memory
LIOT_SIM_SEMAPHORE_CREATE_ERR	Failed to create semaphore
LIOT_SIM_SEMAPHORE_TIMEOUT_ERR	Semaphore wait timeout
LIOT_SIM_NOT_INSERTED_ERR	Card not inserted
LIOT_SIM_CFW_IMSI_GET_REQUEST_ERR	Failed to request IMSI number
LIOT_SIM_CFW_IMSI_GET_RSP_ERR	Failed to respond with IMSI number
LIOT_SIM_CFW_ICCID_GET_REQUEST_ERR	Failed to request ICCID number
LIOT_SIM_CFW_PHONE_NUM_GET_REQUEST_ERR	Failed to request phone number
LIOT_SIM_CFW_PHONE_NUM_GET_RSP_NULL_ERR	Phone number is null
LIOT_SIM_CFW_STATUS_GET_REQUEST_ERR	Failed to request card status
LIOT_SIM_CFW_PIN_ENABLE_REQUEST_ERR	Failed to request PIN code enable
LIOT_SIM_CFW_PIN_DISABLE_REQUEST_ERR	Failed to request PIN code disable
LIOT_SIM_CFW_PIN_VERIFY_REQUEST_ERR	Failed to request PIN code verification
LIOT_SIM_CFW_PIN_CHANGE_REQUEST_ERR	Failed to request PIN code change
LIOT_SIM_CFW_PIN_UNBLOCK_REQUEST_ERR	Failed to request PIN code unlock
LIOT_SIM_OPERATION_NOT_ALLOWED_ERR	Operation not allowed
LIOT_PBK_NOT_EXIT_ERR	Card PBK not exited
LIOT_PBK_NOT_INIT_ERR	Card PBK not initialized
LIOT_PBK_ITEM_NOT_FOUND_ERR	Card PBK item not found

3.2 liot_sim_get_iccid

This function is used to get the SIM card’s ICCID.

• Function

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

• Parameters

nSim:

[In] SIM card used, range: 0~1.

iccid:

[Out] SIM card’s ICCID, string.

iccidLen:

[In] Length of iccid array.

• Return Value

See Chapter 3.1.1 for details.

3.3 liot_sim_get_phonenumber

This function is used to get the SIM card’s phone number.

• Function

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

• Parameters

nSim:

[In] SIM card used, range: 0~1.

phonenumber:

[Out] SIM card phone number, string.

phonenumberLen:

[In] Length of phonenumber array.

• Return Value

See Chapter 4.1.1 for details.

3.4 liot_sim_get_card_status

This function is used to get the SIM card’s cached status information.

• Function

liot_sim_errcode_e liot_sim_get_card_status(uint8_t nSim, liot_sim_status_e *cardStatus)

• Parameters

nSim:

[In] SIM card used, range: 0~1.

cardStatus:

[Out] See Chapter 3.4.1 for details.

• Return Value

See Chapter 4.1.1 for details.

3.4.1 liot_sim_status_e

SIM card status.

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;

• Parameters

Common Parameters	Description
LIOT_SIM_STATUS_READY	Status ready
LIOT_SIM_STATUS_SIMPIN	Waiting for PIN code verification
LIOT_SIM_STATUS_SIMPUK	Waiting for PUK code verification
LIOT_SIM_STATUS_SIMPIN2	Waiting for PIN2 code verification
LIOT_SIM_STATUS_SIMPUK2	Waiting for PUK2 code verification
LIOT_SIM_STATUS_NOSIM	Card not inserted
LIOT_SIM_STATUS_UNKNOW	Unknown status

4 Code Example

Refer to the examples/demo/src/demo_sim.c file for sample code. The following execution result indicates that all information was obtained normally:

5 Common Issues

5.1 Does it Support SIM Card Hot Swap?

Yes, it supports hot swap. On the software side, users need to use the WAKEUP pin to detect card insertion/removal actions, and then call the appSetSIMHotSwapNotify function to notify the protocol stack to go through the card insertion/removal process.

5.2 Does EC718 Support Dual SIM Cards?

Yes, it supports dual SIM cards with single standby. SIM2 only supports 1.8V cards.

5.3 Does EC718 Support APN LIST for Overseas Operators?

Yes. Description as follows:

1. The per-card matching feature is a user-customizable feature. If users need to use it, they need to open the FEATURE_PER_PLMN_ENABLE macro in the psdial_plmn_param.h file (it is undefined by default to save flash and RAM);

2. The per-card configuration function is controlled by NV and is disabled by default. After the first boot, you need to use the AT+ECCFG=“AutoApn”,1 command to enable this feature. If you don’t need to use this function, use the AT+ECCFG=“AutoApn”,0 command to disable it.

3. Since there are many PLMNs worldwide, we currently only provide configuration information for some commonly used PLMNs. If customers need PLMN information that is not in the current table, they can supplement it themselves (customers can customize parameters in the psdial_plmn_param.c file);

4. The current PLMN configuration information occupies a large amount of AP space, and customers can also appropriately trim the PLMN table;

5. After enabling, it adds 20K+ flash and <1K RAM space.