GPIO Digital Output

fastbeeAbout 4 min

GPIO Digital Output

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

Peripheral capability, supported device types, and wiring constraints.
Web console configuration fields and recommended parameter values.
PeriphExec integration, validation steps, and troubleshooting notes.

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

GPIO 数字输出

功能说明

GPIO 数字输出用于控制继电器、LED、蜂鸣器、直流电机等执行器件。输出高/低电平驱动外部负载。

支持的外设类型

类型	type值	说明
GPIO_DIGITAL_OUTPUT	12	标准数字输出

引脚说明

ESP32: GPIO 0-5, 12-33（部分引脚有限制）
ESP32-C3: GPIO 0-10, 18-21
ESP32-S3: GPIO 0-21, 35-48

注意：GPIO 6-11（ESP32）为内部Flash使用，不可配置为输出。

典型应用

应用	接线方式	说明
LED	GPIO → 电阻(220Ω) → LED → GND	高电平点亮
继电器	GPIO → 继电器模块IN	多数模块低电平触发
蜂鸣器	GPIO → 有源蜂鸣器+	高电平发声
直流电机	GPIO → 电机驱动模块	需外部驱动电路

数字输出会直接驱动现场负载，配置时先保持外设禁用，确认继电器或电机驱动模块的触发电平后，再用单项动作验证。

配置方式

方式1：Web界面配置（推荐）

不同外设类型会展开不同参数，保存前重点核对外设 ID、类型、引脚和启用状态。

步骤1：进入外设管理页面

打开浏览器访问 ESP32 IP 地址
登录后点击左侧菜单 外设配置

步骤2：添加GPIO数字输出外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`led1` 或 `relay1`	唯一标识符
名称	`状态指示灯` 或 `风扇继电器`	显示名称
外设类型	GPIO数字输出 (type: 12)	标准数字输出
引脚配置	`2` 或 `15`	根据实际接线填写
初始状态	`0`	0=低电平，1=高电平

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
使用控制面板测试输出状态

方式2：JSON配置文件导入

将以下配置添加到 data/config/peripherals.json 的 peripherals 数组中：

LED 输出

{
  "id": "led1",
  "name": "状态指示灯",
  "type": 12,
  "enabled": false,
  "pins": [2],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

继电器输出（低电平触发）

{
  "id": "relay1",
  "name": "继电器-风扇",
  "type": 12,
  "enabled": false,
  "pins": [15],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

蜂鸣器

{
  "id": "buzzer",
  "name": "报警蜂鸣器",
  "type": 12,
  "enabled": false,
  "pins": [4],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

与外设执行联动

GPIO 数字输出可作为外设执行规则的动作目标：

动作类型	actionType	说明
ACTION_HIGH	0	输出高电平
ACTION_LOW	1	输出低电平
ACTION_HIGH_INVERTED	13	逻辑高（物理低电平）
ACTION_LOW_INVERTED	14	逻辑低（物理高电平）
ACTION_BLINK	2	闪烁（actionValue=间隔ms）
ACTION_BREATHE	3	呼吸灯效果

Web界面配置步骤

步骤1：创建执行规则

切换到 外设执行管理 标签
点击 新增规则 按钮
填写基础配置并配置触发器

步骤2：添加GPIO动作

点击 添加动作 按钮
填写动作配置：
字段填写内容说明
动作类型 选择 高电平 或 低电平 根据需求选择
目标外设 选择 relay1 GPIO输出外设
执行延时 0 立即执行
点击保存

字段	填写内容	说明
动作类型	选择高电平或低电平	根据需求选择
目标外设	选择 `relay1`	GPIO输出外设
执行延时	`0`	立即执行

💡 提示：低电平触发继电器模块请使用“逻辑高（反转）”或“逻辑低（反转）”

JSON配置示例

{
  "targetPeriphId": "relay1",
  "actionType": 0,
  "actionValue": "",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

注意事项

初始状态：initialState 为 0 表示上电默认低电平，1 表示高电平
低电平触发继电器：使用 ACTION_HIGH_INVERTED(13) / ACTION_LOW_INVERTED(14) 实现逻辑反转
电流限制：ESP32 单引脚最大输出电流 40mA，驱动大功率负载需外接驱动电路
PWM 参数：即使是数字输出类型，params 中的 PWM 参数仍需保留（兼容框架设计），实际不影响数字输出行为
平台下发控制：平台可通过 MQTT 下发 [{"id":"relay1","value":"1"}] 控制输出状态