1 文档介绍
1.1 文档范围及版本
本手册详细介绍了WIoTa终端模块及AP模组中FLASH中的静态数据的使用规则及相关接口。
静态数据版本分为AP、IoTE和Async，配置文件在最新的UC烧写工具版本中，本文档只介绍固件版本和静态数据版本的对应关系。
| 固件版本 | 静态数据版本 |
|---|---|
| ap_v0.13 | static_ap_v0.13.xlsx |
| ap_v0.14 | static_ap_v0.14.xlsx |
| iote_v0.13 | static_iote_v0.13.xlsx |
| iote_v0.14 | static_iote_v0.14.xlsx |
| async_v0.02 | static_async_v0.02.xlsx |
async_v0.02与iote_v0.14的静态数据结构完全一致。
1.2 静态数据结构
最新整体结构图如下：
终端静态数据总长度728byte，基站静态数据总长度572byte。
| 结构 | 长度 |
|---|---|
| 静态数据头标志 | 2 byte |
| 静态数据版本号 | 2 byte |
| 总静态数据长度 | 4 byte |
| 有效的静态数据长度 | 4 byte |
| 只读数据长度 | 4 byte |
| CRC32值 | 4 byte |
| 静态数据 | 基站：552 byte 终端：708 byte |
在芯片FLASH中的起始位置如下表。
备份区及其操作对于用户来说不可见，不可操作。
| 类型 | 静态空间起始位置 | 静态空间大小 | 备份空间起始位置 | 备份空间大小 |
|---|---|---|---|---|
| IoTE | 0x7F000 | 4KB | 0x7E000 | 4KB |
| AP | 0x1FF000 | 4KB | 0x1FE000 | 4KB |
1.2.1 静态数据头结构
1.2.1.1 静态数据头标志
静态数据头标志在所有表之前。
| 类型 | 长度(字节) | 内容 |
|---|---|---|
| 静态数据头标志 | 2 | "UC" |
1.2.1.2 静态数据版本
默认值1，随静态数据结构变动而变动。
1.2.1.3 总静态数据长度
基站侧默认值572 byte（v0.13版本为552bytes）， 终端侧默认值728 byte（v0.13版本为724bytes），该值一旦确定便不会更改。
1.2.1.4 有效静态数据长度
有效静态数据长度是指实际的静态数据长度，基站侧默认值552 byte（v0.14版本为552bytes，v0.13版本为532bytes）， 终端侧默认值708byte（v0.14版本为708bytes，v0.13版本为704bytes），该值一旦确定便不会更改。
1.2.1.5 只读静态数据长度
不可更改的成员的总长度。
1.2.2 静态数据
1.2.2.1 OTA静态信息表
OTA静态信息表，总长36bytes，其中未用到的空间为预留位。(v0.14版本为36bytes，v0.13版本为32bytes，区别详见下表，之前版本不再支持)
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| baud_flag | 1 | 数值 | 0 | 是否设置过uboot波特率 | 0/1 |
| mode | 1 | 字符串 | ` | uboot工作模式 | 小写字母'a'~'g' |
| uart_flag | 1 | 数值 | 1 | 日志串口选择 | 0/1 |
| log_flag | 1 | 数值 | 0 | 日志开关 | 0/1 |
| select_flag | 1 | 数值 | 1 | uboot提示开关 | 0/1,v0.14开始才有此参数 |
| NA | 3 | 无 | 0 | 预留 | v0.14开始才有此参数 |
| baud_rate | 4 | 数值 | 115200 | uboot波特率 | >=0 |
| file_size | 4 | 数值 | 0 | 已下载文件文件大小 | 0~252k |
| record_address | 4 | 数值 | 0 | 记录下载文件地址 | reserved开始地址/ota开始地址 |
| version | 4 | 字符串 | v1.0 | uboot版本 | 0~4byte |
| bin_partition_size | 4 | 数值 | 224k | 镜像分区大小 | 224k~476k |
| reserved_partition_size | 4 | 数值 | 128k | 恢复区分区大小 | 0~252k |
| ota_partition_size | 4 | 数值 | 124k | OTA分区大小 | 0~252k |
AP侧的OTA静态信息表，总长20bytes。 （v0.13版本无此表）
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| baud_rate | 4 | 数值 | 115200 | uboot波特率 | >=0 |
| file_size | 4 | 数值 | 0 | 已下载文件文件大小 | 0~704k |
| select_flag | 1 | 数值 | 0 | uboot提示开关 | 0/1 |
| log_flag | 1 | 数值 | 0 | 日志开关 | 0/1 |
| uart_flag | 1 | 数值 | 1 | 日志串口选择 | 0/1 |
| empty_flag | 1 | 空位 | 0 | 占位用的 | --- |
| version | 4 | 字符串 | v1.0 | uboot版本 | 0~4byte |
| baud_flag | 1 | 数值 | 0 | 是否设置过uboot波特率 | 0/1 |
| ota_flag | 1 | 字符串 | 0 | uboot工作模式 | 小写字母'a'~'g' |
| rt_ota_flag | 1 | 字符串 | 0 | uboot工作模式 | 小写字母'a'~'g' |
| reserved | 1 | 空位 | 0 | 对齐位 | --- |
1.2.2.2 设备静态信息表
设备信息表，总长128bytes，其中未用到的空间为预留位。
| 名称 | 长度(字节) | 类型 | 用途 | 备注 |
|---|---|---|---|---|
| user_id | 8 | 数值 | 用户ID | 1~8byte |
| dev_name | 16 | 字符串 | 设备名称 | 0~16byte |
| dev_serial | 16 | 字符串 | 设备串号 | 0~16byte |
| soft_ver | 16 | 字符串 | 软件版本号 | 0~16byte |
| manufacture_name | 16 | 字符串 | 厂商名字 | 0~16byte |
| hardware_ver | 16 | 字符串 | 硬件版本号 | 0~16byte |
| is_oscillator | 1 | 数值 | 是否有源晶体 | 0/1，基站无此项 |
| auto_connect/auto_run | 1 | 数值 | 终端自动连接/基站自动运行 | 0/1 |
| dtu_enable | 1 | 数值 | DTU开启状态 | 0/1 |
| dtu_at_show | 1 | 数值 | DTU状态下是否显示AT格式 | 0/1 |
| dtu_timeout | 2 | 数值 | DTU发送超时 | 0~65535 |
| dtu_wait | 2 | 数值 | DTU等待时长 | 0~65535 |
| dtu_exit | 8 | 字符串 | DTU退出字符串 | 1~8byte |
| NA | 24 | 无 | 预留 | 无 |
1.2.2.3 子系统配置表
子系统配置表，总长64bytes，其中未用到的空间为预留位。
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| apMaxPow | 1 | 数值 | 22 | 基站的最大功率 | 可设置范围为：0 - 29dbm |
| idLen | 1 | 数值 | 1 | 用户ID长度 | 0:16bit,1:32bit,2:48bit |
| pp | 1 | 数值 | 1 | pp配置，默认值为1，暂不支持修改 | 0:1,1:2,2:4 |
| symbolLen | 1 | 数值 | 1 | symbol长度 | 0:128,1:256,2:512,3:1024 |
| dlUlRatio | 1 | 数值 | 0 | 下行上行比 | 0:1比1,1:1比2 |
| subSysBt | 1 | 数值 | 1 | BT值 | 0:BT_1.2,1:BT_0.3 |
| groupNum | 1 | 数值 | 0 | 帧结构中的group数量 | 0:1,1:2,2:4,3:8 |
| spectrumIdx | 1 | 数值 | 3 | 指示所用频段 | 频谱idx，默认3即为470M-510M，详见频谱划分文档 |
| systemId | 4 | 数值 | 0x11223344 | 网络ID | 网络配置信息，32bit |
| subSysId | 4 | 数值 | 0x21456981 | 子系统ID | 子系统ID，32bit |
| freqList | 16 | 数值 | 0xFF、0xFF、…… | 频点列表 | 可以连接的频点集合，每个字节代表一个频点 |
| NA | 32 | 无 | 0 | 预留 | 无 |
1.2.2.4 射频静态信息表
射频静态信息表，终端总长160bytes，基站总长度84byte，其中未用到的空间为预留位。
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| temp_list | 32 | signed char | -49,-37,-33,-29,-25,-20,-16,-12, -6,1,8,15,22,31,43,55, 62,65,67,70,73,76,79,81, 84,89,94,99,104,109,114,119 |
温度列表 | -50度 ~ 127度，AP没有此表！ |
| dcxo_list | 32 | unsigned char | 35,34,33,32,31,30,29,28, 29,30,31,32,33,34,35,36, 35,34,33,32,31,30,29,28, 27,27,27,27,27,27,27,27 |
dcxo列表 | 大于等于对应温度，则为该dcxo，AP没有此表！ |
| powMin | 1 | signed char | -16 | 最小功率 | 单位dbm |
| powNum | 1 | unsigned char | 38 | 标志ramp_list表中有效数据数量 | 可根据最小功率和powNum推算出最大功率 |
| tx_mode | 1 | unsigned char | 3 | 功率模式，不同的功率模式，ramp_list也不同 | 0/1/2/3 四种功率模式，终端默认使用模式3，AP默认模式0 |
| rf_reserved | 1 | 数值 | 0 | 预留位 | 保证4字节对齐 |
| ramp_list | 80 | 数值 | 终端：0,2,4,7,10,14,17,20,26,28, 34,37,43,50,57,65,75,85,98,110, 117,140,159,179,200,229,260,290,322,361, 410,451,510,570,640,730,850,1023,1023,1023 基站：0,4,10,14,19,25,31,37,45,52, 61,72,82,94,108,123,141,160,182,207, 234,264,300,340,388,449,530,636,787,1023, 1023,1023,1023,1023,1023,1023,1023,1023,1023,1023 |
ramp列表 | 每个功率值对应一个ramp值 |
| NA | 12 | 无 | 0 | 预留 | AP没有此项 |
1.2.2.5 校准动态信息表
校准动态信息表，总长64bytes，其中未用到的空间为预留位。 (AP侧无此表)
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| dcxo | 1 | 数值 | 0x20 | dcxo校准值 | 0~63 |
| aAgcIdx | 1 | 数值 | 0xF | 模拟agc档位 | 0~15 |
| reserved | 2 | 数值 | 0 | 预留位，为了4字节对齐 | 无 |
| tempAdjust | 1 | 数值 | 0 | 温度校准值 | -20 ~ 20°C |
| dcxoDir | 1 | 数值 | 0 | dcxo校准偏移方向 | 0,1,2 |
| dcxoAdjust | 1 | 数值 | 0 | dcxo校准偏移值 | >= 0 |
| tcxoDirection | 1 | 数值 | 0 | tcxo校准偏移方向 | 0,1,2 |
| tcxoOffset | 4 | 数值 | 0 | tcxo校准偏移值 | >= 0 |
| NA | 52 | 无 | 0 | 预留 | 无 |
1.2.2.6 用户定制数据表
用户定制数据表，总长256bytes，由用户自己管理和分配。
| 名称 | 长度(字节) | 类型 | 默认值 | 用途 | 备注 |
|---|---|---|---|---|---|
| user_data | 256 | 无 | 0 | 用户定制数据 | 用户自己管理和分配 |
1.3 静态数据使用方法
FLASH中数据分为两个区，一个是静态区，一个是备份区，更新静态区数据时，先将所有数据写入备份区，再将所有数据写入静态区，防止在读写FLASH过程中突然断电。
出厂时，会初始化FLASH内静态空间的静态数据。芯片启动后，会先读取静态空间的静态数据，如果没有读到，会再去读取备份区的静态数据，如果还是没有读到，会使用内部全局变量的初始值来初始化FLASH内静态数据，如果读到了，会使用FLASH中静态数据初始化内部全局变量。
FLASH的静态数据更新由协议栈统一管理，协议栈启动后，每隔1小时自动将内部全局变量更新到备份区动态数据，每隔16小时自动将内部全局变量更新到静态区，协议栈关闭时，也会将内部全局变量更新到静态区。 协议栈处于关闭状态时，也提供了save接口直接更新FLASH。
用户暂不支持直接更改FLASH中静态数据，可使用已有各种接口修改对应的全局变量参数，然后再使用save接口将全局变量参数更新到FLASH中。
1.4 静态数据使用接口
包含头文件
#include "uc_wiota_static.h"
1.4.1 初始化静态数据
- 目的
初始化静态数据。 - 语法
void uc_wiota_static_data_init(void); - 描述
先读取静态空间的静态数据，如果没有读到，会再去读取备份区的静态数据，如果还是没有读到，会使用内部全局变量的初始值来初始化FLASH内静态数据，如果读到了，会使用FLASH中静态数据初始化内部全局变量。 - 返回值
无。 - 参数
无。 - 注意
应在调用其他静态数据接口之前调用该接口进行初始化。
1.4.2 获取用户ID
- 目的
获取用户ID。 - 语法
void uc_wiota_get_userid(unsigned int *id, unsigned char *len); /* 终端 */ void uc_wiota_get_userid(unsigned char *id, unsigned char *len); /* 基站 */ - 描述
获取用户ID，终端用户ID唯一。 - 返回值
无。 - 参数
id: 用户ID，终端用户ID为数值型，基站用户ID为字符串。
len：用户ID长度，基站用户ID最大长度为8字节。 - 示例
获取终端用户ID。
获取基站用户IDunsigned int user_id[2] = {0}; unsigned char len = 0 uc_wiota_get_userid(user_id, &len);
unsigned char user_id[9] = {0}; unsigned char len = 0; uc_wiota_get_userid(user_id, &len);
1.4.3 获取设备名称
- 目的
获取设备名称。 - 语法
void uc_wiota_get_dev_name(unsigned char *name); - 描述
获取设备的名称，最大长度为16个字节。 - 返回值
无。 - 参数
name: 设备名称。
1.4.4 获取设备序列号
- 目的
获取设备序列号。 - 语法
void uc_wiota_get_dev_serial(unsigned char *serial); - 描述
获取设备的序列号，最大长度为16个字节。 - 返回值
无。 - 参数
serial: 设备序列号。
1.4.5 获取厂商名字
- 目的
获取厂商名字。 - 语法
void uc_wiota_get_manufacture_name(unsigned char *name); - 描述
获取生产厂商的名字，最大长度为16个字节。 - 返回值
无。 - 参数
name: 生产厂商的名字。
1.4.6 获取硬件版本号
- 目的
获取硬件版本号。 - 语法
void uc_wiota_get_hardware_ver(unsigned char *hardware_ver); - 描述
获取硬件版本号，最大长度为16个字节。 - 返回值
无。 - 参数
hardware_ver: 硬件版本号。
1.4.7 获取自动连接/运行标志
- 目的
获取自动连接/运行标志。 - 语法
unsigned char uc_wiota_get_auto_connect_flag(void); /* 终端 */ unsigned char uc_wiota_get_auto_run_flag(void); /* 基站 */ - 描述
获取自动连接/运行标志。 - 返回值
自动连接标志：0，终端开机不自动连接；1，终端开机自动连接。
自动运行标志：0，基站开机不自动运行；1，基站开机自动运行。 - 参数
无
1.4.8 获取DTU配置信息
- 目的
获取数据传输单元配置信息。 - 语法
void uc_wiota_get_dtu_config(dtu_info_t *cfg); - 描述
获取频点列表，可以连接的频点集合，每个字节代表一个频点。 - 返回值
无。 - 参数
cfg: 数据传输单元配置信息。 - 结构体
typedef struct DtuInfoT { unsigned char reserved[2]; /* reserved */ unsigned char dtu_status; /* status: 0 or 1 */ unsigned char dtu_at_show; /* show AT format: 0 or 1 */ unsigned short dtu_timeout; /* send timeout */ unsigned short dtu_wait; /* wait time */ unsigned char dtu_exit[8]; /* exit string */ unsigned char na[24]; /* undefined */ } dtu_info_t;
1.4.9 获取频点列表
- 目的
获取频点列表。 - 语法
void uc_wiota_get_freq_list(unsigned char *list); - 描述
获取频点列表，可以连接的频点集合，每个字节代表一个频点。 - 返回值
无。 - 参数
list: 频点列表。
1.4.10 获取用户定制静态数据首地址
- 目的
获取用户定制静态数据首地址。 - 语法
unsigned char* uc_wiota_get_user_info(void); - 描述
用户可更新其中的数据，目前仅限256字节，超出范围可能引起各种意外的bug！ - 返回值
用户定制数据的首地址。 - 参数
无。 - 注意
不能超出空间限制。
1.4.11 主动更新静态区数据
- 目的
主动更新静态区数据。 - 语法
void uc_wiota_save_static_info(void); - 描述
用户主动更新静态区数据。 使用方法可参考AT接口：AT+WIOTASAVESTATIC。 - 返回值
无。 - 参数
无 - 注意
1.4.12 擦除4KB的FLASH内容
- 目的
擦除4KB的FLASH内容，即将这4KB的FLASH的内容全部bit写成1 - 语法
unsigned int uc_wiota_flash_erase_4K(unsigned int flash_addr); - 描述
在写FLASH内容之前，需要先擦除FLASH，擦除规则只能是一次4KB。 - 返回值
result：操作结果，succ或者fail，与其他接口返回结果统一typedef enum { UC_OP_SUCC = 0, UC_OP_TIMEOUT, UC_OP_FAIL, }UC_OP_RESULT; - 参数
flash_addr：该地址为需要擦除的这4KB空间中的任意地址均可，为方便理解，一般选择4KB的起始地址，例如0x3F000。 -
注意
接口适用地址范围： -
终端侧：0x0~0x7E000，如果终端在同步状态下，需要先调用uc_wiota_suspend_connect，擦除、读写flash之后，再调用需要先调用uc_wiota_recover_connect ！
-
基站侧：0x0~0x1FE000，基站侧直接操作。
其余空间为代码空间，静态数据空间，不允许任意操作。
1.4.13 将数据写入FLASH指定位置
- 目的
将数据写入FLASH指定位置。 - 语法
void uc_wiota_flash_write(unsigned int* data_addr, unsigned int flash_addr, unsigned short length); - 描述
将数据写入flash指定位置 - 返回值
result：操作结果，同上。 - 参数
data_addr：数据起始地址，由用户申请内存空间
flash_addr：需写入flash中的起始地址
length：写入数据长度 - 注意
接口适用地址范围：
-
终端侧：0x0~0x7E000，如果终端在同步状态下，需要先调用uc_wiota_suspend_connect，擦除、读写flash之后，再调用需要先调用uc_wiota_recover_connect ！
-
基站侧：0x0~0x1FE000，基站侧直接操作。
其余空间为代码空间，静态数据空间，不允许任意操作。
1.4.14 读出FLASH指定位置内容
- 目的
读出FLASH指定位置内容。 - 语法
void uc_wiota_flash_read(unsigned int* data_addr, unsigned int flash_addr, unsigned short length); - 描述
读出FLASH指定位置内容 - 返回值
无。 - 参数
data_addr：数据起始地址，由用户申请内存空间
flash_addr：需读取flash中的起始地址
length：读取数据长度 - 注意
接口适用地址范围：
-
终端侧：0x0~0x7E000，如果终端在同步状态下，需要先调用uc_wiota_suspend_connect，擦除、读写flash之后，再调用需要先调用uc_wiota_recover_connect ！
-
基站侧：0x0~0x1FE000，基站侧直接操作。
其余空间为代码空间，静态数据空间，不允许任意操作。