0.9.4 disruptive update
=======================

The configuration is so much changed that updating  from 0.9.0 requires
manual intervention. This could be done using the update scripts or as
a completely manual process.

The outcome of the process is up to three different services by
default controlled by systemd.


The changes
-----------

The hardware.conf file is no longer supported.

The former single lirc service is replaced with the three systemd
services lircd.service, lircmd.service and irexec.service. There is
no counterpart to the 0.9.0 'lirc' service which covered all of these.
Using a transmitter requires yet another service.

0.9.4 defaults to using systemd for controlling the services. This
is not just start/stop functionality, systemd is used to implement
new features and to address shortcomings in 0.9.0. However, traditional
systemV scripts are also installed and could be used although this
is less tested and not really documented.

Previous lirc package installed a udev rule which autostarted lircd
when a new /dev/lirc* device was created, typically when connecting
some kind of USB device. This rule is no longer present, users
depending on lircd needs to start the lircd.service explicitly.

As shipped, lircd is configured to use the devinput driver and the
'auto' device. This should be a working configuration if:
  - The capture device is supported by the kernel.
  - The remote is supported by the kernel.
  - There is exactly one capture device (i. e., /sys/class/rc/ entry).
  - There is no need to send (i. e., to do IR blasting).
Bottom line: lircd has a limited but sometimes working setup as shipped.


Using the update script
-----------------------

If you want to make a non-destructive test use

    $ cp -ar /etc/lirc .
    $ LIRC_DRYRUN=1 /usr/share/lirc/lirc-old2new ./lirc

This will update the files in ./lirc and also just echo the systemctl
commands instead of executing them. To perform the update use:

    $ sudo /usr/share/lirc/lirc-old2new

This will use the files in /etc/lirc, updating lirc_options.conf using data
in hardware conf. It will also start and enable lircd.service, lircmd.service
and irexec.service if the corresponding services was enabled in 0.9.0.

After running script check results using

    $ cat /etc/lirc/lirc_options.conf
    $ systemctl status lircd.socket
    $ systemctl status lircmd.service
    $ systemctl status irexec.service

Note that configurations using a transmitter needs to be handled manually,
see below.


Manual updating
---------------

The manual process is not that hard. The first step is to update
lirc_options.conf using the values in hardware.conf. Usually, this is just
'device' and 'driver' but you might have a different setup.

The [modinit] section contains a single value 'code = '. This is code which
is run by lircd-setup as root before lircd is started. Typical use is
e. g., modprobe(1) and setserial(1) invocations. If in doubts, leave this
as-is.

In the default debian setup lircd runs as root, keeping the old defaults.
Refer to upstream documentation on how to run it as a regular user.

When the lirc_options is in shape, enable the different services. Note
that most users only run one or two of these.

*lircd* requires /etc/lirc/lircd.conf. In an upgrade scenario, this is
already in place and you could enable, start and check lircd using:

    $ sudo systemctl enable lircd.socket
    $ sudo systemctl start lircd.socket
    $ systemctl status lircd.socket

*irexec* requires /etc/lirc/irexec.lircrc. In an upgrade scenario you should
have the old configuration file lircrc available if irexec is used. Do:

    $ sudo cp /etc/lirc/lircrc /etc/lirc/irexec.lircrc
    $ sudo systemctl enable irexec.service
    $ sudo systemctl start irexec.service
    $ systemctl status irexec.service

*lircmd* requires lircmd.conf. In an upgrade scenario this should already
be in place if this service is used. Enable, start and check using

    $ sudo systemctl enable lircmd.service
    $ sudo systemctl start lircmd.service
    $ systemctl status lircmd.service

*Using a transmitter* requires setting up yet another service (i. e.,
a separate lircd instance). This is done by creating a new file like
/etc/systemd/system/lircd-tx.service. An example:

    [Unit]
    Description=LIRC Infrared Signal Decoder (transmitting)
    After=network.target

    [Service]
    Type=simple
    ExecStart=/usr/sbin/lircd --driver=iguanaIR \
                              --device=/var/run/iguanaIR/0 \
                              --output=/var/run/lirc/lircd-tx \
                              --pidfile=/run/lirc/dont-use-lircd-tx.pid \
                              --nodaemon \
                              --allow-simulate

    [Install]
    WantedBy=multi-user.target

The service will use the defaults from the lirc_options.conf file. The
--device, --output and --pidfile must be unique and thus cannot use these
defaults. A configuration file might or might not be needed; the example
uses the default /etc/lirc/lircd.conf.

Once in place this service can be controlled like other services:

    $ sudo systemctl enable lircd-tx.service
    $ sudo systemctl start lircd-tx.service
    $ systemctl status lircd-tx.service


Re-enabling the udev autostart rule.
====================================

The udev rule which autostarts lirc is still available in
/usr/share/lirc/contrib/85-lirc.rules. This can be copied to
/etc/udev/rules.d to re-enable the hotplugging lirc restart. However,
here are dragons:

    - The rule is not compatible with the systemd configuration, the
      sysV scripts must be used to control lirc.
    - The rule is known to cause subtle bugs e. g., lp: #499588.
    - The rule has never worked for other devices then /dev/lirc* ones.
    - The rule has never worked with multiple /dev/lirc* devices.

-- Alec Leamas <al@jessie.nowhere.net>  Mon, 10 Jan 2016 14:11:10 +0200
