pins - 管脚外设复用
作者：马亚丹
一、概述
合宙 pins 核心库的 API 属于高级用法, 仅动态配置管脚时使用，这个功能是为了动态修改管脚复用。
请使用 LuaTools 的可视化工具 https://docs.openluat.com/air780epm/common/luatio/进行管脚配置,通常不需要使用这个 API！！！
本库是专门用于管理合宙模组管脚外设复用、硬件配置加载与调试的核心工具库，核心作用是实现 “管脚功能灵活分配” 与 “硬件配置高效管理”，适配不同外设（如 UART、I2C、GPIO 等）的使用需求，具体可拆解为 3 个核心能力：
核心作用 1：管脚外设复用配置（最核心功能）
合宙模组的管脚支持 “复用”（同一管脚可对应不同外设功能，如某管脚既可选作 GPIO，也可选作 UART_TX），pins.setup() 函数是实现这一功能的关键，作用是在启用外设前，指定管脚的具体外设功能，确保外设能正常工作。
- 支持的外设类型：涵盖常见硬件接口，包括 “UART（串口）、I2C（两线式串行总线）、SPI（串行外设接口）、PWM（脉冲宽度调制）、CAN（控制器局域网）、GPIO（通用输入输出）、ONEWIRE（单总线）”。
- 实际用途：比如将 Air780EPM 的 PIN67 脚配置为 “GPIO18”（用于简单的高低电平控制），或把 PIN55/PIN56 分别配置为 “UART2_RX”“UART2_TX”（用于串口通信），满足不同硬件交互需求。
核心作用 2：管脚状态重置与安全控制
当某个管脚不再使用时，pins.close() 函数可将其设置为高阻态或输入态，避免管脚持续对外输出信号干扰其他电路，起到 “释放管脚资源、保障电路安全” 的作用。
- 例如：Air780EPM 的 PIN67 脚使用完 GPIO 功能后，调用
pins.close(67)，该管脚会停止对外输出，避免误触发其他硬件模块。
核心作用 3：调试辅助（问题排查）
pins.debug() 函数可开启 / 关闭调试模式，开启后会输出更多管脚配置相关的日志，作用是帮助开发者排查管脚配置失败的原因。
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/pins
--配置模组的pin67脚为GPIO18用
log.info ("配置管脚67",pins.setup(67, "GPIO18"))
--配置模组的pin55脚为uart2 rx用
log.info ("配置管脚55",pins.setup(55, "UART2_RXD"))
--配置模组的pin56脚为uart2 tx用
log.info ("配置管脚56",pins.setup(56, "UART2_TXD"))
--关闭pin67脚输出功能，设置为高阻态或输入态
log.info ("关闭管脚",pins.close(67))
--打开调试模式
pins.debug(true)
log.info ("加载配置文件",pins.loadjson("/luadb/pins_Air780EPM.json"))
--关闭调试模式
log.info ("关闭debug",pins.debug(false))
三、常量详解
核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；
如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；
pins 核心库，没有常量。
四、函数详解
4.1 pins.setup(pin, func)
功能
当某种外设允许复用在不同引脚上时，指定某个管脚允许复用成某种外设功能，需要在外设启用前配置好，外设启用时起作用。
注意事项
暂无
参数
pin
参数含义：管脚物理编号
数据类型：number
取值范围：具体查看各模组的管脚说明，对应模组俯视图下的顺序编号, 例如 67, 68
是否必选：必须传入此参数；
注意事项：比如Air780EPM，打开air780EPM.cn->硬件手册和证书->GPIO复用表,即可查看模组管脚复用说明
参数示例：--如下所示，把Air780epm的PIN67脚,做GPIO 18用,第一个参数67即是配置对应的管脚编号
pins.setup(67, "GPIO18")
func
参数含义：功能说明
数据类型：string
取值范围：例如 "GPIO18", "UART1_TX", "UART1_RX", "SPI1_CLK", "I2C1_CLK", 目前支持的外设有"UART","I2C","SPI","PWM","CAN","GPIO","ONEWIRE"
是否必选：必须传入此参数；
注意事项：暂无
参数示例：--如下所示，把Air780epm的PIN67脚,做GPIO 18用,第二个参数"GPIO18"即是配置管脚功能为GPIO18
pins.setup(67, "GPIO18")
-- PIN17脚,做UART1_RX用,第二个参数"UART1_RX"即是配置管脚功能为UART1_RX
pins.setup(17, "UART1_RX")
--PIN67脚,做I2C0_CLK用,第二个参数"I2C0_CLK"即是配置管脚功能为I2C0_CLK
pins.setup(67, "I2C0_CLK")
-- PIN57脚,做SPI1_CLK用,第二个参数"SPI1_CLK"即是配置管脚功能为SPI1_CLK
pins.setup(57, "SPI1_CLK")
--PIN67脚,做PWM0用,第二个参数"PWM0"即是配置管脚功能为PWM0
pins.setup(67, "PWM0")
-- PIN58脚,做ONEWIRE用,第二个参数"ONEWIRE"即是配置管脚功能为ONEWIRE
pins.setup(58, "ONEWIRE")
--PIN28脚,做CAN_RXD用,第二个参数"CAN_RXD"即是配置管脚功能为CAN_RXD
pins.setup(28, "CAN_RXD")
返回值
local result = pins.setup(pin, func)
有一个返回值 result
result
含义说明：配置结果
配置成功,返回true；
其他情况均返回false, 并在日志中提示失败原因，例如pin序号参数错误
数值类型：boolean
取值范围：无特别限制
注意事项：暂无
返回示例：例如返回true时表示配置管脚成功
示例
--把Air780epm的PIN67脚,配置为GPIO 18用
pins.setup(67, "GPIO18")
--把Air780epm的PIN55脚,配置为uart2 rx用
pins.setup(55, "UART2_RXD")
--把Air780epm的PIN56脚,配置为uart2 tx用
pins.setup(56, "UART2_TXD")
4.2 pins.close(pin)
功能
不对外输出，将对应管脚设置为高阻或者输入模式
注意事项
gpio.close 接口只能关闭由 gpio.setup() 打开的 GPIO 引脚
pins.close 接口可以关闭由 pins.setup() 打开的任意功能引脚（GPIO/ADC/PWM 等）
参数
pin
参数含义：管脚物理编号，
数据类型：number
取值范围：具体查看各模组的管脚说明，对应模组俯视图下的顺序编号, 例如 67, 68
是否必选：必须传入此参数；
注意事项：比如Air780EPM，打开 air780EPM.cn->硬件手册和证书->GPIO复用表,即可查看模组管脚复用说明
参数示例：--如下所示，关闭Air780epm的PIN67脚输出功能
pins.close(67)
返回值
local result = pins.close(pin)
有一个返回值 result
result
含义说明：关闭输出结果
关闭成功,返回true；
其他情况均返回false, 并在日志中提示失败原因，例如pin序号参数错误
数值类型：boolean
取值范围：无特别限制
注意事项：暂无
返回示例：例如返回true时表示关闭管脚输出成功
示例
--关闭Air780epm的PIN67脚输出功能
pins.close(67)
4.3 pins.loadjson(path)
功能
加载硬件配置
注意事项
暂无
参数
path
参数含义：配置文件路径
数据类型：string
取值范围：合法的文件路径即可
是否必选：必填参数
注意事项：暂无
参数示例：--如下所示，参数"/luadb/pins_Air780EPM.json"即是加载硬件配置的文件路径
pins.loadjson("/luadb/pins_Air780EPM.json")
返回值
local result,p_int = pins.loadjson(path)
有两个返回值 result ,p_int
result
含义说明：加载结果
成功返回true, 失败返回nil, 并在日志中提示失败原因，例如$path too large!!
数值类型：boolean
取值范围：true/false
注意事项：暂无
返回示例：例如返回true时表示加载文件成功
p_int
含义说明：加载结果返回值
数值类型：number
取值范围： 0，成功
-1，$path not exist!!
-2，$path too large!!
-3， no memory for loading $path
-4，open $path failed /read $path failed
注意事项：暂无
返回示例：例如返回0时表示加载文件成功
示例
-- 如果烧录了pins_$model.json文件，就会自动加载，不需要本API再设置
-- 其中 $model是模组型号, 例如 Air780EPM, 默认加载的是 luadb/pins_Air780EPM.json，其他格式的不会自动加载
-- 以下是自行加载配置的例子, 通常情况下是使用LuatIO工具配置管脚后自动加载，仅动态配置管脚时会使用
log.info ("加载配置文件",pins.loadjson("/luadb/pins_Air780EPM.json"))
log.info ("加载配置文件",pins.loadjson("/luadb/my.json"))
4.4 pins.debug(mode)
功能
调试模式
注意事项
可以在开发调试时打开调试开关，量产时关闭调试开关
参数
mode
参数含义：是否开启调试模式
true是打开调试，false是关闭调试
数据类型：boolean
取值范围：true/false
是否必选：必须传入此参数；
注意事项：默认是关闭的, 打开之后日志多很多
参数示例：--如下所示，表示打开调试模式
pins.debug(true)
返回值
pins.debug(mode)
无返回值
示例
--如下所示，未开启debug,log打印 I/user.加载配置文件 true 0
log.info ("加载配置文件",pins.loadjson("/luadb/pins_Air780EGH.json"))
--如下所示，开启debug,log打印
--D/pins GPIO27 find 5,1,11
-- D/pins luat_pins_setup pin 16 func GPIO27 fid 11 pid 1
--D/pins UART1_RXD find 0,1,0
--....
--D/pins CAN_RXD find 4,0,0
--D/pins luat_pins_setup pin 106 func CAN_RXD fid 0 pid 0
-- I/user.加载配置文件 true 0
pins.debug(true)
log.info ("加载配置文件",pins.loadjson("/luadb/pins_Air780EGH.json"))
五、产品支持说明
支持 LuatOS 开发的所有产品都支持 pins 核心库。