合宙 LuatIO 工具(GPIO 复用初始化配置)使用说明
LuatIO 工具的使用注意事项，本文以 Air780EPM 举例说明。
一，背景介绍
Air780EPM 共有 38 个 GPIO，这 38 个 GPIO 又可以复用为各种各样的功能，如下表所示：
这 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 配置的全过程，我们分为三部分进行说明，分别是：
- LuatIO 可视化 GPIO 复用功能配置工具；
- 由 LuatIO 生成 pins_$model.json 文件；
- API 库函数 pins 动态配置；
- 通过 LuaTools 将 pins_$model.json 文件下载到模组中；
1，LuatIO 工具
-
LuatIO 安装文件；
-
LuatIO 界面截图如下：
其中：
-
左侧为 GPIO 复用功能配置选择栏，空白框内可以写该管脚相应的注释说明；
-
右侧为 Air780EPM 的管脚排列图，其中淡绿色部分为可以配置的 GPIO 管脚；
-
以 Air780EPM 开发板 V1.3 为例，根据其硬件实际使用情况配置后的截图如下：
-
2，生成 pins_Air780EPM.json 文件
-
点击"保存"；
-
命名"pins_Air780EPM"；
说明：
-
文件名必须严格遵守 pins_$model.json 格式：pins_Air780EPM；
-
注意！Air780EPM 中的"Air"为大小写组合，"EPM"必须为大写；
-
文件如下：
- pins_Air780EPM.json 截图如下：
-
3，API 库函数 pins 动态配置
首先，请使用 LuatIO 的可视化工具进行配置，你通常不需要使用这个功能；
其次，本库的 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_Air780EPM.json 下载到模组
首先，本小节我们只针对不需要"API 库函数 pins 动态配置"的情况进行演示；
其次，即便需要"API 库函数 pins 动态配置"的情况，pins 的使用方法跟其它 API 核心库函数没有区别。
-
以 Air780EPM 开发板 V1.3 出厂固件为例；
-
下载地址：合宙 Luat/LuatOS-Air780EPM；
-
截图如下：
-
-
pins_Air780EPM 保存在 json 文件夹内；
-
下载到 Air780EPM 开发板 V1.3 中；
三，其它说明
-
Lua 代码中，需要声明调用 pins_Air780EPM.json 文件吗？
答案：不需要；
更详细的说明，参见 pins - luatos@air780epm - 合宙模组资料中心 中对pins.loadjson(path)函数的描述；
-
只有 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 都支持主推型号，老型号都不再支持。
-
虽然该工具很方便，但我已经习惯了 mcu.altfun()函数配置，还可以继续使用吗？
回答：不可以了；
Air780EPM 底层固件从 V2005 开始，将只支持 pins_Air780EPM.json 一种 GPIO 复用功能配置方式，之前的 mcu.altfun()方式将不再继续支持！遇到动态配置的情况，可以结合 API 库函数 pins 进行操作。
也就是说，如果您使用 Air780EPM 底层固件 V2004 或之前的版本已经量产出货，后续您因某种原因需要远程升级基于 V2005 及其后续底层固件版本的软件时，您的脚本文件也需要通过 pins_Air780EPM.json 的方式重新对 GPIO 复用功能进行配置，原来的 mcu.altfun()配置方式将会失效。
-
为什么我在合宙的 Docs 文档网站里还经常看到关于 mcu.altfun()函数的出现？
回答：在整理了；
mcu.altfun()的 API 库函数说明已经从 Docs 上撤掉，但确实还有非常多的其它文档说明仍然"保留"，我们可能要花一段时间才能完全"清除"；
-
LuatIO 功能将来会集成到 LuaTools 中吗？
回答：一定会的；
目前单独的 LuatIO 工具只是阶段性的存在，很快就会集成到 LuaTools 中，大家一个工具入口即可完成尽可能多的功能；