FDX-B Tag Reader (UART)

Custom ESPHome component for decoding ISO 11784/11785 FDX-B RFID tags over a UART-connected reader.

Overview

• Supports any reader that streams ASCII-encoded frames framed with STX/ETX.
• Parses country code and national ID, publishes sensors for the latest scan and a running list of seen tags.
• Emits Home Assistant compatible sensors plus a binary sensor pulse when a tag is detected.
• Includes optional telemetry via esphome.fdx_tag_scanned log events for automation hooks.

Hardware

Tested with a Seeed XIAO ESP32-C6 wired to a commercial FDX-B reader module:

• ESP pin GPIO17 (D7) -> reader TX
• Common ground between ESP and reader
• Reader powered from a stable 5V rail (per vendor requirements)

Configuration

1. Copy the component into custom_components/fdx_reader inside your ESPHome project.
2. Reference the directory via external_components.
3. Configure a UART block that matches your reader's baud rate (default: 9600 8N1).
4. Instantiate the fdx_reader component, then add the dedicated text_sensor, binary_sensor, and sensor platforms to expose data.

Example

external_components:
  - source:
      type: local
      path: custom_components

uart:
  id: tag_reader_uart
  rx_pin: GPIO17
  baud_rate: 9600

time:
  - platform: homeassistant
    id: homeassistant_time

fdx_reader:
  id: fdx_tag_reader
  uart_id: tag_reader_uart
  time_id: homeassistant_time

text_sensor:
  - platform: fdx_reader
    fdx_reader_id: fdx_tag_reader
    last_tag:
      name: "Last Tag ID"
    last_scan_time:
      name: "Last Scan Time"
    known_tags:
      name: "Known Tags"

binary_sensor:
  - platform: fdx_reader
    fdx_reader_id: fdx_tag_reader
    tag_detected:
      name: "Tag Detected"

sensor:
  - platform: fdx_reader
    fdx_reader_id: fdx_tag_reader
    total_scans:
      name: "Total Scans"

Sensors

• last_tag – text sensor updated with CCC-NNNNNNNNNNNN (country + national ID).
• last_scan_time – timestamp string sourced from the configured time component.
• known_tags – comma-separated list of all tags seen since boot.
• tag_detected – binary sensor pulsed ON for ~2 seconds with each scan.
• total_scans – incremental count of processed tags.

Behaviour Notes

• Incoming packets must be ASCII hex characters framed by 0x02 (STX) and 0x03 (ETX).
• Packets are capped at 64 bytes; shorter than 6 bytes are ignored.
• Known tags are stored in memory for the duration of the boot session; there is no automatic pruning.
• If the configured time source is unavailable, scans still publish tag IDs but timestamps and known tag tracking are deferred until time sync.
• Verbose logging (logger.level = DEBUG or VERBOSE) prints every received byte, which is useful for bring-up but noisy in production.

Troubleshooting

• Verify reader TX voltage levels are compatible with the ESP32 input (use a level shifter if needed).
• Confirm UART RX pin is not re-used by other peripherals.
• Ensure Wi-Fi or serial logs show STX received / ETX received messages when tags are presented.
• Increase logger.baud_rate or temporarily reduce log level if you see UART buffer overruns.

License

This component is provided as-is for personal experimentation. Review vendor and regional regulations before deploying RFID readers.