# IPAE_SDK

**Repository Path**: whyword/ipae_-sdk

## Basic Information

- **Project Name**: IPAE_SDK
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IPAE SDK

**ESIM APN自动配置SDK - 设备端组件**

版本：v1.2

---

## 简介

IPAE SDK帮助eSIM设备自动处理Profile切换后的APN配置问题。

**核心问题：** Profile切换后APN不匹配导致无法联网。

**解决方案：**
- ICCID前缀匹配APN规则
- 网络状态触发检测（AT+CREG?）
- HTTP远程更新规则表
- 种子号救援机制

---

## 特性

| 特性 | 说明 |
|------|------|
| ✅ ICCID前缀匹配 | 最长前缀优先，支持7-8位前缀 |
| ✅ 网络状态触发检测 | 正常不干扰，异常自动检查 |
| ✅ HTTP规则表更新 | 版本比对，按需下载 |
| ✅ HTTP重试机制 | 失败自动重试（默认3次） |
| ✅ HTTP超时配置 | 可配置超时时间（默认10秒） |
| ✅ checksum存储 | 自动存储和显示checksum |
| ✅ 日志级别控制 | INFO/WARN/ERROR/OFF四级 |
| ✅ 存储持久化 | 重启后数据自动恢复 |
| ✅ 事件回调系统 | 5种事件类型通知 |
| ✅ 轻量级实现 | 无外部依赖，纯C实现 |

---

## 快速开始

### 最小集成（5分钟）

```c
#include "esim_apn_sdk.h"

// 实现AT指令发送接口（必需）
int my_at_send(const char* cmd, char* response, int timeout) {
    // 发送AT指令到Modem，返回响应
}

// 初始化SDK
esim_apn_sdk_config_t config = {
    .at_send = my_at_send,
    .server_url = "http://your-server.com",
    .eid = "your-device-eid"
};

esim_apn_sdk_init(&config);

// 定时调用（建议1分钟间隔）
esim_apn_sdk_check_network();
```

**SDK会自动：**
- 检测网络异常
- 读取ICCID变化
- 匹配正确的APN
- 设置APN配置

---

## 目录结构

```
sdk/
├── include/
│   ├── esim_apn_types.h    # 类型定义
│   └── esim_apn_sdk.h      # 主接口
│
├── src/
│   ├── esim_apn_sdk.c      # 主实现
│   ├── apn_matcher.c       # APN匹配算法
│   ├── json_parser.c       # JSON解析
│   └── table_manager.c     # 规则表管理
│
├── test/
│   ├── test_apn_matcher.c  # 匹配模块测试
│   ├── test_json_parser.c  # JSON解析测试
│   └── test_sdk_full.c     # SDK完整测试
│
├── examples/
│   └── esp32_test.ino      # ESP32 Arduino示例
│
├── Makefile                # 编译脚本
└── README.md               # 本文档
```

---

## 内置规则表

| 品牌 | ICCID前缀 | 前缀长度 | APN |
|-----|----------|---------|-----|
| 卓一/盈科 | 8985200 | 7位 | mobile |
| 万利 | 8944461 | 7位 | wanli |
| 中移 | 8985234 | 7位 | cmlink |
| 比利时 | 89320420 | 8位 | bicsapn |

---

## 测试

### 本地测试（无需ESP32）

```bash
cd sdk
make test
```

### 交互式测试

```bash
cd sdk
make interactive
```

可用命令：
- `switch:ICCID` - 模拟Profile切换
- `check` - 检查ICCID变化
- `status` - 显示状态
- `match:ICCID` - 测试匹配
- `test` - 运行所有测试
- `quit` - 退出

---

## ESP32集成

### PlatformIO项目

```
hello_esp32/
├── platformio.ini
├── src/
│   └── main.cpp
└── lib/
    └── esim_apn_sdk/
        ├── esim_apn_sdk.c
        ├── apn_matcher.c
        ├── table_manager.c
        ├── json_parser.c
        ├── esim_apn_sdk.h
        └── esim_apn_types.h
```

### ESP32测试命令

| 命令 | 说明 |
|-----|------|
| `netstat:0-5` | 模拟网络状态 |
| `checknet` | 手动检查网络 |
| `switch:ICCID` | 模拟Profile切换 |
| `update` | HTTP更新规则表 |
| `status` | 显示状态 |
| `match:ICCID` | 测试匹配算法 |
| `test` | 运行自动测试 |
| `boundary` | 边界测试 |
| `stress` | 压力测试 |
| `multiupdate` | 存储测试 |

---

## API概览

### 核心接口

| 函数 | 说明 |
|------|------|
| `esim_apn_sdk_init()` | 初始化SDK |
| `esim_apn_sdk_check_network()` | 检查网络状态（定时调用） |
| `esim_apn_sdk_check_iccid()` | 检查ICCID变化 |
| `esim_apn_sdk_get_apn()` | 根据ICCID获取APN |
| `esim_apn_sdk_set_apn()` | 设置APN配置 |
| `esim_apn_sdk_update_table()` | HTTP更新规则表 |
| `esim_apn_sdk_get_status()` | 获取SDK状态 |
| `esim_apn_sdk_set_callback()` | 注册事件回调 |

### 错误码

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| -1 | 参数无效 |
| -2 | 内存不足 |
| -3 | 无匹配APN |
| -4 | AT指令失败 |
| -5 | HTTP请求失败 |
| -6 | 存储失败 |
| -7 | 解析失败 |
| -8 | 未初始化 |
| -9 | 接口未提供 |

---

## 事件回调

| 事件 | 说明 |
|------|------|
| `PROFILE_SWITCH` | Profile切换 |
| `APN_CHANGED` | APN已变更 |
| `TABLE_UPDATED` | 规则表已更新 |
| `NO_MATCH` | 无匹配APN |
| `NETWORK_ERROR` | 网络异常（ICCID未变） |
| `ERROR` | 错误发生 |

---

## 规则表JSON格式

```json
{
  "version": "v1.0.0",
  "checksum": "abc123def456",
  "seed_apn": {
    "apn": "seed.global.example.com",
    "auth_type": 0
  },
  "rules": [
    {
      "iccid_prefix": "8985200",
      "prefix_length": 7,
      "apn": "mobile",
      "auth_type": 0,
      "comment": "卓一/盈科"
    }
  ]
}
```

---

## 文档

| 文档 | 位置 |
|------|------|
| SDK设计方案 | `docs/SDK设计方案.md` |
| API参考文档 | `docs/API参考文档.md` |
| 集成指南 | `docs/SDK集成指南.md` |
| 更新日志 | `docs/更新日志.md` |
| 真实硬件测试流程 | `docs/真实硬件测试流程.md` |

---

## 版本历史

| 版本 | 日期 | 主要更新 |
|------|------|----------|
| v1.2 | 2026-05-12 | HTTP重试、超时配置、checksum、日志级别 |
| v1.1 | 2026-05-11 | 网络状态触发检测、3位版本号 |
| v1.0 | 2026-05-10 | 初始发布 |

---

## 仓库地址

**码云：** https://gitee.com/whyword/ipae_-sdk

```bash
git clone https://gitee.com/whyword/ipae_-sdk.git
```

---

## License

MIT License