IR Remote Receiver

Overview

The IR remote receiver module receives standard infrared remote control signals (NEC/RC5/Sony and other protocols), decodes them, and generates system events. Suitable for remote control of lights, mode switching, remote control, and other scenarios.

Firmware Requirement: FASTBEE_ENABLE_IR_REMOTE=1 must be compiled and the irRemote feature must be active. The esp32s3-F8R8 release environment excludes IR/RF to avoid an RMT/library conflict; esp32-F8R0 or validated S3 environments such as esp32s3-F16R8 can be used when IR is required.

Supported Peripheral Types

Type	type Value	Description
SENSOR	38	IR receiver (IR Remote)

Event Numbers

Event	Number	Description
EVENT_IR_CODE_RECEIVED	125	IR code received

Hardware Wiring

VS1838B IR Receiver Head

Receiver Pin	ESP32 GPIO	Description
OUT (Signal)	GPIO 15	Data output
VCC	3.3V	Power supply
GND	GND	Ground

IR receiver heads typically have three pins; viewed from the front (convex side facing you): Left=OUT, Center=GND, Right=VCC. Different models may vary; refer to the datasheet.

Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving IR remote configuration, verify receiver/transmitter pins, protocol type, and carrier frequency.

Step 1: Navigate to Peripheral Management Page

1. Open a browser and navigate to the ESP32 IP address
2. After logging in, click Peripheral Configuration in the left menu

Step 2: Add IR Receiver Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	ir_recv1	Unique identifier
   Name	IR Receiver	Display name
   Peripheral Type	Generic Sensor (type: 38)	IR driver
   Pin Configuration	15	OUT signal pin
   Driver Name	IR_REMOTE	Fixed value
   Decode Protocol	NEC	NEC/RC5/SONY/AUTO
   Detection Interval	100	100ms (50-200)

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Press remote control buttons and check reported IR codes

Important: Check /api/features/status before wiring. A feature that is not compiled or active cannot be enabled only by importing a peripheral JSON file.

---

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

{
  "id": "ir_recv1",
  "name": "IR Receiver",
  "type": 38,
  "enabled": false,
  "pins": [15],
  "params": {
    "driver": "IR_REMOTE",
    "protocol": "NEC",
    "interval": 100
  }
}

Parameter Description

Parameter	Description
driver	Driver name, fixed to "IR_REMOTE"
protocol	Decode protocol: NEC (default), RC5, SONY, AUTO (auto-detect)
interval	Receive detection interval (ms), recommend 50-200

pins[0] = IR receiver head data pin

Data Report Format

When IR signal is received, decoded value is reported via MQTT:

[{"id": "ir_recv1", "value": "code:0xFF30CF,protocol:NEC,bits:32"}]

Field	Description
code	Decoded IR code (hexadecimal)
protocol	Identified protocol type
bits	Code bit length

Common NEC Remote Control Code Reference

Common button codes for the Puzhong experiment kit remote control:

Button	Code	Button	Code
CH-	0xFFA25D	CH	0xFF629D
CH+	0xFFE21D	PREV	0xFF22DD
NEXT	0xFF02FD	PLAY	0xFFC23D
VOL-	0xFFE01F	VOL+	0xFFA857
EQ	0xFF906F	0	0xFF6897
1	0xFF30CF	2	0xFF18E7
3	0xFF7A85	4	0xFF10EF
5	0xFF38C7	6	0xFF5AA5
7	0xFF42BD	8	0xFF4AB5
9	0xFF52AD	100+	0xFF9867

Event Trigger Mechanism

When an IR code is received, EVENT_IR_CODE_RECEIVED (125) event is triggered; event data contains the decoded value, which can be used in periph_exec rules.

Peripheral Execution Integration

Web Interface Configuration Steps

Create Remote Control LED Rule

1. Click Peripheral Execution in the left menu
2. Click the Add Rule button
3. Configure event trigger:
   • Trigger Type: Event Trigger
   • Event Source: ir_recv1
   • Event Number: 125 (IR code received)
   • Match Value: 0xFF30CF (button 1 code)
4. Add action:
   • Action Type: Toggle Level
   • Target Peripheral: led1
5. Click Save

💡 Tip: Use the "Common NEC Remote Control Code Reference" table to find button codes

---

JSON Configuration Example

Remote Control LED

{
  "name": "Remote Light On",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "triggerPeriphId": "ir_recv1",
      "eventId": "ir_code_received",
      "operatorType": 0,
      "compareValue": "0xFF30CF"
    }
  ],
  "actions": [
    { "actionType": 30, "targetPeriphId": "led1" }
  ]
}

Remote Control PWM Brightness

{
  "name": "Remote Brightness",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "triggerPeriphId": "ir_recv1",
      "eventId": "ir_code_received",
      "operatorType": 0,
      "compareValue": "0xFFA857"
    }
  ],
  "actions": [
    { "actionType": 4, "targetPeriphId": "pwm_led1", "actionValue": "255" }
  ]
}

Remote Control Mode Switch

{
  "name": "Remote Mode Switch",
  "enabled": true,
  "triggers": [
    {
      "triggerType": 4,
      "triggerPeriphId": "ir_recv1",
      "eventId": "ir_code_received",
      "operatorType": 0,
      "compareValue": "0xFFC23D"
    }
  ],
  "actions": [
    { "actionType": 21, "targetPeriphId": "mode_switch", "actionValue": "next" }
  ]
}

Notes

1. Firmware Environment: Confirm irRemote is compiled and active; esp32s3-F8R8 intentionally excludes it
2. Ambient Light Interference: Strong sunlight or fluorescent lights may interfere with IR reception; recommend shaded installation
3. Reception Angle: VS1838B reception angle is approximately ±45°; best performance when facing directly
4. Repeat Codes: Long-pressing buttons sends repeat codes (0xFFFFFFFF); rule design should consider deduplication
5. Multi-Protocol Support: Setting protocol: "AUTO" enables auto-detection, but decoding speed is slightly slower
6. Distance Limit: Typical reception distance is 5-8m, affected by transmitter power and environment