# yuge_cat1_opencpu

**Repository Path**: yuge-info/yugecat1opencpu

## Basic Information

- **Project Name**: yuge_cat1_opencpu
- **Description**: 域格CAT1模块通用opencpu
支持KE7SA、KE7EU、A09、A19EU、A19EV、A19NA、A19NE、MV9、LV9、B19EU、B19EA等模块二次开发。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-10-21
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


  **<span style="color:red;font-size:30px;"><br>当前SDK版本：V5.8.8<br></span>**  

## 1. 概述

本文档介绍上海域格 Cat.1 通信模块的 OpenCPU SDK。OpenCPU 模式允许用户在模块上直接运行自定义应用程序（以下简称"应用"或"APP"），通过 SDK 提供的丰富接口访问网络、串口、GPIO、文件系统等系统功能，从而快速实现物联网终端产品的开发。

## 2. SDK 特性

- **OpenCPU 本地应用运行**：支持 C 语言开发，应用直接在模块上运行
- **LTE 数据自动拨号**：集成 LTE 数据连接管理，简化网络配置
- **内置网络协议栈**：完整的 TCP/IP 协议栈，支持 HTTP、MQTT 等应用层协议
- **丰富的外设接口**：提供 UART、SPI、I2C、GPIO、ADC 等硬件接口访问
- **AT 命令支持**：内置 ATCMD 客户端和服务端，兼容传统 AT 命令开发模式
- **文件系统**：支持文件读写操作，便于数据存储和管理
- **OTA 升级机制**：支持固件远程升级，便于产品维护和功能更新
- **调试与日志**：完善的调试输出和日志记录功能

## 3. SDK 目录结构
```shell
SDK_ROOT/
├── core/           	# OpenCPU core library and header files
├── doc/            	# SDK documentation
├── fota/ 	        	# fota description
├── sample/         	# API usage examples
├── tools/          	# Build tools including Makefile utilities and compiler
├── build.bat       	# Build script for Windows
├── readme.md       	# Quick start
└── ReleaseNotes.txt    # ReleaseNotes
```
## 4. 开发环境准备

- **操作系统**：Windows 10/11（推荐）
- **获取SDK**：git clone https://gitee.com/yuge-info/yugecat1opencpu

- **交叉编译工具链**

   下载Arm GNU工具链，下载后解压到`tools`目录，并改名为`gcc-arm-none-eabi`。推荐下载地址:  
<https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-win32.zip>

		<select.h> 文件第11行改成 "#if 0"
		//# if !(defined (_WINSOCK_H) || defined (_WINSOCKAPI_) || defined (__USE_W32_SOCKETS))
		#if 0

		
- **模块固件包**：支持OpenCPU的固件包，烧录使用
- **烧录工具**：厂商提供的专用烧录工具
- **串口调试工具**：PuTTY、sscom 或类似串口终端软件

## 5. 快速上手（创建最小可运行应用）

### 5.1 编译步骤

1. **打开命令行**：使用 CMD 或 PowerShell，进入 SDK 顶层目录（vscode等工具打开，使用终端编译也很方便）。
2. **编译示例**：执行 `build.bat -c 1605c -t socket -autopkg A09 sample\example_base` 命令，生成app.bin文件，并自动打包完整烧录固件在out目录下。
4. **烧录模块**：使用aboot工具将固件写入模块

   V5.8.0及以后Git仓库移除aboot下载工具。下载地址:  
<https://docs.yuge-info.com/lib/exe/fetch.php?media=asr:cat1:tool:aboot-tools-2025.02.15-win10-x64.7z>
   a). 打开tools\aboot\aboot.exe,切换到 Download 界面；
   b). Download界面选择固件包，点击start，等待烧录下载;
   c). 重启模块或者使用指令"AT$MYDOWNLOAD=1"使模块自动进入下载模式，即可通过USB进行下载。
   **备注：Download界面不要勾选“Production mode”，勾选后烧录会擦除模块内IMEI、SN、以及射频校准参数。**

5. **调试测试**：通过串口连接模块调试端口或者使用CATStudio工具，观察启动日志并进行交互测试

### 5.2 编译命令示例
```shell
    1. 编译
   	 build.bat -c 1605c -t socket -autopkg A09 sample\example_base
    2. 清空编译
   	 build.bat -c 1605c -t socket -autopkg A09 sample\example_base clean
    3. 指定芯片型号
   	 "-c"，用于指定芯片型号，：1603c、1605c、1605s、1606l、1606c、1606s
    4. 指定编译类型
   	 "-t"，用于指定软件功能，：socket、usbnet、audio、sms、tiny、volte
    	 1). socket: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(仅支持http) ;
    	 2). usbnet: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(仅支持http), rndis/ecm ; 
    	 3). audio: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(支持https), tts, mp3, ppp, rndis/ecm; 
    	 4). sms: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(支持https), sms, ppp, rndis/ecm; 
    	 5). tiny: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(支持https), ppp, rndis/ecm; 
    	 6). volte: 支持socket, gpio, uart, i2c, spi, adc, powerkey, fota(支持https), sms, ppp, rndis/ecm, volte; 
    	 -- 1603c支持的编译类型：volte、audio
    	 -- 1605c支持的编译类型：socket、usbnet
    	 -- 1605s支持的编译类型：audio、sms、tiny
    	 -- 1606l支持的编译类型：socket、usbnet
    	 -- 1606c支持的编译类型：volte、audio
    	 -- 1606s支持的编译类型：volte
    5. 指定模块型号自动打包
   	 "-autopkg"，用于指定自动打包的模块型号：KE7SA、KE7EU、A09、A19EU、A19EV、A19NA、A19NE、A19SA、A19JP、MV9、LV9、B09、B19EU、B19EA
    6. 第三方库编译使用
   	 mqtt 和 mbedtls 以源码形式开放，存放在core目录下，使用可以参照mqtt对应demo中的makefile。
```

## 6. 应用架构（参考sample\example_base）

### 6.1 程序入口

- **主函数**：`main()` 是应用的入口函数，通常仅进行必要的初始化操作
- **任务创建**：建议在 `main()` 中创建新的任务（Task）来处理用户业务逻辑
- **执行时机**：`main()` 在模块初始化阶段被调用，此时网络服务尚未可用，需要等待网络初始化完成，参照demo中`wait_network_ready()`函数。

### 6.2 应用任务

- **任务函数**：`base_task()` 或其他自定义任务函数，用于运行用户业务逻辑


## 7. 调试与日志

### 7.1 日志输出

- **输出接口**：默认通过 UART 输出调试信息
- **启动日志**：模块启动时会输出 boot 日志，便于诊断启动过程
- **应用日志**：应用可通过 `Makefile`的`CFLAGS`定义日志输出
  - `__LOG_UART__` 日志输出到调试串口
  - `__LOG_ACAT__` 日志输出到CATStudio，需要匹配的MDB文件在: `tools\aboot\images\prebuilt\160x\cp_160x`

### 7.2 常见问题排查

#### 无启动日志

1. **检查串口连接**：确认连接的是调试串口（通常为 UART1）
2. **检查电平匹配**：模块调试串口为 1.8V 电平，需使用电平转换器或兼容的调试器
3. **检查波特率**：默认波特率为 115200bps，N-8-1（无校验，8 数据位，1 停止位）

#### 无网络连接

1. **检查 SIM 卡**：确认 SIM 卡已正确插入且未被锁定
2. **检查天线连接**：确认天线已正确连接且阻抗匹配良好
3. **检查 APN 配置**：根据实际网络环境确认是否需要指定APN，现在大部分SIM卡不需要特殊配置APN，使用网络下发的APN即可。

## 8. 开发注意事项

### 8.1 可用存储
```shell
	APP可用RAM空间
	 (1). 静态分配空间: 包含：代码区(.text)‌、常量区(.rodata)、‌全局静态区‌(.data,.bss)
	 (2). 空闲Heap: 该空间app和系统共用，手动管理（如malloc/free）‌，最好控制剩余空间不要小于100KB，如使用RNDIS/ECM尽可能剩余更多以满足带宽需求。
	APP可用ROM空间
	 (1). APP分区: 用于存放app.bin镜像的flash分区大小。
	 (2). NVM分区：文件系统分区，空闲空间用于存储系统文件以及app配置文件，以及存储app单独升级时的fota包，系统差分升级时文件系统可能会被擦除。
	 (3). APPNVM分区：默认都是12KB，用于存储app需要永久保存的参数（example_hal\hal_flash.c）,系统差分升级时也不会擦除。
	-----------------------------------------------------------------------------------------------
	|             project               |  APP静态空间  | 空闲Heap | APP分区 | NVM分区 | APPNVM分区 |
	-----------------------------------------------------------------------------------------------
	| 1603c_volte (8MB RAM + 8MB Flash) |         384KB|    1600KB|    280KB|   380KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1603c_audio (8MB RAM + 8MB Flash) |         384KB|    1600KB|    180KB|   300KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1605c_socket(4MB RAM + 2MB Flash) |         256KB|     380KB|    168KB|   252KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1605c_usbnet(4MB RAM + 2MB Flash) |         160KB|     350KB|    156KB|   220KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1605s_audio (4MB RAM + 4MB Flash) |         512KB|    1200KB|    260KB|   260KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1605s_sms   (4MB RAM + 4MB Flash) |         512KB|    1100KB|    400KB|   600KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1605s_tiny  (4MB RAM + 4MB Flash) |        1024KB|     900KB|    600KB|   900KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1606l_socket(4MB RAM + 2MB Flash) |         128KB|     350KB|    160KB|   200KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1606l_usbnet(4MB RAM + 2MB Flash) |          64KB|     350KB|    140KB|   180KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1606c_volte (4MB RAM + 4MB Flash) |         128KB|     400KB|    260KB|   300KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1606c_audio (4MB RAM + 4MB Flash) |         320KB|    1200KB|    180KB|   220KB|        12KB|
	-----------------------------------------------------------------------------------------------
	| 1606s_volte (8MB RAM + 8MB Flash) |        2048KB|    3000KB|   1500KB|  1700KB|        12KB|
	-----------------------------------------------------------------------------------------------
	
	备注：如果遇到RAM或者FALASH空间稍有不足的情况，可以联系FAE根据具体需求做适当的调整。
```

### 8.2 C 标准库支持

通过在 Makefile 中添加 `USE_LIBC=yes` 来启用 C 标准库。启用后可以使用标准 C 库函数，注意：

- 内存管理函数（`malloc()`/`free()`）始终可用，由系统OS提供，不占用APP可用RAM
- 可以不启用C 标准库，生成的应用Bin文件明显变小
- 启用 `USE_LIBC=yes` 时，应同时启用 `USE_NANO=yes`

### 8.3 生产模式检测

在生产环境中，必须检测模块是否处于生产测试模式（无需原厂使用自定义固件生产的可以忽略）：

- **检测方法**：通过 `dev_IsProductionMode()` API 进行判定
- **安全控制**：模块默认非生产模式，生产时通过USB发送AT*PROD=1进入生产模式，建议开机15s内不要进行重启、关机、禁用USB、飞行模式等操作。
- **模式切换**：重启后自动退出生产模式

### 8.4 应用版本号管理

为便于生产管理和版本追溯，必须设置应用版本号（无需原厂使用自定义固件生产的可以忽略）：

- **设置方法**：通过 `dev_SetAppVersion()` API 设置版本号
- **读取方法**：可通过 AT 命令 `AT+APPVER` 读取已设置的应用版本号
- **版本格式**：可以使用语义化版本号（如 "1.0.0"），提供固件给原厂生产时用于区分版本号

### 8.5 版本发布流程

1. **编译生成**：编译生成 app.bin 文件
2. **固件打包**：自动打包 *.zip 文件在 out 目录下
3. **版本归档**：提供固件给原厂生产时需要提供：
    - *.zip 文件
    - *_MDB.txt 文件 （原厂生产时校准测试需要使用，存放在 `tools\aboot\images\prebuilt\160x\cp_160x` 对应目录下）

### 8.7 其他注意事项
```shell
1. 参照《Gitee仓库订阅指南.pdf》通过邮箱或者微信订阅仓库，SDK如有重大更新需要通过到客户，会通过邮件或者微信及时通知。
2. 关注下《开发注意事项.pdf》中的注意事项。
3. 关注下《ReleaseNotes.txt》中的更新记录。
```