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: Standard firmware enables FASTBEE_ENABLE_IR_REMOTE by default; esp32-F8R4 Full is available. ESP32-S3 Full currently disables the IR driver by default to avoid RMT compatibility issues.

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: Requires FASTBEE_ENABLE_IR_REMOTE=1. ESP32-S3 Full currently disables this switch by default; IR remote control preferably uses Standard firmware.

---

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. Switch to the Peripheral Execution Management tab
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": [
    {
      "type": "event",
      "params": {
        "periphId": "ir_recv1",
        "eventCode": 125,
        "matchValue": "0xFF30CF"
      }
    }
  ],
  "actions": [
    {
      "type": "gpio_toggle",
      "params": {
        "periphId": "led1"
      }
    }
  ]
}

Remote Control PWM Brightness

{
  "name": "Remote Brightness",
  "enabled": true,
  "triggers": [
    {
      "type": "event",
      "params": {
        "periphId": "ir_recv1",
        "eventCode": 125,
        "matchValue": "0xFFA857"
      }
    }
  ],
  "actions": [
    {
      "type": "pwm_write",
      "params": {
        "periphId": "pwm_led1",
        "value": "255"
      }
    }
  ]
}

Remote Control Mode Switch

{
  "name": "Remote Mode Switch",
  "enabled": true,
  "triggers": [
    {
      "type": "event",
      "params": {
        "periphId": "ir_recv1",
        "eventCode": 125,
        "matchValue": "0xFFC23D"
      }
    }
  ],
  "actions": [
    {
      "type": "event_emit",
      "params": { "event": "mode_switch" }
    }
  ]
}

Notes

1. Firmware Version: Standard firmware includes IR driver by default; esp32-F8R4 Full available; ESP32-S3 Full currently disabled by default
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