跳转至

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

作者：陆相成　|　最后修改：2026-04-08

LuatIO，是一个用于配置合宙模组IO初始化功能的配置工具，也就是说，合宙模组的IO可以复用为多种功能，你的产品里用到的是哪种，你就要先指定使用哪种，比如：

Air780EPM，PIN66，如果你要是用其PWM1功能，你就需要在LuatIO工具里先进行指定该管脚使用PWM功能；

说明！PIN66在Air780EPM的管脚图上标注的是I2C1_SDA，为推荐功能，但并不是唯一功能，该管脚可以复用为多种功能，具体见各模组型号的GPIO复用表说明；

当然，其它管脚也一样，模组管脚名仅为选择的一种典型功能做推荐，但并不是唯一功能，各模组型号的GPIO复用表均有详细说明；

零，LuatIO工具在LuaTools的入口

LuatIO工具现已集成在LuaTools中，截图说明如下；

LuaTools如何调用LuatIO？如下五张图为前后步骤。

第一步，进入"项目管理测试"；

第二步，新建项目，选择对应的底层固件和上层脚本代码；

注意！

这一步非常重要，只有当正确选择了底层固件和上层脚本之后，第三步的"管脚配置"，也就是LuatIO工具，才会被正常识别并调用，否则，会显示暗淡色无法被选择并唤起；

本质上，LuaTools会根据底层固件和上层脚本自动识别模组型号，并自动匹配对应型号模组的LuatIO配置界面；

第三步，打开"管脚配置"，根据自己需要选择新建还是使用之前的配置；

第四步，根据自己项目的需要，通过LuatIO为每个管脚初始化需要使用的功能；

一，背景介绍

Air8000系列模组的 GPIO 可以复用为各种各样的功能，如下表所示：

Air780Exx系列模组的 GPIO 可以复用为各种各样的功能，如下表所示：

以Air780EPM为例，几乎每个 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 工具

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

  1. LuatIO工具使用； 目前LuatIO工具已集成在luatools中，可以在项目管理界面打开：

  2. LuatIO 界面截图如下： 其中：

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

  4. 右侧为 Air780EPM 的管脚排列图，其中淡绿色部分为可以配置的 GPIO 管脚；

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

2，生成 pins_$model.json 文件

生成对应型号的json文件分为以下几步

​ 1.打开LuatIO配置工具。

image-20250707101205067

​ 2.点击型号选择

image-20250707101231506

​ 3.配置自己需要复用的管脚

image-20250707101326077

4.配置完成后管脚处会显示对应功能，右侧俯视图对应管脚显示会变暗，下方会显示对应功能。

image-20250707101805869

​ 5.点击保存即可

  • 生成.josn配置文件最新固件兼容三种命名,以Air780EPM为例

  • pins_Air780epmjson

  • pins_Air780epmjson
  • pins_Air780epmjson

image-20250707102024412

2.1，生成 pins_air8000a.json 文件

1.点击“保存”；

image-20250703101103294

2.命名"pins_Air8000A"；

image-20250703101312040

说明：

（1）文件名必须严格遵守 pins_$model.json 格式：pins_Air8000A；

（2）文件如下：

​ pins_Air8000A

（3）pins_air8000a.json 截图如下：

1751509106944

2.2，生成 pins_Air780epmjson 文件

1.点击"保存"；

2.命名"pins_Air780EPM"；

说明：

（1）文件名必须严格遵守 pins_$model.json 格式：pins_Air780EPM；

（2）文件如下：

​ pins_Air780EPM

（3）pins_Air780epmjson 截图如下：

2.3，生成 pins_air8101.json 文件

1.点击"保存"；

2.命名"pins_air8101.json"；

说明：

（1）文件名必须严格遵守 pins_$model.json 格式：pins_air8101.json；

（2）文件如下：

​ pins_air8101

（4）pins_air8101.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_air8000a.json 下载到模组

1.以 Air8000A V2008固件为例；

下载地址：Air8000A最新固件

截图如下：662dc27caf8eadc1182858f31b310fb 2.pins_Air8000A 保存在 json 文件夹内；

image-20250704095846457

3.下载到 Air8000A 中；

image-20250704100316459

4.2，将 pins_Air780epmjson 下载到模组

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

下载地址：Air780EPM最新固件 截图如下：

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

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

4.3，将 pins_air8101.json 下载到模组

1.以 Air8101 核心板为例，选择最新的固件；

下载地址：Air8101最新固件

2.将pins_air8101.json引脚配置文件增加到脚本和资源列表；

3.将pins_air8101.json 同代码一起下载到 Air8101 核心板中；

三，其它说明

1. Lua 代码中，需要声明调用 pins_Air780epmjson 文件吗？

答案：

不需要；

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

2. 只有 Air780EPM 支持 pins_Air780epmjson 和 API 库函数 pins 搭配的配置方式吗？

回答：

不是的；

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

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

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

回答：

不可以了；

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

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

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

回答：

在整理了；

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

5. 如果未进行pins_Air780EPM.json的配置，代码可以运行吗？

回答：

可以运行；

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

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

6. 模组的demo和json文件需要分开烧录吗？

回答：

不用分开烧录，在项目管理界面添加自己的demo和配置好的文件后烧录一次即可。