433MHz 射频模块

功能说明

433MHz 射频模块提供同步OOK发射与接收学习。接收驱动按EV1527式脉冲比例解码，可通过Web捕获编码并命名存入按键库；具体遥控器和兼容编码须实测，不能只凭产品名称宣称所有EV1527/PT2262设备都兼容。正常接收的有效解码产生规则事件，学习状态下捕获的那一次不派发事件。

固件要求：接收学习需要FASTBEE_ENABLE_RF_LEARN=1。当前标准矩阵只有esp32s3-F8R8显式关闭，其他标准环境含esp32s3-F8R0和esp32s3-F16R8编入；定制环境核对实际开关。TX实现不依赖RF学习开关。编入不代表接线、接收或无线负载通过验收。
TX候选的参数、来源占用、失败处理和时序限制见RF发送来源与受检输出边界。TX的本地测试不能延伸为RX学习、按键存储或实物通过。

支持的外设类型

类型	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 导线

示例GPIO只作经典ESP32参考；逐板核对输入能力、输出能力及Flash/PSRAM等占用。供电按模块数据手册，接收器若用5V供电仍须核对其OUT电平是否兼容ESP32，必要时做电平转换；不能把VCC额定值直接当GPIO耐压。

配置方式

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

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

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

步骤2：添加 RF 外设

点击 新增外设 按钮

填写配置：

发射模式：

字段	填写内容	说明
外设ID	`rf_tx_01`	唯一标识符
名称	`433M发射`	显示名称
外设类型	433MHz射频模块 (type: 48)	RF_MODULE
引脚配置	`4`	DATA 引脚
模式	发射	TX 模式
编码位数	`24`	持久字段bitLength，动作bits可覆盖本次发送
脉宽	`350`	单位 μs，EV1527 典型值

接收学习模式：

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

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

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

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

学习距离、朝向、天线和环境干扰须按具体接收模块与遥控器核验，不以统一距离保证成功。捕获结束后恢复正常接收，后续按键可能触发已启用规则。

方式2：JSON配置文件导入

发射外设：

json

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

接收学习外设：

json

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

参数说明

参数	说明
mode	`0`=发射(TX)，`1`=接收学习(RX)
pulseWidth	发射脉宽（μs），EV1527 典型 350，范围 100-2000
bitLength	默认编码位数（持久字段）；发送动作使用bits字段
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	清除全部按键

学习状态响应示例

json

{
  "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：

json

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

数据上报格式

驱动不自动生成“接收器ID + 编码”的MQTT上报。它派发下面的内部全局事件，实际动作或上报取决于匹配规则；载荷没有接收器ID，不能据此区分多个接收器。

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

事件触发机制

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

json

{
  "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

json

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

按原始编码匹配

json

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

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

json

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

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

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

json

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

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

调试接口

http

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

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

解码原理

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

帧间隔检测：检测大于同步阈值的相邻边沿间隔，结合已采集的数据量标记前帧完成或重置缓冲；该判断不包含电平极性
数据采集：记录后续高低电平脉宽序列（最多 128 个脉冲）
位解码：找到最小脉冲作为 1T 基准，每 2 个脉冲判一位
- 高电平占比 ≥2 → bit 1
- 低电平占比 ≥2 → bit 0
编码输出：组合为 24 位（或 12-32 位）十六进制编码

解码按上述OOK脉冲比例进行，具体遥控器编码和重复帧行为以实测为准。

注意事项

固件环境：接收学习开关按实际构建确认；当前标准矩阵中esp32s3-F8R8关闭，不能概括为所有S3关闭
天线：发射和接收模块都建议接 17cm 导线天线，否则距离极短
供电：射频模块对供电敏感，建议使用独立 3.3V/5V 供电而非 GPIO 取电
干扰：环境中可能存在同频干扰，接收稳定性和误触发须实测
发射限制：不要连续高频发送，建议由规则按事件触发或低频定时触发
学习距离：按具体模块、遥控器、天线与环境确认有效距离，不采用统一最佳距离
编码边界：当前键库记录固定码值/位长，不保证滚动码、加密码或所有遥控器行为；本地编码也不标识唯一的远端设备
脉宽匹配：如果学习到的脉宽与发射默认值不同，发射时需使用学习到的脉宽
示例启用：导入示例保持禁用；完成目标板引脚、配置保全、接线与负载确认后再启用规则或外设
验收分界：RX学习/配置事务与TX发送分别验收。页面提示、GPIO SDK成功或TX的host测试都不能证明接收器学习、重启恢复或无线负载动作成功

RX候选的并发、存储与错误边界

候选接收器使用一致状态快照；规则事件在接收锁外派发，停止遇到在途派发会返回失败并保留接收器，等待结束后重试停止。此时拒绝重新绑定或开始学习；不能把一次停止请求当作已经取消所有进入队列的动作。单例已绑定其他活动引脚时也拒绝接管。ISR以跨核临界区和代次token隔离旧callback；真实中断时序仍须目标板验证。

RF按键保存在独立的/config/rf_keys.json数组，最多40项。修改会先读取来源、检查私有候选、写临时文件并读回，再比较来源和原子替换，提交成功后才更新缓存。打开、短写、已观察到的来源冲突、rename失败都会返回失败；主文件或外部已写入的来源不会为修复失败而被主动删除。这个占用只串行RF模块自己的操作，不能当成任意文件管理器/工厂恢复入口都共享的全局CAS；最后来源比较与rename之间的外部写入竞态仍未封闭。

学习timeoutMs须为1000～60000的完整整数；键库bits须12～32，pulse须80～2000微秒，code须为完整十六进制且不超出位长。RX键库的80微秒下限不同于TX发送的100微秒下限；捕获或存入一个码不等于TX能合法重放。参数非法返回400，无法开始学习返回409，真正找不到删除名称返回404，存储/源变化/繁忙或快照未确认返回503；清空不会忽略写盘失败而报告成功。

没有初始化接收器也可管理按键。首次文件读取失败时按键列表会重试，并在仍无法确认时返回503；原始码接收不因此假装已有空键库。关闭PERIPH_EXEC但保留RF_LEARN时仍可接收、学习和保存RF自己的文件，只不派发规则。此候选的本地门禁结果须看对应记录，TX的34项通过不覆盖RX；真实接收/接线/掉电恢复/负载动作和长稳仍分别待验收。

433MHz 射频模块 ​

功能说明 ​

支持的外设类型 ​

事件编号 ​

硬件接线 ​

发射模块（如 SYN115/F115） ​

接收模块（如 SYN470R/SYN480R） ​

配置方式 ​

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

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

步骤2：添加 RF 外设 ​

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

方式2：JSON配置文件导入 ​

参数说明 ​

对码学习 API ​

学习状态响应示例 ​

按键库存储 ​

数据上报格式 ​

事件触发机制 ​

与外设执行联动 ​

Web界面配置步骤 ​

JSON配置示例 ​

RF 遥控控制 LED ​

按原始编码匹配 ​

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

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

调试接口 ​

解码原理 ​

注意事项 ​

RX候选的并发、存储与错误边界 ​

433MHz 射频模块

功能说明

支持的外设类型

事件编号

硬件接线

发射模块（如 SYN115/F115）

接收模块（如 SYN470R/SYN480R）

配置方式

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

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

步骤2：添加 RF 外设

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

方式2：JSON配置文件导入

参数说明

对码学习 API

学习状态响应示例

按键库存储

数据上报格式

事件触发机制

与外设执行联动

Web界面配置步骤

JSON配置示例

RF 遥控控制 LED

按原始编码匹配

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

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

调试接口

解码原理

注意事项

RX候选的并发、存储与错误边界