Air780E软件指南：C语言内存数组(zbuff)

一、ZBUFF(C内存数组)简介

zbuff库可以用c风格直接操作(下标从0开始)，例如buff[0]=buff[3]

可以在sram上或者psram上申请空间，也可以自动申请(如存在psram则在psram进行申请,如不存在或失败则在sram进行申请)。

操作里面的元素时，可以根据光标进行增删改查。偏移方式有三种：从头、当前位置、末尾开始。常用参数如下：

常量	类型	解释
zbuff.SEEK_SET	number	以头为基点
zbuff.SEEK_CUR	number	以当前位置为基点
zbuff.SEEK_END	number	以末尾为基点
zbuff.HEAP_AUTO	number	自动申请 (如存在psram，则在psram进行申请, 如不存在或失败则在sram进行申请)
zbuff.HEAP_SRAM	number	在sram申请
zbuff.HEAP_PSRAM	number	在psram申请

二、演示功能概述

本demo将演示ZBUFF的创建、写入数据、读取数据、获取zbuff长度、获取光标位置。

三、准备硬件环境

3.1 780E开发板一套，包括天线、USB数据线

此核心板的详细使用说明参考：
https://docs.openluat.com/air780e/product/

Air780E产品手册中的<<开发板Core_Air780E使用说明V1.0.5.pdf>>，X.X.X指版本号；核心板使用过程中遇到任何问题，可以直接参考这份使用说明pdf文档。

3.2 SIM卡

请准备一张可正常上网的SIM卡，该卡可以是物联网卡或您的个人手机卡。

特别提醒：请确保SIM卡未欠费且网络功能正常，以便顺利进行后续操作。

3.3 数据通信线

typec接口USB数据线即可。

3.4 PC电脑

WINDOWS系统。

四、准备软件环境

4.1 基本的下载调试工具

使用说明参考：Luatools下载和详细使用；

五、ZBUFF操作软硬件资料

5.1 文档和工具：

780E模块使用固件：SDK&Demo-合宙文档中心，本demo使用的固件版本是：

LuatOS-SoC_V1112_EC618_FULL.soc
本教程使用的demo：

https://gitee.com/openLuat/LuatOS-Air780E/tree/master/demo/zbuff
将固件和脚本烧录到模块中：Luatools下载和使用教程-合宙模组资料中心
源码和固件已打包，如下所示：点我,下载完整压缩文件包
zbuff-全部api地址，如果只看本demo的api直接看下面的5.2demo使用api介绍即可。

5.2 demo使用api介绍

zbuff.create(length,data,type)

作用：创建zbuff。

参数

参数	传入值类型	解释
length	int	字节数
data	any	可选参数，number时为填充数据，string时为填充字符串
type	number	可选参数，内存类型。可选值：zbuff.HEAP_SRAM（内部sram，默认），zbuff.HEAP_PSRAM（外部psram），zbuff.HEAP_AUTO（自动申请内存）

返回值

返回值类型	解释
object	zbuff对象，创建失败返回nil

buff:write(para,…)

作用：zbuff写数据（从当前指针位置开始；执行后指针会向后移动）。

参数

参数	传入值类型	解释
para	any	写入buff的数据。string时为一个参数，number时可为多个参数

返回值

返回值类型	解释
number	数据成功写入的长度

buff:read(length)

作用：zbuff读数据（从当前指针位置开始；执行后指针会向后移动）

参数

参数	传入值类型	解释
length	int	读取buff中的字节数

返回值

返回值类型	解释
string	读取结果

buff:clear(num)

作用：zbuff清空数据（与当前指针位置无关；执行后指针位置不变）

参数

参数	传入值类型	解释
num	int	可选，默认为0。要设置的值，不会改变指针位置

返回值

无

buff:seek(base,offset)

作用：zbuff设置光标位置（可能与当前指针位置有关；执行后指针会被设置到指定位置）

参数

参数	传入值类型	解释
offset	int	偏移长度
base	int	基点，默认zbuff.SEEK_SET。可选值：zbuff.SEEK_SET（文件开头），zbuff.SEEK_CUR（当前位置），zbuff.SEEK_END（文件尾）

返回值

返回值类型	解释
int	设置光标后从buff开头计算起的位置

buff:pack(format,val1,val2,…)

作用：将一系列数据按照格式字符转化，并写入（从当前指针位置开始；执行后指针会向后移动）

参数

参数	传入值类型	解释
format	string	后面数据的格式（符号含义见示例）
val	val	传入的数据，可以为多个数据

返回值

返回值类型	解释
int	成功写入的数据长度

例子：

buff:unpack(format)

作用：将一系列数据按照格式字符读取出来（从当前指针位置开始；执行后指针会向后移动）

参数

参数	传入值类型	解释
format	string	数据的格式（符号含义见pack示例）

返回值

返回值类型	解释
int	成功读取的数据字节长度
any	按格式读取的数据

buff:read类型()

作用：读取一个指定类型的数据（从当前指针位置开始；执行后指针会向后移动）

参数

类型可为：（前缀I指有符号位，U指无符号位，后面的数字指有几位）I8、U8、I16、U16、I32、U32、I64、U64。

（浮点数）F32、F64

返回值

返回值类型	解释
number	读取的数据，越界则为nil

例如:

buff:write类型(data)

作用：写入一个指定类型的数据（从当前指针位置开始；执行后指针会向后移动）

参数

参数	传入值类型	解释
data	number	待写入的数据

写入类型，可为：（前缀I指有符号位，U指无符号位，后面的数字指有几位）I8、U8、I16、U16、I32、U32、I64、U64。

（浮点数）F32、F64

返回值

返回值类型	解释
number	成功写入的长度

例如:

locallen=buff:writeI8(10)locallen=buff:writeU32(1024)

buff:len()

作用：获取zbuff对象的长度（与当前指针位置无关；执行后指针位置不变）

参数

无

返回值

返回值类型	解释
int	zbuff对象的长度

buff:used()

作用：获取zbuff中最后一个数据位置指针到首地址的偏移量，表示zbuff内已有有效数据量大小。注意，此值不同于分配的空间大小，seek()会改变最后一个数据位置指针，也会影响used()的返回值。

参数

无

返回值

返回值类型	解释
int	有效数据量大小

六、代码示例介绍

6.1 zbuff操作示例

6.1.1 创建zbuff，以c语言数组的形式操作zbuff

6.1.2 以io的形式操作

6.1.3 清除zbuff

6.1.4 以pack库的形式写入或读取数据

6.1.5 按类型读写数据

读取类型可为：I8、U8、I16、U16、I32、U32、I64、U64、F32、F64

读取的时候，记得注意下标位置。

6.1.6 取出指定区间的数据

6.1.7 获取创建的zbuff的长度，和指针当前位置

6.1.8 测试F32（32位单精度浮点数）类型数据的读写

七、功能验证

测试zbuff的使用

八、总结

本示例介绍了zbuff的作用和用法。

九、常见问题

9.1 先buff:write(0x12)，再设置光标到正确位置后，使用buff:read(1)读取不到数据。

直接读取是不可见字符，要使用buff:read(1):toHex()读取数据。