跳转至

合宙 LuatIO 工具(GPIO 复用初始化配置)使用说明

一,背景介绍

Air8000共有51个GPIO,Air8000A共有53个GPIO,Air8000W共有58个GPIO,Air8000G共有37个GPIO,Air8000D共有39个GPIO,Air8000T共有46个GPIO,这些 GPIO 又可以复用为各种各样的功能,如下表所示:

eb77f20074acbd0243a363efa4e7b20

Air780EPM 共有 38 个 GPIO,Air780EHM共有38个GPIO,Air780EHV共有30个GPIO,Air780EGH共有34个GPIO,这些 GPIO 又可以复用为各种各样的功能,如下表所示:

以AIr780EPM这 38 个 GPIO为例,几乎每个 GPIO 都可以复用为多个功能,比如 PIN66:

什么时候用作 I2C0_SDA?

什么时候用作 I2C1_SDA?

什么时候用作 GPIO19?

什么时候用作 PWM1?

默认功能是什么?

如何进行初始化配置?

如何在初始化之后进行动态的配置?

LuatOS 之前的做法是,通过 mcu.altfun()函数进行配置,这个函数非常晦涩难懂,因为不仅要涉及到 Air780EPM 所使用主芯片对应的 PAD 脚,还要知晓该 PAD 脚所需配置复用功能的 AltFunc 顺序号,对初学者非常不友好。

基于此,我们设计了 GPIO 可视化配置工具"LuatIO",并由此工具生成对应的"pins_$model.json"文件,结合 API 库函数 pins 动态配置,最后再以脚本的形式下载到模组中,即可完成该模组型号的 GPIO 复用配置。

二,GPIO 配置

GPIO 配置的全过程,我们分为三部分进行说明,分别是:

  1. LuatIO 可视化 GPIO 复用功能配置工具;
  2. 由 LuatIO 生成 pins_$model.json 文件;
  3. API 库函数 pins 动态配置;
  4. 通过 LuaTools 将 pins_$model.json 文件下载到模组中;

1,LuatIO 工具

  1. LuatIO 安装文件;

LuatIO安装文件

注意:LuatIO工具仅支持Win10及之上Windows操作系统。

  1. LuatIO 界面截图如下:

其中:

  • 左侧为 GPIO 复用功能配置选择栏,空白框内可以写该管脚相应的注释说明;

  • 右侧为 Air780EPM 的管脚排列图,其中淡绿色部分为可以配置的 GPIO 管脚;

  • 以 Air780EPM 开发板 V1.3 为例,根据其硬件实际使用情况配置后的截图如下:

2,生成 pins_$model.json 文件,

2.1,生成 pins_Air8000.json 文件

1.点击“保存”;

image-20250702155213098

2.命名"pins_Air8000";

image-20250702155631506

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000;

(2)注意!Air8000 中的"Air"首字母大写,其余字母小写;

(3)文件如下:

pins_Air8000

(4)pins_Air8000.json 截图如下:

image-20250702162427694

2.2,生成 pins_Air8000A.json 文件

1.点击“保存”;

image-20250703101103294

2.命名"pins_Air8000A";

image-20250703101312040

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000A;

(2)注意!Air8000A 中的"Air"为大小写组合,"A"必须为大写;

(3)文件如下:

pins_Air8000A

(4)pins_Air8000A.json 截图如下:

1751509106944

2.3,生成 pins_Air8000D.json 文件

1.点击“保存”;

image-20250703104225096

2.命名"pins_Air8000D";

image-20250703104540109

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000D;

(2)注意!Air8000D 中的"Air"为大小写组合,"D"必须为大写;

(3)文件如下:

pins_Air8000D

(4)pins_Air8000D.json 截图如下:

image-20250703104951896

2.4,生成 pins_Air8000G.json 文件

1.点击“保存”;

image-20250703105835667

2.命名"pins_Air8000G";

image-20250703152009280

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000G;

(2)注意!Air8000G 中的"Air"为大小写组合,"G"必须为大写;

(3)文件如下:

pins_Air8000G

(4)pins_Air8000G.json 截图如下:

image-20250703150357078

2.5,生成 pins_Air8000T.json 文件

1.点击“保存”;

image-20250703152400557

2.命名"pins_Air8000T";

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000T;

(2)注意!Air8000T 中的"Air"为大小写组合,"T"必须为大写;

(3)文件如下:

pins_Air8000T

(4)pins_Air8000T.json 截图如下:

image-20250703152919687

2.6,生成 pins_Air8000W.json 文件

1.点击“保存”;

image-20250703153220375

2.命名"pins_Air8000W";

image-20250703154016169

说明:

(1)文件名必须严格遵守 pins_$model.json 格式:pins_Air8000W;

(2)注意!Air8000W 中的"Air"为大小写组合,"W"必须为大写;

(3)文件如下:

pins_Air8000W

(4)pins_Air8000W.json 截图如下:

image-20250703154328899

2.7,生成 pins_Air780EPM.json 文件

  1. 点击"保存";

  1. 命名"pins_Air780EPM";

说明:

  • 文件名必须严格遵守 pins_$model.json 格式:pins_Air780EPM;

  • 注意!Air780EPM 中的"Air"为大小写组合,"EPM"必须为大写;

  • 文件如下:

    pins_Air780EPM

  • pins_Air780EPM.json 截图如下:

3,API 库函数 pins 动态配置

首先,请使用 LuatIO 的可视化工具进行配置,如果不需要io复用功能通常用不到pins这个功能;

其次,本库的 API 属于高级用法, 仅动态配置管脚时使用(LuatIO 本来已经初始化好了,但在代码运行过程中需要对某个或某些 GPIO 的复用功能进行动态调整);

再次,pins 是 LuatOS 核心库,在脚本代码中不需要 require,可以直接使用;

关于 pins 的详细说明,参见 pins - luatos@air780epm - 合宙模组资料中心

pins.setup(pin, func)

在 pins_$model.json 文件初始化之后,再一次或多次指定某个或多个管脚的功能变化;

说明!此功能是为了动态修改管脚复用,99% 的用户可能不会用到本 API;

pins.setup(pin, func)
--参数: pin, 整数型, 管脚物理编号, 对应模组俯视图下的顺序编号, 例如 67, 68
--参数: func, 字符串类型, 功能说明, 例如 "GPIO18", "UART1_TX", "UART1_RX", "SPI1_CLK", "I2C1_CLK"

--返回值: 配置成功,返回true, 其他情况均返回nil, 并在日志中提示失败原因

--使用示例

-- 把PIN67脚,做GPIO 18用, 用Air780EPM演示
--pins.setup(67, "GPIO18")

-- 把PIN56脚,做ONEWIRE用,用Air780EPM演示
-- pins.setup(56, "ONEWIRE")

4,将 pins_$model.json 下载到模组

首先,本小节我们只针对不需要"API 库函数 pins 动态配置"的情况进行演示;

其次,即便需要"API 库函数 pins 动态配置"的情况,pins 的使用方法跟其它 API 核心库函数没有区别。

4.1 将 pins_Air8000.json 下载到模组

  1. 以 Air8000 开发板 V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:

image-20250703175128136

2.pins_Air8000 保存在 json 文件夹内;

image-20250704093443846

3.下载到 Air8000 开发板中;

image-20250704094154507

4.2 将 pins_Air8000A.json 下载到模组

  1. 以 Air8000A V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000A]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:662dc27caf8eadc1182858f31b310fb

2.pins_Air8000A 保存在 json 文件夹内;

image-20250704095846457

3.下载到 Air8000A 中;

image-20250704100316459

4.3 将 pins_Air8000D.json 下载到模组

  1. 以 Air8000D V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000D]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:

662dc27caf8eadc1182858f31b310fb

2.pins_Air8000D 保存在 json 文件夹内;

image-20250704101621134

3.下载到 Air8000D 中;

image-20250704102242736

4.4 将 pins_Air8000G.json 下载到模组

  1. 以 Air8000G V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000D]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:

662dc27caf8eadc1182858f31b310fb

2.pins_Air8000G 保存在 json 文件夹内;

image-20250704104119314

3.下载到 Air8000G 核心板中;

image-20250704104237171

4.5 将 pins_Air8000T.json 下载到模组

  1. 以 Air8000T V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000T]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:

662dc27caf8eadc1182858f31b310fb

2.pins_Air8000T 保存在 json 文件夹内;

image-20250704105302061

3.下载到 Air8000T 核心板中;

image-20250704105428028

4.6 将 pins_Air8000W.json 下载到模组

  1. 以 Air8000W V2008固件为例;
下载地址:[合宙 Luat/LuatOS-Air8000W]([components/pins/meta · 合宙Luat/LuatOS - 码云 - 开源中国](https://gitee.com/openLuat/LuatOS/tree/master/components/pins/meta));

​ 截图如下:

662dc27caf8eadc1182858f31b310fb

2.pins_Air8000W 保存在 json 文件夹内;

image-20250704111728984

3.下载到 Air8000W 核心板中;

image-20250704111820726

4.7 将 pins_Air780EPM.json 下载到模组

  1. 以 Air780EPM 开发板 V1.3 出厂固件为例;

下载地址:合宙 Luat/LuatOS-Air780EPM

截图如下:

2.pins_Air780EPM 保存在 json 文件夹内;

3.下载到 Air780EPM 开发板 V1.3 中;

三,其它说明

  1. Lua 代码中,需要声明调用 pins_Air780EPM.json 文件吗?

答案:不需要;

更详细的说明,参见 pins - luatos@air780epm - 合宙模组资料中心 中对pins.loadjson(path)函数的描述;

  1. 只有 Air780EPM 支持 pins_Air780EPM.json 和 API 库函数 pins 搭配的配置方式吗?

回答:不是的;

合宙 25 年主推型号都会支持,包括 Air780EPM/EHM/EHV/EGH,Air8000/8000W/8000G/8000T,Air8101/8101A,Air8201,以及将来可能的新型号; 已经不再主推的老型号,比如 Air780E、Air780EP、Air780EPS、Air724UG 等,不再新增支持该功能;

注意!LuatIO 工具(pins_$model.json)和 API 函数 pins 都支持主推型号,老型号都不再支持。

  1. 虽然该工具很方便,但我已经习惯了 mcu.altfun()函数配置,还可以继续使用吗?

回答:不可以了;

Air780EPM 底层固件从 V2006 开始,将只支持 pins_Air780EPM.json 一种 GPIO 复用功能配置方式,之前的 mcu.altfun()方式将不再继续支持!遇到动态配置的情况,可以结合 API 库函数 pins 进行操作。

也就是说,如果您使用 Air780EPM 底层固件 V2005 或之前的版本已经量产出货,后续您因某种原因需要远程升级基于 V2006 及其后续底层固件版本的软件时,您的脚本文件也需要通过 pins_Air780EPM.json 的方式重新对 GPIO 复用功能进行配置,原来的 mcu.altfun()配置方式将会失效。

  1. 为什么我在合宙的 Docs 文档网站里还经常看到关于 mcu.altfun()函数的出现?

回答:在整理了;

mcu.altfun()的 API 库函数说明已经从 Docs 上撤掉,但确实还有非常多的其它文档说明仍然"保留",我们可能要花一段时间才能完全"清除";

  1. LuatIO 功能将来会集成到 LuaTools 中吗?

回答:一定会的;

目前单独的 LuatIO 工具只是阶段性的存在,很快就会集成到 LuaTools 中,大家一个工具入口即可完成尽可能多的功能;

  1. 如果未进行pins_Air780EPM.json的配置,代码可以运行吗?

回答:可以运行;

会以Air780EPM各GPIO的默认功能执行;

如果所引用的GPIO复用功能跟默认功能不一致,代码就会无法执行。