How to Use an IR Remote in Raspberry Pi: Bookworm Python Guide

If you are trying to set up an IR remote in Raspberry Pi environments running modern OS versions (Debian 12 Bookworm and later), you have likely hit a wall: the legacy lirc (Linux Infrared Remote Control) daemon is effectively dead, poorly supported, and a nightmare to compile on 64-bit ARM kernels. The modern, bulletproof approach on the workbench is to bypass kernel-level IR drivers entirely and use the pigpio library to read microsecond pulse timings directly from the GPIO pins. This guide walks you through wiring a standard VS1838B receiver, writing a jitter-free Python decoder, and debugging the exact errors that stall most embedded projects.

Project Spec Sheet & Hardware Requirements

Before stripping wires, verify your components against this spec sheet. The VS1838B is the industry standard for 38kHz consumer remotes, but its voltage tolerance is where most beginners fry their Pi's GPIO bank.

Hardware Wiring & Pin Mapping

The VS1838B module usually arrives on a small breakout board with a built-in pull-up resistor and a filtering capacitor. You only need three wires.

Software Setup: Bypassing LIRC for pigpio

Linux is not a real-time operating system. If you try to read IR pulses using standard Python loops, the kernel's task scheduler will introduce jitter, turning a crisp 560µs pulse into a 900µs smear. The pigpio library solves this by running a C-based daemon (pigpiod) that samples the GPIO ring buffer at the hardware level.

Run these commands in your Pi's terminal to install the daemon and the Python bindings:

sudo apt update
sudo apt install pigpio python3-pigpio
sudo systemctl enable pigpiod
sudo systemctl start pigpiod

Verify the daemon is running without errors:

sudo systemctl status pigpiod

Complete Python IR Decoding Script

Instead of relying on a rigid protocol library, the most practical bench approach is to capture the raw pulse gaps. This script uses pigpio callbacks to measure the time between falling and rising edges, grouping them into a unique "hash" for each button press. Target Board Variant: This code is tested on Raspberry Pi 5 and Pi 4B running Raspberry Pi OS (Bookworm 64-bit, Python 3.11).

import pigpio
import time
import sys

# --- PIN DEFINITIONS ---
IR_GPIO_PIN = 17  # Physical Pin 11

# --- GLOBAL STATE ---
pi = None
last_tick = 0
pulses = []

def ir_callback(gpio, level, tick):
    """
    Callback triggered on every edge (rising or falling).
    Calculates the microsecond gap between edges.
    """
    global last_tick, pulses
    
    if last_tick != 0:
        # pigpio ticks are in microseconds and wrap around after ~71 minutes
        diff = pigpio.tickDiff(last_tick, tick)
        
        # Ignore massive gaps (space between button presses)
        if diff < 100000: 
            pulses.append(diff)
        else:
            # End of a transmission block, process the data
            if len(pulses) > 10:
                process_ir_block(pulses)
            pulses = []
            
    last_tick = tick

def process_ir_block(raw_pulses):
    """
    Converts raw microsecond timings into a simplified hex-like signature.
    This avoids needing to implement full NEC/RC5 state machines.
    """
    # A simple quantization: divide by 500µs to group similar pulse lengths
    quantized = [int(p / 500) for p in raw_pulses]
    
    # Create a hashable string signature
    signature = "".join(map(str, quantized))
    
    # Filter out noise (short bursts less than 15 edges)
    if len(quantized) > 15:
        print(f"[IR RX] Button Signature: {signature} (Raw edges: {len(raw_pulses)})")

def main():
    global pi
    print(f"Starting IR Listener on GPIO {IR_GPIO_PIN}...")
    print("Press Ctrl+C to exit.\n")
    
    try:
        pi = pigpio.pi()
        if not pi.connected:
            raise ConnectionError("Can't connect to pigpio at localhost(8888)")
            
        # Set pin as input with internal pull-up (safety net)
        pi.set_mode(IR_GPIO_PIN, pigpio.INPUT)
        pi.set_pull_up_down(IR_GPIO_PIN, pigpio.PUD_UP)
        
        # Attach callback for BOTH edges to capture full pulse width
        cb = pi.callback(IR_GPIO_PIN, pigpio.EITHER_EDGE, ir_callback)
        
        # Keep main thread alive
        while True:
            time.sleep(1)
            
    except ConnectionError as e:
        print(f"[FATAL] {e}")
        print("Fix: Run 'sudo systemctl start pigpiod' and check daemon status.")
        sys.exit(1)
    except KeyboardInterrupt:
        print("\nStopping IR Listener...")
    finally:
        if pi is not None and pi.connected:
            cb.cancel()
            pi.stop()

if __name__ == "__main__":
    main()

Debugging: First Three Things to Check When It Fails

When integrating an IR remote in Raspberry Pi builds, the hardware rarely fails; the environment and daemon states do. If the script above throws an error or outputs garbage, run through this exact diagnostic sequence.

1. The Exact Error: Can't connect to pigpio at localhost(8888)

This is the most common failure. It means the Python script cannot talk to the C daemon.
The Fix: The daemon is either not installed, not running, or blocked by a firewall. Run sudo systemctl enable pigpiod followed by sudo systemctl restart pigpiod. If you are running the script inside a Docker container, you must pass the host's network stack (--network host) or map port 8888.

2. Output is Pure Noise (Random Signatures Without Pressing Buttons)

IR receivers are essentially light sensors. Compact Fluorescent (CFL) bulbs, cheap LED drivers, and direct sunlight emit broadband infrared noise that overwhelms the 38kHz filter.
The Fix: Cup your hand over the receiver dome. If the noise stops, your ambient lighting is the culprit. Shield the VS1838B with a piece of heat-shrink tubing or dark acrylic, leaving only the front lens exposed, or move the receiver away from your desk lamp.

3. Script Runs, But Output is Missing the First Few Pulses

The NEC protocol starts with a massive 9ms AGC (Automatic Gain Control) lead pulse. If your receiver's internal capacitor is too small, the first pulse causes the internal gain to max out, temporarily blinding the sensor.
The Fix: Check your breakout board. If it lacks a capacitor between VCC and GND, solder a 10µF ceramic capacitor directly across the power pins on the module to stabilize the voltage rail during high-current draw spikes.

Extending and Simplifying the Build

Once you have raw signatures printing to your console, you have a decision to make based on your project's end goal.

How to Simplify (The "I Just Want a Media Center" Route):
If your goal is simply to control Kodi or RetroPie with a TV remote, stop wiring GPIO pins. Buy a Flirc USB dongle (~$25). It contains its own microcontroller, handles all 38kHz demodulation and protocol decoding in hardware, and presents itself to the Pi as a standard USB keyboard. You map the buttons via the Flirc desktop app, and the Pi requires zero custom Python code or daemon management.

For further reading on handling microsecond timing on ARM Linux architectures, refer to the official pigpio documentation and the Raspberry Pi Hardware Compute Module datasheets for exact GPIO current draw limits.