433MHz 射频模块

fastbee大约 6 分钟

433MHz 射频模块

功能说明

433MHz 射频模块支持 OOK 调制信号的发射与接收学习。接收模式下内置 EV1527/PT2262 协议解码器，可通过 Web 界面进行对码学习（捕获遥控编码 → 命名 → 存入按键库），解码后产生系统事件用于规则联动。

固件要求：Standard 固件默认启用 FASTBEE_ENABLE_RF_LEARN；Lite 固件不含学习功能（仅保留发射）。

支持的外设类型

类型	type值	说明
RF_MODULE	48	433MHz 射频模块（发射/接收学习）

事件编号

事件	编号	说明
EVENT_RF_CODE_RECEIVED	130	收到 RF 编码（学习模式解码成功）

硬件接线

发射模块（如 SYN115/F115）

模块引脚	ESP32 GPIO	说明
VCC	3.3V 或 5V	按模块标称供电
GND	GND	必须共地
DIN / DATA	GPIO4（示例）	数据输入，不能使用输入专用 GPIO
ANT	天线	建议接 17cm 导线或配套弹簧天线

接收模块（如 SYN470R/SYN480R）

模块引脚	ESP32 GPIO	说明
VCC	3.3V 或 5V	按模块标称供电
GND	GND	必须共地
OUT / DATA	GPIO16（示例）	数据输出，需可输入 GPIO
ANT	天线	建议接 17cm 导线

⚠️ 发射引脚不要选 GPIO34-39 等输入专用脚，也不要选 Flash/PSRAM 保留脚。

配置方式

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

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

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

步骤2：添加 RF 外设

点击 新增外设 按钮

填写配置：

发射模式：

字段	填写内容	说明
外设ID	`rf_tx_01`	唯一标识符
名称	`433M发射`	显示名称
外设类型	433MHz射频模块 (type: 48)	RF_MODULE
引脚配置	`4`	DATA 引脚
模式	发射	TX 模式
编码位数	`24`	多数遥控器为 24 位
脉宽	`350`	单位 μs，EV1527 典型值

接收学习模式：

字段	填写内容	说明
外设ID	`rf_rx_01`	唯一标识符
名称	`433M接收`	显示名称
外设类型	433MHz射频模块 (type: 48)	RF_MODULE
引脚配置	`16`	OUT 数据引脚
模式	接收(学习)	RX 模式，启用对码学习

点击保存，然后启用该外设

步骤3：对码学习（接收模式）

在外设列表中点击 RF 接收外设的编辑按钮
在弹窗底部找到 RF 遥控管理 面板
设置学习超时（默认 10 秒）
点击 开始学习
在超时时间内按下遥控器按键
捕获成功后输入按键名称（如 gate_btn），点击 保存按键
按键库中可查看/删除已学习的按键

💡 提示：学习时遥控器尽量靠近接收模块（30cm 内），确保信号稳定。

方式2：JSON配置文件导入

发射外设：

{
  "id": "rf_tx_01",
  "name": "433M发射",
  "type": 48,
  "enabled": true,
  "pins": [4],
  "params": {
    "mode": 0,
    "pulseWidth": 350,
    "repeat": 8
  }
}

接收学习外设：

{
  "id": "rf_rx_01",
  "name": "433M接收",
  "type": 48,
  "enabled": true,
  "pins": [16],
  "params": {
    "mode": 1,
    "activeHigh": true
  }
}

参数说明

参数	说明
mode	`0`=发射(TX)，`1`=接收学习(RX)
pulseWidth	发射脉宽（μs），EV1527 典型 350，范围 100-2000
repeat	发射重复次数（默认 8），增强接收端识别率
activeHigh	接收电平极性（默认 true）

pins[0] = RF 模块 DATA 引脚

对码学习 API

接收模式下可通过 HTTP API 控制学习流程：

端点	方法	说明
`/api/rf/status`	GET	查询 RF 学习驱动状态
`/api/rf/learn/start`	POST	开始学习（参数 `timeoutMs`）
`/api/rf/learn/status`	GET	查询学习进度
`/api/rf/learn/stop`	POST	取消学习
`/api/rf/keys`	GET	获取按键库列表
`/api/rf/keys`	POST	保存按键（name/code/bits/pulse）
`/api/rf/keys/delete`	POST	删除指定按键（name）
`/api/rf/keys/clear`	POST	清除全部按键

学习状态响应示例

{
  "success": true,
  "data": {
    "initialized": true,
    "learnState": "captured",
    "code": "0xA1B2C3",
    "bits": 24,
    "pulse": 350,
    "remainingMs": 0
  }
}

learnState 取值：idle（空闲）、learning（学习中）、captured（已捕获）、timeout（超时）。

按键库存储

按键持久化到 LittleFS /config/rf_keys.json：

[
  { "name": "gate_btn", "code": "0xA1B2C3", "bits": 24, "pulse": 350 },
  { "name": "alarm_off", "code": "0xD4E5F6", "bits": 24, "pulse": 350 }
]

数据上报格式

收到 RF 信号并解码成功时通过 MQTT 上报：

[{"id": "rf_rx_01", "value": "code:0xA1B2C3,bits:24,pulse:350"}]

字段	说明
code	解码后的编码（十六进制）
bits	编码位数（通常 24）
pulse	脉宽（μs）

事件触发机制

解码成功时触发 EVENT_RF_CODE_RECEIVED（130）事件，事件数据格式：

{
  "code": "0xA1B2C3",
  "bits": 24,
  "pulse": 350,
  "key": "gate_btn"
}

key 字段：如果编码匹配按键库中的已学习按键，则包含按键名称；否则为空字符串。

与外设执行联动

Web界面配置步骤

创建 RF 遥控控制 LED 规则：

切换到 外设执行管理 标签
点击 新增规则 按钮
配置事件触发器：
- 触发类型：事件触发
- 触发事件：RF编码接收（rf_code_received）
- RF按键：选择已学习的按键（如 gate_btn），或留空表示任意编码
添加动作：
- 动作类型：切换电平
- 目标外设：led1
点击保存

💡 提示：RF 按键下拉会自动加载按键库中已学习的按键；也可手动填写原始编码（如 0xA1B2C3）或 key:名称 格式。

JSON配置示例

RF 遥控控制 LED

{
  "name": "RF遥控开灯",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "rf_code_received",
      "compareValue": "key:gate_btn"
    }
  ],
  "actions": [
    { "actionType": 2, "targetPeriphId": "led1" }
  ]
}

按原始编码匹配

{
  "name": "RF编码触发",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "rf_code_received",
      "compareValue": "0xA1B2C3"
    }
  ],
  "actions": [
    { "actionType": 2, "targetPeriphId": "relay1" }
  ]
}

任意 RF 编码触发（不限按键）

{
  "name": "任意RF触发",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "rf_code_received",
      "compareValue": ""
    }
  ],
  "actions": [
    { "actionType": 2, "targetPeriphId": "buzzer1" }
  ]
}

发射编码（外设执行调用）

通过外设执行规则的 调用其他外设 动作发送 RF 编码：

{
  "periphId": "rf_tx_01",
  "action": "send",
  "code": "0xA1B2C3",
  "bits": 24,
  "pulseWidth": 350,
  "repeat": 8
}

code 支持十进制、0x 十六进制、0b 二进制格式。

调试接口

POST /api/peripherals/write
Content-Type: application/x-www-form-urlencoded

id=rf_tx_01&code=0xA1B2C3&bits=24&pulseWidth=350&repeat=8

解码原理

接收学习模式使用 GPIO 中断捕获脉冲时序：

同步头检测：检测 >3000μs 的高电平脉冲作为帧起始
数据采集：记录后续高低电平脉宽序列（最多 128 个脉冲）
位解码：找到最小脉冲作为 1T 基准，每 2 个脉冲判一位
- 高电平占比 ≥2 → bit 1
- 低电平占比 ≥2 → bit 0
编码输出：组合为 24 位（或 12-32 位）十六进制编码

支持的协议：EV1527、PT2262 及兼容编码格式。

注意事项

固件版本：Standard 固件默认包含 RF 学习驱动；Lite 固件仅保留发射功能
天线：发射和接收模块都建议接 17cm 导线天线，否则距离极短
供电：射频模块对供电敏感，建议使用独立 3.3V/5V 供电而非 GPIO 取电
干扰：433MHz 频段为 ISM 开放频段，环境中可能存在同频干扰，近距离测试优先
发射限制：不要连续高频发送，建议由规则按事件触发或低频定时触发
学习距离：对码学习时遥控器距接收模块 30cm 内效果最佳
编码唯一性：同一遥控器不同按键编码不同，但同一按键每次发送编码相同
脉宽匹配：如果学习到的脉宽与发射默认值不同，发射时需使用学习到的脉宽