Most Raspberry Pis are connected to a TV.
Nearly all TVs have an infrared (IR) remote control.
Using Linux Infrared Remote Control (LIRC), you can control your Raspberry Pi with an IR remote control.

This tutorial was written for Raspbian 9 (stretch) in January, 2019.

Contents

Hardware: Infrared Receiver

Run the following command on the Raspberry Pi to show the pin layout: 

pinout

Connect an IR receiver to the following pins:

Raspberry Pi 3 IR receiver TSOP4838
(12) GPIO18 1 = OUT
(14) GND 2 = GND
(17) 3V3 3 = VS

Be sure to check the datasheet if you are using another IR receiver.

Driver: Kernel Module

By default, the kernel module lirc_rpi uses GPIO18 for receiving and GPIO17 for transmitting.
A reboot loads the kernel module. When it is loaded, the device /dev/lirc0 will be available.

/boot/config.txt
# Uncomment this to enable the lirc-rpi module
dtoverlay=lirc-rpi

Addendum, 2019-05-22

Kernel 4.19.y requires gpio-ir to be loaded. lirc-rpi is no longer available.

/boot/config.txt
# Uncomment this to enable infrared communication.
dtoverlay=gpio-ir   # uses gpio_pin=18 by default

Software: LIRC

Install LIRC: 

sudo apt install lirc
/etc/lirc/lirc_options.conf
[lircd]
driver = default
device = /dev/lirc0

[lircmd]
uinput = True

[lircd-uinput]
add-release-events = True

Addendum, 2020-03-15

Config files (lirc_options.conf and lircd.conf) are missing in the lirc package in Raspbian 10 (buster).
This causes an error during installation of the package.
Writing the missing files before the package is installed fixes the error.

/etc/lirc/lircd.conf
include "lircd.conf.d/*.conf"

First Test

Reboot to load the kernel module: 

sudo reboot

Stop LIRC daemon: 

sudo /etc/init.d/lircd stop

Show raw signals from IR receiver (use a remote to generate some signals): 

mode2 -d /dev/lirc0

Configuration

List valid button names: 

irrecord --list-namespace

Record signals from a remote control and generate a configuration for decoding: 

irrecord myremote.lircd.conf

Use the configuration system-wide: 

cd /etc/lirc/lircd.conf.d
sudo mv devinput.lircd.conf devinput.lircd.dist
sudo mv /home/pi/myremote.lircd.conf /etc/lirc/lircd.conf.d/

Restart LIRC daemon to load the new configuration: 

sudo /etc/init.d/lircd restart

Test Configuration

Show decoded signals: 

irw

Applications

LIRC as a Mouse Input Device

/etc/lirc/lircmd.conf
PROTOCOL IntelliMouse

ACCELERATOR 2 32 2

MOVE_N * KEY_UP
MOVE_E * KEY_RIGHT
MOVE_S * KEY_DOWN
MOVE_W * KEY_LEFT

# mouse wheel
MOVE_OUT * KEY_CHANNELUP
MOVE_IN * KEY_CHANNELDOWN

# left and right mouse buttons
BUTTON1_CLICK * KEY_OK
BUTTON3_CLICK * KEY_MENU

Execute Commands

/etc/lirc/irexec.lircrc
begin
  prog   = irexec
  button = KEY_POWER
  config = shutdown -h now
end

begin
  prog   = irexec
  button = KEY_VOLUMEUP
  repeat = 1
  config = amixer sset PCM 1dB+
end

begin
  prog   = irexec
  button = KEY_VOLUMEDOWN
  repeat = 1
  config = amixer sset PCM 1dB-
end

Audacious Audio Player

Install Audacious: 

sudo apt install audacious

Enable the LIRC Plugin under File > Settings > Plugins.

/home/pi/.lircrc
begin
  prog   = audacious
  button = KEY_PLAY
  config = PLAY
end

begin
  prog   = audacious
  button = KEY_STOP
  config = STOP
end

begin
  prog   = audacious
  button = KEY_PAUSE
  config = PAUSE
end

begin
  prog   = audacious
  button = KEY_NEXT
  config = NEXT
end

begin
  prog   = audacious
  button = KEY_PREVIOUS
  config = PREV
end

begin
  prog   = audacious
  button = KEY_FASTFORWARD
  repeat = 1
  config = FWD
end

begin
  prog   = audacious
  button = KEY_REWIND
  repeat = 1
  config = BWD
end

Service Units

Service Description
irexec Executes commands as configured in /etc/lirc/irexec.lircrc
lircd The LIRC daemon
lircd-setup
lircd-uinput Generates keystrokes when you press a button on the remote
lircmd LIRC mouse device

To enable or disable services, execute the following command: 

sudo systemctl disable lircd-uinput.service

Known Issues