MFRC522 RFID Card Reader

Overview

MFRC522 is a 13.56MHz RFID card reader module that communicates via SPI bus, supporting reading UIDs of Mifare S50/S70 and other IC cards. Suitable for access control systems, attendance tracking, identity recognition, and other scenarios.

Firmware Requirement: Requires FASTBEE_ENABLE_RFID=1 and an active rfid runtime feature.

Supported Peripheral Types

Type	type Value	Description
SENSOR	38	SPI sensor (MFRC522)

Event Numbers

Event	Number	Description
EVENT_RFID_CARD_DETECTED	120	New card detected
EVENT_RFID_CARD_REMOVED	121	Card removed

Hardware Wiring

MFRC522 Pin	ESP32 GPIO	Description
SDA (SS)	GPIO 5	SPI chip select
SCK	GPIO 18	SPI clock
MOSI	GPIO 23	SPI master out slave in
MISO	GPIO 19	SPI master in slave out
RST	GPIO 4	Reset pin
VCC	3.3V	Power supply
GND	GND	Ground

MFRC522 operates at 3.3V; do not connect 5V!

Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving MFRC522 configuration, verify SPI pins, chip select pin, reset pin, and 3.3V power supply.

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 RFID Card Reader Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	rfid1	Unique identifier
   Name	RFID Card Reader	Display name
   Peripheral Type	Generic Sensor (type: 38)	RFID driver
   SS Pin	5	SPI chip select
   RST Pin	4	Reset pin
   Driver Name	MFRC522	Fixed value
   Detection Interval	500	500ms (200-500)

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Swipe a card and check the reported UID

⚠️ Important: MFRC522 must use 3.3V power supply; 5V will damage the module; firmware must enable FASTBEE_ENABLE_RFID=1.

---

Method 2: JSON Configuration File Import

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

{
  "id": "rfid1",
  "name": "RFID Card Reader",
  "type": 38,
  "enabled": false,
  "pins": [5, 4],
  "params": {
    "driver": "MFRC522",
    "ssPin": 5,
    "rstPin": 4,
    "interval": 500
  }
}

Parameter Description

Parameter	Description
driver	Driver name, fixed to "MFRC522"
ssPin	SPI chip select pin (consistent with pins[0])
rstPin	Reset pin (consistent with pins[1])
interval	Polling detection interval (ms), recommend 200-500

SPI bus pins (SCK/MOSI/MISO) use ESP32 default SPI pins; no need to specify in configuration.

Data Report Format

When a card is detected, UID is reported via MQTT:

[{"id": "rfid1", "value": "uid:A1B2C3D4"}]

When card is removed:

[{"id": "rfid1", "value": "uid:removed"}]

Event Trigger Mechanism

When the RFID module detects a card, it triggers system events:

• EVENT_RFID_CARD_DETECTED (120): New card brought near
• EVENT_RFID_CARD_REMOVED (121): Card removed

These events can be used as trigger conditions in periph_exec rules.

Peripheral Execution Integration

Web Interface Configuration Steps

Create Card Swipe Door Open 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: rfid1
   • Event Number: 120 (card detected)
4. Add actions:
   • Action 1: Servo door open
     • Action Type: Set PWM
     • Target Peripheral: servo1
     • Action Value: 180
   • Action 2: Delay 3 seconds
     • Action Type: Delay
     • Delay Value: 3000 (milliseconds)
   • Action 3: Servo door close
     • Action Type: Set PWM
     • Target Peripheral: servo1
     • Action Value: 0
5. Click Save

💡 Tip: Can use event 120 (card swipe) and 121 (card removed)

---

JSON Configuration Example

Card Swipe Door Open

{
  "name": "Card Swipe Door Open",
  "enabled": true,
  "triggers": [
    { "triggerType": 4, "triggerPeriphId": "rfid1", "eventId": "rfid_card_detected" }
  ],
  "actions": [
    { "actionType": 10, "targetPeriphId": "servo1", "actionValue": "180" },
    { "actionType": 10, "targetPeriphId": "servo1", "actionValue": "0", "syncDelayMs": 3000 }
  ]
}

After a card is detected, the servo opens the door at 180° and returns to 0° after 3 seconds.

Card Swipe Display UID

{
  "name": "Display Card Number",
  "enabled": true,
  "triggers": [
    { "triggerType": 4, "triggerPeriphId": "rfid1", "eventId": "rfid_card_detected" }
  ],
  "actions": [
    { "actionType": 27, "targetPeriphId": "oled1", "actionValue": "#Card UID\n${rfid1.uid}" }
  ]
}

Notes

1. Firmware State: Confirm rfid is compiled and active in /api/features/status
2. Voltage Requirement: MFRC522 module must use 3.3V power supply; 5V will damage the module
3. SPI Conflict: If using SD card or other SPI devices simultaneously, different CS pins must be used
4. Read Distance: Typical read distance is 2-5cm, affected by card type and antenna quality
5. Multi-Card Handling: Can only read one card at a time when multiple cards are present; operate one at a time
6. UID Uniqueness: Some low-cost cards may have duplicate UIDs; verify sector data for security scenarios